Correios Web Services API
Agent-ready OpenAPI document · curated by JenticE CommerceShipping Logisticsbasic, bearer15 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For 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.
Use for: Get the address details for CEP 01310-100, Calculate the shipping price from São Paulo to Rio de Janeiro for a 2 kg parcel, Estimate delivery time for a SEDEX shipment between two CEPs, Track a Correios shipment by its tracking code
Not supported: Does not handle international courier services, customs clearance, or multi-carrier comparison - use for Brazilian Correios postal pricing, tracking, and pre-postage only.
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.
Install Jentic One Beta
Connect the Correios Web Services API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Correios Web Services API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcorreios.com.br%2Fcorreios" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcorreios.com.br%2Fcorreios" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Correios Web Services API.
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
Patterns agents use Correios Web Services API for, with concrete tasks.
★ 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.
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.
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.
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.
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
15 endpoints — jentic publishes the only available openapi specification for correios web services api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Correios Web Services API through Jentic.
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.
GET STARTED