Manual - API Prazo

Sumário

1. Apresentação

1.1 Objetivo do manual

Este manual tem como objetivo apresentar a API de prazos de entrega dos Correios, quais são as especificações e critérios técnicos para seu consumo, caminhos, dados de retorno e fluxo ideal de consulta dos prazos corretamente.

1.2 Escopo da API

A API Prazo é restrita, sendo liberada somente para clientes de contrato, que devem ter cadastrados em seu contrato, o código de serviço 38210 API PRAZOS. Sem este cadastro, ao tentar consumir a API, será retornado erro de API restrita.

1.3 Público alvo

  • Clientes de contrato com os Correios na modalidade a faturar.
  • Lojas virtuais e outros sistemas que desejam exibir de forma rápida e confiável, o prazo de entrega das encomendas enviadas por meios dos Correios, nas diversas modalidades de entrega fornecidas pela empresa.

2. Visão Geral da API

A API de prazos permite a solicitação de cálculo de prazo, em dias corridos, da entrega de objetos nacionais e internacionais. Para objetos nacionais, ainda é possível calcular a data prevista de entrega dos objetos.

2.1 Finalidade da API

Exibir o prazo da entrega de objetos nacionais e internacionais, de acordo com os dados informados pelo solicitante.

2.2 Funcionalidades Principais

  • Prazo de Entrega Nacional;
  • Prazo de Entrega Internacional;
  • Data Prevista de entrega.

2.3 Arquitetura e Tecnologias Utilizadas

A Arquitetura utilizada é RESTful. Os retornos são em formato JSON. Os acessos são realizados via HTTP (GET e POST).

A arquitetura utilizada é RESTful. Este padrão de mercado permite escolher ou adotar qual a linguagem de programação que preferir, tais como: ASP, .Net, Java, PHP, Ruby, Python, entre outras.

Entre outras características, os atributos que mais se destacam na API são:

  • Ausência de aplicativos proprietários: Para utilizar a API não há necessidade de instalação de um ambiente específico.
  • Simplicidade: O protocolo utilizado é puramente o HTTPS.
  • Credenciais: O tratamento das credenciais do cliente trafega em ambiente seguro.

2.4 Fluxo Geral de Integração

API Correios - Prazo - Figura 01.png

  1. Pré-requisitos
  2. Autenticação
    • Gerar token de acesso:
    • Autenticação via cartão de postagem.
    • Utilizar endpoint de autenticação fornecido pelo CWS.
    • Armazenar o token com segurança armazenando o prazo de validade.
  3. Identificação da Necessidade
    • Definir o tipo de consulta: Nacional, Internacional, Serviços Adicionais.
  4. Consumo da API
    • Acessar o endpoint da API Preço correspondente à necessidade:
    • Enviar os parâmetros obrigatórios (CEP origem/destino, código de serviço, etc.).
    • Incluir o token de acesso no cabeçalho da requisição.
  5. Tratamento de Retorno
    • Verificar o status HTTP da resposta.
    • Tratar mensagens de erro: Token inválido ou expirado, Parâmetros incorretos, Serviço não disponível para a origem e destino.
    • Interpretar os dados retornados: Prazo de entrega, Serviços adicionais aplicáveis.
  6. Ambiente de Produção
    • Após testes em homologação, migrar para o ambiente de produção:
    • Atualizar URLs dos endpoints.
    • Gerar token de produção.
    • Validar novamente os serviços vinculados ao contrato.

3. Autenticação e Autorização

3.1 Métodos de Autenticação Suportados

O modo de autenticação da API é Bearer Token.

3.2 Obtenção de Credenciais

Para obter um token de acesso, pode-se utilizar a API Token (5), endpoint “/token/v1/autentica/cartaopostagem” ou uma chave de sub-delegação de acesso, método em que um usuário pessoa jurídica delega o acesso à uma ou mais APIs criando uma chave de acesso.

3.3 Escopos e permissões

A API de prazos está disponível somente para clientes de contrato com os Correios na modalidade a faturar.

Caso a API não esteja disponível, solicitar a sua liberação junto a gestão comercial do Correios. Esta liberação ocorrerá mediante cadastro de serviço específico no seu contrato.

3.4 Exemplo de Requisição Autenticada

Exemplo cURL de requisição POST:

Exemplo cURL de requisição POST
Figura 2 – Requisição POST cURL

Exemplo de cURL de requisição GET:

Exemplo cURL de requisição GET para /v1/nacional/{coProduto}
Figura 3 – Requisição GET cURL

4. Padrões Técnicos utilizados

4.1 Formato das Requisições e Respostas

Os retornos da API, independentemente do verbo utilizado, se dão em formato JSON.

As requisições de consulta (GET), têm o envio dos parâmetros diretamente na URL de consulta, com estes parâmetros variando de acordo com o endpoint consumido.

4.2 Endpoints

URL Base:

Verbos:

  • GET - Consulta
  • POST – Cria lista

Limites de Requisições (Rate Limit) e bloqueio de acesso:

O acesso às APIs é limitado a 150 requisições por segundo por usuário e IP.

Isso implica que o mesmo usuário, se utilizar mais de um IP, tem essa limitação por IP (dois IPs permitem 300 requisições, 150 por IP).

4.3 Códigos de Status HTTP e Tratamento de Erros

Toda requisição que é enviada para o servidor retorna um código de status. Esses códigos são divididos em cinco famílias: 1xx, 2xx, 3xx, 4xx e 5xx.

Alguns dos códigos mais importantes e mais utilizados são:

2xx (Códigos de Sucesso)

  • 200 – OK: Indica que a operação indicada teve sucesso.
  • 201 – Created: Indica que o recurso desejado foi criado com sucesso. Deve retornar um cabeçalho Location, que deve conter a URL onde o recurso recém-criado está disponível.
  • 202 – Accepted: Indica que a solicitação foi recebida e será processada em outro momento. É tipicamente utilizada em requisições assíncronas, que não serão processadas em tempo real. Por esse motivo, pode retornar um cabeçalho Location.
  • 204 – No Content: Usualmente enviado em resposta a uma requisição PUT, POST ou DELETE, onde o servidor pode recusar-se a enviar conteúdo.

3xx (Códigos de Redirecionamento)

  • 301 – Moved Permanently: Significa que o recurso solicitado foi realocado permanentemente. Uma resposta com o código 301 deve conter um cabeçalho Location com a URL completa de onde o recurso está atualmente.
  • 303 – See Other: É utilizado quando a requisição foi processada, mas o servidor não deseja enviar o resultado do processamento. Ao invés disso, o servidor envia a resposta com este código de status e o cabeçalho Location.
  • 304 – Not Modified: É utilizado principalmente em requisições GET condicionais.
  • 307 – Temporary Redirect: Similar ao 301, mas indica que o redirecionamento é temporário, não permanente.

4xx (Erros Causados pelo Cliente)

  • 400 – Bad Request: É uma resposta genérica para qualquer tipo de erro de processamento cuja responsabilidade é do cliente do serviço.
  • 401 – Unauthorized: Utilizado quando o cliente está tentando realizar uma operação sem ter fornecido dados de autenticação (ou a autenticação fornecida for inválida).
  • 403 – Forbidden: Utilizado quando o cliente está tentando realizar uma operação sem ter a devida autorização.
  • 404 – Not Found: Utilizado quando o recurso solicitado não existe.
  • 405 – Method Not Allowed: Utilizado quando o método HTTP utilizado não é suportado pela URL. Deve incluir um cabeçalho Allow na resposta.
  • 409 – Conflict: Utilizado quando há conflitos entre dois recursos. Comumente utilizado em resposta a criações de conteúdos que tenham restrições de dados únicos.
  • 410 – Gone: Semelhante ao 404, mas indica que um recurso já existiu neste local.
  • 415 – Unsupported Media Type: Utilizado em resposta a clientes que solicitam um tipo de dados que não é suportado.

5xx (Erros Originados no Servidor)

  • 500 – Internal Server Error: É uma resposta de erro genérica.
  • 503 – Service Unavailable: Indica que o serviço não está funcionando corretamente. Pode incluir um cabeçalho Retry-After.

5. Documentação dos Endpoints

URL Base

• Produção - https://api.correios.com.br/prazo/v3
• Homologação - https://api.correios.com.br/prazo/v3

Nacional - Prazo de produtos e serviços nacionais

Permite a pesquisa em lote de prazos de entrega, com tamanho máximo de 20 itens por lote.

POST - /v1/nacional - Consulta prazo de uma lista de produtos

Cabeçalhos

Cabeçalhos Tipo
Authorization Bearer Token
Content-Type application/json
Accept application/json

Lista de campos

Campo Tipo Descrição Obrigatório
idLote String Identificador do lote de consulta Sim
parametrosPrazo String Parâmetros da Consulta Sim
coProduto String Código de Produto / Serviço Sim
nuRequisicao String Controle do requisitante Não
dtEvento String Data de referência para cálculo do prazo Não
cepOrigem String Cep de origem da postagem Sim
cepDestino String Cep de destino da postagem Sim
dataPostagem String Data da postagem do objeto Não

Modelo de Requisição (JSON)

{
  "idLote": "01",
  "parametrosPrazo": [
    {
      "coProduto": "01234",
      "nuRequisicao": "001",
      "dtEvento": "01/01/2025",
      "cepOrigem": "01001001",
      "cepDestino": "01001001",
      "dataPostagem": "2025-01-02"
    },
    {
      "coProduto": "01234",
      "nuRequisicao": "002",
      "dtEvento": "01/01/2025",
      "cepOrigem": "01001001",
      "cepDestino": "01001001",
      "dataPostagem": "2025-01-02"
    }
  ]
}

GET - /v1/nacional/{coProduto} - Consulta prazo de um produto/serviço

Cabeçalhos

Cabeçalhos Tipo
Authorization Bearer Token
Content-Type application/json
Accept application/json

Lista de Campos

Campo Tipo Descrição Obrigatório
coProduto String Código de Produto / Serviço Sim
cepOrigem String Cep de origem da postagem Sim
cepDestino String Cep de destino da postagem Sim
dtEvento String Data de referência para cálculo do prazo Não

Modelo de requisição (GET)

https://api.correios.com.br/prazo/v1/nacional/01234?cepOrigem=01001001&cepDestino=01001001

Data prevista

GET - /v1/data-prevista - Calcula a data prevista de entrega

Calcula a data prevista de entrega baseada no município, data de postagem e prazo em dias.

Cabeçalhos

Cabeçalhos Tipo
Authorization Bearer Token
Content-Type application/json
Accept application/json

Lista de Campos

Campo Tipo Descrição Obrigatório
cepOrigem String Cep de origem da postagem Sim
cepDestino String Cep de destino da postagem Sim
prazo Integer Prazo de entrega em dias Sim
dtPostagem String Data da postagem formato DD-MM-AAAA Sim
isEncomendaUPU Boolean Indica se é uma encomenda da UPU (true ou false) Não
isSabadoDiaUtil Boolean Consulta se sábado é considerado dia útil (true ou false) Não
isDomingoDiaUtil Boolean Consulta se domingo é considerado dia útil (true ou false) Não

Modelo de requisição (GET)

https://api.correios.com.br/prazo/v1/data-prevista?cepOrigem=01001001&cepDestino=01001001&prazo=5&dtPostagem=26-09-2025&isSabadoDiaUtil=true

Internacional - Prazo de produtos e serviços internacionais

Lista de serviços disponíveis para consulta:

Código de serviço Nome do Serviço
45012 DOCUMENTO INTERNACION EXPRESSO
45403 DOCUMENTO INTER EXPRESSO TA
45071 DOCUMENTO INTER STANDARD CHANC
45039 DOCUMENTO INTERNACION STANDARD
45209 EXPORTA FACIL ECONOMICO
45454 EXPORTA FACIL PRE PG 2
45110 EXPORTA FACIL EXPRESSO
45128 EXPORTA FACIL STANDARD

GET - /v2/internacional/importacao/{coProduto} - Consulta prazo de importação

Consulta prazo de importação de um produto/serviço, já nacionalizado.

Cabeçalhos

Cabeçalhos Tipo
Authorization Bearer Token
Content-Type application/json
Accept application/json

Lista de Campos

Campo Tipo Descrição Obrigatório
coProduto String Código de Produto / Serviço Sim
cepOrigem String Cep de origem da postagem Sim
cepDestino String Cep de destino da postagem Sim
dtEvento String Data de referência para cálculo do prazo Não

Modelo de requisição (GET)

https://api.correios.com.br/prazo/v2/internacional/importacao/45110?cepOrigem=89220030&cepDestino=71930000

GET - /v2/internacional/exportacao/{coProduto} - Consulta prazo internacional de exportação

Cabeçalhos

Cabeçalhos Tipo
Authorization Bearer Token
Content-Type application/json
Accept application/json

Lista de Campos

Campo Tipo Descrição Obrigatório
coProduto String Código de Produto / Serviço Sim
sgPaisOrigem String Sigla do país de origem (BR) Sim
sgPaisDestino String Sigla do país de destino Sim
dtPostagem String Data de postagem (DD-MM-AAAA) Sim

Modelo de requisição (GET)

https://api.correios.com.br/prazo/v2/internacional/exportacao/45320?sgPaisOrigem=BR&sgPaisDestino=US&dtPostagem=26-09-2025

6. Exemplos de Integração

O padrão de arquitetura RESTful permite que a API Prazo seja consumida pelos mais diversos tipos de linguagens disponíveis no mercado, com o padrão de conexão REST sendo utilizado para conexão.

6.1 Exemplos requisições (ex: em Linguagens Populares)

Exemplos de consumo da API Prazo, cURL usando os verbos GET e POST:

cURL - POST - /v1/nacional - Consulta prazo de uma lista de produtos

curl -X 'POST' \
  'https://api.correios.com.br/prazo/v1/nacional' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer “Token de Acesso”' \
  -d '{
    "idLote": "01",
    "parametrosPrazo": [
      {
        "coProduto": "03220",
        "nuRequisicao": "001",
        "dtEvento": "01/01/2025",
        "cepOrigem": "01001001",
        "cepDestino": "01001001",
        "dataPostagem": "2025-01-02"
      },
      {
        "coProduto": "03220",
        "nuRequisicao": "002",
        "dtEvento": "01/01/2025",
        "cepOrigem": "01001001",
        "cepDestino": "01001001",
        "dataPostagem": "2025-01-02"
      }
    ]
  }'

cURL - GET - /v1/data-prevista - Calcula a data prevista de entrega

curl -X 'GET' \
  'https://api.correios.com.br/prazo/v1/data-prevista?cepOrigem=01001001&cepDestino=01001001&prazo=5&dtPostagem=26-09-2025&isSabadoDiaUtil=true' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer “Token de Acesso”'

6.2 Casos de Uso Comuns

Caso de Uso 1: Buscar Prazo de entrega para um serviço (GET)

Busca Prazo de entrega para o serviço Sedex – Código 03220, com Cep de origem 01001-001 e destino 70064-000, com data de postagem dia 01/10/2025.

  • Resumo: Testa a recuperação dos dados de prazo de entrega, informando os dados de serviço, CEP de origem e destino.
  • Pré-condições: Token de acesso ou chave de subdelegação válidos, com a API Prazo (34) entre as APIs liberadas, serviço, CEPs de origem e destino.
  • Etapas:
    1. Enviar uma solicitação GET para /v1/nacional/03220?cepOrigem=01001001&cepDestino=70064000.
    2. Verificar se o código de status da resposta é **200 (OK)**.
    3. Afirmar que os dados **JSON** retornados contêm as informações esperadas (prazoEntrega, entregaDominiciliar, entregaSabado).
  • Resultados Esperados: Dados de prazo de entrega, data máxima, entrega domiciliar, entrega aos sábados são entregues corretamente.
  • Resultados Reais (Exemplo JSON):
{
  "coProduto": "03220",
  "prazoEntrega": 1,
  "dataMaxima": "2025-10-02T23:59:59",
  "entregaDomiciliar": "N",
  "entregaSabado": "N",
  "entregaDomingo": "N"
}

Caso de Uso 2: Buscar Prazo de entrega para uma lista de serviços (POST)

Busca o prazo de entrega de uma lista de serviços (Sedex - 03220, Pac - 03298, Sedex 10 – 03158, Sedex 12 - 03140) para o CEP de origem 01001001 e o CEP de destino 70064000, com postagem no dia 01/10/2025. Recurso comum para exibição de possíveis modalidades de entrega em página de produtos de um e-commerce.

  • Resumo: Testa a recuperação dos dados de prazo de entrega de diversos serviços.
  • Pré-condições: Token de acesso ou chave de subdelegação válidos, com a API Prazo (34) entre as APIs liberadas, lista de serviços, CEPs de origem e destino.
  • Etapas:
    1. Enviar uma solicitação POST para /v1/nacional.
    2. No corpo da requisição (body), enviar os dados em formato JSON conforme exemplo abaixo.
  • Corpo da Requisição (Exemplo JSON):
{
  "idLote": "01",
  "parametrosPrazo": [
    {
      "coProduto": "03220",
      "nuRequisicao": "001",
      "dtEvento": "01/01/2025",
      "cepOrigem": "01001001",
      "cepDestino": "70064000",
      "dataPostagem": "2025-10-01"
    },
    {
      "coProduto": "03298",
      "nuRequisicao": "002",
      "dtEvento": "01/01/2025",
      "cepOrigem": "01001001",
      "cepDestino": "70064000",
      "dataPostagem": "2025-10-01"
    },
    {
      "coProduto": "03158",
      "nuRequisicao": "003",
      "dtEvento": "01/01/2025",
      "cepOrigem": "01001001",
      "cepDestino": "70064000",
      "dataPostagem": "2025-10-01"
    },
    {
      "coProduto": "03140",
      "nuRequisicao": "004",
      "dtEvento": "01/01/2025",
      "cepOrigem": "01001001",
      "cepDestino": "70064000",
      "dataPostagem": "2025-10-01"
    }
  ]
}

Verificar se o código de status da resposta é 200 (OK) ou 206 (indica indisponibilidade de um ou mais dos serviços consultados).

Afirmar que os dados JSON retornados contêm as informações esperadas do usuário (prazoEntrega, entregaDominiciliar, entregaSabado).

Resultados Esperados: Dados de prazo de entrega, data máxima, entrega domiciliar, entrega aos sábados são entregues corretamente.

  • Resultados Reais (Exemplo JSON):
[
  {
    "coProduto": "03220",
    "nuRequisicao": "001",
    "prazoEntrega": 1,
    "dataMaxima": "2025-01-03T23:59:59",
    "entregaDomiciliar": "N",
    "entregaSabado": "N",
    "entregaDomingo": "N"
  },
  {
    "coProduto": "03298",
    "nuRequisicao": "002",
    "prazoEntrega": 5,
    "dataMaxima": "2025-01-09T23:59:59",
    "entregaDomiciliar": "N",
    "entregaSabado": "N",
    "entregaDomingo": "N"
  },
  {
    "coProduto": "03158",
    "nuRequisicao": "003",
    "txErro": "PRZ-008: Serviço indisponível para o trecho informado"
  },
  {
    "coProduto": "03140",
    "nuRequisicao": "004",
    "prazoEntrega": 1,
    "dataMaxima": "2025-01-03T12:00:59",
    "entregaDomiciliar": "N",
    "entregaSabado": "N",
    "entregaDomingo": "N"
  }
]

7. Ambientes Disponíveis

7.1 Ambiente de Homologação

7.2 Ambiente de Produção

8. Boas Práticas

Aplicando boas práticas, você evita erros ao utilizar nossas APIs e consegue obter melhor desempenho e performance em suas integrações. Dentre várias ações, destacamos:

  • Tratar os retornos corretamente, inclusive os erros recebidos.
  • Respeitar os limites de uso da API.
  • Uso eficiente dos dados.
  • Legalidade (LGPD).

8.1 Segurança na Integração

  • Não compartilhe dados de acesso às APIs em grupos, fóruns ou documentos compartilhados.
  • No caso de fornecimento de acesso à equipes de desenvolvimento, prefira o uso de chave de subdelegação de acesso, pois estas chaves têm validade e podem ser canceladas ou revogadas a qualquer momento.

8.2 Validação de Dados

Sempre valide os dados a serem consultados antes de enviar as solicitações. Os CEPs de origem e destino podem ser validados na API CEP (41), e os serviços disponíveis (Pac, Sedex, etc...) podem ser verificados na API Meu Contrato (566). Isso ajuda a diminuir o consumo de recursos de TI.

9. Suporte e Contato

9.1 Canais de Suporte Técnico

Entre em contato com o representante comercial responsável pelo seu contrato com os Correios; ele é responsável pelo redirecionamento ao suporte tecnológico da sua região.

Suporte tecnológico: https://faleconosco.correios.com.br/faleconosco//app/cadastro/suporte/tecnologico/index.php

Também é possível a abertura de chamado via Fale Com os Correios. https://www.correios.com.br/falecomoscorreios/central-de-atendimento

9.2 Processo de Abertura de Chamados

Fale Com os Correios - Suporte tecnológico: https://www.correios.com.br/falecomoscorreios/central-de-atendimento

10. Anexos

10.1 Glossário de Termos Técnicos

Termo Descrição
API Application Programming Interfaces (Interface de Programação de Aplicações): conjunto de regras e protocolos que permite a comunicação entre diferentes softwares.
API Manager Sistema gerador de tokens para acesso de APIs.
Autenticação Processo de verificação de uma identidade digital do usuário.
Autorização Processo para verificar quais são os privilégios concedidos.
Cartão de postagem Cartão que identifica um usuário como cliente de contrato dos Correios.
CEP Código de Endereçamento Postal - código numérico de oito dígitos usado pelos Correios no Brasil.
Código de acesso a APIs Código de acesso criado pelo usuário no site Correios Web Services.
Contrato comercial Instrumento que o cliente firma com os Correios para a prestação de serviços.
DNE Diretório Nacional de Endereços - Base de endereçamento dos Correios.
HTTPS Hypertext Transfer Protocol Secure: versão segura do protocolo HTTP.
Meu Correios Mecanismo de autenticação e autorização para acesso aos serviços dos Correios via internet.
REST Representational State Transfer - estilo de arquitetura de software para comunicação entre sistemas na web.
Token (ou bearer token) Credencial de segurança que concede acesso a recursos protegidos.
Unidade Denominação comum aos endereços dos Correios (agências, centros de distribuição, etc.).

10.2 Referências e links úteis

10.3 Histórico de Alterações da API e da respectiva documentação

Data Evento Versão Responsável Observações
24/11/2025 Criação do Manual 1.0 Correios -