Como obter dados de frete via API com endpoint dos Correios

Se você precisa obter dados de frete via API, o ponto central não é apenas “consultar um preço”. Na prática, produtos de e-commerce, ERPs, hubs logísticos, marketplaces e agentes de IA precisam de um endpoint de frete que devolva dados estruturados, previsíveis e fáceis de integrar.

É exatamente esse o papel da API de frete dos Correios na GeckoAPI: transformar a calculadora pública de frete em um payload amigável para sistemas, com CEP de origem, CEP de destino, dimensões do pacote, prazo de entrega, preço do Sedex, preço do PAC e outros campos úteis em JSON.

Se o seu objetivo é montar uma cotação de frete via API, automatizar checkout, alimentar BI logístico ou expor dados de prazo e preço em um app, este guia mostra o que você precisa saber.

O que são dados de frete via API

Quando alguém busca por dados de frete via API, normalmente quer acessar programaticamente informações como:

Preço do frete por serviço
Prazo de entrega por serviço
Opções disponíveis como Sedex e PAC
Códigos dos serviços usados no app/site ou na agência
CEP de origem e destino normalizados
Valores prontos para uso em checkout, ERP ou automação

Em vez de depender de uma interface visual, você consome um endpoint HTTP e recebe um JSON estruturado. Isso facilita muito a vida de times de produto, engenharia, operações e growth.

Por que usar um endpoint de frete em vez de scraping manual

Muita gente ainda tenta resolver isso com scraping do site, automação de navegador ou lógica acoplada ao front-end. O problema é que isso vira manutenção constante.

Os gargalos mais comuns são:

Mudança de layout da página pública
Respostas pouco amigáveis para API
Dificuldade para padronizar o retorno
Mais trabalho para transformar HTML em JSON confiável
Dependência de um fluxo visual para um problema que deveria ser sistêmico

Se você já passou por esse cenário, vale comparar com a abordagem de API pronta no post Web Scraping vs API Pronta.

Quando faz sentido consultar frete por API

Uma API de frete dos Correios faz sentido em cenários como:

Checkout de e-commerce com simulação de prazo e preço
Marketplaces e sellers que precisam calcular frete sob demanda
ERPs e hubs logísticos com enriquecimento de pedidos
Automação comercial que precisa estimar custo de envio antes da venda
BI logístico para monitorar faixas de preço e prazo por rota
Chatbots e agentes de IA que respondem perguntas sobre envio com dados reais

Em todos esses casos, a vantagem não é só “ver o valor do frete”. A vantagem é ter um endpoint estável, pensado para máquina, não para navegação humana.

Como funciona a API de frete dos Correios na GeckoAPI

Na GeckoAPI, a integração é feita pelo endpoint:

POST https://api.geckoapi.com.br/v1/extract

Para o caso dos Correios, o payload é API-friendly. Você nao precisa mandar URL manual nem reproduzir a navegação do site. Basta enviar:

target
type
originZipCode
destinationZipCode
packageHeightCm
packageWidthCm
packageLengthCm

Ou seja: em vez de montar scraping, você informa só os dados que seu sistema já possui.

Exemplo de chamada para obter frete dos Correios via API

curl -X POST \
  -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
  }' \
  https://api.geckoapi.com.br/v1/extract

Esse request consulta o endpoint dos Correios a partir de um payload limpo e devolve as opções de frete em JSON.

Se você quiser ver a documentação técnica completa, ela está em:

Exemplo de resposta JSON com Sedex e PAC

{
  "requestId": "34e5db41-d7cb-44c0-9e41-84031fc30001",
  "executionId": "34e5db41-d7cb-44c0-9e41-84031fc30002",
  "data": {
    "source": "correios.com.br",
    "type": "quote",
    "originZipCode": "01001000",
    "destinationZipCode": "20040002",
    "packageHeightCm": 10,
    "packageWidthCm": 15,
    "packageLengthCm": 20,
    "totalOptions": 2,
    "options": [
      {
        "serviceName": "Sedex",
        "deliveryTimeText": "1 dia util",
        "priceAppOrSite": 31.56,
        "priceAgency": 43,
        "currency": "BRL"
      },
      {
        "serviceName": "PAC",
        "deliveryTimeText": "5 dias uteis",
        "priceAppOrSite": 21.46,
        "priceAgency": 27.5,
        "currency": "BRL"
      }
    ]
  }
}

Na prática, isso significa que seu sistema consegue:

mostrar Sedex e PAC lado a lado
comparar prazo vs preço
distinguir preço no app/site e preço em agência
guardar um histórico de cotação em banco ou data warehouse

Campos de entrada pensados para integracao

Uma das vantagens da GeckoAPI é que o endpoint dos Correios foi desenhado para uso via sistema. O foco não é copiar a UI pública, e sim expor um contrato simples.

Campo	O que representa
`originZipCode`	CEP de origem
`destinationZipCode`	CEP de destino
`packageHeightCm`	Altura do pacote em cm
`packageWidthCm`	Largura do pacote em cm
`packageLengthCm`	Comprimento do pacote em cm

Regras importantes do endpoint:

originZipCode e destinationZipCode aceitam CEP com ou sem hífen
packageHeightCm aceita valores de 1 a 100
packageWidthCm aceita valores de 8 a 100
packageLengthCm aceita valores de 13 a 100
url não é suportada nesse seam, porque o backend resolve a URL canônica automaticamente

Esse detalhe é importante para quem busca uma API de frete amigável para desenvolvedor: você integra com os campos do seu domínio, e não com uma URL externa frágil.

Exemplo em JavaScript

const response = await fetch("https://api.geckoapi.com.br/v1/extract", {
  method: "POST",
  headers: {
    Authorization: "Bearer SUA_CHAVE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    target: "correios.com.br",
    type: "quote",
    originZipCode: "01001-000",
    destinationZipCode: "20040-002",
    packageHeightCm: 10,
    packageWidthCm: 15,
    packageLengthCm: 20,
  }),
});

const payload = await response.json();
const options = payload.data.options;

console.log(options);

Exemplo em Python

import requests

response = requests.post(
    "https://api.geckoapi.com.br/v1/extract",
    headers={
        "Authorization": "Bearer SUA_CHAVE",
        "Content-Type": "application/json",
    },
    json={
        "target": "correios.com.br",
        "type": "quote",
        "originZipCode": "01001-000",
        "destinationZipCode": "20040-002",
        "packageHeightCm": 10,
        "packageWidthCm": 15,
        "packageLengthCm": 20,
    },
)

payload = response.json()

for option in payload["data"]["options"]:
    print(option["serviceName"], option["priceAppOrSite"], option["deliveryTimeText"])

O que dá para construir com dados de frete em JSON

Quando você passa a ter dados de frete em JSON via endpoint, abre espaço para várias automações:

1. Simulador de frete no checkout

Você consulta o endpoint assim que o usuário informa CEP e dimensões do pacote, e renderiza a lista de opções com prazo e preço.

2. Motor de roteamento e comparação

Você usa os Correios como baseline e compara com outras transportadoras ou regras internas.

3. BI de logística

Com as cotações armazenadas, dá para analisar:

variação de preço por faixa de CEP
rotas com maior prazo
diferença entre app/site e agência
impacto de dimensão no custo final

4. ERP ou OMS

Seu sistema pode enriquecer pedidos com custo estimado de envio sem depender de fluxo manual.

5. Agentes e assistentes

Um agente de IA pode responder perguntas como:

“Quanto custa enviar esse pacote para o Rio?”
“Qual opção chega mais rápido?”
“PAC ou Sedex vale mais a pena para esse pedido?”

Tudo isso com dados consultados em tempo real, e não com resposta inventada.

SEO tecnico: por que isso importa para times de produto

Muita busca por API de frete, endpoint de frete, cotação de frete por API e API dos Correios vem de times que já sabem o problema, mas ainda estão presos em soluções frágeis.

Os sinais de que você precisa sair do modo manual são claros:

seu time mantém scraping só para calcular frete
a lógica de cotação está espalhada no front-end
você precisa alimentar CRM, ERP, OMS e BI com os mesmos dados
quer integrar frete em chatbot, app ou automação sem reinventar parsing

Nesses casos, o ganho real vem de padronizar a integração em um endpoint único.

Perguntas frequentes sobre API de frete dos Correios

Como consultar frete dos Correios por API?

Faça um POST em https://api.geckoapi.com.br/v1/extract com target: "correios.com.br", type: "quote" e os campos de CEP e dimensões do pacote.

Dá para obter Sedex e PAC no mesmo request?

Sim. A resposta retorna data.options[] com as opções disponíveis, incluindo serviços como Sedex e PAC, com prazo e preço.

Preciso mandar uma URL dos Correios?

Não. Esse endpoint foi desenhado para ser mais fácil de integrar. Você manda apenas origem, destino e dimensões. O backend resolve a URL canônica.

Essa API serve para checkout e ERP?

Sim. Esse é justamente um dos melhores usos: checkout, ERP, OMS, CRM, BI logístico e automações comerciais.

Onde vejo a documentação do endpoint de frete?

Você pode acessar:

Resumo

Se você quer obter dados de frete via API, o caminho mais eficiente é integrar com um endpoint que já devolve os dados em formato amigável para sistema.

Com a GeckoAPI para Correios, você consegue:

consultar prazo e preço de frete
comparar Sedex e PAC
integrar com checkout, ERP, BI e agentes
evitar scraping manual de uma interface pública
trabalhar com JSON padronizado

Quer testar a API de frete dos Correios? Acesse a landing da API dos Correios, veja a documentação do endpoint ou crie sua conta em dashboard.geckoapi.com.br.