Ankorstore Catalog Integrations API
## 👋 Getting Started The catalogue integration process relies on the concept of operations. An operation is a batch of records representing the products to create, update or delete. The completion state of an operation depends on the execution result for every record it contains. It means an operation might fail without necessarily stopping or marking the whole operation as failed (this particular state is defined as “Partially failed”). - Operations can be of type `import`, `update` or `delete`. - Only one open operation (not yet started) is allowed at a time. - Only one operation can be performed (`started`) at a time. - Any subsequent operation will be queued with status `pending` until previous one has finished processing. - If no previous operation is being processed, operation will start processing right away. ### Operation Statuses The `status` attribute represents the current state of the operation, below is a table that describes each state: | Status | Description | |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `created` | The operation was created and not yet started. At this stage, the operation is considered open and products can still be added to the batch. | | `skipped` | The operation is empty and was skipped (No action required). When an operation is skipped, an empty report is generated and the callback URL is called to notify operation is completed. | | `started` | The operation started and is processing. | | `pending` | Operation is waiting for its turn on the processing queue. The operation could not be started because another one was being processed. | | `succeeded` | All products were successfully processed. | | `failed` | All products failed to be processed. | | `partially_failed` | Not all products were successfully processed. | ## 💡 Operation workflow The complete workflow for an operation occurs in 3 stages: operation creation, operation processing and reporting. The following diagram illustrates these stages and how they are chained. %%{init: {"flowchart": {"curve":"basis", "htmlLabels":false, "diagramPadding":24 } } }%% graph LR created("Operation Created") start("Start Processing") started("Processing\nStarted") succeeded(Succeeded):::success skipped("Processing Skipped"):::success pending("Operation pending") failed(Failed):::failure partial(Partially Failed):::warning report("Report\nGenerated") notified(Callback Sent) subgraph creating[Creating Operation] created -- Add Products --> created end created -- Start Operation --> Start{?} Start -->|"Another Operation execution in progress"| pending Start --->|"No other Operation in progress"| start --> E{?} E -->|"Batch.size > 0"| processing E --->|"Batch is empty"| skipped subgraph processing[Processing Operation] direction LR started --> succeeded started --> partial started --> failed end succeeded --> operationCompletedActions partial --> operationCompletedActions failed --> operationCompletedActions subgraph reporting[Reporting] report -- Notify --> notified end subgraph triggerNext[Trigger next pending Operation] end subgraph operationCompletedActions[Post-Complete Operation Actions] reporting triggerNext end pending -- Wait for previous Operation to finish execution --> start skipped -- Generate empty report --> operationCompletedActions classDef default stroke:#4b475f,stroke-width:1px,fill:#ffffff,color:#4b475f classDef success stroke:#1aae9f,stroke-width:1px,fill:#cfeeeb,color:#293845 classDef failure stroke:#d3455b,stroke-width:1px,fill:#f6d8dd,color:#293845 classDef warning stroke:#f7c325,stroke-width:1px,fill:#fdf2d1,color:#293845 linkStyle default stroke:#788896,stroke-width:1px,fill:transparent ### Creating an Operation The full flow of creating a complete operation consists in two steps: #### 1. Create a new operation Send a `POST` request to `/api/v1/catalog/integrations/operations` Example request: ```json { "data": { "type": "catalog-integration-operation", "attributes": { "source": "shopify", "callbackUrl": "https://callback.url/called/after/processing", "operationType": "import" } } } ``` - At this point the new operation has been created and waiting to receive products data - Operation ID will be returned in the response payload #### 2. Add product data to operation Send a `POST` request to `/api/v1/catalog/integrations/operations/{operationId}/products` Products can be added only to operations with status `created`. If operation has been started already (having any of `started`, `pending`, `skipped`, `succeeded`, `partially_failed`, `failed`, `cancelled` status), the request will fail with a `403 Forbidden` status code. Example request: ```json { "products": [ { "id": "B006GWO5WK", "type": "catalog-integration-product", "attributes": { "external_id": "B006GWO5WK", "name": "Example product" // ... } } ] } ``` You can perform as many requests as needed to append product data during this stage. ### Operation Processing In order to start processing the operation, you have to send a `PATCH` request to `/api/v1/catalog/integrations/operations/{operationId}` with the expected operation status (i.e. “started”). If there is any other operation being executed at that time, the operation will be enqueued to be processed with the status `pending` and will be started as soon as it gets a free slot in the queue. Otherwise, the operation will be started right away. Example request: ```json { "data": { "id": "90567710-de47-49e4-8536-aab80c1a469c", "type": "catalog-integration-operation", "attributes": { "status": "started" } } } ``` ### Execution Report When an operation completes, an execution report is generated. It provides the execution results (success or failure) for every product of the operation. You can access this report by reading from the following endpoint. ```http GET /api/v1/catalog/integrations/operations/{operationId}/results ``` ## 💡 Event Callbacks Callbacks enable you to get notified when events occur in the operation process. For example, you can configure a callback to notify you when the operation is completed. The notification is sent via an HTTP request to the URL you specify in the operation settings. Callbacks can be used to trigger automated actions in your integration. ### Supported events You can find here below the complete list of all the topics `{{resource}}.{{event}}` you can monitor: | Topic | Trigger | |-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `catalog-integration-operation.completed` | An operation reaches a completed state such as **Success**, **Failed**, or **Partially Failed** | | `catalog-integration-operation.cancelled` | An operation was cancelled. This event is triggered when an operation processing is **Skipped** (i.e. the operation batch is empty and no action is required). | ### Event schema A callback event is represented as a JSON object and has the following properties: - `event` — the name of the event that occurred (e.g. “completed”) - `topic` — the event category represented as a unique identifier of the event type. The topic is defined as a concatenation of the resource and event names `{$.data.type}.{$.event}`, e.g. “catalog-integration-operation.completed”. You might use this topic as a partition key to distribute the callback events you receive to separate queues or pools of workers to process the callbacks asynchronously. - `occurredAt` — the date and time when the event occurred - `data` — the JSON:API resource describing the state of the entity which triggered the callback A callback event is delivered as a `POST` request to your endpoint. The following payload represents the notification request that is triggered when an operation successfully completes: ```json { "event": "completed", "topic": "catalog-integration-operation.completed", "occurredAt": "2024-03-21T13:42:54+00:00", "data": { "id": "90567710-de47-49e4-8536-aab80c1a469c", "type": "catalog-integration-operation", "attributes": { // ... "status": "succeeded", "createdAt": "2024-03-21T13:13:03+00:00", "startedAt": "2024-03-21T13:19:32+00:00", "completedAt": "2024-03-21T13:42:54+00:00" // ... } } } ``` ### Handling callbacks The endpoint listening for callbacks has **3 seconds** to respond with a `2xx` (usually `200`) response code, acknowledging a successful delivery. If the request times out or gets a response with a status code other than `2xx`, it is considered failed. #### Handling webhook failures If a callback fails (whatever the reason) no further calls to the related endpoint are made. ### Testing callback A number of websites, such as https://webhook.site and https://requestbin.com, provide free URLs that can be used to test callbacks. Simply create a URL on one of these sites, then configure your webhook to use it. These sites allow you to see the details of the request sent to them by the callback service. In addition, the Ngrok service (https://ngrok.com) allows you to tunnel callback requests to a non-publicly accessible server, enabling you to test your callback-handling code before making it public. ### Operations and Drafts behaviour | Type | Behaviour | |----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `import` | When executing an import operation existing drafts will be cleaned and new ones will be created if any of the products attached to the operation has any validation issue. | | `update` | Will not have any impact on existing drafts. | | `delete` | Will not have any impact on existing drafts. |