{ "openapi": "3.1.0", "info": { "title": "Click2Drop AMSped API", "version": "1.0.0", "description": "**AMSped** sends us its dropshippers' orders; our staff run them end to end \u2014 matching the products, checking the address, confirming to the warehouse \u2014 and the marketplace reads what became of each order by asking us. Nothing is pushed back: the marketplace polls.\n\nBase URL: `https://dev-v2.click2drop.eu/api/amsped/v1`\n\n## Authentication\n\nEvery request carries the connector token issued in our admin panel as a bearer token:\n\n```\nAuthorization: Bearer ams_live_xxxxxxxx_\u2026\nAccept: application/json\n```\n\nThe token is shown once, when it is issued, and can be replaced at any time; a missing, unknown or switched-off token answers **401**.\n\n## Whose order it is\n\nEvery call names the client the order belongs to with `supplier_code` \u2014 the store code we assigned when the client was connected (in the body of `POST /orders`, in the query string of `GET` and `DELETE`). An unknown or switched-off code answers **404** `unknown-supplier`.\n\n## The four calls\n\n| Call | Does |\n|---|---|\n| `POST /orders` | Records an order and answers with our order number (the platform's own format, e.g. `PL210926-F3RH`), which the order keeps for good \u2014 unless a correction or an address fix has to replace an order already at the warehouse: the replacement is a new order with a new number of ours, and `GET` under the same `order_number` answers with it (the history keeps both). The same `order_number` for the same `supplier_code` sent again answers **200** with the existing order \u2014 never recorded twice, so a retry is always safe. To correct an order, send it again under the same `order_number` with the corrected content: our team takes the correction over. After a withdrawal, the same number with changed content is recorded as a new order (**201**). |\n| `GET /orders/{order_number}?supplier_code=` | The order's status in our vocabulary, what it waits for, its shipments with parcels and carrier scans, and one merged history, oldest first \u2014 each entry an `event` code and a short `note` (a label such as `Held: address problem`). |\n| `DELETE /orders/{order_number}?supplier_code=` | Withdraws the order (**200**, also when already withdrawn): an order not yet placed is rejected, a placed one is cancelled and released at the warehouse. Once the parcel has left the warehouse **409** `already-shipped`; any other reason we cannot withdraw answers **409** `not-cancellable` with `status_now`. |\n| `POST /addresses/check` | The same address check an order goes through, ahead of time: problems that would stop the order, warnings that would not, and the normalised address. Send the optional `supplier_code` to also check that the supplier has a courier for the country (see Couriers below). |\n\n## Statuses\n\n`received` \u2192 `needs_review` (a product we could not match, or a person has to confirm) / `address_problem` / `waiting_for_stock` \u2192 `confirmed` \u2192 `at_warehouse` \u2192 `shipped` \u2192 `in_transit` \u2192 `delivered` (or `returned`); `cancelled` (withdrawn after it was placed), `rejected` (withdrawn or refused before). While waiting for stock the answer names the products and the missing quantities under `waiting_for`; while a person has to look, `problems` says what.\n\n## Couriers\n\nWhich couriers deliver a supplier's orders, and to which countries, is set up on our side per supplier. Until a courier is set up for a country:\n\n- `POST /addresses/check` with `supplier_code` returns the problem `no_courier` on `country_code` (without `supplier_code` the check only tells whether we deliver to the country at all: `country_not_served`);\n- an order to that country is still **accepted** (201): it is read as `needs_review`, with the problem `no.courier` under `problems`;\n- as soon as a courier is set up for the country, the order goes on by itself \u2014 nothing to send again.\n\n## Polling\n\nRead an order's status every 15 minutes or so; nothing changes faster than the warehouse works. Requests are limited per token \u2014 a **429** carries `Retry-After` with the seconds to wait \u2014 and polling every open order every minute would hit it.\n\n## Errors\n\nEvery error is an RFC 9457 problem-details document (`application/problem+json`):\n\n```json\n{\n \"type\": \"https://dev-v2.click2drop.eu/docs/amsped/errors/unknown-supplier\",\n \"title\": \"Unknown supplier\",\n \"status\": 404,\n \"detail\": \"Supplier code [X] is not known on this account.\",\n \"request_id\": \"\u2026\"\n}\n```\n\n`type` is stable \u2014 switch on it in code. The types this door answers with: `unknown-supplier` (404), `unknown-order` (404), `supplier-disconnected` (410 \u2014 the code takes no new orders; its existing orders stay readable), `already-shipped` and `not-cancellable` (409), `validation` (422), `rate-limited` (429). Validation errors carry `errors` per field. Quote the `request_id` when you write to us.\n" }, "servers": [ { "url": "https://dev-v2.click2drop.eu/api/amsped" } ], "security": [ { "http": [] } ], "paths": { "/v1/addresses/check": { "post": { "operationId": "amsped.addresses.check", "description": "The same check an order goes through before the warehouse: `problems`\nwould stop the order (fix them before sending), `warnings` would not,\nand `normalised` is the address the way we would store it.\n\nWith `supplier_code` it also checks that the supplier's store has a\ncourier switched on for the country: `no_courier` when it has none.\nThat one is not the address's fault \u2014 an order sent now is accepted\nand waits (`needs_review`) until a courier is switched on, then goes\non by itself. Without `supplier_code` only the platform as a whole is\nchecked (`country_not_served`).", "summary": "Check an address", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmspedAddressRequest" } } } }, "responses": { "200": { "description": "Checked", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "problems": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "code", "message" ] } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "code", "message" ] } }, "normalised": { "type": "object", "additionalProperties": {} } }, "required": [ "valid", "problems", "warnings", "normalised" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "description": "Unknown supplier code", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "410": { "description": "Supplier code disconnected \u2014 it takes no new orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "401": { "description": "The token is missing, unknown or switched off", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders": { "post": { "operationId": "amsped.orders.store", "description": "Records the order for the client behind `supplier_code` and answers\nwith our id. The same `order_number` sent again for the same supplier\nis answered with the existing order (200), never recorded twice. The\norder is then matched, checked and \u2014 once the desk confirms it \u2014\nplaced at the warehouse; poll `GET /orders/{order_number}` for its\nstatus.\n\nTo correct an order, send it again under the same `order_number` with\nthe corrected content: our team takes the correction over \u2014 before the\nwarehouse has the order it is updated, after that our team cancels and\nre-sends it while the parcel has not left. After a withdrawal the same\nnumber with changed content is recorded as a new order (201).", "summary": "Send an order", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmspedOrderRequest" } } } }, "responses": { "200": { "description": "Already known", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "received_at": { "type": [ "string", "null" ] } }, "required": [ "id", "order_number", "status", "received_at" ] } }, "required": [ "data" ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "errors", "request_id" ] } } } }, "201": { "description": "Recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "received_at": { "type": [ "string", "null" ] } }, "required": [ "id", "order_number", "status", "received_at" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Unknown supplier code", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "410": { "description": "Supplier code disconnected \u2014 it takes no new orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The token is missing, unknown or switched off", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/{orderNumber}": { "get": { "operationId": "amsped.orders.show", "description": "The order's status in our vocabulary (`received`, `needs_review`,\n`address_problem`, `waiting_for_stock`, `confirmed`, `at_warehouse`,\n`shipped`, `in_transit`, `delivered`, `returned`, `cancelled`,\n`rejected`), what it waits for, its shipments with parcels and\ncarrier scans, and one merged history, oldest first.", "summary": "Get an order's tracking history", "parameters": [ { "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "supplier_code", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_number": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string" }, "status_since": { "type": [ "string", "null" ] }, "received_at": { "type": [ "string", "null" ] }, "confirmed_at": { "type": [ "string", "null" ] }, "placed_at": { "type": [ "string", "null" ] }, "waiting_for": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "variant_id": { "type": "integer" }, "missing_quantity": { "type": "integer" } }, "required": [ "variant_id", "missing_quantity" ] } }, "problems": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "platform_order_number": { "type": [ "string", "null" ] }, "shipments": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "number": { "type": "string" }, "status": { "type": "string" }, "warehouse_reference": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "parcels": { "type": "array", "items": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "shipped_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } }, "required": [ "at", "status", "location", "note" ] } } }, "required": [ "tracking_number", "carrier", "status", "shipped_at", "delivered_at", "events" ] } } }, "required": [ "number", "status", "warehouse_reference", "carrier", "service", "parcels" ] } }, "history": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "at", "event", "note" ] } } }, "required": [ "order_number", "id", "status", "status_since", "received_at", "confirmed_at", "placed_at", "waiting_for", "problems", "platform_order_number", "shipments", "history" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "description": "Unknown order or supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The token is missing, unknown or switched off", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } }, "delete": { "operationId": "amsped.orders.destroy", "description": "Before the parcel leaves the warehouse the order is cancelled (200);\nonce it has shipped it cannot be (409) \u2014 the tracking says where it\nis. Withdrawing an order already withdrawn is answered 200 again.", "summary": "Withdraw an order", "parameters": [ { "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "supplier_code", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "reason", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } } ], "responses": { "200": { "description": "Withdrawn", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_number": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "order_number", "id", "status" ] } }, "required": [ "data" ] } } } }, "409": { "description": "Already shipped", "content": { "application/problem+json": { "schema": { "type": "array", "items": {} } }, "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" }, "status_now": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id", "status_now" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "description": "Unknown order or supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The token is missing, unknown or switched off", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "The connector token issued in our admin panel: `Authorization: Bearer ams_live_\u2026`", "scheme": "bearer" } }, "schemas": { "AmspedAddressRequest": { "type": "object", "description": "The body of POST /api/amsped/v1/addresses/check \u2014 a recipient block, as\nit would be sent with an order.", "properties": { "supplier_code": { "type": [ "string", "null" ], "description": "Optional: with it the check also asks whether this supplier's\nstore has a courier switched on for the country.", "maxLength": 64 }, "first_name": { "type": [ "string", "null" ], "maxLength": 100 }, "last_name": { "type": [ "string", "null" ], "maxLength": 100 }, "street": { "type": [ "string", "null" ], "maxLength": 200 }, "house_number": { "type": [ "string", "null" ], "maxLength": 20 }, "apartment": { "type": [ "string", "null" ], "maxLength": 20 }, "city": { "type": [ "string", "null" ], "maxLength": 100 }, "zip": { "type": [ "string", "null" ], "maxLength": 20 }, "province_code": { "type": [ "string", "null" ], "maxLength": 10 }, "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "The same rules as the order's recipient: a check that passes\nmust not turn into a 422 on the order.", "maxLength": 255 }, "notes": { "type": [ "string", "null" ], "maxLength": 39 } }, "required": [ "country_code" ], "title": "AmspedAddressRequest" }, "AmspedOrderRequest": { "type": "object", "description": "The body of POST /api/amsped/v1/orders \u2014 the contract the platform\ndefines and the marketplace fills.", "properties": { "order_number": { "type": "string", "maxLength": 64 }, "supplier_code": { "type": "string", "maxLength": 64 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "price": { "type": "number", "minimum": 0 }, "cod": { "type": "boolean" }, "cod_amount": { "type": [ "number", "null" ] }, "sender": { "type": "object", "properties": { "company": { "type": [ "string", "null" ], "maxLength": 200 }, "first_name": { "type": [ "string", "null" ], "maxLength": 100 }, "last_name": { "type": [ "string", "null" ], "maxLength": 100 }, "street": { "type": [ "string", "null" ], "maxLength": 200 }, "house_number": { "type": [ "string", "null" ], "maxLength": 20 }, "city": { "type": [ "string", "null" ], "maxLength": 100 }, "zip": { "type": [ "string", "null" ], "maxLength": 20 }, "province_code": { "type": [ "string", "null" ], "maxLength": 10 }, "country_code": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "vat_id": { "type": [ "string", "null" ], "maxLength": 40 } } }, "recipient": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "street": { "type": "string", "maxLength": 200 }, "house_number": { "type": [ "string", "null" ], "maxLength": 20 }, "apartment": { "type": [ "string", "null" ], "maxLength": 20 }, "city": { "type": "string", "maxLength": 100 }, "zip": { "type": "string", "maxLength": 20 }, "province_code": { "type": [ "string", "null" ], "maxLength": 10 }, "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "notes": { "type": [ "string", "null" ], "maxLength": 39 } }, "required": [ "first_name", "last_name", "street", "city", "zip", "country_code", "phone" ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "maxLength": 128 }, "variation": { "type": [ "string", "null" ], "maxLength": 128 }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "unit_price": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "sku", "quantity" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "order_number", "supplier_code", "currency", "price", "cod", "recipient", "products" ], "title": "AmspedOrderRequest" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }