A collection of endpoints to create assortment files and list its information.
All endpoints below needs a token for authentication. Please, go to this article in order to discover how to generate one.
The general idea of this endpoint is to be able to post assortment data per customer number (as some customers might have different assortments & prices than others). Of course if you (as a supplier) use the same assortment & prices for all your customers, you can just post one file with 'a customer number' that can be used by all of our mutual customers. In this sense it's more of an assortment id. So the customer number field is used to identify/reference an assortment in that sense.
POST /integrations/suppliers/files/
Use this endpoint to create assortment files that'll be synced asynchronously by Apicbase's software. Check directly in the API here.
The expected format is JSON and we'll apply some validation before saving it.
Expected payload:
Please, note that both field are required.
{
"file": json_file,
"customer_number": string
}
Fields information:
- customer_number -> It's the unique identifier in your system for a given customer.
Expected format:
[
{
"third_party_id": string, --> required
"shared_id": string,
"supplier_outlet_id": string,
"brand": string,
"name": string, --> required
"description": string,
"package_type": string,
"price_type_code": integer, --> required (0: per package; 1: per unit)
"orderable": boolean, --> defaults to true
"gtin": string,
"price": decimal, --> required
"package_description": { --> required if "package_description_str" is missing
"quantity": decimal, --> required
"gtin":string,
"package": {
"quantity": decimal,
"unit_name": string --> required at lower level
}
},
"package_description_str": string --> required if "package_description" is missing
},
{...}
]
One note about package_description: it has a recursive nature, which means it can have several nested packages. The following is also a viable representation:
{
"package_description": {
"quantity": decimal, --> required
"gtin":string,
"package": { --> required for nested packages
"quantity": decimal,
"package": {
"quantity": decimal,
"package: {
....
"unit_name": string --> required at lower level
}
}
}
}
}
Now, let's deep dive into the meaning of the fields:
- third_party_id -> Package's unique identifier (REQUIRED);
- shared_id -> Article's identifier (or an identifier shared between packages);
- supplier_outlet_id -> Supplier distribution center identifier associated with the assortment;
- brand -> Article's brand;
- name -> Article's name (REQUIRED);
- description -> Extra information about the package;
- package_type -> Package's type (if it's a box, case or ...)
- price_type_code -> If the package is billed by its unit (1) or by the whole package (0);
- orderable -> True, if the package can be ordered (default). False, otherwise;
- gtin -> Article's GTIN/EAN/UPC;
- Use this field only if you'll send the package structure with the package_description_str field (see below). Otherwise, send it directly within package_description.
- We don't validate its value here but we'll when syncing the data;
- price -> The price of the article;
- package_description -> How the package is structured. You can provide this value in two ways (and one of the two is REQUIRED).
The package_description key is the most important in sending integrated assortment items. We will evaluate the integrated assortment based on the richness of this field. For example: we won't allow every item to be sent in pieces (without any notion of weights, volumes or multipliers/quantities).- As a nested JSON (use the package_description field):
{
"package_description": {
"quantity": 2.0,
"gtin": "26989625952452",
"package": {
"quantity": 3.0,
"package": {
"quantity": 100.0,
"unit_name": "g"
}
}
}
} - A pure string (use the package_description_str field):
{"package_description_str": "2 x 3 x 100 g"}Please, note that if you are going to use this field you must be consistent with the "package multipliers", i.e., we'll expect that all articles from all files have the format above and not something like "2/3/100g". Although we can interpret both, we must know a pattern beforehand.
- As a nested JSON (use the package_description field):
-
- Here's a list of available* units on our side:
-
- Mass:
- μg
- mg
- g
- kg
- tonne
- oz
- lb
- metric ton
- short ton
- long ton
- Volume:
- cm³ (use as cubic_centimeter)
- dm³ (use as cubic_decimeter)
- ft³ (use as cubic_foot)
- in³ (use as cubic_inch)
- m³ (use as cubic_meter)
- mm³ (use as cubic_milliliter)
- cup (UK)
- cup (US)
- fl oz (UK)
- fl oz (US)
- gal (UK)
- gal (US)
- l
- pt (UK)
- pt (US)
- qt (UK)
- qt (UK)
- tbsp (UK)
- tbsp (UK)
- tsp (UK)
- tsp (UK)
- DZ
- #10
- Piece:
- piece
- Mass:
-
- Here's a list of available* units on our side:
*Be aware that if you provide a different unit we'll try to fallback to piece.
Extended comments on nested packages
Imagine that you have a package which consists of a box (6) of wine bottles (750 ml). Lets deep dive into the package_description structure simulating the scenario where an individual bottle is orderable or not.
- Bottles are individually orderable
Since you have two orderable packages we need two items in the array. Each item will have the same shared_id but unique third_party_ids:
[
{
"third_party_id": "CS123456",
"shared_id": "123456",
"package_description": {
"quantity": 6.0,
"package": {
"quantity": 750.0,
"unit_name": "ml"
},
"gtin": "2698962595245"
},
...
},
{
"third_party_id": "EA123456",
"shared_id": "123456",
"package_description": {
"quantity": 750.0,
"unit_name": "ml",
"gtin": "6820540261525"
},
...
},
]This will generate two orderable packages: one that represents the whole box and other that represents the bottles.
- Bottles are not individually orderable
Without nested packages, you should provide only one item:
[
{
"third_party_id": "123456",
"package_description": {
"quantity": 6.0,
"package": {
"quantity": 750.0,
"unit_name": "ml"
},
"gtin": "2698962595245"
},
...
}
]There's no need to provide a value for shared_id either. This will generate a package for the whole box.
Response schema:
{"apic_id": string}
Response example:
{"apic_id": "466000210040001"}
GET /integrations/suppliers/files/
List information from all files for a given supplier integration. Check directly in the API here.
Filters:
- customer_number -> string equality;
- synced -> Possible values: 1 (the file wasn't synced yet), 2 (the file was partially synced) or 3 (the file was fully synced);
- created_at__lte -> Filter by creation date less or equal than (date time - ISO 8601 format);
- created_at__gte -> Filter by creation date greater or equal than (date time - ISO 8601 format).
Response schema:
{
"count": integer,
"next": integer | null,
"previous": integer | null,
"results": [
{
"apic_id": string,
"created_at": string, (date time - ISO 8601 format)
"customer_number": string | null,
"synced": integer (1 | 2 | 3)
}
]
}
Response example:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"apic_id": "466000210040001",
"created_at": "2022-05-10T02:00:00+02:00",
"customer_number": "23014",
"synced": 1
}
]
}
GET /integrations/suppliers/files/{apic_id}/
Retrieve information from a specific file. Check directly in the API here.
Response schema:
{
"apic_id": string,
"created_at": string,
"assortment_sync_id": string | null,
"synced": integer,
}
Get more info on the specific customer numbers configured for you as a supplier or get insights on the synchronization that took place for the assortments: