Connect via REST API

Это содержимое пока не доступно на вашем языке.

If your system can make an HTTPS request, the REST API is the most direct way to send orders to SamVertex. You POST each order as JSON, we reply with a receipt, and the order lands in your Needs review list.

Endpoint and authentication

POST https://api.samvertex.com/ingest/orders
Authorization: Bearer <your api key>
Content-Type: application/json

Your API key identifies your account. Issue one yourself in the portal Integrations card, or ask the SamVertex team to issue one for you. Treat the key like a password: it is shown once when created and cannot be retrieved later, only replaced.

The order body

The body is one JSON object. The only required field is source_order_id, your own unique id for the order, which we use to avoid creating the same order twice. Everything else is best effort: send what you have.

{
  "source_order_id": "string",
  "order_number": "string",
  "customer": { "name": "string", "phone": "string", "email": "string", "id": "string" },
  "address": "string",
  "emirate": "string",
  "area": "string",
  "items": [ { "name": "string", "quantity": 1, "sku": "string" } ],
  "total": "number or string",
  "currency": "string",
  "delivery_instructions": "string"
}

Field by field:

source_order_id (required). Your unique id for the order. The same value is how we deduplicate, so reuse it if you resend.
order_number (optional). A display reference shown on the order. If you omit it, we use source_order_id.
customer (optional object). name, phone, email, and your own customer id. Phone matters most; the driver uses it on arrival.
address (optional). The full delivery address as one string.
emirate (optional). The Emirate, for routing.
area (optional). The area or district within the Emirate.
items (optional array). Each item is { name, quantity, sku }. sku may be null.
total (optional). The order total, as a number or a string.
currency (optional). Defaults to AED if omitted.
delivery_instructions (optional). Free text the driver sees, for example a gate code or a drop note.

The receipt

A successful POST returns 202 with a receipt id:

{ "receipt_id": "b7c1f2a0-..." }

The 202 means we accepted the order for processing, not that the SamVertex order is written yet; a background worker does that within moments. Keep the receipt_id if you want to check the result.

Idempotency

To make a retry safe, send an Idempotency-Key header with a value unique to that order:

Idempotency-Key: <your unique key>

If you POST the same key twice, we return the original receipt and do not create a second order:

{ "receipt_id": "b7c1f2a0-...", "duplicate": true }

Sending the same source_order_id again, even without the header, also will not create a duplicate order.

Check the status

Look up any receipt with your Bearer key:

GET https://api.samvertex.com/ingest/status/<receipt_id>
Authorization: Bearer <your api key>

{ "receipt_id": "b7c1f2a0-...", "status": "written", "order_id": 1234 }

The status moves through received, then normalized, then one of written (the order exists, order_id is set), duplicate (already sent), failed, or dead. See receipts, status, and errors for the full lifecycle and the error responses.

A full example

Create a key in the portal Integrations card and copy it.

POST the order:

curl -X POST https://api.samvertex.com/ingest/orders \
  -H "Authorization: Bearer $SVX_KEY" \
  -H "Idempotency-Key: order-9001" \
  -H "Content-Type: application/json" \
  -d '{
    "source_order_id": "9001",
    "order_number": "WEB-9001",
    "customer": { "name": "Lina K", "phone": "+9715XXXXXXXX" },
    "address": "Marina Gate 1, Dubai Marina, Dubai",
    "emirate": "Dubai",
    "items": [ { "name": "Serum 30ml", "quantity": 1, "sku": "SRM-30" } ],
    "total": "180",
    "currency": "AED"
  }'

Read the receipt from the response, then confirm the order on your Needs review list in the portal.