// docs
Extracts shipping quotes from Correios by origin CEP, destination CEP and package dimensions, returning options such as Sedex and PAC with deadline and price.
correios.com.br:quote · 1 credit per request
Standard credit cost. Your account pricing is shown in the sandbox.
Try this operation in the sandbox
curl -X POST https://api.geckoapi.com.br/v1/extract \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": "correios.com.br",
"type": "quote",
"originZipCode": "01001-000",
"destinationZipCode": "20040-002",
"packageHeightCm": 10,
"packageWidthCm": 15,
"packageLengthCm": 20
}'Keep your API key on your server. See the quickstart for authentication and response handling.
The hosted MCP tool fixes target and type for this operation. Its remaining arguments use the same input rules as Extract.
POST /v1/mcp · Bearer or X-API-Key authentication
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "correios_com_br_quote",
"arguments": {
"originZipCode": "01001-000",
"destinationZipCode": "20040-002",
"packageHeightCm": 10,
"packageWidthCm": 15,
"packageLengthCm": 20,
"executionId": "exec_example_123"
}
}
}Conditional fields depend on the alternatives and constraints in the rule column. Fields marked unsupported are omitted.
| Field | Type | Requirement | Rule | Default | Example |
|---|---|---|---|---|---|
| originZipCode CEP used in the freight quote for Correios. API accepts with or without a hyphen and normalizes to 8 digits. | string (CEP) | Required | CEP in the format 00000-000 or 8 digits. | - | 01001-000 |
| destinationZipCode Destination CEP used in the freight quote for Correios. API accepts with or without a hyphen and normalizes to 8 digits. | string (CEP) | Required | Target CEP in the format 00000-000 or 8 digits. | - | 20040-002 |
| packageHeightCm Package height in centimeters for the Correios shipping quote. | integer (1-100) | Required | Height in centimeters. The public Correios calculator accepts values between 1 and 100. | - | 10 |
| packageWidthCm Package width in centimeters for the Correios shipping quote. | integer (8-100) | Required | Width in centimeters. The public Correios calculator accepts values between 8 and 100. | - | 15 |
| packageLengthCm Package length in centimeters for the Correios shipping quote. | integer (13-100) | Required | Length in centimeters. The public Correios calculator accepts values between 13 and 100. | - | 20 |
| target Target source for extraction. | enum | Required | Always mandatory and must be correios.com.br. | - | correios.com.br |
| type Extraction type: pdp, idp, plp, ilp, quote, review or places. | enum | Required | Always mandatory and must be quote. | - | quote |
Calculates Sedex and PAC for a standard package originating in Sao Paulo and ending in Rio.
{
"target": "correios.com.br",
"type": "quote",
"originZipCode": "01001-000",
"destinationZipCode": "20040-002",
"packageHeightCm": 10,
"packageWidthCm": 15,
"packageLengthCm": 20
}Uses the minimum measurements accepted by the Correios public calculator.
{
"target": "correios.com.br",
"type": "quote",
"originZipCode": "30130-010",
"destinationZipCode": "80010-000",
"packageHeightCm": 1,
"packageWidthCm": 8,
"packageLengthCm": 13
}Leaf paths and expected types. Field names and enum values are part of the API contract.
{
"requestId": "string (uuid)",
"executionId": "string (uuid)",
"notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
"data.source": "string",
"data.type": "string",
"data.parser": "\"1.0.0\"",
"data.url": "string",
"data.requestUrl": "string",
"data.extractedAt": "string (iso datetime)",
"data.originZipCode": "string",
"data.destinationZipCode": "string",
"data.packageHeightCm": "number",
"data.packageWidthCm": "number",
"data.packageLengthCm": "number",
"data.totalOptions": "number",
"data.options[].status": "number",
"data.options[].serviceName": "string",
"data.options[].rawTitle": "string",
"data.options[].serviceCodeAppOrSite": "string",
"data.options[].serviceCodeAgency": "string",
"data.options[].deliveryTimeText": "string",
"data.options[].priceAppOrSiteText": "string",
"data.options[].priceAgencyText": "string",
"data.options[].priceAppOrSite": "number",
"data.options[].priceAgency": "number",
"data.options[].currency": "string",
"data.options[].imageUrl": "string",
"data.options[].messagePriceAppOrSite": "string",
"data.options[].messagePriceAgency": "string",
"data.options[].messageDeliveryTime": "string",
"data.options[].message": "string"
}Illustrative response. Product names, reviews and other source content retain their original language. Missing and null values do not imply zero stock, free shipping or zero reviews.
{
"requestId": "34e5db41-d7cb-44c0-9e41-84031fc30001",
"executionId": "34e5db41-d7cb-44c0-9e41-84031fc30002",
"data": {
"source": "correios.com.br",
"type": "quote",
"parser": "1.0.0",
"url": "https://www.correios.com.br/@@precosEPrazosView",
"requestUrl": "https://www.correios.com.br/@@precosEPrazosView",
"extractedAt": "2026-04-16T00:00:00.000Z",
"originZipCode": "01001000",
"destinationZipCode": "20040002",
"packageHeightCm": 10,
"packageWidthCm": 15,
"packageLengthCm": 20,
"totalOptions": 2,
"options": [
{
"status": 200,
"serviceName": "Sedex",
"rawTitle": "Sedex a encomenda expressa dos Correios",
"serviceCodeAppOrSite": "41955",
"serviceCodeAgency": "04014",
"deliveryTimeText": "1 dia util",
"priceAppOrSiteText": "R$ 31,56",
"priceAgencyText": "R$ 43,00",
"priceAppOrSite": 31.56,
"priceAgency": 43,
"currency": "BRL",
"imageUrl": "https://www.correios.com.br/estrutura-da-pagina/precos-e-prazos/imagens/sedex.png",
"messagePriceAppOrSite": "Postagem no App ou site dos Correios",
"messagePriceAgency": "Postagem nas agencias",
"messageDeliveryTime": "Prazo de entrega",
"message": "Disponivel"
},
{
"status": 200,
"serviceName": "PAC",
"rawTitle": "PAC a encomenda economica dos Correios",
"serviceCodeAppOrSite": "03395",
"serviceCodeAgency": "04510",
"deliveryTimeText": "5 dias uteis",
"priceAppOrSiteText": "R$ 21,46",
"priceAgencyText": "R$ 27,50",
"priceAppOrSite": 21.46,
"priceAgency": 27.5,
"currency": "BRL",
"imageUrl": "https://www.correios.com.br/estrutura-da-pagina/precos-e-prazos/imagens/pac.png",
"messagePriceAppOrSite": "Postagem no App ou site dos Correios",
"messagePriceAgency": "Postagem nas agencias",
"messageDeliveryTime": "Prazo de entrega",
"message": "Disponivel"
}
]
}
}| Path | Type | Description | Example |
|---|---|---|---|
| data.destinationZipCode | string | CEP normalized to 8 digits. | 20040002 |
| data.extractedAt | string (iso datetime) | Extraction timestamp UTC. | 2026-04-16T00:00:00.000Z |
| data.options[].currency | string | Currency of returned values. | BRL |
| data.options[].deliveryTimeText | string | Textual deadline informed by upstream. | 1 dia util |
| data.options[].imageUrl | string | Image associated with the service returned by upstream. | https://www.correios.com.br/estrutura-da-pagina/precos-e-prazos/imagens/sedex.png |
| data.options[].message | string | Additional message associated with the service. | Disponivel |
| data.options[].messageDeliveryTime | string | Caption used by upstream for the deadline. | Prazo de entrega |
| data.options[].messagePriceAgency | string | Legend used by upstream for agency pricing. | Postagem nas agencias |
| data.options[].messagePriceAppOrSite | string | Caption used by upstream for pricing on the app/website. | Postagem no App ou site dos Correios |
| data.options[].priceAgency | number | Numerical price for posting to an agency. | 43 |
| data.options[].priceAgencyText | string | Textual price for posting at an agency. | R$ 43,00 |
| data.options[].priceAppOrSite | number | Numerical price for posting on the app/website. | 31.56 |
| data.options[].priceAppOrSiteText | string | Textual price for posting on the app/website. | R$ 31,56 |
| data.options[].rawTitle | string | Raw service title returned by upstream. | Sedex a encomenda expressa dos Correios |
| data.options[].serviceCodeAgency | string | Product code for agency posting. | 04014 |
| data.options[].serviceCodeAppOrSite | string | Product code for posting on the Correios app/website. | 41955 |
| data.options[].serviceName | string | Simplified name of the service (ex: Sedex, PAC). | Sedex |
| data.options[].status | number | Status returned by the Correios calculator item. | 200 |
| data.originZipCode | string | Source CEP normalized to 8 digits. | 01001000 |
| data.packageHeightCm | number | Package height used in the query. | 10 |
| data.packageLengthCm | number | Length of the packet used in the query. | 20 |
| data.packageWidthCm | number | Packet width used in the query. | 15 |
| data.parser | "1.0.0" | Stable version of the API response format. | 1.0.0 |
| data.requestUrl | string | Same value as `data.url`; never exposes the queried internal endpoint. | https://www.correios.com.br/@@precosEPrazosView |
| data.source | string | Extraction source. | correios.com.br |
| data.totalOptions | number | Total quantity of shipping options returned. | 2 |
| data.type | string | Extraction type. | quote |
| data.url | string | Canonical endpoint used to consult the Correios public calculator. | https://www.correios.com.br/@@precosEPrazosView |
| executionId | string (uuid) | Field executionId returned in the response payload. | 34e5db41-d7cb-44c0-9e41-84031fc30002 |
| notFound | boolean (optional; true when the upstream entity was not found and data is null) | Present and true when the upstream entity was not found. In this case data is null and the request still completes successfully. | N/A |
| requestId | string (uuid) | Field requestId returned in the response payload. | 34e5db41-d7cb-44c0-9e41-84031fc30001 |
When supported by this operation, an entity not found upstream can return HTTP 200 with data: null and notFound: true. Check the documented response fields before interpreting an empty result. Source-specific behavior and exceptions are described above.
| HTTP status | Error code | Meaning |
|---|---|---|
| 400 | INVALID_PAYLOAD | Invalid JSON or a request that violates the documented validation rules. |
| 401 | UNAUTHORIZED | Missing authorization or an invalid API key or token. |
| 402 | INSUFFICIENT_CREDITS | The account has insufficient credits for this operation. |
| 403 | FORBIDDEN | The account does not have access, or the API is temporarily disabled. |
| 409 | EXECUTION_CONFLICT | The execution identifier conflicts with an incompatible execution state. |
| 429 | RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS | A rate limit or simultaneous request limit was exceeded. |
| 5xx | UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERROR | An upstream, worker or gateway failure. Failed requests follow the platform refund policy. |