// docs
Extrai cotacoes de frete dos Correios por CEP de origem, CEP de destino e dimensoes do pacote, retornando opcoes como Sedex e PAC com prazo e preco.
Nota importante: alguns campos podem retornar null em produção,
dependendo da página de origem. Consulte o schema e a descrição de cada campo
para tratar valores ausentes; os exemplos mostram uma resposta possível.
Quando a entidade consultada não existe na origem, o extract e a tool MCP retornam
200 com data: null e
notFound: true. Esse caso é tratado como resposta concluída,
não como erro de servidor.
curl -X POST https://api.geckoapi.com.br/v1/extract \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"target": "correios.com.br",
"type": "quote",
"originZipCode": "01001-000",
"destinationZipCode": "20040-002",
"packageHeightCm": 10,
"packageWidthCm": 15,
"packageLengthCm": 20
}'
A mesma seam também aparece no MCP hospedado como uma tool dedicada.
Os argumentos reaproveitam os campos do extract, mas target e type
já ficam fixos pela tool.
Endpoint
POST /v1/mcp
Tool name
correios_com_br_quote
Auth
Bearer ou X-API-Key
{
"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"
}
}
}
Campos suportados nesta API do POST /v1/extract,
com regras específicas de obrigatoriedade e condicionais.
| Campo | Tipo | Status | Regra | Default | Exemplo |
|---|---|---|---|---|---|
| originZipCode CEP de origem usado na cotacao de frete dos Correios. A API aceita com ou sem hifen e normaliza para 8 digitos. | string (CEP) | Obrigatório | CEP de origem no formato 00000-000 ou 8 digitos. | - | 01001-000 |
| destinationZipCode CEP de destino usado na cotacao de frete dos Correios. A API aceita com ou sem hifen e normaliza para 8 digitos. | string (CEP) | Obrigatório | CEP de destino no formato 00000-000 ou 8 digitos. | - | 20040-002 |
| packageHeightCm Altura do pacote em centimetros para a cotacao de frete dos Correios. | integer (1-100) | Obrigatório | Altura em centimetros. A calculadora publica dos Correios aceita valores entre 1 e 100. | - | 10 |
| packageWidthCm Largura do pacote em centimetros para a cotacao de frete dos Correios. | integer (8-100) | Obrigatório | Largura em centimetros. A calculadora publica dos Correios aceita valores entre 8 e 100. | - | 15 |
| packageLengthCm Comprimento do pacote em centimetros para a cotacao de frete dos Correios. | integer (13-100) | Obrigatório | Comprimento em centimetros. A calculadora publica dos Correios aceita valores entre 13 e 100. | - | 20 |
| target Fonte alvo da extração. | enum | Obrigatório | Sempre obrigatorio e deve ser correios.com.br. | - | correios.com.br |
| type Tipo da extração: pdp, idp, plp, ilp, quote, review ou places. | enum | Obrigatório | Sempre obrigatorio e deve ser quote. | - | quote |
Calcula Sedex e PAC para um pacote padrao com origem em Sao Paulo e destino no Rio.
{
"target": "correios.com.br",
"type": "quote",
"originZipCode": "01001-000",
"destinationZipCode": "20040-002",
"packageHeightCm": 10,
"packageWidthCm": 15,
"packageLengthCm": 20
}Usa as medidas minimas aceitas pela calculadora publica dos Correios.
{
"target": "correios.com.br",
"type": "quote",
"originZipCode": "30130-010",
"destinationZipCode": "80010-000",
"packageHeightCm": 1,
"packageWidthCm": 8,
"packageLengthCm": 13
}Mapa de paths de saída com tipo esperado para esta API.
{
"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"
}{
"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 | Tipo | Descrição | Exemplo |
|---|---|---|---|
| data.destinationZipCode | string | CEP de destino normalizado para 8 digitos. | 20040002 |
| data.extractedAt | string (iso datetime) | Timestamp UTC da extracao. | 2026-04-16T00:00:00.000Z |
| data.options[].currency | string | Moeda dos valores retornados. | BRL |
| data.options[].deliveryTimeText | string | Prazo textual informado pelo upstream. | 1 dia util |
| data.options[].imageUrl | string | Imagem associada ao servico retornada pelo upstream. | https://www.correios.com.br/estrutura-da-pagina/precos-e-prazos/imagens/sedex.png |
| data.options[].message | string | Mensagem adicional associada ao servico. | Disponivel |
| data.options[].messageDeliveryTime | string | Legenda usada pelo upstream para o prazo. | Prazo de entrega |
| data.options[].messagePriceAgency | string | Legenda usada pelo upstream para o preco em agencia. | Postagem nas agencias |
| data.options[].messagePriceAppOrSite | string | Legenda usada pelo upstream para o preco no app/site. | Postagem no App ou site dos Correios |
| data.options[].priceAgency | number | Preco numerico para postagem em agencia. | 43 |
| data.options[].priceAgencyText | string | Preco textual para postagem em agencia. | R$ 43,00 |
| data.options[].priceAppOrSite | number | Preco numerico para postagem no app/site. | 31.56 |
| data.options[].priceAppOrSiteText | string | Preco textual para postagem no app/site. | R$ 31,56 |
| data.options[].rawTitle | string | Titulo bruto do servico retornado pelo upstream. | Sedex a encomenda expressa dos Correios |
| data.options[].serviceCodeAgency | string | Codigo do produto para postagem em agencia. | 04014 |
| data.options[].serviceCodeAppOrSite | string | Codigo do produto para postagem no app/site dos Correios. | 41955 |
| data.options[].serviceName | string | Nome simplificado do servico (ex: Sedex, PAC). | Sedex |
| data.options[].status | number | Status retornado pelo item da calculadora dos Correios. | 200 |
| data.originZipCode | string | CEP de origem normalizado para 8 digitos. | 01001000 |
| data.packageHeightCm | number | Altura do pacote usada na consulta. | 10 |
| data.packageLengthCm | number | Comprimento do pacote usado na consulta. | 20 |
| data.packageWidthCm | number | Largura do pacote usada na consulta. | 15 |
| data.parser | "1.0.0" | Versão estável do formato de resposta da API. | 1.0.0 |
| data.requestUrl | string | Mesmo valor de `data.url`; nunca expõe o endpoint interno consultado. | https://www.correios.com.br/@@precosEPrazosView |
| data.source | string | Fonte da extracao. | correios.com.br |
| data.totalOptions | number | Quantidade total de opcoes de frete retornadas. | 2 |
| data.type | string | Tipo da extracao. | quote |
| data.url | string | Endpoint canonico usado para consultar a calculadora publica dos Correios. | https://www.correios.com.br/@@precosEPrazosView |
| executionId | string (uuid) | Campo executionId retornado no payload de resposta. | 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) | Campo requestId retornado no payload de resposta. | 34e5db41-d7cb-44c0-9e41-84031fc30001 |
Respostas com notFound: true não entram nesta tabela,
porque retornam sucesso HTTP 200.
| Status | errorCode | Quando acontece |
|---|---|---|
| 400 | INVALID_PAYLOAD | JSON inválido ou violação das regras de validação do payload. |
| 401 | UNAUTHORIZED | Header Authorization ausente ou token/chave inválida. |
| 402 | INSUFFICIENT_CREDITS | Saldo de créditos insuficiente para a API solicitada. |
| 403 | FORBIDDEN | Usuário sem acesso ou API temporariamente desabilitada. |
| 409 | EXECUTION_CONFLICT | executionId conflita com uma execução em estado incompatível. |
| 429 | RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS | Limite de taxa ou limite de requisições em voo excedido. |
| 5xx | UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_INVOCATION_FAILED / WORKER_FUNCTION_ERROR / WORKER_INVALID_RESPONSE / INTERNAL_ERROR | Falha de servidor no worker, provider/proxy ou gateway. Nesses casos os créditos são estornados automaticamente. |