Skip to main content

Python quickstart

This walks through the minimal integration: validate, create and track a delivery. Responses are TypedDicts, so editors and type checkers know every field.

1. Create a client​

import os
from cargo_core_api_sdk import CargoApiError, CargoClient

client = CargoClient(api_key=os.environ["CARGO_API_KEY"], environment="dev")

2. Define the order​

An order is a list of action points, the ordered stops the courier makes. It needs at least one STORE and one CLIENT. On PICK_UP points, products lists what is collected. On DROP_OFF points it is always an empty list.

order = {
    "order_id": "my-unique-id",  # also the idempotency key
    "total_value": 40000,
    "vehicle_type": "BIKE",
    "payment_method": "ONLINE",
    "priority_enabled": False,
    "action_points": [
        {
            "external_picking_point_id": "PP_123",
            "products": [
                {"product_id": "HAM123", "name": "Cheeseburger", "units": 2, "unit_price": 15500}
            ],
            "action_type": "PICK_UP",
            "location_type": "STORE",
        },
        {"products": [], "action_type": "DROP_OFF", "location_type": "CLIENT"},
    ],
    "client_info": {
        "email": "oscar@example.com",
        "phone": "3023311130",
        "phone_country_code": "57",
        "first_name": "Oscar",
        "last_name": "Perez",
        "address": "calle 93 #19-58",
        "city": "Bogota",
    },
}

3. Validate, create, track​

try:
    # Optional: same checks as create, without creating anything.
    validation = client.order_v3.validate_order(order)
    print(f"ETA: {validation['eta_for_immediate_delivery']} min")

    created = client.order_v3.create_order(order)
    print(f"Created: {created['cargo_order_id']}")

    status = client.order_v3.get_order_status({"rappi_order_id": created["rappi_order_id"]})
    print(f"State: {status['state']}")
except CargoApiError as err:
    print(err.status, err.code, err)
Retries are safe

order_id is the idempotency key. If a request times out, retry create_order with the same order_id and Cargo will not create a duplicate.

Next steps​