---
title: "Quickstart"
description: "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.