External International Delivery
2 API calls in this section.
Create International Delivery
/external/international-deliveries?tenant_id={{tenant_id}}Create an international delivery using a warehouse pickup and a delivery address object. Authentication: - Requires valid authentication token (Authorization header) Key Behavior: - Pickup address is automatically taken from the specified warehouse's address (no pickup address in payload). - Creates inventory items from provided products (bulk insert). - Creates a receiving order with item_details built from created items and product quantities. - Creates a delivery record with status set to 'draft'. Required Fields (Body): - warehouse_id (string): UUID of the warehouse for pickup - delivery_address (object): Must include lat, lng, full_address; contact_info optional - delivery_service_id (string) - payer_type (string): one of ['sender','receiver'] - payment_method (string): one of ['wallet','cod'] - external_reference_id (string): External system reference; must be unique per tenant - order_number (string): Customer order number used on shipment labels - products (array<object>): Each item requires name, sku, barcode, unit_size, quantity Conditionally Required: - customer_id (string): Required unless caller is a customer/no-role, in which case it is set from the authenticated user Optional Fields (Body): - cod_amount (number) - notes (string) - scheduled_pickup_time (ISO datetime) - scheduled_delivery_time (ISO datetime) - priority (number 1-4) - unit_size (number) - bulk_group (string) - tracking_provider (string) - package_details (object with special_instructions and items[{name,description,quantity,weight,length,width,height}]) Receiving Order Fields (Body - root-level): - expected_arrival_date (date, optional) - receiving_details (object, optional) - actual_arrival_date (date, optional) - received_by (uuid, optional) - notes (string, optional) - supplier_id (uuid, optional) Notes: - reference_number for the receiving order is auto-generated (RIO-<timestamp>). - receiving_orders.status is set to 'pending'. - delivery.status is set to 'draft'.
1curl --request POST "$ONDI_BASE_URL/external/international-deliveries?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}" \4 --header "Content-Type: application/json" \5 --header "Content-Type: application/json" \6 --data '{7 "warehouse_id": "{{warehouse_id}}",8 "delivery_address": {9 "lat": {{delivery_lat}},10 "lng": {{delivery_lng}},11 "full_address": "{{delivery_full_address}}",12 "city": "{{delivery_city}}",13 "state": "{{delivery_state}}",14 "country": "{{delivery_country}}",15 "postal_code": "{{delivery_postal_code}}",16 "contact_info": {17 "name": "{{receiver_name}}",18 "phone": "{{receiver_phone}}",19 "email": "{{receiver_email}}",20 "tel_phone": "{{receiver_tel}}"21 }22 },23 "customer_id": "{{customer_id}}",24 "delivery_service_id": "{{delivery_service_id}}",25 "payer_type": "sender",26 "payment_method": "wallet",27 "external_reference_id": "{{external_reference_id}}",28 "order_number": "{{order_number}}",29 "cod_amount": 0,30 "notes": "International shipment",31 "scheduled_pickup_time": "2024-01-15T10:00:00Z",32 "scheduled_delivery_time": "2024-01-20T18:00:00Z",33 "priority": 1,34 "unit_size": 1,35 "bulk_group": "GROUP-INTL-001",36 "tracking_provider": "internal",37 "package_details": {38 "special_instructions": "International shipment - handle with care",39 "items": [40 {41 "name": "{{item_name}}",42 "description": "{{item_description}}",43 "quantity": 1,44 "weight": 2.5,45 "length": 30,46 "width": 20,47 "height": 1548 }49 ]50 },51 "products": [52 {53 "name": "Widget A",54 "sku": "WIDGET-A",55 "barcode": "1234567890123",56 "unit_size": 1,57 "quantity": 2,58 "description": "Blue widget",59 "brand": "Acme",60 "model": "A1",61 "category": "Widgets",62 "subcategory": "Standard"63 },64 {65 "name": "Gadget B",66 "sku": "GADGET-B",67 "barcode": "9876543210987",68 "unit_size": 1,69 "quantity": 170 }71 ],72 "sender": {73 "name": "{{sender_name}}",74 "phone": "{{sender_phone}}",75 "full_address": "{{sender_full_address}}"76 },77 "expected_arrival_date": "2024-01-19",78 "receiving_details": {79 "carrier": "DHL",80 "incoterms": "DAP"81 },82 "actual_arrival_date": null,83 "received_by": null,84 "supplier_id": null85}'1{2 "warehouse_id": "{{warehouse_id}}",3 "delivery_address": {4 "lat": {{delivery_lat}},5 "lng": {{delivery_lng}},6 "full_address": "{{delivery_full_address}}",7 "city": "{{delivery_city}}",8 "state": "{{delivery_state}}",9 "country": "{{delivery_country}}",10 "postal_code": "{{delivery_postal_code}}",11 "contact_info": {12 "name": "{{receiver_name}}",13 "phone": "{{receiver_phone}}",14 "email": "{{receiver_email}}",15 "tel_phone": "{{receiver_tel}}"16 }17 },18 "customer_id": "{{customer_id}}",19 "delivery_service_id": "{{delivery_service_id}}",20 "payer_type": "sender",21 "payment_method": "wallet",22 "external_reference_id": "{{external_reference_id}}",23 "order_number": "{{order_number}}",24 "cod_amount": 0,25 "notes": "International shipment",26 "scheduled_pickup_time": "2024-01-15T10:00:00Z",27 "scheduled_delivery_time": "2024-01-20T18:00:00Z",28 "priority": 1,29 "unit_size": 1,30 "bulk_group": "GROUP-INTL-001",31 "tracking_provider": "internal",32 "package_details": {33 "special_instructions": "International shipment - handle with care",34 "items": [35 {36 "name": "{{item_name}}",37 "description": "{{item_description}}",38 "quantity": 1,39 "weight": 2.5,40 "length": 30,41 "width": 20,42 "height": 1543 }44 ]45 },46 "products": [47 {48 "name": "Widget A",49 "sku": "WIDGET-A",50 "barcode": "1234567890123",51 "unit_size": 1,52 "quantity": 2,53 "description": "Blue widget",54 "brand": "Acme",55 "model": "A1",56 "category": "Widgets",57 "subcategory": "Standard"58 },59 {60 "name": "Gadget B",61 "sku": "GADGET-B",62 "barcode": "9876543210987",63 "unit_size": 1,64 "quantity": 165 }66 ],67 "sender": {68 "name": "{{sender_name}}",69 "phone": "{{sender_phone}}",70 "full_address": "{{sender_full_address}}"71 },72 "expected_arrival_date": "2024-01-19",73 "receiving_details": {74 "carrier": "DHL",75 "incoterms": "DAP"76 },77 "actual_arrival_date": null,78 "received_by": null,79 "supplier_id": null80}Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "delivery_created_successfully",4 "delivery": {5 "id": "DEL-000001"6 },7 "pickup_address_id": "warehouse-address-uuid",8 "delivery_address": {9 "id": "address-uuid",10 "full_address": "456 Broadway..."11 },12 "inventory_item": {13 "id": "item-uuid-1",14 "sku": "WIDGET-A",15 "name": "Widget A"16 },17 "receiving_order": {18 "id": "ro-uuid",19 "reference_number": "RIO-1700000000000",20 "status": "pending"21 }22}1{2 "success": false,3 "message": "tenant_id is required"4}1{2 "success": false,3 "message": "products_array_cannot_be_empty"4}1{2 "success": false,3 "message": "warehouse_not_found"4}1{2 "success": false,3 "message": "delivery_address_creation_failed"4}1{2 "success": false,3 "message": "external_reference_id_already_exists"4}1{2 "success": false,3 "message": "internal_server_error"4}Create International Delivery
/external/international-deliveries?tenant_id={{tenant_id}}Create an international delivery using a warehouse pickup and a delivery address object. Authentication: - Requires valid authentication token (Authorization header) Key Behavior: - Pickup address is automatically taken from the specified warehouse's address (no pickup address in payload). - Creates inventory items from provided products (bulk insert). - Creates a receiving order with item_details built from created items and product quantities. - Creates a delivery record with status set to 'draft'. Required Fields (Body): - warehouse_id (string): UUID of the warehouse for pickup - delivery_address (object): Must include lat, lng, full_address; contact_info optional - delivery_service_id (string) - payer_type (string): one of ['sender','receiver'] - payment_method (string): one of ['wallet','cod'] - external_reference_id (string): External system reference; must be unique per tenant - order_number (string): Customer order number used on shipment labels - products (array<object>): Each item requires name, sku, barcode, unit_size, quantity Conditionally Required: - customer_id (string): Required unless caller is a customer/no-role, in which case it is set from the authenticated user Optional Fields (Body): - cod_amount (number) - notes (string) - scheduled_pickup_time (ISO datetime) - scheduled_delivery_time (ISO datetime) - priority (number 1-4) - unit_size (number) - bulk_group (string) - tracking_provider (string) - package_details (object with special_instructions and items[{name,description,quantity,weight,length,width,height}]) Receiving Order Fields (Body - root-level): - expected_arrival_date (date, optional) - receiving_details (object, optional) - actual_arrival_date (date, optional) - received_by (uuid, optional) - notes (string, optional) - supplier_id (uuid, optional) Notes: - reference_number for the receiving order is auto-generated (RIO-<timestamp>). - receiving_orders.status is set to 'pending'. - delivery.status is set to 'draft'.
1curl --request POST "$ONDI_BASE_URL/external/international-deliveries?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}" \4 --header "Content-Type: application/json" \5 --header "Content-Type: application/json" \6 --data '{7 "warehouse_id": "{{warehouse_id}}",8 "delivery_address": {9 "lat": {{delivery_lat}},10 "lng": {{delivery_lng}},11 "full_address": "{{delivery_full_address}}",12 "city": "{{delivery_city}}",13 "state": "{{delivery_state}}",14 "country": "{{delivery_country}}",15 "postal_code": "{{delivery_postal_code}}",16 "contact_info": {17 "name": "{{receiver_name}}",18 "phone": "{{receiver_phone}}",19 "email": "{{receiver_email}}",20 "tel_phone": "{{receiver_tel}}"21 }22 },23 "customer_id": "{{customer_id}}",24 "delivery_service_id": "{{delivery_service_id}}",25 "payer_type": "sender",26 "payment_method": "wallet",27 "external_reference_id": "{{external_reference_id}}",28 "order_number": "{{order_number}}",29 "cod_amount": 0,30 "notes": "International shipment",31 "scheduled_pickup_time": "2024-01-15T10:00:00Z",32 "scheduled_delivery_time": "2024-01-20T18:00:00Z",33 "priority": 1,34 "unit_size": 1,35 "bulk_group": "GROUP-INTL-001",36 "tracking_provider": "internal",37 "package_details": {38 "special_instructions": "International shipment - handle with care",39 "items": [40 {41 "name": "{{item_name}}",42 "description": "{{item_description}}",43 "quantity": 1,44 "weight": 2.5,45 "length": 30,46 "width": 20,47 "height": 1548 }49 ]50 },51 "products": [52 {53 "name": "Widget A",54 "sku": "WIDGET-A",55 "barcode": "1234567890123",56 "unit_size": 1,57 "quantity": 2,58 "description": "Blue widget",59 "brand": "Acme",60 "model": "A1",61 "category": "Widgets",62 "subcategory": "Standard"63 },64 {65 "name": "Gadget B",66 "sku": "GADGET-B",67 "barcode": "9876543210987",68 "unit_size": 1,69 "quantity": 170 }71 ],72 "sender": {73 "name": "{{sender_name}}",74 "phone": "{{sender_phone}}",75 "full_address": "{{sender_full_address}}"76 },77 "expected_arrival_date": "2024-01-19",78 "receiving_details": {79 "carrier": "DHL",80 "incoterms": "DAP"81 },82 "actual_arrival_date": null,83 "received_by": null,84 "supplier_id": null85}'1{2 "warehouse_id": "{{warehouse_id}}",3 "delivery_address": {4 "lat": {{delivery_lat}},5 "lng": {{delivery_lng}},6 "full_address": "{{delivery_full_address}}",7 "city": "{{delivery_city}}",8 "state": "{{delivery_state}}",9 "country": "{{delivery_country}}",10 "postal_code": "{{delivery_postal_code}}",11 "contact_info": {12 "name": "{{receiver_name}}",13 "phone": "{{receiver_phone}}",14 "email": "{{receiver_email}}",15 "tel_phone": "{{receiver_tel}}"16 }17 },18 "customer_id": "{{customer_id}}",19 "delivery_service_id": "{{delivery_service_id}}",20 "payer_type": "sender",21 "payment_method": "wallet",22 "external_reference_id": "{{external_reference_id}}",23 "order_number": "{{order_number}}",24 "cod_amount": 0,25 "notes": "International shipment",26 "scheduled_pickup_time": "2024-01-15T10:00:00Z",27 "scheduled_delivery_time": "2024-01-20T18:00:00Z",28 "priority": 1,29 "unit_size": 1,30 "bulk_group": "GROUP-INTL-001",31 "tracking_provider": "internal",32 "package_details": {33 "special_instructions": "International shipment - handle with care",34 "items": [35 {36 "name": "{{item_name}}",37 "description": "{{item_description}}",38 "quantity": 1,39 "weight": 2.5,40 "length": 30,41 "width": 20,42 "height": 1543 }44 ]45 },46 "products": [47 {48 "name": "Widget A",49 "sku": "WIDGET-A",50 "barcode": "1234567890123",51 "unit_size": 1,52 "quantity": 2,53 "description": "Blue widget",54 "brand": "Acme",55 "model": "A1",56 "category": "Widgets",57 "subcategory": "Standard"58 },59 {60 "name": "Gadget B",61 "sku": "GADGET-B",62 "barcode": "9876543210987",63 "unit_size": 1,64 "quantity": 165 }66 ],67 "sender": {68 "name": "{{sender_name}}",69 "phone": "{{sender_phone}}",70 "full_address": "{{sender_full_address}}"71 },72 "expected_arrival_date": "2024-01-19",73 "receiving_details": {74 "carrier": "DHL",75 "incoterms": "DAP"76 },77 "actual_arrival_date": null,78 "received_by": null,79 "supplier_id": null80}Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "delivery_created_successfully",4 "delivery": {5 "id": "DEL-000001"6 },7 "pickup_address_id": "warehouse-address-uuid",8 "delivery_address": {9 "id": "address-uuid",10 "full_address": "456 Broadway..."11 },12 "inventory_item": {13 "id": "item-uuid-1",14 "sku": "WIDGET-A",15 "name": "Widget A"16 },17 "receiving_order": {18 "id": "ro-uuid",19 "reference_number": "RIO-1700000000000",20 "status": "pending"21 }22}1{2 "success": false,3 "message": "tenant_id is required"4}1{2 "success": false,3 "message": "products_array_cannot_be_empty"4}1{2 "success": false,3 "message": "warehouse_not_found"4}1{2 "success": false,3 "message": "delivery_address_creation_failed"4}1{2 "success": false,3 "message": "external_reference_id_already_exists"4}1{2 "success": false,3 "message": "internal_server_error"4}