1. Requirements

Before getting started, please check if you fulfill the following requirements:

1. The customer must have an assortment in Apicbase platform maintained either by:
   1. The supplier: Via the assortment integration.
   2. The customer: Please make sure the customer uses the same article numbers (the unique code to identify articles) as you use in your system. This is the code we'll send in the orders.
2. Please check the topics below and make sure you can support the automation either via webhooks or consuming our API endpoint.

2. Integration Methods

2.1. Webhooks

Webhooks are the most recommended integration method for ordering as long as you can provide us a HTTP/S endpoint for the orders to be posted to. If so, please contact [email protected] with the URL and we'll set it up for you.

The advantages of using this approach is:

1. Simplicity. The only thing required on your side is to develop the endpoint linked to the webhook to process the order and return an appropriated HTTP status code.
2. The orders are immediately sent to the configured endpoint as soon as the order is placed on Apicbase platform.
3. Orders placed on our platform and rejected by the webhook endpoint (any response code different than 2XX) will immediately display an error to the customer at the end of the process. The customer must place the order again manually to complete the process, which avoids the need of contacting the customer about orders that can't be fulfilled. That's useful specially for orders with the HTTP response status code 4XX.

However, please be aware of the drawbacks:

1. The security is less robust than using the API endpoint.
2. Orders rejected by the webhook due to issues in the endpoint server (e.g. bugs, server unavailable), .i.e. 5XX error codes, are not retried automatically. That means the customer will not be able to place the order while the issue is not fixed.

Please note that failing orders due to errors either on our side or on the webhook's endpoint (any response code different than 2XX) will result on an error message to be displayed to the customer. The order status will remain as in progress (i.e. not sent) and the customer will have to retry sending it manually after the issue is fixed. So it's important to understand that failed orders will not be automatically retried and will clearly be shown as not sent to the customer.

❗️

A note about security.

To ensure the security of these requests, each request from Apicbase is signed with an X-APIC-WEBHOOK-SIGNATURE header key. It is highly recommended that the supplier uses this value to verify if the payload being received is indeed sent by Apicbase.

This verification requires using the client secret and the received payload to generate a HMAC-SHA256 Hexdigest value. By default, the client secret value is the same one used to generate new tokens, but it's also possible to use a different unique key that is only used to encode this header. Just let us know and we can arrange this for you.

Also please make sure to do the verification using the raw request data content or to ensure the content has the ASCII encoding. Else, your application might change the request data slightly, for example for characters such as á, é, etc and the verification will fail.

Here's a code snippet with some sample Python code that validates the signature header:

Python

import json
from hmac import HMAC

def endpoint(request):
    signature = request.headers["X-APIC-WEBHOOK-SIGNATURE"]
    
    result = HMAC(
        key="<your_client_secret>",
        msg=json.dumps(request.data).encode(),
        digestmod="sha256"
    ).hexdigest()
    
    if signature != result:
        return Response("Incorrect signature", status_code=403)

2.2. API Endpoint

Using our API is an alternative to the webhook approach. The response JSON is the same as the webhook one and more information about it can be found in the endpoint reference.

We recommend using it if one or more of the points below are applicable:

1. There's more flexibility about when to process orders placed by the customer (instead of processing it immediately).
2. You need a more robust security. The API endpoint will follow our standard OAuth2 authentication.
3. Avoid rejecting orders due to errors on your side. As mentioned in the webhook section, orders placed by the customer will fail if we receive any error (any response code different than 2XX) from the webhook endpoint. Therefore the API is useful for 5XX errors, since the orders can be processed later retroactively once the issue is fixed.

However, please be aware of the drawbacks:

1. This approach is more complex when compared to the webhook because you must:
   1. Keep track of which orders were already processed from our list endpoint;
   2. Periodically call our API endpoint to get new orders, taking into account our rate limits.
2. When a customer places an order in Apicbase, its status will be updated immediately to ORDERED (i.e. sent to the suppler) and this status can't be reverted. However, the webhook approach only updates the order status after getting a successful response from the linked endpoint. That means it's not possible run any validation before the order status is updated in the API approach. Thus invalid orders that are later rejected when our API is consumed should be communicated directly to the customer.

3. Data Structure

Regardless of the method chosen to handle orders, the purchase order data should be the same, a JSON object with the following structure:

{
  "id": string, -> Apicbase internal Purchase Order ID
  "order_number": string,
  "status": "ORDERED", -> fixed value
  "ordered_on": datetime,
  "owned_by": {"username": string} | null,
  "order_remarks": string | null,
  "packages": [
    {
      "stock_item": {
        "name": string
      },
      "supplier_package": {
        "supplier_article_number": string,
        "theoretical_price_per_package": string
      },
      "quantity_ordered": integer,
      "total_theoretical_price": string
    }
  ],
  "expected_delivery_date": datetime | null,
  "theoretical_price": string,
  "supplier_customer_number": string
}

Here are the most relevant fields in the JSON above:

• order_number: It's a unique identifier as the id field but also displayed to the customers in Apicbase platform, which makes it important for debugging, tracking orders and to place in invoices if possible.
• expected_delivery_date: When the customer expects to receive the order.
• supplier_customer_number: Unique customer location identifier arbitrarily defined by the supplier. Apicbase expects to receive this number to setup the customer locations before the customer starts placing orders.
• packages:
  • supplier_package.supplier_article_number: Unique identifier used by the supplier to identify the article.
  • quantity_ordered: Amount of articles ordered.

4. Testing

Please check our Sandobx Account guide in order to test your ordering integration.