{"openapi": "3.0.3", "info": {"title": "Yaqin Carrier API", "version": "1.0.0", "description": "The Yaqin Carrier API lets a shipping company receive the shipments that merchants on Yaqin ERP (yaqinerp.com) send it, and report back on them.\n\n**Flow**\n1. `POST /oauth/token` with your client id and secret → an access token (1 hour).\n2. `GET /shipments?state=new` → shipments waiting for you (or receive the `shipment.created` webhook).\n3. `POST /shipments/{id}/accept` with your tracking number (and `label_url`), or `POST /shipments/{id}/reject` with a reason.\n4. `POST /shipments/{id}/events` for every status change: PICKED_UP … OUT_FOR_DELIVERY … DELIVERED (with proof of delivery).\n5. `POST /cod-remittances` when you pay the merchants the cash you collected.\n\n**Environments** — sandbox credentials (`yq_test_…`) see only shipments from Yaqin's test companies; live credentials (`yq_live_…`) open when Yaqin approves your account.\n\n**Rules** — JSON (UTF-8); times ISO 8601 with time zone; 120 calls a minute per client; send an `Idempotency-Key` header on POST so a retry never does the work twice; paging with `next_cursor`.\n\n**Errors** — `{\"error\": {\"code\", \"message\", \"details\"}}` with 400, 401, 403, 404, 409 (wrong state), 422 (validation), 429, 500.\n\n**Webhooks (optional)** — give Yaqin a URL and we POST `shipment.created` and `shipment.cancelled`. Check `X-Yaqin-Signature: t=<unix time>,v1=<hex>` where v1 = HMAC-SHA256(webhook secret, `<t>.<raw body>`).\n\n**Statuses**\n\n| code | meaning | final |\n|---|---|---|\n| `NEW` | Sent by the merchant, waiting for the carrier to accept it |  |\n| `ACCEPTED` | Accepted by the carrier (set by POST /accept) |  |\n| `REJECTED` | Refused by the carrier (set by POST /reject) | yes |\n| `CANCELLED` | Cancelled by the merchant before pickup | yes |\n| `PICKUP_SCHEDULED` | Pickup planned with the merchant |  |\n| `PICKUP_FAILED` | The driver could not collect the parcel |  |\n| `PICKED_UP` | Collected from the merchant |  |\n| `AT_HUB` | At a hub / sorting centre |  |\n| `IN_TRANSIT` | On the way between cities or hubs |  |\n| `OUT_FOR_DELIVERY` | With the driver for delivery today |  |\n| `DELIVERY_ATTEMPT_FAILED` | Delivery tried and failed (add the reason in note) |  |\n| `ON_HOLD` | Held (address, payment, customer request…) |  |\n| `DELIVERED` | Delivered to the recipient (send proof_of_delivery) | yes |\n| `RETURN_IN_TRANSIT` | Coming back to the merchant |  |\n| `RETURNED` | Returned to the merchant | yes |\n| `LOST` | Lost | yes |\n| `DAMAGED` | Damaged | yes |", "contact": {"name": "VLUMU Digital — Yaqin", "url": "https://yaqinerp.com", "email": "support@yaqinerp.com"}}, "servers": [{"url": "https://app.yaqinerp.com/api/shipping/v1", "description": "Sandbox and live (the credentials decide)"}], "tags": [{"name": "Auth"}, {"name": "Reference"}, {"name": "Shipments"}, {"name": "COD"}], "components": {"securitySchemes": {"bearer": {"type": "http", "scheme": "bearer", "description": "Access token from POST /oauth/token"}}, "schemas": {"Shipment": {"type": "object", "properties": {"id": {"type": "string", "example": "shp_3f9a0c1b2d4e5f60"}, "reference": {"type": "string", "description": "the merchant's order number, print it on the label", "example": "yqdemosa-DN-2026-00012"}, "environment": {"type": "string", "enum": ["sandbox", "live"]}, "state": {"type": "string", "enum": ["new", "accepted", "rejected", "cancelled", "delivered", "returned", "failed"]}, "status": {"type": "string", "enum": ["NEW", "ACCEPTED", "REJECTED", "CANCELLED", "PICKUP_SCHEDULED", "PICKUP_FAILED", "PICKED_UP", "AT_HUB", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERY_ATTEMPT_FAILED", "ON_HOLD", "DELIVERED", "RETURN_IN_TRANSIT", "RETURNED", "LOST", "DAMAGED"]}, "status_at": {"type": "string", "format": "date-time"}, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}, "merchant": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "account_number": {"type": "string", "description": "the merchant's account with you"}}}, "sender": {"type": "object", "properties": {"name": {"type": "string"}, "phone": {"type": "string"}, "email": {"type": "string"}, "country": {"type": "string", "example": "SA"}, "city": {"type": "string", "example": "Riyadh"}, "district": {"type": "string"}, "street": {"type": "string"}, "address": {"type": "string"}, "building_number": {"type": "string"}, "postal_code": {"type": "string"}, "short_address": {"type": "string", "description": "Saudi national address short code, e.g. RHOD3474"}, "location": {"type": "object", "nullable": true, "properties": {"lat": {"type": "number"}, "lng": {"type": "number"}}}, "pickup_point": {"type": "string", "description": "sender only: the merchant's warehouse name"}}}, "recipient": {"type": "object", "properties": {"name": {"type": "string"}, "phone": {"type": "string"}, "email": {"type": "string"}, "country": {"type": "string", "example": "SA"}, "city": {"type": "string", "example": "Riyadh"}, "district": {"type": "string"}, "street": {"type": "string"}, "address": {"type": "string"}, "building_number": {"type": "string"}, "postal_code": {"type": "string"}, "short_address": {"type": "string", "description": "Saudi national address short code, e.g. RHOD3474"}, "location": {"type": "object", "nullable": true, "properties": {"lat": {"type": "number"}, "lng": {"type": "number"}}}, "pickup_point": {"type": "string", "description": "sender only: the merchant's warehouse name"}}}, "parcels": {"type": "object", "properties": {"count": {"type": "integer"}, "weight_kg": {"type": "number"}, "length_cm": {"type": "number"}, "width_cm": {"type": "number"}, "height_cm": {"type": "number"}}}, "items": {"type": "array", "items": {"type": "object", "properties": {"name": {"type": "string"}, "sku": {"type": "string"}, "quantity": {"type": "number"}, "unit_price": {"type": "number"}}}}, "value": {"type": "object", "properties": {"amount": {"type": "number"}, "currency": {"type": "string"}}}, "cash_on_delivery": {"type": "object", "nullable": true, "properties": {"amount": {"type": "number"}, "currency": {"type": "string"}}, "description": "null = already paid; otherwise collect this amount from the recipient"}, "description": {"type": "string"}, "notes": {"type": "string"}, "tracking_number": {"type": "string", "nullable": true}, "carrier_reference": {"type": "string", "nullable": true}, "label_url": {"type": "string", "nullable": true}, "estimated_delivery": {"type": "string", "nullable": true}, "reject_reason": {"type": "string", "nullable": true}, "cod": {"type": "object", "properties": {"amount": {"type": "number"}, "currency": {"type": "string"}, "collected": {"type": "number", "nullable": true}, "remitted": {"type": "number"}}}, "charges": {"type": "array", "items": {"$ref": "#/components/schemas/Charge"}}, "events": {"type": "array", "items": {"$ref": "#/components/schemas/Event"}, "description": "only on GET /shipments/{id}"}}}, "Party": {"type": "object", "properties": {"name": {"type": "string"}, "phone": {"type": "string"}, "email": {"type": "string"}, "country": {"type": "string", "example": "SA"}, "city": {"type": "string", "example": "Riyadh"}, "district": {"type": "string"}, "street": {"type": "string"}, "address": {"type": "string"}, "building_number": {"type": "string"}, "postal_code": {"type": "string"}, "short_address": {"type": "string", "description": "Saudi national address short code, e.g. RHOD3474"}, "location": {"type": "object", "nullable": true, "properties": {"lat": {"type": "number"}, "lng": {"type": "number"}}}, "pickup_point": {"type": "string", "description": "sender only: the merchant's warehouse name"}}}, "EventIn": {"type": "object", "required": ["status"], "properties": {"status": {"type": "string", "enum": ["PICKUP_SCHEDULED", "PICKUP_FAILED", "PICKED_UP", "AT_HUB", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERY_ATTEMPT_FAILED", "ON_HOLD", "DELIVERED", "RETURN_IN_TRANSIT", "RETURNED", "LOST", "DAMAGED"]}, "occurred_at": {"type": "string", "format": "date-time", "description": "when it happened (ISO 8601 with time zone); default = now"}, "note": {"type": "string", "description": "e.g. the reason of a failed attempt"}, "location": {"type": "object", "properties": {"city": {"type": "string"}, "district": {"type": "string"}, "hub": {"type": "string"}, "lat": {"type": "number"}, "lng": {"type": "number"}}}, "proof_of_delivery": {"type": "object", "description": "with DELIVERED", "properties": {"receiver_name": {"type": "string"}, "receiver_relation": {"type": "string"}, "photo_url": {"type": "string"}, "signature_url": {"type": "string"}, "otp_verified": {"type": "boolean"}}}, "cod_collected": {"type": "number", "description": "with DELIVERED on a COD shipment: the cash collected (default = the COD amount)"}}}, "Event": {"type": "object", "properties": {"status": {"type": "string"}, "occurred_at": {"type": "string", "format": "date-time"}, "note": {"type": "string", "nullable": true}, "location": {"type": "object", "nullable": true}, "proof_of_delivery": {"type": "object", "nullable": true}}}, "Charge": {"type": "object", "properties": {"type": {"type": "string", "example": "shipping"}, "amount": {"type": "number"}, "currency": {"type": "string"}, "description": {"type": "string"}, "at": {"type": "string"}}}, "Remittance": {"type": "object", "properties": {"reference": {"type": "string"}, "paid_at": {"type": "string", "format": "date"}, "currency": {"type": "string"}, "total": {"type": "number"}, "bank_reference": {"type": "string"}, "lines": {"type": "array", "items": {"type": "object", "properties": {"shipment_id": {"type": "string"}, "amount": {"type": "number"}}}}}}, "Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}, "details": {"type": "object"}}}}}}, "responses": {"BadRequest": {"description": "Bad request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "Unauthorized": {"description": "Missing / wrong / expired token", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "NotFound": {"description": "Not found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "Conflict": {"description": "Not allowed in the shipment's current state", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "Invalid": {"description": "Validation error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "TooMany": {"description": "Too many calls", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "security": [{"bearer": []}], "paths": {"/oauth/token": {"post": {"tags": ["Auth"], "summary": "Get an access token", "security": [], "description": "OAuth2 client credentials. Send JSON, a form, or HTTP Basic (client_id:client_secret).", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["client_id", "client_secret"], "properties": {"grant_type": {"type": "string", "example": "client_credentials"}, "client_id": {"type": "string"}, "client_secret": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"access_token": {"type": "string"}, "token_type": {"type": "string", "example": "Bearer"}, "expires_in": {"type": "integer", "example": 3600}, "environment": {"type": "string"}, "carrier": {"type": "string"}}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooMany"}}}}, "/ping": {"get": {"tags": ["Reference"], "summary": "Check the token", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}}}}, "/statuses": {"get": {"tags": ["Reference"], "summary": "The standard statuses", "security": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}}}}, "/shipments": {"get": {"tags": ["Shipments"], "summary": "List shipments sent to you", "parameters": [{"name": "state", "in": "query", "schema": {"type": "string"}, "example": "new", "description": "new, accepted, rejected, cancelled, delivered, returned, failed (comma separated)"}, {"name": "updated_since", "in": "query", "schema": {"type": "string", "format": "date-time"}}, {"name": "reference", "in": "query", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "cursor", "in": "query", "schema": {"type": "string"}, "description": "next_cursor of the previous page"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Shipment"}}, "has_more": {"type": "boolean"}, "next_cursor": {"type": "string", "nullable": true}}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "422": {"$ref": "#/components/responses/Invalid"}}}}, "/shipments/{id}": {"get": {"tags": ["Shipments"], "summary": "One shipment with its events", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "example": "shp_3f9a0c1b2d4e5f60"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Shipment"}}}}, "404": {"$ref": "#/components/responses/NotFound"}}}}, "/shipments/{id}/accept": {"post": {"tags": ["Shipments"], "summary": "Accept a new shipment", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "example": "shp_3f9a0c1b2d4e5f60"}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 100}, "description": "Any unique string (a UUID). Repeating a POST with the same key returns the first answer and does nothing twice."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["tracking_number"], "properties": {"tracking_number": {"type": "string"}, "label_url": {"type": "string", "description": "https link to the label PDF"}, "carrier_reference": {"type": "string"}, "estimated_delivery": {"type": "string", "example": "2026-11-10"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Shipment"}}}}, "409": {"$ref": "#/components/responses/Conflict"}, "422": {"$ref": "#/components/responses/Invalid"}}}}, "/shipments/{id}/reject": {"post": {"tags": ["Shipments"], "summary": "Refuse a new shipment", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "example": "shp_3f9a0c1b2d4e5f60"}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 100}, "description": "Any unique string (a UUID). Repeating a POST with the same key returns the first answer and does nothing twice."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["reason"], "properties": {"reason": {"type": "string", "example": "Out of our coverage area"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Shipment"}}}}, "409": {"$ref": "#/components/responses/Conflict"}, "422": {"$ref": "#/components/responses/Invalid"}}}}, "/shipments/{id}/label": {"post": {"tags": ["Shipments"], "summary": "Give or replace the label link", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "example": "shp_3f9a0c1b2d4e5f60"}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 100}, "description": "Any unique string (a UUID). Repeating a POST with the same key returns the first answer and does nothing twice."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["label_url"], "properties": {"label_url": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Shipment"}}}}, "409": {"$ref": "#/components/responses/Conflict"}, "422": {"$ref": "#/components/responses/Invalid"}}}}, "/shipments/{id}/events": {"get": {"tags": ["Shipments"], "summary": "The tracking history", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "example": "shp_3f9a0c1b2d4e5f60"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Event"}}}}}}}}}, "post": {"tags": ["Shipments"], "summary": "Report a status", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "example": "shp_3f9a0c1b2d4e5f60"}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 100}, "description": "Any unique string (a UUID). Repeating a POST with the same key returns the first answer and does nothing twice."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EventIn"}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object"}}}}, "409": {"$ref": "#/components/responses/Conflict"}, "422": {"$ref": "#/components/responses/Invalid"}}}}, "/shipments/{id}/charges": {"post": {"tags": ["Shipments"], "summary": "Report a charge (shipping, re-weigh, return, storage…)", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "example": "shp_3f9a0c1b2d4e5f60"}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 100}, "description": "Any unique string (a UUID). Repeating a POST with the same key returns the first answer and does nothing twice."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["amount"], "properties": {"type": {"type": "string", "example": "shipping"}, "amount": {"type": "number", "example": 25.3}, "currency": {"type": "string", "example": "SAR"}, "description": {"type": "string"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object"}}}}, "422": {"$ref": "#/components/responses/Invalid"}}}}, "/cod-remittances": {"get": {"tags": ["COD"], "summary": "Your COD payouts", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}}}, "post": {"tags": ["COD"], "summary": "Report a COD payout to merchants", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 100}, "description": "Any unique string (a UUID). Repeating a POST with the same key returns the first answer and does nothing twice."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Remittance"}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Remittance"}}}}, "409": {"$ref": "#/components/responses/Conflict"}, "422": {"$ref": "#/components/responses/Invalid"}}}}}}