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

codespar_ship

Meta-tool

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.

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

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);

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}],
})

Direct execute

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:

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

label:

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

track:

{
  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.

codespar_ship

codespar_ship

Rails

Typed wrapper

Direct execute

Args shape

Result shape — varies by action

Operator setup

See also

On this page