Ankorstore Catalog Integrations API

## 👋 Getting StartedThe catalogue integration process relies on the concept of operations. An operation is a batch of recordsrepresenting the products to create, update or delete. The completion state of an operation dependson the execution result for every record it contains. It means an operation might fail without necessarilystopping 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 finishedprocessing. - If no previous operation is being processed, operation will start processing right away.### Operation StatusesThe `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 workflowThe 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 LRcreated("Operation Created")start("Start Processing")started("Processing\nStarted")succeeded(Succeeded):::successskipped("Processing Skipped"):::successpending("Operation pending")failed(Failed):::failurepartial(Partially Failed):::warningreport("Report\nGenerated")notified(Callback Sent)subgraph creating[Creating Operation]created -- Add Products --> createdendcreated -- Start Operation --> Start{?}Start -->|"Another Operation execution in progress"| pendingStart --->|"No other Operation in progress"| start --> E{?}E -->|"Batch.size > 0"| processingE --->|"Batch is empty"| skippedsubgraph processing[Processing Operation]direction LRstarted --> succeededstarted --> partialstarted --> failedendsucceeded --> operationCompletedActionspartial --> operationCompletedActionsfailed --> operationCompletedActionssubgraph reporting[Reporting]report -- Notify --> notifiedendsubgraph triggerNext[Trigger next pending Operation]endsubgraph operationCompletedActions[Post-Complete Operation Actions]reportingtriggerNextendpending -- Wait for previous Operation to finish execution --> startskipped -- Generate empty report --> operationCompletedActionsclassDef default stroke:#4b475f,stroke-width:1px,fill:#ffffff,color:#4b475fclassDef success stroke:#1aae9f,stroke-width:1px,fill:#cfeeeb,color:#293845classDef failure stroke:#d3455b,stroke-width:1px,fill:#f6d8dd,color:#293845classDef warning stroke:#f7c325,stroke-width:1px,fill:#fdf2d1,color:#293845linkStyle default stroke:#788896,stroke-width:1px,fill:transparent### Creating an OperationThe full flow of creating a complete operation consists in two steps:#### 1. Create a new operationSend 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 operationSend 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 ProcessingIn order to start processing the operation, you have to send a `PATCH` requestto `/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 processedwith the status `pending` and will be started as soon as it gets a free slot in the queue. Otherwise, theoperation will be started right away.Example request:```json{ "data": { "id": "90567710-de47-49e4-8536-aab80c1a469c", "type": "catalog-integration-operation", "attributes": { "status": "started" } }}```### Execution ReportWhen 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.```httpGET /api/v1/catalog/integrations/operations/{operationId}/results```## 💡 Event CallbacksCallbacks enable you to get notified when events occur in the operation process. For example, you canconfigure a callback to notify you when the operation is completed. The notification is sent viaan HTTP request to the URL you specify in the operation settings.Callbacks can be used to trigger automated actions in your integration.### Supported eventsYou 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 schemaA 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 callbacksasynchronously. - `occurredAt` — the date and time when the event occurred- `data` — the JSON:API resource describing the state of the entity which triggered the callbackA callback event is delivered as a `POST` request to your endpoint. The following payload represents the notificationrequest 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 callbacksThe 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 responsewith a status code other than `2xx`, it is considered failed.#### Handling webhook failuresIf a callback fails (whatever the reason) no further calls to the related endpoint are made.### Testing callbackA number of websites, such as https://webhook.site and https://requestbin.com, provide free URLs thatcan be used to test callbacks. Simply create a URL on one of these sites, then configure your webhookto 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-publiclyaccessible 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. |