{"openapi":"3.1.0","info":{"title":"ae.delivery API","version":"2026-09-25","description":"Shipment-centric REST API. Test keys (aed_test_sk_…) never send, never bill and never reach a real rider. Money is integer fils."},"servers":[{"url":"https://api.ae.delivery/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"aed_(test|live)_sk_…"}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"title_ar":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"request_id":{"type":"string"}},"required":["type","title","status","code"]}}},"paths":{"/quotes":{"post":{"summary":"Quote a price, promised date and serviceability","tags":["Quotes"],"security":[{"bearer":["quotes:write"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"description":"Required for tenant keys; ignored for merchant keys","type":"string"},"service":{"default":"next_day","type":"string","enum":["next_day","same_day","scheduled","express","return_pickup"]},"payment_type":{"default":"prepaid","type":"string","enum":["prepaid","cod","card_on_delivery","pay_by_link"]},"cod_amount":{"default":0,"type":"integer","minimum":0,"maximum":100000000,"description":"Integer fils (AED 1.00 = 100)"},"pickup_location_id":{"type":"string"},"destination":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":500,"description":"The address exactly as entered, in its original language"},"emirate":{"type":"string","enum":["AUH","DXB","SHJ","AJM","UAQ","RAK","FUJ"]},"area":{"description":"Area/community name (EN or AR) or a gazetteer id like shj-al-nahda","type":"string","maxLength":120},"street":{"type":"string","maxLength":200},"building":{"type":"string","maxLength":120},"floor":{"type":"string","maxLength":20},"unit":{"type":"string","maxLength":40},"landmark":{"type":"string","maxLength":200},"lat":{"type":"number","minimum":22,"maximum":27},"lng":{"type":"number","minimum":51,"maximum":57},"pin_source":{"type":"string","enum":["receiver","merchant","geocoder","rider","makani"]},"makani":{"type":"string","pattern":"^\\d{5}\\s?\\d{5}$"}}},"ready_for_pickup_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}}}}}}},"/shipments":{"post":{"summary":"Create a shipment (or a draft)","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["shipment"]},"livemode":{"type":"boolean"},"tracking_number":{"type":"string"},"tracking_url":{"type":"string"},"merchant_reference":{"type":"string"},"status":{"type":"string"},"sub_status":{"nullable":true,"type":"string"},"status_label":{"type":"object","properties":{"en":{"type":"string"},"ar":{"type":"string"}},"required":["en","ar"]},"service":{"type":"string","enum":["next_day","same_day","scheduled","express","return_pickup"]},"payment_type":{"type":"string","enum":["prepaid","cod","card_on_delivery","pay_by_link"]},"cod_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee":{"type":"object","properties":{"net":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vat":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"gross":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vat_basis":{"type":"string"}},"required":["net","vat","gross","vat_basis"]},"promised_date":{"nullable":true,"type":"string"},"window":{"nullable":true,"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cod_state":{"type":"string"},"pod_state":{"type":"string"},"reconciliation_state":{"type":"string"},"receiver":{"nullable":true,"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"language":{"type":"string"}},"required":["name","phone","language"]},"address":{"type":"object","properties":{"text":{"type":"string"},"emirate":{"nullable":true,"type":"string"},"area":{"nullable":true,"type":"string"},"area_ar":{"nullable":true,"type":"string"},"lat":{"nullable":true,"type":"number"},"lng":{"nullable":true,"type":"number"},"pin_source":{"nullable":true,"type":"string"}},"required":["text","emirate","area","area_ar","lat","lng","pin_source"]},"pieces":{"type":"array","items":{"type":"object","properties":{"barcode":{"type":"string"}},"required":["barcode"]}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","livemode","tracking_number","tracking_url","merchant_reference","status","sub_status","status_label","service","payment_type","cod_amount","fee","promised_date","window","attempts","cod_state","pod_state","reconciliation_state","receiver","address","pieces","metadata","created_at","updated_at"]}}}},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"description":"Required for tenant keys; ignored for merchant keys","type":"string"},"merchant_reference":{"type":"string","minLength":1,"maxLength":64,"description":"Your order id; unique per merchant; echoed everywhere"},"service":{"default":"next_day","type":"string","enum":["next_day","same_day","scheduled","express","return_pickup"]},"payment_type":{"type":"string","enum":["prepaid","cod","card_on_delivery","pay_by_link"]},"cod_amount":{"default":0,"type":"integer","minimum":0,"maximum":100000000,"description":"Integer fils (AED 1.00 = 100)"},"declared_value":{"type":"integer","minimum":0,"maximum":100000000,"description":"Integer fils (AED 1.00 = 100)"},"quote_id":{"type":"string"},"pickup_location_id":{"type":"string"},"ready_for_pickup_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"requested_delivery_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date in Asia/Dubai"},"receiver":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"phone":{"type":"string","minLength":7,"maxLength":20,"description":"UAE mobile; normalised to E.164"},"alt_phone":{"type":"string","minLength":7,"maxLength":20},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"language":{"default":"ar","type":"string","enum":["ar","en"]}},"required":["name","phone"]},"address":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":500,"description":"The address exactly as entered, in its original language"},"emirate":{"type":"string","enum":["AUH","DXB","SHJ","AJM","UAQ","RAK","FUJ"]},"area":{"description":"Area/community name (EN or AR) or a gazetteer id like shj-al-nahda","type":"string","maxLength":120},"street":{"type":"string","maxLength":200},"building":{"type":"string","maxLength":120},"floor":{"type":"string","maxLength":20},"unit":{"type":"string","maxLength":40},"landmark":{"type":"string","maxLength":200},"lat":{"type":"number","minimum":22,"maximum":27},"lng":{"type":"number","minimum":51,"maximum":57},"pin_source":{"type":"string","enum":["receiver","merchant","geocoder","rider","makani"]},"makani":{"type":"string","pattern":"^\\d{5}\\s?\\d{5}$"}},"required":["text"]},"parcel":{"default":{"pieces":1,"flags":[]},"type":"object","properties":{"description":{"type":"string","maxLength":300},"pieces":{"default":1,"type":"integer","minimum":1,"maximum":50},"weight_grams":{"type":"integer","minimum":1,"maximum":100000},"size_class":{"type":"string","enum":["S","M","L","XL"]},"flags":{"default":[],"type":"array","items":{"type":"string","enum":["fragile","perishable","cold_chain","age_check_18","age_check_21","pharmacy","high_value","dangerous_goods","id_required","open_box_inspection_allowed"]}}}},"notes":{"type":"string","maxLength":500},"consent":{"type":"object","properties":{"channels":{"minItems":1,"type":"array","items":{"type":"string","enum":["whatsapp","sms","email"]}},"wording":{"type":"string","minLength":10,"maxLength":1000,"description":"The exact wording the receiver agreed to; it must name the delivery company"},"captured_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"source":{"type":"string","maxLength":80}},"required":["channels","wording","captured_at","source"]},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500}},"draft":{"default":false,"type":"boolean"},"exchange":{"description":"Exchange: also collect an item from the receiver at the same stop (creates a linked return pickup)","type":"object","properties":{"description":{"type":"string","maxLength":300},"pieces":{"default":1,"type":"integer","minimum":1,"maximum":50}}}},"required":["merchant_reference","payment_type","receiver","address"]}}}}},"get":{"summary":"List shipments (cursor pagination)","tags":["Shipments"],"security":[{"bearer":["shipments:read"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/shipments/{id}":{"get":{"summary":"Retrieve a shipment","tags":["Shipments"],"security":[{"bearer":["shipments:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["shipment"]},"livemode":{"type":"boolean"},"tracking_number":{"type":"string"},"tracking_url":{"type":"string"},"merchant_reference":{"type":"string"},"status":{"type":"string"},"sub_status":{"nullable":true,"type":"string"},"status_label":{"type":"object","properties":{"en":{"type":"string"},"ar":{"type":"string"}},"required":["en","ar"]},"service":{"type":"string","enum":["next_day","same_day","scheduled","express","return_pickup"]},"payment_type":{"type":"string","enum":["prepaid","cod","card_on_delivery","pay_by_link"]},"cod_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee":{"type":"object","properties":{"net":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vat":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"gross":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vat_basis":{"type":"string"}},"required":["net","vat","gross","vat_basis"]},"promised_date":{"nullable":true,"type":"string"},"window":{"nullable":true,"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cod_state":{"type":"string"},"pod_state":{"type":"string"},"reconciliation_state":{"type":"string"},"receiver":{"nullable":true,"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"language":{"type":"string"}},"required":["name","phone","language"]},"address":{"type":"object","properties":{"text":{"type":"string"},"emirate":{"nullable":true,"type":"string"},"area":{"nullable":true,"type":"string"},"area_ar":{"nullable":true,"type":"string"},"lat":{"nullable":true,"type":"number"},"lng":{"nullable":true,"type":"number"},"pin_source":{"nullable":true,"type":"string"}},"required":["text","emirate","area","area_ar","lat","lng","pin_source"]},"pieces":{"type":"array","items":{"type":"object","properties":{"barcode":{"type":"string"}},"required":["barcode"]}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","livemode","tracking_number","tracking_url","merchant_reference","status","sub_status","status_label","service","payment_type","cod_amount","fee","promised_date","window","attempts","cod_state","pod_state","reconciliation_state","receiver","address","pieces","metadata","created_at","updated_at"]}}}},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"summary":"Edit a draft (any field, re-priced); after confirming, notes and metadata only","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_reference":{"type":"string","minLength":1,"maxLength":64},"service":{"type":"string","enum":["next_day","same_day","scheduled","express","return_pickup"]},"payment_type":{"type":"string","enum":["prepaid","cod","card_on_delivery","pay_by_link"]},"cod_amount":{"type":"integer","minimum":0,"maximum":100000000,"description":"Integer fils (AED 1.00 = 100)"},"requested_delivery_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date in Asia/Dubai"},"receiver":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"phone":{"type":"string","minLength":7,"maxLength":20,"description":"UAE mobile; normalised to E.164"},"alt_phone":{"type":"string","minLength":7,"maxLength":20},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"language":{"default":"ar","type":"string","enum":["ar","en"]}}},"address":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":500,"description":"The address exactly as entered, in its original language"},"emirate":{"type":"string","enum":["AUH","DXB","SHJ","AJM","UAQ","RAK","FUJ"]},"area":{"description":"Area/community name (EN or AR) or a gazetteer id like shj-al-nahda","type":"string","maxLength":120},"street":{"type":"string","maxLength":200},"building":{"type":"string","maxLength":120},"floor":{"type":"string","maxLength":20},"unit":{"type":"string","maxLength":40},"landmark":{"type":"string","maxLength":200},"lat":{"type":"number","minimum":22,"maximum":27},"lng":{"type":"number","minimum":51,"maximum":57},"pin_source":{"type":"string","enum":["receiver","merchant","geocoder","rider","makani"]},"makani":{"type":"string","pattern":"^\\d{5}\\s?\\d{5}$"}},"required":["text"]},"parcel":{"type":"object","properties":{"description":{"type":"string","maxLength":300},"weight_grams":{"type":"integer","minimum":1,"maximum":100000},"size_class":{"type":"string","enum":["S","M","L","XL"]},"flags":{"type":"array","items":{"type":"string","enum":["fragile","perishable","cold_chain","age_check_18","age_check_21","pharmacy","high_value","dangerous_goods","id_required","open_box_inspection_allowed"]}}}},"notes":{"type":"string","maxLength":500},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500}}}}}}}}},"/shipments/{id}/confirm":{"post":{"summary":"Confirm a draft","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/shipments/{id}/cancel":{"post":{"summary":"Cancel (before pickup only; 409 cancellation_window_closed after). Optional {reason, note}","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["merchant_request","customer_changed_mind","duplicate","no_service_area","company_decision"]},"note":{"type":"string","maxLength":500}}}}}}}},"/shipments/{id}/return":{"post":{"summary":"Request return to origin. Optional {reason, note}","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["merchant_request","cancelled_after_pickup","recipient_refused","max_attempts","unclaimed","address_unresolvable","out_of_service_area","damaged","company_decision","partial_delivery_remainder"]},"note":{"type":"string","maxLength":500}}}}}}}},"/shipments/{id}/hold":{"post":{"summary":"Put a parcel on hold (merchants: reason merchant_request; before pickup or at the hub)","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"default":"merchant_request","description":"Merchants may use merchant_request only","type":"string","enum":["merchant_request","receiver_request","address_check","id_check","payment_check","damaged","missing","company_check"]},"note":{"type":"string","maxLength":500}}}}}}}},"/shipments/{id}/release":{"post":{"summary":"Release your own hold (back to awaiting pickup, or to the hub queue)","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":500}}}}}}}},"/shipments/{id}/reattempt":{"post":{"summary":"Ask for another delivery attempt after a failure (optionally on a day)","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"description":"Optional new day (GST); omit for the next working day","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"note":{"type":"string","maxLength":500}}}}}}}},"/shipments/{id}/reverse-pickup":{"post":{"summary":"Book a return pickup from the receiver of a delivered parcel (linked; priced as return_pickup)","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["shipment"]},"livemode":{"type":"boolean"},"tracking_number":{"type":"string"},"tracking_url":{"type":"string"},"merchant_reference":{"type":"string"},"status":{"type":"string"},"sub_status":{"nullable":true,"type":"string"},"status_label":{"type":"object","properties":{"en":{"type":"string"},"ar":{"type":"string"}},"required":["en","ar"]},"service":{"type":"string","enum":["next_day","same_day","scheduled","express","return_pickup"]},"payment_type":{"type":"string","enum":["prepaid","cod","card_on_delivery","pay_by_link"]},"cod_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee":{"type":"object","properties":{"net":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vat":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"gross":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vat_basis":{"type":"string"}},"required":["net","vat","gross","vat_basis"]},"promised_date":{"nullable":true,"type":"string"},"window":{"nullable":true,"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cod_state":{"type":"string"},"pod_state":{"type":"string"},"reconciliation_state":{"type":"string"},"receiver":{"nullable":true,"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"language":{"type":"string"}},"required":["name","phone","language"]},"address":{"type":"object","properties":{"text":{"type":"string"},"emirate":{"nullable":true,"type":"string"},"area":{"nullable":true,"type":"string"},"area_ar":{"nullable":true,"type":"string"},"lat":{"nullable":true,"type":"number"},"lng":{"nullable":true,"type":"number"},"pin_source":{"nullable":true,"type":"string"}},"required":["text","emirate","area","area_ar","lat","lng","pin_source"]},"pieces":{"type":"array","items":{"type":"object","properties":{"barcode":{"type":"string"}},"required":["barcode"]}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","livemode","tracking_number","tracking_url","merchant_reference","status","sub_status","status_label","service","payment_type","cod_amount","fee","promised_date","window","attempts","cod_state","pod_state","reconciliation_state","receiver","address","pieces","metadata","created_at","updated_at"]}}}},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","maxLength":300},"pieces":{"default":1,"type":"integer","minimum":1,"maximum":50},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date in Asia/Dubai"},"notes":{"type":"string","maxLength":500}}}}}}}},"/shipments/{id}/timeline":{"get":{"summary":"The stage timeline (stage keys, EN/AR labels, times in GST, who) and the stage stepper","tags":["Shipments"],"security":[{"bearer":["shipments:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/shipments/{id}/forget-receiver":{"post":{"summary":"Forget the receiver: replace name, phones, email, address and pin with a pseudonymous token (company keys only; idempotent; body {reason})","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/shipments/{id}/reschedule":{"post":{"summary":"Reschedule delivery","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date in Asia/Dubai"},"reason":{"type":"string","maxLength":300}},"required":["date"]}}}}}},"/shipments/{id}/change-requests":{"post":{"summary":"Request a change after pickup","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field":{"type":"string","enum":["address","phone","date","cod"]},"value":{},"reason":{"type":"string","maxLength":300}},"required":["field","value"]}}}}}},"/shipments/{id}/delivery-details":{"post":{"summary":"Add the receiver and address to a parcel a rider collected by your own barcode/QR (status picked_up / awaiting_details; it cannot go out until this is done)","tags":["Shipments"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["shipment"]},"livemode":{"type":"boolean"},"tracking_number":{"type":"string"},"tracking_url":{"type":"string"},"merchant_reference":{"type":"string"},"status":{"type":"string"},"sub_status":{"nullable":true,"type":"string"},"status_label":{"type":"object","properties":{"en":{"type":"string"},"ar":{"type":"string"}},"required":["en","ar"]},"service":{"type":"string","enum":["next_day","same_day","scheduled","express","return_pickup"]},"payment_type":{"type":"string","enum":["prepaid","cod","card_on_delivery","pay_by_link"]},"cod_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee":{"type":"object","properties":{"net":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vat":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"gross":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vat_basis":{"type":"string"}},"required":["net","vat","gross","vat_basis"]},"promised_date":{"nullable":true,"type":"string"},"window":{"nullable":true,"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cod_state":{"type":"string"},"pod_state":{"type":"string"},"reconciliation_state":{"type":"string"},"receiver":{"nullable":true,"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"language":{"type":"string"}},"required":["name","phone","language"]},"address":{"type":"object","properties":{"text":{"type":"string"},"emirate":{"nullable":true,"type":"string"},"area":{"nullable":true,"type":"string"},"area_ar":{"nullable":true,"type":"string"},"lat":{"nullable":true,"type":"number"},"lng":{"nullable":true,"type":"number"},"pin_source":{"nullable":true,"type":"string"}},"required":["text","emirate","area","area_ar","lat","lng","pin_source"]},"pieces":{"type":"array","items":{"type":"object","properties":{"barcode":{"type":"string"}},"required":["barcode"]}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","livemode","tracking_number","tracking_url","merchant_reference","status","sub_status","status_label","service","payment_type","cod_amount","fee","promised_date","window","attempts","cod_state","pod_state","reconciliation_state","receiver","address","pieces","metadata","created_at","updated_at"]}}}},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"receiver":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"phone":{"type":"string","minLength":7,"maxLength":20,"description":"UAE mobile; normalised to E.164"},"alt_phone":{"type":"string","minLength":7,"maxLength":20},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"language":{"default":"ar","type":"string","enum":["ar","en"]}},"required":["name","phone"]},"address":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":500,"description":"The address exactly as entered, in its original language"},"emirate":{"type":"string","enum":["AUH","DXB","SHJ","AJM","UAQ","RAK","FUJ"]},"area":{"description":"Area/community name (EN or AR) or a gazetteer id like shj-al-nahda","type":"string","maxLength":120},"street":{"type":"string","maxLength":200},"building":{"type":"string","maxLength":120},"floor":{"type":"string","maxLength":20},"unit":{"type":"string","maxLength":40},"landmark":{"type":"string","maxLength":200},"lat":{"type":"number","minimum":22,"maximum":27},"lng":{"type":"number","minimum":51,"maximum":57},"pin_source":{"type":"string","enum":["receiver","merchant","geocoder","rider","makani"]},"makani":{"type":"string","pattern":"^\\d{5}\\s?\\d{5}$"}},"required":["text"]},"service":{"description":"Defaults to the service the parcel was collected under (next_day)","type":"string","enum":["next_day","same_day","scheduled","express","return_pickup"]},"payment_type":{"default":"prepaid","type":"string","enum":["prepaid","cod","card_on_delivery","pay_by_link"]},"cod_amount":{"default":0,"type":"integer","minimum":0,"maximum":100000000,"description":"Integer fils (AED 1.00 = 100)"},"declared_value":{"type":"integer","minimum":0,"maximum":100000000,"description":"Integer fils (AED 1.00 = 100)"},"requested_delivery_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date in Asia/Dubai"},"parcel":{"type":"object","properties":{"description":{"type":"string","maxLength":300},"weight_grams":{"type":"integer","minimum":1,"maximum":100000},"size_class":{"type":"string","enum":["S","M","L","XL"]},"flags":{"default":[],"type":"array","items":{"type":"string","enum":["fragile","perishable","cold_chain","age_check_18","age_check_21","pharmacy","high_value","dangerous_goods","id_required","open_box_inspection_allowed"]}}}},"notes":{"type":"string","maxLength":500},"consent":{"type":"object","properties":{"channels":{"minItems":1,"type":"array","items":{"type":"string","enum":["whatsapp","sms","email"]}},"wording":{"type":"string","minLength":10,"maxLength":1000,"description":"The exact wording the receiver agreed to; it must name the delivery company"},"captured_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"source":{"type":"string","maxLength":80}},"required":["channels","wording","captured_at","source"]}},"required":["receiver","address"]}}}}}},"/shipments/{id}/events":{"get":{"summary":"The shipment's event history","tags":["Shipments"],"security":[{"bearer":["shipments:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/shipments/{id}/label":{"get":{"summary":"Label with your default label profile (?profile=<id>; ?format=pdf|png|tspl; png takes ?page=n)","tags":["Labels"],"security":[{"bearer":["labels:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/labels":{"get":{"summary":"Labels for many parcels in one file (?ids=a,b,c up to 500; ?profile, ?format=pdf|png, ?page)","tags":["Labels"],"security":[{"bearer":["labels:read"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/print-station/heartbeat":{"post":{"summary":"Print station: report host and printers (print-station keys only)","tags":["Print stations"],"security":[{"bearer":["print:station"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/print-station/claim":{"post":{"summary":"Print station: take the next queued job, or 204","tags":["Print stations"],"security":[{"bearer":["print:station"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/print-station/jobs/{id}/document":{"get":{"summary":"Print station: the job's file (?format=pdf|png, ?page)","tags":["Print stations"],"security":[{"bearer":["print:station"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/print-station/jobs/{id}/ack":{"post":{"summary":"Print station: report done or failed ({ ok, error?, station_job_ref? })","tags":["Print stations"],"security":[{"bearer":["print:station"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/pickups":{"post":{"summary":"Request a pickup","tags":["Pickups"],"security":[{"bearer":["pickups:write"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"type":"string"},"pickup_location_id":{"type":"string"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date in Asia/Dubai"},"window_from":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"window_to":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"expected_count":{"type":"integer","minimum":1,"maximum":500},"shipment_ids":{"maxItems":500,"type":"array","items":{"type":"string"}}},"required":["pickup_location_id","date"]}}}}},"get":{"summary":"List pickups","tags":["Pickups"],"security":[{"bearer":["pickups:write"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/meta/statuses":{"get":{"summary":"The versioned status set with EN/AR labels","tags":["Reference"],"security":[],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/service-areas":{"get":{"summary":"Emirates and areas served","tags":["Reference"],"security":[],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/addresses/validate":{"post":{"summary":"Resolve an address to an area and a quality score","tags":["Reference"],"security":[],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":500,"description":"The address exactly as entered, in its original language"},"emirate":{"type":"string","enum":["AUH","DXB","SHJ","AJM","UAQ","RAK","FUJ"]},"area":{"description":"Area/community name (EN or AR) or a gazetteer id like shj-al-nahda","type":"string","maxLength":120},"street":{"type":"string","maxLength":200},"building":{"type":"string","maxLength":120},"floor":{"type":"string","maxLength":20},"unit":{"type":"string","maxLength":40},"landmark":{"type":"string","maxLength":200},"lat":{"type":"number","minimum":22,"maximum":27},"lng":{"type":"number","minimum":51,"maximum":57},"pin_source":{"type":"string","enum":["receiver","merchant","geocoder","rider","makani"]},"makani":{"type":"string","pattern":"^\\d{5}\\s?\\d{5}$"}},"required":["text"]}}}}}},"/tracking/{tracking_number}":{"get":{"summary":"Public tracking (receiver-safe fields only)","tags":["Tracking"],"security":[{"bearer":["tracking:read"]}],"parameters":[{"name":"tracking_number","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/webhook-endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Create a webhook endpoint (secret shown once)","tags":["Webhooks"],"security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"description":{"type":"string","maxLength":200},"events":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Event types, or [\"*\"]"},"include_pii":{"default":false,"type":"boolean"}},"required":["url","events"]}}}}}},"/webhook-endpoints/{id}":{"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/webhook-endpoints/{id}/test":{"post":{"summary":"Send a ping event","tags":["Webhooks"],"security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/webhook-endpoints/{id}/deliveries":{"get":{"summary":"Delivery log","tags":["Webhooks"],"security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/webhook-deliveries/{id}/retry":{"post":{"summary":"Resend a delivery","tags":["Webhooks"],"security":[{"bearer":["webhooks:manage"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/events":{"get":{"summary":"Events feed (?after=<cursor>), 30-day retention","tags":["Webhooks"],"security":[{"bearer":["shipments:read"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/finance/balances":{"get":{"summary":"Live balances (COD held, fees due, remittable now)","tags":["Finance"],"security":[{"bearer":["finance:read"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/statements":{"get":{"summary":"Statement for a period (?from&to), from the one builder","tags":["Finance"],"security":[{"bearer":["finance:read"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/settlements":{"post":{"summary":"Record a settlement (tenant keys; idempotent)","tags":["Finance"],"security":[{"bearer":["finance:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"type":"string"},"shipment_ids":{"minItems":1,"maxItems":2000,"type":"array","items":{"type":"string"}},"method":{"type":"string","enum":["bank_transfer","cash","ziina"]},"external_reference":{"type":"string","minLength":3,"maxLength":80,"description":"The real-world reference: bank transfer ref, Ziina payment id or cash receipt"},"value_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date in Asia/Dubai"},"direction":{"default":"to_merchant","description":"to_merchant: the company pays the merchant its COD minus fees. from_merchant: fees exceed the COD held, and the merchant pays the difference.","type":"string","enum":["to_merchant","from_merchant"]},"expected_transfer_amount":{"type":"integer","minimum":0,"maximum":100000000,"description":"The amount that actually moved (always positive); must equal the computed net in the stated direction or the request is refused"}},"required":["merchant_id","shipment_ids","method","external_reference","value_date","expected_transfer_amount"]}}}}},"get":{"summary":"List settlements","tags":["Finance"],"security":[{"bearer":["finance:read"]}],"parameters":[{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/test/shipments/{id}/advance":{"post":{"summary":"Test mode: advance one step","tags":["Test mode"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-test-mode-only":true}},"/test/shipments/{id}/simulate":{"post":{"summary":"Test mode: run a scenario","tags":["Test mode"],"security":[{"bearer":["shipments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"AE-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-09-25"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-test-mode-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"string","enum":["happy_path","failed_then_delivered","rto","cod_short"]}},"required":["scenario"]}}}}}}},"x-webhook-events":["shipment.created","shipment.confirmed","shipment.updated","shipment.status_changed","shipment.pickup_assigned","shipment.picked_up","shipment.pickup_failed","shipment.received_at_hub","shipment.out_for_delivery","shipment.arrived","shipment.delivery_attempt_failed","shipment.rescheduled","shipment.address_changed","shipment.on_hold","shipment.released","shipment.delivered","shipment.return_initiated","shipment.returned","shipment.cancelled","shipment.corrected","pickup.created","pickup.assigned","pickup.completed","pickup.failed","pickup.cancelled","pod.captured","label.generated","shipment.feedback_received","complaint.created","cod.collected","cod.collection_failed","cod.handed_over","settlement.created","settlement.voided","statement.issued","import.completed","import.failed","carrier.status_unmapped","carrier.booking_failed","webhook_endpoint.disabled","api_key.created","api_key.revoked","ping","eta.updated","shipment.at_risk","shipment.pickup_requested","shipment.pickup_en_route","shipment.pickup_arrived","shipment.sorted","shipment.transfer_departed","shipment.transfer_arrived","shipment.handed_to_carrier","shipment.en_route","shipment.partially_delivered","shipment.reattempt_requested","shipment.return_assigned","shipment.return_out_for_delivery","shipment.return_attempt_failed","shipment.pieces_mismatch","shipment.issue_reported","shipment.exception_closed","shipment.reopened","shipment.exchange_created","shipment.reverse_pickup_created","cod.not_collected","cod.reversed","shipment.created_at_pickup"]}