canonical: https://jentic.com/apis/correios.com.br/correios # Correios Web Services API Jentic publishes the only available OpenAPI specification for Correios Web Services API, keeping it validated and agent-ready. The Correios Web Services API integrates Brazil's national postal service into e-commerce and logistics workflows, exposing 15 endpoints for CEP postal-code lookup, shipping price and delivery time calculation, shipment tracking, and pre-postage label generation. Authentication uses a two-step flow: Basic auth against the token endpoint to obtain a bearer token, then bearer auth on the business endpoints. Service is split into Production (cws.correios.com.br) and Homologation environments for testing. ## For AI agents Look up Brazilian CEP postal codes, quote shipping prices and delivery times, track shipments, and generate pre-postage labels with the Correios Web Services API. Bearer-token authentication obtained via the `/token/v1/autentica` endpoint. ## Scope Does not handle international courier services, customs clearance, or multi-carrier comparison - use for Brazilian Correios postal pricing, tracking, and pre-postage only. ## Capabilities - Resolve a Brazilian CEP postal code to a structured address with street, neighbourhood, city, and state - Quote national shipping prices for a given service, weight, and origin-destination CEP pair before checkout - Estimate national delivery time by service code and origin-destination CEP for shipping promises on product pages - Track one shipment or a batch of shipments by their tracking codes and stream events to a customer-facing tracking page - Create, list, retrieve, and cancel pre-postages so warehouses can prepare shipments in bulk before drop-off - Download the printable shipping label (rotulo) for a confirmed pre-postage - Inspect Correios contract and postage card details for the authenticated CNPJ ## Use cases ### Checkout Shipping Quote and ETA When a Brazilian shopper enters their CEP at checkout, the storefront calls the Correios price and delivery time endpoints to quote freight cost and a delivery promise. CEP lookup pre-fills the address fields, the price endpoint returns the freight, and the delivery time endpoint produces the days-in-transit string shown next to the price. Example prompt: On CEP entry call GET `/cep/v2/enderecos/{cep}`, then POST `/preco/v1/nacional` and POST `/prazo/v1/nacional` with the cart's weight and dimensions to render quote plus ETA at checkout. ### Customer-Facing Shipment Tracking Power a self-serve tracking page where customers enter a tracking code and see a timeline of Correios scan events. The bulk-tracking endpoint also lets the merchant pre-fetch tracking for every open order on a daily schedule and notify customers of status changes. Example prompt: On the tracking page call GET `/rastro/v1/objetos/{codigoObjeto}`, render the events; on a daily cron call GET `/rastro/v1/objetos` with a list of open orders to detect status changes. ### Warehouse Pre-Postage Workflow Operations teams batch-create pre-postages overnight so the next morning's pickup is ready to go: each order is registered through the pre-postage endpoint, the printable label is fetched, and any cancelled order is removed before the carrier arrives. This keeps the warehouse and Correios in sync without manual portal entry. Example prompt: For each order call POST `/prepostagem/v1/prepostagens`, store the returned idPrePostagem, fetch GET `/prepostagem/v1/prepostagens/{idPrePostagem}/rotulo` to print the label, and DELETE `/prepostagem/v1/prepostagens/{idPrePostagem}` for any cancellation. ### AI Agent Brazil Shipping Assistant via Jentic An agent answers shopper or merchant questions like 'how much will it cost to send this 1.5 kg box from CEP 04567-001 to 88000-000 by SEDEX?' by searching Jentic for the Correios price operation, calling it with the right inputs, and returning the rate plus delivery time in plain language. The agent never needs to read Correios documentation. Example prompt: Search Jentic for 'calculate Correios shipping price', load POST `/preco/v1/nacional`, execute it with the requested weight and CEPs, then call POST `/prazo/v1/nacional` and combine the results into one answer. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/token/v1/autentica` | Exchange Basic credentials for a bearer token | | GET | `/cep/v2/enderecos/{cep}` | Look up an address by Brazilian postal code | | POST | `/preco/v1/nacional` | Calculate national shipping price | | POST | `/prazo/v1/nacional` | Calculate national delivery time | | GET | `/rastro/v1/objetos/{codigoObjeto}` | Track a single shipment | | POST | `/prepostagem/v1/prepostagens` | Create a pre-postage | | GET | `/prepostagem/v1/prepostagens/{idPrePostagem}/rotulo` | Download the printable shipping label | ## Key resources - **Authentication** — Obtain a bearer token via `/token/v1/autentica` using Basic auth, optionally scoped to a postage card. - **CEP** — Look up Brazilian addresses by postal code (CEP). - **Price** — Quote national shipping prices for given service, weight, and route. - **Delivery Time** — Estimate or fetch national delivery times by service and route. - **Tracking** — Track one or many Correios shipments by tracking code. - **Pre-Postage** — Create, list, fetch, cancel, and download labels for pre-postages. - **Contract** — Inspect contract and postage card details for the authenticated CNPJ. ## Why Jentic - **Setup:** Wiring Correios by hand means posting your username and access code to `/token/v1/autentica`, carrying the returned bearer token, refreshing it as it expires, and choosing the right host between production and homologation. Through Jentic you install once, import the Correios Web Services API from the API Directory, store the credentials once, and your agent calls it. - **Permission scoping:** Correios pricing, tracking, and pre-postage operations carry their targets in the request, so scope this by operations: allow the agent the calls it needs, such as calculating a shipping price and tracking an object, and leave pre-postage creation and label generation out unless you add them. Each operation you credit the agent with stays inside that allowed set. - **Credential handling:** Your Correios username and access code are stored once, encrypted, by your own Jentic One instance, which exchanges them for a bearer token and refreshes it at execution time. Neither secret enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'calculate a Correios shipping price' or 'track a Correios shipment', and Jentic returns the matching operation with its input and response schemas so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **FedEx API** — Global courier API covering rating, shipping, and tracking outside Brazil's domestic postal network. - **DHL Shipment Tracking Unified API** — DHL's unified tracking API for international shipments handed off from local carriers. - **AfterShip API** — Multi-carrier tracking aggregator that can normalise Correios events alongside other carriers. ## FAQ ### Why is there no official OpenAPI spec for Correios Web Services API? Correios does not publish a single OpenAPI specification covering all of its web services. Jentic generates and maintains this spec so that AI agents and developers can call Correios Web Services API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Correios Web Services API use? The API uses a two-step flow. Call POST `/token/v1/autentica` with HTTP Basic auth (username or CNPJ plus access code) to receive a bearer token, then send that token in the Authorization: Bearer header on every business endpoint. Through Jentic, both credentials are stored encrypted and the bearer token is refreshed automatically. ### Can I look up a Brazilian address by CEP with this API? Yes. GET `/cep/v2/enderecos/{cep}` returns the structured address - street, neighbourhood, city, and state - for a given CEP, which is the canonical primitive for any Brazilian shipping or address-validation flow. ### How do I track multiple shipments in one call? Use GET `/rastro/v1/objetos` with a list of tracking codes as query parameters. This is the recommended path for daily batch jobs that refresh tracking status for every open order rather than calling the single-object endpoint repeatedly. ### What are the rate limits for the Correios Web Services API? The OpenAPI spec does not declare numeric rate limits. Treat HTTP 429 responses as authoritative, back off using the Retry-After header where present, and confirm contract-specific limits with Correios before high-volume jobs. ### How do I generate a shipping label through Jentic? Search Jentic for 'create Correios pre-postage', execute POST `/prepostagem/v1/prepostagens` with the parcel and recipient details, then load and execute GET `/prepostagem/v1/prepostagens/{idPrePostagem}/rotulo` to fetch the printable label. ### Can I limit what my agent is allowed to do with the Correios Web Services API? Yes. Because you self-host Jentic One, your own rules decide which Correios operations and credentials the agent may use, and every Correios call carries its target in the request. You can allow only the operations the agent needs, such as calculating a shipping price with POST `/preco/v1/nacional` and tracking an object with GET `/rastro/v1/objetos/{codigoObjeto}`, while leaving pre-postage creation and label generation out unless you add them. Each operation you credit the agent with stays inside that allowed set, so it never calls an endpoint you have not approved.