NAV
php go javascript shell

Introduction

Welcome to the Topgeschenken API! Here we explain how you can use our endpoints, get some additional information and examples.

We have split the documentation into various section which can be found in the menu. We assume some basic knowledge on how to use an API, but tried to keep things as simple as possible.

We have examples in PHP, JavaScript, cURL and some Go. If you have your own language which you want to add, feel free to add those via a Pull Request (merge request if you're familiar with Git terminology). You can switch the programming language of the examples with the tabs in the top right.

This documentation page was created with Slate. Feel free to edit it if you think something is unclear and you think you have something valuable to add.

Authentication

Every endpoint within our API implements OAuth2 authentication. By default authentication is done via the grant type authorization. This will generate a bearer token for a specific user. Using this token is the default and preferred method.

An alternative method is logging in with client credentials, this normally results in a anonymous bearer token. One exception for this grant type is using a machine account (service account) which is coupled to a company.

Authenticating with client credentials

$result = $yourApiClient->post('/api/v1/token', [
  'client_id' => 'REPLACE_WITH_YOUR_CLIENT_ID',
  'client_secret' => 'REPLACE_WITH_YOUR_CLIENT_SECRET',
  'grant_type' => 'client_credentials', // dont change this
]);

// We dont have an example for JS this yet, feel free to submit it via a pull request!

// We dont have an example for Go this yet, feel free to submit it via a pull request!

// We dont have an example for Shell this yet, feel free to submit it via a pull request!

The above command returns JSON structured like this:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJasdger0e...IMhtreqqrjHU"
}

// Or an Access Denied if the credentials aren't accepted

Which can now be used like this:

$yourApiClient->setHeader('Authorization', 'Bearer ' . $result->access_token);
$yourApiClient->get('/api/v1/products');

// We dont have an example for JS this yet, feel free to submit it via a pull request!

// We dont have an example for Go this yet, feel free to submit it via a pull request!

// We dont have an example for Shell this yet, feel free to submit it via a pull request!

POST https://api.topgeschenken.nl/api/v1/token

Request Parameters

Parameter Required Description
client_id true The provided client_id, also known as username
client_secret true The provided client_secret, also known as password
grant_type true Must always be client_credentials

The Topgeschenken API authenticates via OAuth2 via the standard oAuth logic. To reiterate:

Authenticating with authorization flow

TODO

Generic

Basics

Some concept in our API arent specific for an endpoint, but to all/most of them.

Most endpoints provide HYDRO information. We've implemented this to standardize the return. Please not that future endpoints might deviate from this. At this point we're exploring our options on what works best. We try to respect SEMVER as much as possible.

Most endpoints provide an IRI (basically an url with an UUID) if you want more details about something. Eg an Order has a Customer. It will not provide information about the customer, but provides a direct link on where to get the information.

Methods

We try to apply the proper method types (eg GET or POST) as standardized as possible.

Method Description
GET To get information, wether its a list or detail. Get endpoints don't affect any data. Requesting a GET endpoint will always result in the same.
POST To create a (completely) new item, like a new Cart or a new Customer. Repeating these actions will(/might) result in duplicate entries.
PATCH To update an exists item, like adding a Product to an existing Cart, or updating an email for a Customer
DELETE This method is the only method used to delete endpoints. This will destroy data and is often not reversible.

Translations

While we are a dutch company, we do offer translations for a lot of our data, like product names. To recieve the translated version of something, just add the Accept-Language. Not sending this header, or using * as value will result in nl_NL.

Accept-Language: en_US

Filters

We have multiple filter available so that you can get a result you want. Some endpoints have specific filter options, those will be described per endpoint. Most, if not all endpoints have these common filters to provide a broad sense of control

Method Type Description
created_since string (datetime) Remove items from result which are created before this moment
updated_since string (datetime) Remove items from result which are updated before this moment
updated_until string (datetime) Remove items from result which are updated after this moment
pagination boolean (default: true) If true, a maximum of page_items items will get returned
page_items integer (default: 30) The max number items returned (eg LIMIT 30)
page integer (default: 1) The Nth page of page_items result. Eg 1→1-30, 2→31-60, etc
search string Search through entity specific properties for this string. What those properties are depends on the entity.

Catalog (todo)

Assortments

Get all Assortments

$result = $yourApiClient->get('/api/v1/catalog/assortments');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/assortments')
xhr.onload = function() {
  console.log(Loaded: $</span><span class="p">${</span><span class="nx">xhr</span><span class="p">.</span><span class="nx">status</span><span class="p">}</span><span class="s2"> </span><span class="p">${</span><span class="nx">xhr</span><span class="p">.</span><span class="nx">response</span><span class="p">}</span><span class="s2">);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" </span>
     --url 'https://api.topgeschenken.nl/api/v1/catalog/assortments'

The above command returns JSON structured like this:

{
  "@context": "/api/v1/contexts/Assortment",
  "@id": "/api/v1/catalog/assortments",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/v1/catalog/assortments/11111111-2222-3333-4444-555555555555",
      "@type": "Assortment",
      "name": "Assortment name",
      "title": "Assortment title",
      "uuid": "11111111-2222-3333-4444-555555555555",
      "createdAt": "2021-07-01T12:00:00+00:00",
      "updatedAt": "2021-07-02T07:00:00+00:00"
    }
  ],
  "hydra:totalItems": 1,
  "hydra:search": {
    "@type": "hydra:IriTemplate",
    "hydra:template": "/api/v1/catalog/assortments{?created_since,updated_since,search,uuids}",
    "hydra:variableRepresentation": "BasicRepresentation",
    "hydra:mapping": [
      {
        "@type": "IriTemplateMapping",
        "variable": "some_filters_available",
        "property": "property",
        "required": false
      }
    ]
  }
}

GET api.topgeschenken.nl/api/v1/catalog/assortments

The assortments endpoint gives you the summary of the available assortments. Think 'Baby and kids', 'get well soon' or 'petit fours'. This info is suitable for an overview of assortment and/or to get UUIDs for more details per assortment.

Get Assortment Detail

$result = $yourApiClient->get('/api/v1/catalog/assortments/11111111-2222-3333-4444-555555555555');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/assortments/11111111-2222-3333-4444-555555555555')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/catalog/assortments/11111111-2222-3333-4444-555555555555'

The above command returns JSON structured like this:

{
  "@context": "/api/v1/contexts/Assortment",
  "@id": "/api/v1/catalog/assortments/11111111-2222-3333-4444-555555555555",
  "@type": "Assortment",
  "name": "Assortment name",
  "title": "Assortment title",
  "uuid": "11111111-2222-3333-4444-555555555555",
  "createdAt": "2021-07-01T12:00:00+00:00",
  "updatedAt": "2021-07-02T07:00:00+00:00",
  "products": [
    {
      "@context": "/api/v1/contexts/Product",
      "@id": "/api/v1/catalog/products/11111111-2222-3333-4444-555555555555",
      "@type": "Product",
      "sku": null,
      "type": "generic_product",
      "title": "Product name",
      "uuid": "11111111-2222-3333-4444-555555555555",
      "createdAt": "2021-10-21T12:00:00+00:00",
      "updatedAt": "2021-10-22T13:00:00+00:00",
      "variations": [
        "/api/v1/catalog/products/11111111-2222-3333-4444-555555555555"
      ],
      "orderable": false,
      "mainImage": {
        "small": "https://topgeschenken.nl/media/cache/resolve/product_thumbnail/images/product/77/770b32df8237e.png",
        "medium": "https://topgeschenken.nl/media/cache/product_assortment/images/product/77/770b32df8237e.png",
        "large": "https://topgeschenken.nl/media/cache/resolve/product_image_optimized/images/product/77/770b32df8237e.png"
      }
    }
  ]
}

GET api.topgeschenken.nl/api/v1/catalog/assortments/<UUID>

For more details about a assortments, like 'content' and 'position', you can call the detail endpoint with an UUID.

Products(todo)

Get all Products

$result = $yourApiClient->get('/api/v1/catalog/products');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/products')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/catalog/products'

The above command returns JSON structured like this: json { "todo": "todo", }

GET api.topgeschenken.nl/api/v1/catalog/products

The products endpoint gives you the summary of the available products.

Get Product Detail

$result = $yourApiClient->get('/api/v1/catalog/products/11111111-2222-3333-4444-555555555555');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/products/11111111-2222-3333-4444-555555555555')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/catalog/products/11111111-2222-3333-4444-555555555555'

The above command returns JSON structured like this:

{
    "todo": "todo",
}

GET api.topgeschenken.nl/api/v1/catalog/products/<UUID>

For more details about a products, like description, SKU, min-/max orderable quantity, you can call the detail endpoint with an UUID.

ProductGroups

Get all ProductGroups

$result = $yourApiClient->get('/api/v1/catalog/product-group');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/product-group')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/catalog/product-group'

The above command returns JSON structured like this:

{
    "todo": "todo",
}

GET api.topgeschenken.nl/api/v1/catalog/product-group

This endpoint gives you the summary of the available productgroups.

Get ProductGroup Detail

The above command returns JSON structured like this:

{
    "todo": "todo",
}

GET api.topgeschenken.nl/api/v1/catalog/product-group/<UUID>

For more details about a assortments, like 'SkuPrefix', you can call the detail endpoint with an UUID.

Carts

How a Cart is constructed

{
    ...,
    "customer": "https://uriToACustomer", // todo
    "company":  "https://uriToACompany", // todo
    "createdAt":  "2030-02-20 12:34:56",
    "orders": [
      {
        ...,
        "deliveryDate": "2030-02-24",
        "deliveryAddress": {"street": "SomeStreet", "number": 60, ...},
        "lines": [
          {
            ...,
            "product": "https://uriToProductA", // todo
            "quantity": 7,
          },{
            ...,
            "product": "https://uriToDeliveryProduct", // E.g. the delivery product
            "quantity": 1,
          }
        ],
      },{
        ...,
        "deliveryDate": "2030-03-28",
        "deliveryAddress": {"street": "OtherStreet", "number": 23, ...},
        "lines": [
          {
            ...,
            "product": "https://uriToProductB", // todo
            "quantity": 3,
          },{
            ...,
            "product": "https://uriToDeliveryProduct", // E.g. the delivery product
            "quantity": 1,
          }
        ],
      }
    ],
}

Via the TG system you can place multiple orders for multiple addresses over multiple dates (if you want to, one order for one date is perfectly fine too). To facilitate this, we have a structure to accommodate this, consisting of a Cart, with CartOrders, which in turn have CartOrderLines. An example:

Get All Carts

$result = $yourApiClient->get('/api/v1/order/carts');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/order/carts')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/order/carts'

The above command returns JSON structured like this:

{
  "@context": "/api/v1/contexts/Cart",
  "@id": "/api/v1/order/carts",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/v1/order/carts/11111111-2222-3333-4444-555555555555",
      "@type": "Cart",
      "cartSecret": "",
      "invoiceAddress": null,
      "totalPrice": 0,
      "totalPriceIncl": 0,
      "uuid": "11111111-2222-3333-4444-555555555555",
      "createdAt": "2021-03-26T13:31:28+00:00",
      "updatedAt": "2021-03-26T13:31:28+00:00"
    }
  ],
  "hydra:totalItems": 1,
  "hydra:search": {
    "@type": "hydra:IriTemplate",
    "hydra:template": "/api/v1/order/carts{?created_since,updated_since}",
    "hydra:variableRepresentation": "BasicRepresentation",
    "hydra:mapping": [
      {
        "@type": "IriTemplateMapping",
        "variable": "some_filters_available",
        "property": "property",
        "required": false
      }
    ]
  }
}

GET api.topgeschenken.nl/api/v1/order/carts

This endpoint retrieves all carts available for the user. These are all carts that are not yet finalized (not convert to an order, or on the queue ready to be converted).

Get Cart Detail

$result = $yourApiClient->get('/api/v1/order/carts/11111111-2222-3333-4444-555555555555');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/order/carts/11111111-2222-3333-4444-555555555555')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/order/carts/11111111-2222-3333-4444-555555555555'

The above command returns JSON structured like this:

{
  "@context": "/api/v1/contexts/Cart",
  "@id": "/api/v1/order/carts/11111111-2222-3333-4444-555555555555",
  "@type": "Cart",
  "company": "/api/v1/relation/companies/11111111-2222-3333-4444-555555555555",
  "customer": null,
  "cartSecret": null,
  "invoiceAddress": "/api/v1/relation/addresses/11111111-2222-3333-4444-555555555555",
  "orders": [
    {
      "@id": "/api/v1/order/cart-orders/11111111-2222-3333-4444-555555555555",
      "@type": "CartOrder",
      "deliveryDate": "2022-12-01T00:00:00+00:00",
      "deliveryAddress": "/api/v1/relation/addresses/11111111-2222-3333-4444-555555555555",
      "pickupAddress": null,
      "deliveryRemark": null,
      "lines": [
        {
          "uuid": "11111111-2222-3333-4444-555555555555",
          "createdAt": "2022-11-24T12:29:06+00:00",
          "updatedAt": "2022-11-24T12:29:06+00:00",
          "product": "/api/v1/catalog/products/11111111-2222-3333-4444-555555555555"
        },
        {
          "uuid": "11111111-2222-3333-4444-555555555555",
          "createdAt": "2022-11-24T12:29:06+00:00",
          "updatedAt": "2022-11-24T12:29:06+00:00",
          "product": "/api/v1/catalog/products/11111111-2222-3333-4444-555555555555"
        }
      ],
      "totalPrice": 0,
      "totalPriceIncl": 0,
      "uuid": "11111111-2222-3333-4444-555555555555",
      "createdAt": "2022-11-24T12:29:06+00:00",
      "updatedAt": "2022-11-24T12:29:06+00:00",
      "activity": null
    }
  ],
  "totalPrice": 0,
  "totalPriceIncl": 0,
  "contactEmail": "[email protected]",
  "uuid": "11111111-2222-3333-4444-555555555555",
  "createdAt": "2022-11-24T12:28:49+00:00",
  "updatedAt": "2022-11-24T12:28:49+00:00"
}

GET api.topgeschenken.nl/api/v1/order/carts/<UUID>

This endpoint retrieves one cart. For an example, please look at how a cart is constructed.

Create a Cart

$result = $yourApiClient->post('/api/v1/order/carts', 
{
  "requestedPaymentMethod": "invoice",
  "company": "/api/v1/relation/companies/11111111-2222-3333-4444-555555555555",
  "invoiceAddress": {
    "attn": "Invoice receiver",
    "street": "Example street",
    "number": "1",
    "numberAddition": "",
    "postcode": "1000AA",
    "city": "Amsterdam",
    "country": "NL"
  },
  "orders": [],
  "contactEmail": "[email protected]"
}
);

let xhr = new XMLHttpRequest()
xhr.open('POST', '/api/v1/order/carts')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request POST -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/order/carts'

POST api.topgeschenken.nl/api/v1/order/carts

Via this endpoint you can create a Cart. Note: A Cart is not an Order. You can see it as a draft version of an cart. As long as a cart has not been finalized, you can alter it as you please.

Create a Cart order

$result = $yourApiClient->post('/api/v1/order/cart-orders', 
{
  "cart": "/api/v1/order/carts/11111111-2222-3333-4444-555555555555",
  "deliveryDate": "2030-01-01T00:00:00+02:00",
  "deliveryAddress": {
    "attn": "Delivery name",
    "street": "Example street",
    "number": "1",
    "numberAddition": "",
    "postcode": "1000AA",
    "city": "Amsterdam",
    "country": "NL"
  },
  "deliveryRemark": null,
  "lines": [
    {
    "children": [
      {
        "product": "/api/v1/catalog/products/11111111-2222-3333-4444-555555555555",
        "quantity": 1,
        "metadata": {
          "text": "text",
          "is_card": true
        }
      }
    ],
    "product": "/api/v1/catalog/products/11111111-2222-3333-4444-555555555555",
    "quantity": 1
    }
  ]
}
);

let xhr = new XMLHttpRequest()
xhr.open('POST', '/api/v1/order/cart-orders')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request POST -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/order/cart-orders'

POST api.topgeschenken.nl/api/v1/order/cart-orders

Via this endpoint you can create a Cart. Note: A Cart is not an Order. You can see it as a draft version of an cart. As long as a cart has not been finalized, you can alter it as you please.

Finalize a Cart

$result = $yourApiClient->post('/api/v1/order/carts/11111111-2222-3333-4444-555555555555/finalize');

let xhr = new XMLHttpRequest()
xhr.open('POST', '/api/v1/order/carts/11111111-2222-3333-4444-555555555555/finalize')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request POST -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/order/carts/11111111-2222-3333-4444-555555555555/finalize'

POST api.topgeschenken.nl/api/v1/order/carts/<UUID>/finalize

To make a Cart definitive you have to finalize it. First you create a cart and populate it with the required data. After calling this endpoint the Cart with its CartOrders will be prepared to be converted to an OrderCollection with Orders. After a successful call you will get an OrderCollection number. This is NOT per se a fully processed.

Orders

How an OrderCollection is constructed

{
    ...,
    "customer": "https://uriToACustomer", // todo
    "company":  "https://uriToACompany", // todo
    "createdAt":  "2030-02-20 12:34:56",
    "orders": [
      {
        ...,
        "deliveryDate": "2030-02-24",
        "deliveryAddress": {"street": "SomeStreet", "number": 60, ...},
        "lines": [
          {
            ...,
            "product": "https://uriToProductA", // todo
            "quantity": 7,
          },{
            ...,
            "product": "https://uriToDeliveryProduct", // E.g. the delivery product
            "quantity": 1,
          }
        ],
      },{
        ...,
        "deliveryDate": "2030-03-28",
        "deliveryAddress": {"street": "OtherStreet", "number": 23, ...},
        "lines": [
          {
            ...,
            "product": "https://uriToProductB", // todo
            "quantity": 3,
          },{
            ...,
            "product": "https://uriToDeliveryProduct", // E.g. the delivery product
            "quantity": 1,
          }
        ],
      }
    ],
}

Via the TG system you can place multiple orders for multiple addresses over multiple dates (if you want to, one order for one date is perfectly fine too). To facilitate this, we have a structure to accommodate this, consisting of a OrderCollection, with Orders, which in turn have OrderLines. An example:

Place a full order

$result = $yourApiClient->post('/api/v1/order/order-collections', 
{
  "requestedPaymentMethod": "invoice",
  "invoiceAddress": {
    "attn": "Invoice receiver",
    "street": "Example street",
    "number": "1",
    "numberAddition": "",
    "postcode": "1000AA",
    "city": "Amsterdam",
    "country": "NL"
  },
  "orders": [
    {
      "deliveryDate": "2022-12-01T00:00:00+02:00",
      "deliveryAddress": {
        "attn": "Delivery name",
        "street": "Example street",
        "number": "1",
        "numberAddition": "",
        "postcode": "1000AA",
        "city": "Amsterdam",
        "country": "NL"
      },
      "pickupAddress": null,
      "deliveryRemark": null,
      "lines": [
        {
          "children": [],
          "product": "11111111-2222-3333-4444-555555555555",
          "quantity": 3
        }
      ]
    }
  ],
  "contactEmail": "[email protected]"
}
);

let xhr = new XMLHttpRequest()
xhr.open('POST', '/api/v1/order/order-collections')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request POST -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/order/order-collections'

POST api.topgeschenken.nl/api/v1/order/order-collections

Responses

Code Description
201 OrderCollection resource created
400 Invalid input
404 Resource not found
422 Unprocessable entity

This endpoint will create a full cart with all information included to fulfill a order. After cart creation this endpoint will immediately try to finalize the cart to create a order collection.

Get All Orders

$result = $yourApiClient->get('/api/v1/order/orders');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/order/orders')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/order/orders'

The above command returns JSON structured like this:

{
  "@context": "/api/v1/contexts/Order",
  "@id": "/api/v1/order/orders",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/v1/order/orders/11111111-2222-3333-4444-555555555555",
      "@type": "Order",
      "orderCollection": "/api/v1/order/order-collections/11111111-2222-3333-4444-555555555555",
      "orderNumber": "10000001-0001",
      "status": "completed",
      "deliveryDate": "2022-02-22T00:00:00+00:00",
      "totalPrice": 1,
      "totalPriceIncl": 1,
      "uuid": "11111111-2222-3333-4444-555555555555",
      "createdAt": "2021-06-09T12:00:00+00:00",
      "updatedAt": "2021-06-11T12:00:00+00:00",
      "activity": null
    }
  ],
  "hydra:totalItems": 1,
  "hydra:view": {
    "@id": "/api/v1/order/orders?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/v1/order/orders?page=1",
    "hydra:last": "/api/v1/order/orders?page=2",
    "hydra:next": "/api/v1/order/orders?page=2"
  },
  "hydra:search": {
    "@type": "hydra:IriTemplate",
    "hydra:template": "/api/v1/order/orders{?created_since,updated_since,updated_until,updated_between_from,updated_between_until,uuids,status,sites,delivery_from,delivery_until,auto_order,force_manual,product_groups,status,search}",
    "hydra:variableRepresentation": "BasicRepresentation",
    "hydra:mapping": [
      {
        "@type": "IriTemplateMapping",
        "variable": "some_filters_available",
        "property": "property",
        "required": false
      }
    ]
  }
}

GET api.topgeschenken.nl/api/v1/order/orders

This endpoint retrieves all orders.

Get Order details

$result = $yourApiClient->get('/api/v1/order/orders/11111111-2222-3333-4444-555555555555');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/order/orders/11111111-2222-3333-4444-555555555555')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/order/orders/11111111-2222-3333-4444-555555555555'

The above command returns JSON structured like this:

{
  "@context": "/api/v1/contexts/Order",
  "@id": "/api/v1/order/orders/11111111-2222-3333-4444-555555555555",
  "@type": "Order",
  "orderCollection": "/api/v1/order/order-collections/11111111-2222-3333-4444-555555555555",
  "orderNumber": "10000001-0001",
  "status": "completed",
  "deliveryStatus": null,
  "deliveryDate": "2022-02-22T00:00:00+00:00",
  "deliveryRemark": null,
  "invoiceReference": null,
  "lines": [
    {
      "@type": "OrderLine",
      "@id": "_:19150",
      "children": [],
      "quantity": 1,
      "title": "Ordered product",
      "price": 1,
      "vatSpecification": [
        {
          "price": 1,
          "percentage": 0
        }
      ],
      "productgroupUuid": "11111111-2222-3333-4444-555555555555",
      "product_type": "GenericProduct",
      "uuid": "11111111-2222-3333-4444-555555555555",
      "createdAt": "2022-02-22T22:22:22+00:00",
      "updatedAt": "2022-02-22T22:22:22+00:00",
      "product": "/api/v1/catalog/products/11111111-2222-3333-4444-555555555555",
      "priceIncl": 1,
      "extraInfo": [],
      "metadata": []
    }
  ],
  "colli": [],
  "totalPrice": 1,
  "totalPriceIncl": 1,
  "uuid": "11111111-2222-3333-4444-555555555555",
  "createdAt": "2021-06-09T12:00:00+00:00",
  "updatedAt": "2021-06-11T12:00:00+00:00",
  "activity": null,
  "deliveryAddress": {
    "attn": "Delivery attn",
    "companyName": "My Company",
    "street": "Example street",
    "number": "1",
    "numberAddition": null,
    "postcode": "1000AA",
    "city": "Amsterdam",
    "country": "NL",
    "type": null
  },
  "metadata": []
}

GET api.topgeschenken.nl/api/v1/order/orders/<UUID>

This endpoint retrieves details for one order. For an example, please look at how a OrderCollection is constructed.

Relation (todo)

Customers

Get all Customers

$result = $yourApiClient->get('/api/v1/catalog/relation/customers');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/relation/customers')
xhr.onload = function() {
  console.log(Loaded: $</span><span class="p">${</span><span class="nx">xhr</span><span class="p">.</span><span class="nx">status</span><span class="p">}</span><span class="s2"> </span><span class="p">${</span><span class="nx">xhr</span><span class="p">.</span><span class="nx">response</span><span class="p">}</span><span class="s2">);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" </span>
     --url 'https://api.topgeschenken.nl/api/v1/catalog/relation/customers'

The above command returns JSON structured like this:

{
    "todo": "todo",
}

GET api.topgeschenken.nl/api/v1/catalog/relation/customers

This endpoint retrieves all Customers available for the user. These could be other Customers for the same Company as the requesting user belongs to.

Get Customer Detail

$result = $yourApiClient->get('/api/v1/catalog/relation/customers/11111111-2222-3333-4444-555555555555');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/relation/customers/11111111-2222-3333-4444-555555555555')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/catalog/relation/customers/11111111-2222-3333-4444-555555555555'

The above command returns JSON structured like this:

{
    "todo": "todo",
}

GET api.topgeschenken.nl/api/v1/catalog/relation/customers/<UUID>

For more details about a Customer, like 'email', 'birthday' or 'phone number', you can call the detail endpoint with an UUID.

Companies

Get all Companies

$result = $yourApiClient->get('/api/v1/catalog/relation/companies');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/relation/companies')
xhr.onload = function() {
  console.log(Loaded: $</span><span class="p">${</span><span class="nx">xhr</span><span class="p">.</span><span class="nx">status</span><span class="p">}</span><span class="s2"> </span><span class="p">${</span><span class="nx">xhr</span><span class="p">.</span><span class="nx">response</span><span class="p">}</span><span class="s2">);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" </span>
     --url 'https://api.topgeschenken.nl/api/v1/catalog/relation/companies'

The above command returns JSON structured like this:

{
    "todo": "todo",
}

GET api.topgeschenken.nl/api/v1/catalog/relation/companies

This endpoint retrieves all Companies available for the user.

Get Company Detail

$result = $yourApiClient->get('/api/v1/catalog/relation/companies/11111111-2222-3333-4444-555555555555');

let xhr = new XMLHttpRequest()
xhr.open('GET', '/api/v1/catalog/relation/companies/11111111-2222-3333-4444-555555555555')
xhr.onload = function() {
  console.log(`Loaded: $${xhr.status} ${xhr.response}`);
};

// We dont have an example for Go this yet, feel free to submit it via a pull request!

curl --request GET -H "Authorization: Bearer {token}" \
     --url 'https://api.topgeschenken.nl/api/v1/catalog/relation/companies/11111111-2222-3333-4444-555555555555'

The above command returns JSON structured like this:

{
    "todo": "todo",
}

GET api.topgeschenken.nl/api/v1/catalog/relation/companies/<UUID>

For more details about a Company, like 'chamberOfCommerceNumber', 'companyRegistration' or 'financialSettings', you can call the detail endpoint with an UUID.

Errors

The Topgeschenken API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong or expired. If you think this is incorrect, please contact us.
403 Forbidden -- We acknowledge youre auth, but you gave no access to this item
404 Not Found -- The request item could not be found (or no longer exists).
405 Method Not Allowed -- Please use the method specified.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Contribute

We try to be clear and informative in this manual, but we obviously have insider knowledge. Is something unclear in the docs? Found a typo? Have more code examples? Feel absolutely free to add those via a Pull Request (the BitBucket variant of a Merge Request).

In order to keep things structured, we do have a few rules we have to enforce.

RULES

While we own the manual, we still love see receive input! External input might just help other developers in the future.

  1. If you add a section to the docs, stick to the directory structure that already exists.
    • If multiple sections, those need to be split up
      • The main file is called source/partials/{REPLACE}/index.md.erb
      • The subsections get placed in the source/partials/{REPLACE}/ as well
      • Section names are singular: product, not products.
  2. Copy paste as much as you can! Everything in the same format! Use the simple-codeblock as much as possible
  3. If you create a pull request, please explain what and why you did that, even if it's small.
  4. If you want to add a new language in the examples add it properly, not just one example. We prefer you update all examples.

We reserve the right to decline or change it at any time. Please ask ahead if you're uncertain wether your suggested contribution will be accepted, we dont want to waste anyones time unnecessary.

php go javascript shell