---
title: codespar_ship
description: Domestic shipping. Three rails on Melhor Envio — domestic-label, domestic-quote, domestic-track. Typed wrapper session.ship(args).
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";

# codespar_ship

<Callout title="Meta-tool" type="info">
**Sell-side.** Your agent is the merchant: it collects from, invoices, ships to, or verifies a counterparty.

`codespar_ship` covers Brazilian domestic shipping via Melhor Envio. The `action` argument picks one of three rails — quote, label, or track. Covered by `session.ship(args)` typed wrapper.
</Callout>

## Rails

All three are Melhor Envio under the hood, exposed as distinct rails so the agent can pick the right intent without learning the carrier API.

| Rail | Default? | Action arg | Purpose |
|---|---|---|---|
| `domestic-label` | Yes | `action: "label"` | Generate a paid shipping label after picking a quote |
| `domestic-quote` | — | `action: "quote"` | Quote rates across Correios, Jadlog, Loggi, etc. — no label generated |
| `domestic-track` | — | `action: "track"` | Track an existing shipment by `tracking_code` |

`domestic-label` is the default if `action` is omitted.

## Typed wrapper

<Tabs items={["TypeScript", "Python"]}>

```ts tab="TypeScript"
const quote = await session.ship({
  action: "quote",
  origin: { postal_code: "01310100" },
  destination: { postal_code: "20040020" },
  items: [{ weight_grams: 500, length_cm: 20, width_cm: 15, height_cm: 5 }],
});

// Pick a quote, then generate a label:
const label = await session.ship({
  action: "label",
  service_level: quote.quotes[0].service_id,
  origin: { postal_code: "01310100", /* full address */ },
  destination: { postal_code: "20040020", /* full address */ },
  items: [{ weight_grams: 500, length_cm: 20, width_cm: 15, height_cm: 5 }],
});

console.log(label.tracking_code, label.label_url);
```

```python tab="Python"
quote = session.ship({
    "action": "quote",
    "origin": {"postal_code": "01310100"},
    "destination": {"postal_code": "20040020"},
    "items": [{"weight_grams": 500, "length_cm": 20, "width_cm": 15, "height_cm": 5}],
})

label = session.ship({
    "action": "label",
    "service_level": quote["quotes"][0]["service_id"],
    "origin": {"postal_code": "01310100"},
    "destination": {"postal_code": "20040020"},
    "items": [{"weight_grams": 500, "length_cm": 20, "width_cm": 15, "height_cm": 5}],
})
```

</Tabs>

## Direct execute

```ts
const tracking = await session.execute("codespar_ship", {
  action: "track",
  tracking_code: "BR123456789",
});
```

## Args shape

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `"label"` \| `"quote"` \| `"track"` | No | Defaults to `"label"` |
| `origin` | `object` | quote, label | `{ postal_code, address?, number?, city?, state? }` |
| `destination` | `object` | quote, label | Same shape as origin |
| `items` | `array` | quote, label | `[{ weight_grams, length_cm, width_cm, height_cm, insurance_value? }]` |
| `service_level` | `string` | label | Melhor Envio service id from a quote response |
| `tracking_code` | `string` | track | Carrier tracking code returned by `label` |
| `metadata` | `object` | No | Arbitrary key-value pairs |

## Result shape — varies by action

**`quote`:**

```ts
{
  quotes: Array<{
    carrier: string;        // "correios", "jadlog", "loggi"
    service_id: string;
    service_name: string;
    price_minor: number;    // BRL centavos
    estimated_days: number;
  }>;
}
```

**`label`:**

```ts
{
  tracking_code: string;
  label_url: string;        // PDF
  carrier: string;
  service_name: string;
  cost_minor: number;
}
```

**`track`:**

```ts
{
  tracking_code: string;
  carrier: string;
  status: "in_transit" | "out_for_delivery" | "delivered" | "exception";
  events: Array<{ timestamp: string; description: string; location?: string }>;
}
```

## Operator setup

- **Melhor Envio** — OAuth flow. Operator clicks Connect in `/dashboard/auth-configs`, redirects to Melhor Envio, picks the warehouse account, and authorizes. Sandbox vs production toggle in the modal.

Operator needs to fund the Melhor Envio wallet before `domestic-label` calls succeed; quotes work without a balance.

## See also

- [SDK reference](/docs/api/sdk#shipargs-promiseshipresult) — `session.ship()` typed wrapper
- [E-Commerce Checkout cookbook](/docs/cookbooks/ecommerce-checkout) — quote + label as part of fulfillment
- [Webhook Listener cookbook](/docs/cookbooks/webhook-listener) — trigger label generation on settlement
- [Tools & meta-tools](/docs/concepts/tools) — full meta-tool list