{"openapi":"3.1.0","info":{"title":"ODTC Partner API","version":"2.5.0","description":"Partner API v2.4. Sandbox and Production are selected by the bearer credential. Production supports ODTC-administered Prepaid, Postpaid and Hybrid billing; wallet funding is optional at developer-account level. Both actual Production handover codes are returned in the authenticated successful order-creation response. Signed webhook notifications are optional additional delivery channels. Verification still requires the assigned rider private photo evidence."},"servers":[{"url":"https:\/\/odtclogistics.com\/odtc-api\/odtc\/v1\/partner\/v2"}],"security":[{"PartnerBearer":[]}],"components":{"securitySchemes":{"PartnerBearer":{"type":"http","scheme":"bearer","bearerFormat":"CLIENT_ID.SECRET"}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"type":"object"}}},"PickupVerificationRequest":{"type":"object","required":["pickup_code"],"properties":{"pickup_code":{"type":"string","pattern":"^[0-9]{6}$","example":"482913"}}},"DeliveryVerificationRequest":{"type":"object","required":["delivery_code","recipient_name","signature"],"properties":{"delivery_code":{"type":"string","pattern":"^[0-9]{6}$","example":"739251"},"recipient_name":{"type":"string","maxLength":160,"example":"Ada Okafor"},"signature":{"type":"string","description":"Typed recipient confirmation text; this is not a drawn signature image.","example":"Ada Okafor confirms receipt of parcel"}}},"VerificationResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"verified":{"type":"boolean","example":true},"stage":{"type":"string","enum":["pickup","delivery"]},"external_order_id":{"type":"string"},"booking_reference":{"type":"string"},"shipment_id":{"type":"integer"},"previous_status":{"type":"string"},"status":{"type":"string"},"verified_at":{"type":"string","example":"2026-11-12T15:30:00"},"message":{"type":"string"}}},"PartnerOrderCreateResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"external_order_id":{"type":"string","example":"STORE-1001"},"booking_reference":{"type":"string","example":"ODTC-ABC123"},"shipment_id":{"type":"integer","example":125},"verification":{"type":"object","required":["pickup_code","delivery_code"],"properties":{"pickup_code":{"type":"string","pattern":"^[0-9]{6}$","example":"482913"},"delivery_code":{"type":"string","pattern":"^[0-9]{6}$","example":"739251"}}},"verification_delivery":{"type":"object","properties":{"pickup_webhook_queued":{"type":"boolean"},"delivery_webhook_queued":{"type":"boolean"},"customer_email_sent":{"type":"boolean"},"action_required":{"type":"boolean"},"webhook_notification_issue":{"type":"boolean"}}}}},"PartnerRider":{"type":"object","description":"The latest accepted or in-transit rider, or the completed rider retained on the completed order. Null while the latest offer is awaiting acceptance or is no longer current.","properties":{"name":{"type":"string"},"phone":{"type":"string"},"vehicle_type":{"type":"string"},"assignment_status":{"type":"string","enum":["accepted","in_transit","completed"]},"assigned_at":{"type":"string","format":"date-time"}}}}},"paths":{"\/health":{"get":{"summary":"Test API authentication","responses":{"200":{"description":"Authenticated health response"},"401":{"description":"Invalid or missing credentials"}}}},"\/wallet":{"get":{"summary":"Read partner wallet, billing policy and ledger","responses":{"200":{"description":"Sandbox zero-balance wallet or Production wallet, Prepaid\/Postpaid\/Hybrid policy, approved credit limit, outstanding invoices and ledger"}}}},"\/quote":{"post":{"summary":"Request an official quote without creating a booking","description":"Minimal request requires pickup_lat, pickup_lng, dropoff_lat, dropoff_lng and vehicle_type. ODTC reverse-geocodes both points and validates enabled Nigerian operating-state coverage. For backward compatibility, callers may also supply all pickup\/drop-off address, city and state fields; coordinates remain required. Quote requests do not create bookings or shipments, assign riders or debit partner funds.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["pickup_lat","pickup_lng","dropoff_lat","dropoff_lng","vehicle_type"],"properties":{"pickup_address":{"type":"string","description":"Optional with the other five address metadata fields for legacy integrations."},"pickup_city":{"type":"string"},"pickup_state":{"type":"string"},"pickup_lat":{"type":"number","example":6.4541},"pickup_lng":{"type":"number","example":3.3947},"dropoff_address":{"type":"string"},"dropoff_city":{"type":"string"},"dropoff_state":{"type":"string"},"dropoff_lat":{"type":"number","example":6.6018},"dropoff_lng":{"type":"number","example":3.3515},"vehicle_type":{"type":"string","enum":["motorcycle","car","bus"],"example":"motorcycle"},"package_description":{"type":"string","description":"Optional; collect full parcel details at order creation."}},"example":{"pickup_lat":6.4541,"pickup_lng":3.3947,"dropoff_lat":6.6018,"dropoff_lng":3.3515,"vehicle_type":"motorcycle"}}}}},"responses":{"200":{"description":"Quote-only response with quote_only=true, booking_created=false, quote_reference, amount\/total_fare, fare breakdown and expiry"},"400":{"description":"Invalid route or request"},"422":{"description":"Coordinates cannot be resolved or are outside enabled operating coverage"},"503":{"description":"Pricing engine unavailable"}}}},"\/orders":{"post":{"summary":"Create Sandbox simulation or Production shipment using the ODTC-assigned Prepaid, Postpaid or Hybrid billing policy","description":"Wallet funding is optional for developer account setup. Prepaid orders debit available wallet balance; Postpaid orders create an invoice within the approved credit limit; Hybrid orders use available wallet balance first and invoice the approved shortfall. Both Production pickup and delivery verification codes are generated when the order is accepted and returned in verification.pickup_code and verification.delivery_code in the authenticated successful order-creation response. Signed verification.codes_issued webhook events and customer_email are optional additional delivery channels.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["external_order_id","quote_reference"],"properties":{"external_order_id":{"type":"string","maxLength":190},"quote_reference":{"type":"string"},"customer_name":{"type":"string","description":"Required in Production; not required for Sandbox simulation."},"customer_phone":{"type":"string","description":"Required in Production; not required for Sandbox simulation."},"customer_email":{"type":"string","format":"email","description":"Optional. ODTC emails both Production handover codes to this address when the order is accepted. The authenticated order-creation response also returns both codes."},"recipient_name":{"type":"string"},"recipient_phone":{"type":"string"},"package_description":{"type":"string"},"delivery_instructions":{"type":"string"}}}}}},"responses":{"201":{"description":"Order created; Production response includes verification.pickup_code and verification.delivery_code with actual six-digit values.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PartnerOrderCreateResponse"}}}},"200":{"description":"Idempotent duplicate response may return any still-actionable code values for this partner-owned order."},"402":{"description":"Prepaid wallet balance or ODTC-approved Postpaid\/Hybrid credit limit is insufficient"},"422":{"description":"Invalid, expired or consumed quote"}}}},"\/orders\/{external_id}":{"get":{"summary":"Retrieve partner-owned order, billing and assigned rider contact details","description":"The rider object includes name, phone and vehicle type after the latest rider accepts the assignment; null while an offer is awaiting acceptance or is no longer current. Completed rider details remain available on the completed order.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your unique external_order_id supplied when the order was created."}],"responses":{"200":{"description":"Order status, billing and rider (PartnerRider or null)"},"404":{"description":"Order not found"}}}},"\/orders\/{external_id}\/tracking":{"get":{"summary":"Retrieve shipment tracking timeline and assigned rider contact details","description":"Returns the accepted\/current rider contact object and active rider location when available. Rider details are scoped to this authenticated partner-owned order.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your unique external_order_id supplied when the order was created."}],"responses":{"200":{"description":"Tracking timeline, rider (PartnerRider or null) and location"},"404":{"description":"Order not found"}}}},"\/sandbox\/orders\/{external_id}\/evidence":{"post":{"summary":"Record synthetic Sandbox pickup or delivery photo evidence","description":"Sandbox credentials only. Record proof_type=pickup at arrived_pickup or proof_type=delivery at arrived_dropoff before using the synthetic verification endpoint. This creates metadata only; no image is uploaded and no live evidence record is created.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your unique external_order_id supplied when the order was created."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["proof_type"],"properties":{"proof_type":{"type":"string","enum":["pickup","delivery"]}}},"example":{"proof_type":"pickup"}}}},"responses":{"200":{"description":"Synthetic evidence metadata saved"},"403":{"description":"Production credentials cannot use the simulator"},"404":{"description":"Sandbox order not found"},"409":{"description":"Evidence stage does not match current lifecycle status"}}}},"\/sandbox\/orders\/{external_id}\/advance":{"post":{"summary":"Advance a Sandbox-only simulated shipment lifecycle","description":"Sandbox credentials only. Allowed states: ready_for_dispatch, assigned, arrived_pickup, in_transit, arrived_dropoff, delivery_failed and cancelled. Handover completion states picked_up and delivered must be reached through the synthetic verification endpoints. This never changes a live shipment, rider, wallet or customer notification.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your unique external_order_id supplied when the order was created."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ready_for_dispatch","assigned","arrived_pickup","in_transit","arrived_dropoff","delivery_failed","cancelled"]}}},"example":{"status":"arrived_pickup"}}}},"responses":{"200":{"description":"Synthetic state transition and tracking event recorded"},"403":{"description":"Production credentials cannot use the simulator"},"404":{"description":"Sandbox order not found"},"409":{"description":"Invalid or terminal lifecycle transition"}}}},"\/orders\/{external_id}\/verify-pickup":{"post":{"summary":"Verify pickup handover code and confirm pickup","description":"Production: pickup and delivery codes are both issued when the order is accepted. Shipment must be at arrived_pickup and the assigned rider must have uploaded a private pickup parcel photo. Sandbox: use synthetic code 123456 after advancing the Sandbox order to arrived_pickup. Sandbox does not access live shipment or rider records.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your unique external_order_id supplied when the order was created."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PickupVerificationRequest"},"example":{"pickup_code":"482913"}}}},"responses":{"200":{"description":"Pickup code verified and status updated","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/VerificationResponse"},"example":{"success":true,"verified":true,"stage":"pickup","external_order_id":"STORE-1001","booking_reference":"ODTC-ABC123","shipment_id":125,"previous_status":"arrived_pickup","status":"picked_up","verified_at":"2026-11-12T15:30:00","message":"Pickup code verified successfully."}}}},"400":{"description":"Missing or malformed code"},"401":{"description":"Missing or invalid bearer credentials"},"403":{"description":"Incorrect code or missing verification:manage scope"},"409":{"description":"Wrong lifecycle stage, missing rider assignment or pickup photo"},"404":{"description":"Partner-owned order or shipment not found"},"429":{"description":"Too many incorrect attempts"},"500":{"description":"Could not commit verification"}}}},"\/orders\/{external_id}\/verify-delivery":{"post":{"summary":"Verify delivery code and complete delivery","description":"Production: the delivery code is also issued when the order is accepted and remains confidential until recipient handover. Shipment must be arrived_dropoff or delivery_attempted, with assigned-rider private delivery photo, recipient_name and typed recipient confirmation text in signature (not a drawn signature image). Sandbox: use synthetic code 654321 after advancing the Sandbox order to arrived_dropoff; recipient_name and signature are still required. Sandbox never accesses live shipment or rider records.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your unique external_order_id supplied when the order was created."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DeliveryVerificationRequest"},"example":{"delivery_code":"739251","recipient_name":"Ada Okafor","signature":"Ada Okafor confirms receipt of parcel"}}}},"responses":{"200":{"description":"Delivery code verified and shipment completed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/VerificationResponse"},"example":{"success":true,"verified":true,"stage":"delivery","external_order_id":"STORE-1001","booking_reference":"ODTC-ABC123","shipment_id":125,"previous_status":"arrived_dropoff","status":"delivered","verified_at":"2026-11-12T16:45:00","message":"Delivery code verified successfully."}}}},"400":{"description":"Missing code, recipient name or signature"},"401":{"description":"Missing or invalid bearer credentials"},"403":{"description":"Incorrect code or missing verification:manage scope"},"409":{"description":"Wrong lifecycle stage, missing rider assignment or delivery photo"},"404":{"description":"Partner-owned order or shipment not found"},"429":{"description":"Too many incorrect attempts"},"500":{"description":"Could not commit verification"}}}},"\/orders\/{external_id}\/cancel":{"post":{"summary":"Cancel an eligible pre-dispatch Production order","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your unique external_order_id supplied when the order was created."}],"responses":{"200":{"description":"Cancellation result"},"409":{"description":"Order is no longer cancellable"}}}},"\/orders\/{external_id}\/verification\/reissue":{"post":{"summary":"Reissue the current handover verification code via subscribed webhook; both initial codes are issued at Production order acceptance","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your unique external_order_id supplied when the order was created."}],"responses":{"200":{"description":"Verification event queued"},"422":{"description":"Required webhook subscription missing"}}}}}}