Entrega
Documentation

Developer docs

Deliveries

Create, list, retrieve, filter, and cancel deliveries.

View as Markdown

Deliveries

Deliveries are created from persisted quotes. The create request must send the same origin, destination, and parcel payload that produced the quote.

Create a delivery

http 
POST /v1/deliveries
bash 
curl -X POST https://entrega.ao/v1/deliveries \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "8c1e1a90-7f08-4b2c-9d5d-9a4ab7f59c0e",
    "company_id": "0b1e6fc0-a821-4be4-8bd7-df56b8c0caa4",
    "origin": {"address_line": "Rua 21 de Janeiro", "city": "Luanda", "province": "Luanda"},
    "destination": {"address_line": "Rua Marien Nguabi", "city": "Luanda", "province": "Luanda"},
    "parcel": {"weight_grams": 1200, "description": "Photo prints"},
    "payment_method": "prepaid",
    "options": {"metadata": {"checkout_id": "WEB-4821"}}
  }'

Create fields

Field Required Notes
quote_id Yes Returned by POST /v1/quotes .
company_id No If present, must match the quote company.
origin Yes Must match the quote payload.
destination Yes Must match the quote payload.
parcel Yes Must match the quote payload.
payment_method No prepaid , bank_transfer , or cod . Defaults to prepaid .
cash_collect_aoa Conditional Required for cash-on-delivery flows.
scheduled_pickup_at No ISO8601 timestamp.
scheduled_delivery_at No ISO8601 timestamp.
options.metadata No Free-form metadata echoed in responses and webhooks.
Do not send courier_fee_aoa . Entrega rejects client-supplied courier fees with courier_fee_aoa_not_accepted .

List and lookup

http 
GET /v1/deliveries
GET /v1/deliveries/{id}
DELETE /v1/deliveries/{id}

The list endpoint is paginated and tenant-scoped. It does not return a total count; use pagination.has_more .

Supported filters

Query param Example Behavior
status pending Single status.
status pending,assigned,in_transit Comma-separated status list.
inserted_at_gte 2026-02-01T00:00:00Z Created on or after timestamp. Inclusive.
inserted_at_lte 2026-03-01T00:00:00Z Created on or before timestamp. Inclusive.
sort inserted_at_desc Newest first. Default.
sort inserted_at_asc Oldest first.
search DLV-2026 Substring match on reference, origin/destination city, and address line.
limit 50 Page size. Minimum 1 , maximum 100 .
offset 100 Page offset. Maximum 100000 .

List examples

bash 
curl "https://entrega.ao/v1/deliveries?status=pending,assigned&limit=20" \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY"
bash 
curl "https://entrega.ao/v1/deliveries?inserted_at_gte=2026-02-01T00:00:00Z&inserted_at_lte=2026-03-01T00:00:00Z&sort=inserted_at_asc" \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY"
bash 
curl "https://entrega.ao/v1/deliveries?search=Maianga&offset=20&limit=20" \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY"

Cancellable states

DELETE /v1/deliveries/{id} succeeds only when the delivery is awaiting_payment , pending , or assigned . Other states return 409 Conflict .