Developer docs

Quickstart

Create a quote, turn it into a delivery, and expose live tracking.

Quickstart

This guide creates a delivery using the server-side Core API.

1. Set your secret key

Secret keys belong on your backend only.

bash

export ENTREGA_SECRET_KEY="sk_live_..."
export ENTREGA_BASE_URL="https://entrega.ao"

2. Request quotes

POST /v1/quotes returns one quote per available courier company. Each quote includes a persisted quote_id.

bash

curl -X POST "$ENTREGA_BASE_URL/v1/quotes" \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {
      "address_line": "Rua 21 de Janeiro, Talatona",
      "city": "Luanda",
      "province": "Luanda",
      "contact": {"name": "Loja Central", "phone": "+244923000000"}
    },
    "destination": {
      "address_line": "Rua Marien Nguabi, Maianga",
      "city": "Luanda",
      "province": "Luanda",
      "contact": {"name": "Joao Silva", "phone": "+244924000000"}
    },
    "parcel": {
      "weight_grams": 1200,
      "description": "Photo prints",
      "declared_value_aoa": 15000
    }
  }'

json

{
  "data": [
    {
      "quote_id": "8c1e1a90-7f08-4b2c-9d5d-9a4ab7f59c0e",
      "valid_until": "2026-04-29T18:05:00Z",
      "company_id": "0b1e6fc0-a821-4be4-8bd7-df56b8c0caa4",
      "company_name": "Luanda Express",
      "fee_aoa": 3500,
      "eta_minutes": 45,
      "require_delivery_pin": false
    }
  ]
}

3. Create the delivery

Use the quote_id from the quote response. Entrega rejects courier_fee_aoa in create requests because pricing is server-authoritative.

bash

curl -X POST "$ENTREGA_BASE_URL/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, Talatona",
      "city": "Luanda",
      "province": "Luanda"
    },
    "destination": {
      "address_line": "Rua Marien Nguabi, Maianga",
      "city": "Luanda",
      "province": "Luanda"
    },
    "parcel": {"weight_grams": 1200, "description": "Photo prints"},
    "payment_method": "prepaid",
    "options": {"metadata": {"checkout_id": "WEB-4821"}}
  }'

4. Read delivery status

bash

curl "$ENTREGA_BASE_URL/v1/deliveries/$DELIVERY_ID" \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY"

Use the returned tracking_url for customers, or call the public tracking shape directly:

bash

curl "$ENTREGA_BASE_URL/v1/deliveries/$DELIVERY_ID/tracking"

5. Configure webhooks

Add your webhook URL and secret in the dashboard. Entrega signs every outbound webhook with the x-entrega-signature header.