Skip to main content

TypeScript quickstart

This walks through the minimal integration: validate, create and track a delivery. Every request and response below is fully typed.

1. Create a client​

import { CargoApiError, CargoClient } from "@rappi_cargo/cargo-core-api-sdk";

const client = new CargoClient({
  apiKey: process.env.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 array.

const order = {
  order_id: "my-unique-id", // also the idempotency key
  total_value: 40000,
  vehicle_type: "BIKE" as const,
  payment_method: "ONLINE" as const,
  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" as const,
      location_type: "STORE" as const,
    },
    { products: [], action_type: "DROP_OFF" as const, location_type: "CLIENT" as const },
  ],
  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.
  const validation = await client.orderV3.validateOrder(order);
  console.log(`ETA: ${validation.eta_for_immediate_delivery} min`);

  const created = await client.orderV3.createOrder(order);
  console.log(`Created: ${created.cargo_order_id}`);

  const status = await client.orderV3.getOrderStatus({
    rappi_order_id: created.rappi_order_id,
  });
  console.log(`State: ${status.state}`);
} catch (err) {
  if (err instanceof CargoApiError) {
    console.error(err.status, err.code, err.message);
  } else {
    throw err;
  }
}
Retries are safe

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

Next steps​