Manual - Uso da API Token

Sumário

1. Apresentação

1.1 Objetivo do Manual

Este material foi desenvolvido para contribuir no planejamento e integração com a API Token dos Correios do Brasil em qualquer plataforma desejada pelo cliente.

1.2 Escopo da API

A API Token tem o escopo exclusivo autenticação nas diversas APIs dos Correios.

1.3 Público-Alvo

Esta API é indicada a todos os clientes com contrato comercial firmado junto aos Correios que desejem utilizar outras APIs dos Correios, como Pré Postagem, Busca CEP, Busca Agências, entre outras.

2. Visão Geral da API

2.1 Finalidade da API

A API Token permite gerar um token com os dados informados. Esse token deve ser enviado na autenticação em outras APIs dos Correios.

2.2 Funcionalidades Principais

As funcionalidades principais incluem:

  • Gerar token apenas com login e senha;
  • Gerar token com login, senha e contrato comercial;
  • Gerar token com login, senha e cartão de postagem.

2.3 Arquitetura e Tecnologias Utilizadas

As APIs dos Correios foram desenvolvidas com a tecnologia REST. Este padrão de mercado permite ao cliente escolher ou adotar qualquer linguagem de programação, como: ASP, .Net, Java, PHP, Ruby, ou Python, entre outras.

Entre as características que mais se destacam na API estão:

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

Tanto o corpo da requisição feita à API quanto a resposta recebida são em formato JSON.

2.4 Fluxo Geral de Integração

Fluxo geral de integração

Figura 1 – Fluxo geral de integração


3. Autenticação e Autorização

3.1 Métodos de Autenticação Suportados

Esta API utiliza o método de autenticação Basic.

3.2 Obtenção de Credenciais

Para que seja possível acessar a API Token com o nível adequado de credenciais é necessário:

  • Conta de Pessoa Jurídica no Meu Correios;
  • Contrato comercial firmado junto aos Correios, exceto Clube Correios;
  • Deve ser criado código de acesso às APIs no CWS – Correios Web Services para geração do token.

3.3 Escopos e Permissões

O escopo da API Token é apenas para gerar o token. As permissões vão refletir apenas aquilo que os clientes já possuem habilitação: a API não permite alteração de permissões existentes — para esse tipo de alteração, é recomendado contato com o contato comercial.

3.4 Exemplo de Requisição Autenticada

Requisição Autenticada

Figura 2 – Requisição Autenticada


4. Padrões Técnicos utilizados

4.1 Formato das Requisições e Respostas

Tanto o corpo da requisição feita à API quanto a resposta recebida são em formato JSON.

4.2 Endpoints (REST, etc.)

A API Token possui arquitetura REST e utiliza o protocolo HTTPS. Ou seja, é fornecida uma URL base e com o verbo HTTP POST, exclusivamente.

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 – Informacionais;
  • 2xx – Códigos de sucesso;
  • 3xx – Códigos de redirecionamento;
  • 4xx – Erros causados pelo cliente;
  • 5xx – Erros originados no servidor.

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`, contendo 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 e pode retornar um cabeçalho `Location` com uma URL de consulta.
  • 204 – No Content: Usualmente enviado em resposta a uma requisição PUT, POST ou DELETE, quando o servidor recusa-se a enviar conteúdo.

3xx (Códigos de Redirecionamento)

  • 301 – Moved Permanently: Significa que o recurso solicitado foi realocado permanentemente. Deve conter um cabeçalho `Location` com a URL completa do novo local.
  • 303 – See Other: Utilizado quando a requisição foi processada, mas o servidor não deseja enviar o resultado, enviando o cabeçalho `Location` para informar onde a resposta está.
  • 304 – Not Modified: Utilizado principalmente em requisições GET condicionais, quando a resposta não foi alterada desde a última requisição.
  • 307 – Temporary Redirect: Similar ao 301, mas indica que o redirecionamento é temporário.

4xx (Erros Causados pelo Cliente)

  • 400 – Bad Request: Resposta genérica para qualquer erro de processamento cuja responsabilidade é do cliente.
  • 401 – Unauthorized: Utilizado quando o cliente está tentando realizar uma operação sem ter fornecido dados de autenticação válidos.
  • 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 em criações de conteúdos que tenham restrições de dados únicos. Se for causado por outro recurso, a resposta deve conter um cabeçalho `Location`.
  • 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, como solicitar JSON quando apenas XML é suportado.

5xx (Erros Originados no Servidor)

  • 500 – Internal Server Error: Resposta de erro genérica, utilizada quando nenhuma outra se aplica.
  • 503 – Service Unavailable: Indica que o servidor está atendendo requisições, mas o serviço em questão não está funcionando corretamente. Pode incluir um cabeçalho 'Retry-After', dizendo ao cliente quando ele deveria tentar submeter a requisição novamente.

5. Documentação dos Endpoints

5.1 Estrutura de Documentação (método, URL, parâmetros, exemplo)

Para acesso à documentação completa da API, após todas as permissões devidamente recebidas, deve ser acessado o CWS - Correios Web Services. As instruções de acesso estão no *Manual Correios Web Services*.

Mesmo antes do preenchimento das credenciais e geração do token, já será possível encontrar no campo de pesquisa a Token (5), e ela virá com sua documentação aberta, pois é pública.

Imagem mostrando a API Token (5) em destaque na pesquisa de credenciais.

Figura 3 - Token


A estrutura das requisições consiste na URL base e o endpoint, além do verbo POST. Esses dados são conseguidos no próprio Swagger.

Imagem destacando a URL Base, o Verbo POST e o Endpoint da API Token no Swagger.

Figura 3.1 – Token - endpoint


Nesse exemplo, para invocar o endpoint, utilizamos o endereço `https://api.correios.com.br/token/autentica` utilizando o verbo POST.

Recomendamos estudo intensivo dos dados disponibilizados nas páginas demonstradas acima, pois as atualizações são disponibilizadas primeiro no Swagger da API no CWS, que será sempre a documentação mais completa e atualizada.

É importante verificar, na descrição da API, as regras do token, pois elas são essenciais para o uso correto do recurso, prevenindo erros como o 429 (Too Many Requests) ou de “token expirado”.

Imagem mostrando regras de geração, expiração e limite de solicitações do Token no Swagger.

Figura 3.2 – Token – Endpoint


O primeiro link, logo abaixo do nome da API, se trata da documentação em JSON, que pode ser baixada e importada em aplicativos de teste de APIs REST, como Postman, SoapUI, Katalon Studio, Swagger UI, Apidog, entre outros. Recomenda-se consultar os manuais desses aplicativos para aproveitar essa funcionalidade.

5.2 Endpoints por Domínio Funcional ou por categoria

Token

Finalidade: Geração de tokens para acesso de APIs.

Endpoints

POST /v1/autentica – Gera um token para acesso a APIs, cuja autorização foi concedida diretamente para usuário idCorreios.

  • Parâmetros obrigatórios: Nenhum.
  • Parâmetros opcionais: Nenhum.
  • Corpo (BODY) da requisição: Não possui.

POST /v1/autentica/contrato – Gera um token para acesso de APIS, cuja autorização seja pelo número de contrato.

  • Parâmetros obrigatórios: Nenhum.
  • Parâmetros opcionais: Nenhum.
  • Corpo (BODY) da requisição:
{
  "numero": "string",
  "dr": 0
}

  • `numero` (obrigatório): número do contrato comercial com os Correios.
  • `dr` (opcional): número da Superintendência Estadual do contrato, ex: 10. Pode ser obtido na consulta à documentação do contrato, no cartão Correios Fácil (SUP. EST.), no Correios Empresas ou utilizando a API Meu Contrato.

POST /v1/autentica/cartaopostagem – Gera um token para acesso a APIs, cuja autorização seja por cartão de postagem.

  • Parâmetros obrigatórios: Nenhum.
  • Parâmetros opcionais: Nenhum.
  • Corpo (BODY) da requisição:
{
  "numero": "string",
  "contrato": "string",
  "dr": 0
}
  • `numero` (obrigatório): número do cartão de postagem.
  • `contrato` (opcional): número do contrato comercial com os Correios.
  • `dr` (opcional): número da Superintendência Estadual do contrato, ex: 10. Pode ser obtido na consulta à documentação do contrato, no cartão Correios Fácil (SUP. EST.), no Correios Empresas ou utilizando a API Meu Contrato.

6. Exemplos de Integração

6.1 Exemplos requisições

Gerar token apenas com login do Meu Correios:

Exemplo de Requisição e Resposta cURL para autenticação via Login.


Gerar token com login do Meu Correios e contrato:

Exemplo de Requisição e Resposta cURL para autenticação via Login e Contrato.


Gerar token com login do Meu Correios e cartão de postagem:

Exemplo de Requisição e Resposta cURL para autenticação via Login e Cartão de Postagem.


6.2 Casos de Uso Comuns

O único caso de uso possível para essa API é a geração de token.

7. Ambientes Disponíveis

7.1 Ambiente de Homologação

Para acesso ao ambiente de homologação do Correios Web Services (CWS), é necessário primeiro obter o acesso em produção, com o serviço devidamente habilitado no contrato.

Após o acesso ser completado em produção, o cliente deve entrar em contato com o representante comercial de seu contrato para pedir a replicação dos dados do contrato em homologação.

Por fim, o cliente deve criar uma conta no Meu Correios de homologação, vinculada aos mesmos dados do CNPJ já existente em produção. O endereço do Meu Correios de homologação é: https://meucorreioshom.correios.com.br/.

A documentação Swagger da API está disponível no endereço de homologação do CWS, a saber: http://cwshom.correios.com.br/.

7.2 Ambiente de Produção

Após os passos definidos no item 3.2 deste manual, o acesso do cliente em produção já está disponível. A documentação Swagger da API está disponível no endereço de produção do CWS: https://cws.correios.com.br/.

8. Boas Práticas

8.1 Segurança na Integração

Os Correios recomendam os procedimentos de segurança padrão do mercado: não expor os códigos de acesso, mantê-los seguros em suas aplicações, não repassá-los indiscriminadamente, utilizar sempre protocolo HTTPS e manter a aplicação atualizada.

8.2 Validação de Dados

É importante validar todos os dados ao enviar à API. Os formatos de validação constam no CWS, conforme já citado neste manual.

8.3 Validade do token

É essencial atentar à data de expiração do token e programar a aplicação de acordo com esse dado, gerando corretamente novo token apenas quando o anterior estiver próximo do vencimento. Para mais detalhes, consulte a documentação da API no CWS.

9. Suporte e Contato

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.

Para suporte tecnológico e abertura de chamados, acesse: https://faleconosco.correios.com.br/faleconosco//app/cadastro/suporte/tecnologico/index.php.

Também é possível utilizar o contato telefônico com a Central de Atendimento dos Correios, informando o problema enfrentado. Os números estão disponíveis na página: https://www.correios.com.br/falecomoscorreios/central-de-atendimento.

Procedimento para Clientes com Contrato

Para os clientes com contrato junto ao gestor comercial, não é necessário abertura de chamado. Basta contatar o gestor e enviar os dados, com a requisição e a resposta da API.

Procedimento para Clientes com Empresas Terceirizadas

Para clientes que contrataram outras empresas (TMS, ERP, e-commerce, etc.) que desenvolveram a integração, o chamado deve ser aberto na empresa contratada. Caso a empresa afirme que o problema é nos Correios, ela deve fornecer a requisição e a resposta da API, ou tratar diretamente com os Correios.

É fundamental que sempre sejam enviados a requisição à API e a resposta recebida, pois é com base nesses dados que é feita a análise do problema encontrado.

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, funcionando como uma ponte que facilita a troca de informações e funcionalidades entre eles.
API Manager Sistema gerador de tokens para acesso de APIs. Gera uma string codificada com a finalidade de garantir a segurança de quem está usando a API e evitar fraudes.
Autenticação Processo de verificação de uma identidade digital do usuário, ou seja, para assegurar que o usuário é realmente aquele quem diz ser.
Autorização Processo para verificar quais são os privilégios concedidos, para utilizar uma aplicação.
Cartão de postagem Cartão que identifica um usuário como cliente de contrato dos Correios.
Código de acesso a APIs Código de acesso criado pelo usuário no site Correios Web Services que permite esse usuário utilizar os componentes disponibilizados pelos Correios.
Contrato comercial Instrumento que o cliente firma com os Correios para a prestação de serviços de encomendas, mensagens, marketing direto e outros.
CWS Correios Web Services – site principal para conhecimento e testes das integrações dos Correios: produção https://cws.correios.com.br.
HTTPS Hypertext Transfer Protocol Secure: versão segura do protocolo HTTP, que utiliza a criptografia SSL/TLS para proteger os dados. Garante confidencialidade, integridade e autenticidade da comunicação.
Meu Correios Mecanismo de autenticação e autorização para acesso aos serviços que os Correios disponibilizam via internet.
REST Representational State Transfer - estilo de arquitetura de software que define princípios para a comunicação entre sistemas na web, tornando-os mais confiáveis, escaláveis e fáceis de modificar.
Token (ou bearer token) Credencial de segurança que concede acesso a recursos protegidos. É usado na autenticação de APIs (protocolo OAuth 2.0) para verificar a identidade do cliente e autorizá-lo a acessar determinados recursos.

10.2 Referências e links úteis

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

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