Manual - API Faturas

Manual de uso da API Faturas

Sumário

1. Apresentação

1.1 Objetivo do Manual

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

1.2 Escopo da API

A API Faturas tem o escopo exclusivo de consulta aos dados de faturas pelos clientes detentores de contratos comerciais.

1.3 Público-Alvo

Esta API é indicada a todos os clientes dos Correios que possuam contratos comerciais a faturar e desejam obter esses dados de forma automatizada, ao invés de solicitar as faturas de forma manual no Correios Empresas.

2. Visão Geral da API

2.1 Finalidade da API

A API Faturas permite retornar dados das faturas, analíticos (completos) ou sintéticos (resumo), além da consulta do boleto da fatura.

2.2 Funcionalidades Principais

  • Emitir extrato analítico da fatura;
  • Emitir extrato sintético da fatura;
  • Emitir prévia de fatura;
  • Emitir boleto da fatura;
  • Consultar divergência de faturas.

2.3 Arquitetura e Tecnologias Utilizadas

As APIs dos Correios foram desenvolvidas com a tecnologia REST. Este padrão de mercado permite escolher ou adotar qualquer linguagem de programação, 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.

Tanto o corpo da requisição feita à API quanto a resposta recebida são em formato JSON, quando aplicável – visto que algumas requisições e respostas podem não possuir corpo. As exceções à regra, como retorno em CSV ou PDF, estão pontuadas neste manual.

2.4 Fluxo Geral de Integração

Sumário do Manual de uso da API Faturas-DIAGRAMA.png

3. Autenticação e Autorização

3.1 Métodos de Autenticação Suportados

Esta API utiliza exclusivamente o método de autenticação Bearer Token.

O token a ser utilizado deve ser obtido com base na integração com a API Token. Deve ser observada a validade do token em questão para, quando tal validade expirar, seja criado um novo token pelo mesmo processo.

Alternativamente, para facilitar o acesso de terceiros às APIs e sistemas dos Correios em nome de um cliente com contrato ativo, de forma que o detentor do contrato não precise fornecer suas senhas de acesso existe a opção de subdelegar acesso. A chave de acesso gerada será usada como token, conforme referência neste manual.

3.2 Obtenção de Credenciais

Para que seja possível acessar a API Faturas 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.
  • O token utilizado deve ser gerado com o endpoint /v1/autentica/contrato – a documentação de uso desse recurso está no manual de uso da API Token.

3.3 Escopos e Permissões

O escopo da API Faturas é apenas de consulta e suas permissões refletem o escopo em questão, sendo uma API simples, com poucos endpoints.

Importante notar que alguns endpoints são assíncronos, então o resultado depende de um segundo endpoint, que indicará o processamento da requisição, e de um terceiro endpoint, que traz os dados da requisição.

3.4 Exemplo de Requisição Autenticada

Exemplo de requisição para solicitar o extrato analítico de uma fatura:

Requisição

curl -X 'GET' \
  ' https://api.correios.com.br/faturas/v1/faturas/1234567/analitico?tipoDocumento=RE&drFatura=00010&itemFatura=001' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [TOKEN]'

Resposta (Retorna o ID do processamento, que deve ser consultado posteriormente)

{
    "id": "99efe3c7-d12e-471a-a254-be0545b1c443",
    "tipoProcessamento": "EXTRATO_ANALITICO",
    "status": "SOLICITADO",
    "dataSolicitacao": "2025-10-06T13:47:57",
    "parametros": {
      "tipoDocumento": "RE",
      "drFatura": "00010",
      "idFatura": "3497318",
      "itemFatura": "001"
    }
}

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, quando aplicável – visto que algumas requisições e respostas podem não possuir corpo.

4.2 Endpoints (REST, etc.)

A API Faturas possui arquitetura REST e utiliza o protocolo HTTPS. É fornecida uma URL base e os verbos HTTP (GET, POST, PUT, DELETE, entre outros) indicam a ação requisitada pelo cliente.

4.3 Códigos de Status HTTP e Tratamento de Erros

Toda requisição retorna um código de status HTTP, dividido em cinco famílias: 1xx (Informacionais), 2xx (Sucesso), 3xx (Redirecionamento), 4xx (Erros do Cliente) e 5xx (Erros do Servidor).

Os códigos mais importantes e utilizados são:

2xx (Sucesso)

  • 200 – OK: Operação bem-sucedida.
  • 201 – Created: Recurso criado com sucesso. Deve retornar um cabeçalho Location.
  • 202 – Accepted: Solicitação recebida e será processada posteriormente (uso comum em requisições assíncronas).
  • 204 – No Content: Resposta sem conteúdo, comum em PUT, POST ou DELETE.

3xx (Redirecionamento)

  • 301 – Moved Permanently: Recurso realocado permanentemente. Deve conter cabeçalho Location com a nova URL.
  • 303 – See Other: Requisição processada, mas o resultado está em outro local (indicado pelo cabeçalho Location).
  • 304 – Not Modified: Utilizado em requisições GET condicionais, indicando que o recurso não foi alterado.
  • 307 – Temporary Redirect: Redirecionamento temporário.

4xx (Erros do Cliente)

  • 400 – Bad Request: Erro genérico de responsabilidade do cliente.
  • 401 – Unauthorized: Falha na autenticação (credenciais não fornecidas ou inválidas).
  • 403 – Forbidden: Cliente sem autorização para a operação.
  • 404 – Not Found: Recurso solicitado não existe.
  • 405 – Method Not Allowed: Método HTTP não suportado pela URL. Deve incluir cabeçalho Allow.
  • 409 – Conflict: Conflito entre recursos (ex: criação de item duplicado).
  • 410 – Gone: Recurso existiu, mas foi removido.
  • 415 – Unsupported Media Type: Formato de dados solicitado não suportado (ex: pedir XML quando só há JSON).

5xx (Erros do Servidor)

  • 500 – Internal Server Error: Erro genérico no servidor.
  • 503 – Service Unavailable: Serviço indisponível. Pode incluir cabeçalho Retry-After.

5. Documentação dos Endpoints

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

A documentação completa da API está disponível no CWS - Correios Web Services, após a obtenção das permissões. As instruções de acesso estão no Manual Correios Web Services.

Após a geração do token, a API Faturas pode ser encontrada no campo de pesquisa do CWS. A estrutura das requisições é composta pela URL base, o endpoint e o verbo HTTP, conforme detalhado no Swagger da API.

Sumário do Manual de uso da API Faturas-img1.png

A estrutura das requisições consiste na URL base e o endpoint, além do verbo (GET, POST, PUT, PATCH ou DELETE)> Esses dados são conseguidos no próprio Swagger:

Sumário do Manual de uso da API Faturas-img2.png

Nesse exemplo, para invocar o endpoint, utilizamos o endereço https://api.correios.com.br/cp/v2/enderecos utilizando o verbo GET.

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.

Adicionalmente, 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, IntelliJ IDEA, P`yCharm, API Fortress, entre outros. Recomendamos se referir aos manuais desses aplicativos para aproveitar essa funcionalidade.

5.2 Endpoints por Domínio Funcional ou por categoria

Prévias

Finalidade: Consulta das prévias de fatura, que contêm apenas registros a faturar.

Endpoints

POST /v1/previas – Solicita o processamento e geração da prévia do extrato sintético. Este endpoint é **assíncrono**. O status deve ser consultado em GET /v1/processamentos/{idProcessamento} e o arquivo baixado em GET /v1/processamentos/{idProcessamento}/file.

Parâmetros obrigatórios:

  • tipoPrevia: SINTETICO ou ANALITICO.
  • contrato: número do contrato comercial (ex: 9912345678).
  • dr: número da Superintendência Estadual do contrato (ex: 10).

Parâmetros opcionais:

  • centroCusto: código do centro de custo (ex: 65535).

Faturas

Finalidade: Consulta de faturas para clientes externos.

Endpoints

POST /v1/faturas/{fatura}/analitico – Solicita o processamento e geração do extrato analítico em CSV. Este endpoint é **assíncrono**. O status deve ser consultado em GET /v1/processamentos/{idProcessamento} e o arquivo baixado em GET /v1/processamentos/{idProcessamento}/file.

Parâmetros obrigatórios:

  • fatura: número da fatura.
  • tipoDocumento: tipo do documento (ex: RE). Tipos possíveis:
Valor Descrição
RE Faturas originadas no módulo de faturamento
R4 Faturas migradas do sistema CRB
RA Faturas geradas a partir de parcelamentos de débitos TRD - Termo de Reconhecimento de Dívida
R6 Faturas REFIS Postal
R8 Faturas Acordo Judicial
RT Faturas por estimativa
RZ Faturas zeradas
R3 Fatura de fornecedor

Clientes com contrato a faturar normalmente utilizam RE, RZ, RT ou RZ. Os outros itens devem ser utilizados apenas se aparecerem na consulta ao endpoint GET /v1/faturas.

  • drFatura: número da Superintendência Estadual do contrato (ex: 10, precedido por 000, ex: 00010).
  • itemFatura: item da fatura (numérico, 3 dígitos, ex: 001). Diferente de 001 apenas em faturas parceladas (RA).

GET /v1/faturas – Consulta a fatura pelo contrato e período.

Parâmetros obrigatórios:

  • contrato: número do contrato comercial.
  • dr: número da Superintendência Estadual do contrato.
  • dataInicial: Data inicial do período (formato DD-MM-YYYY).
  • dataFinal: Data final do período (formato DD-MM-YYYY).

GET /v1/faturas/{fatura}/sintetico/pdf – Consulta o extrato sintético em PDF de uma fatura. O resultado é um arquivo PDF.

Parâmetros obrigatórios:

  • fatura: número da fatura.
  • tipoDocumento: tipo do documento (mesmos valores da consulta analítica).
  • drFatura: número da Superintendência Estadual da fatura (ex: 00010).
  • itemFatura: item da fatura (ex: 001).

GET /v1/faturas/{fatura}/boleto/pdf – Consulta o boleto em PDF de uma fatura. O resultado é um arquivo PDF.

Parâmetros obrigatórios:

  • fatura: número da fatura.
  • tipoDocumento: tipo do documento (mesmos valores da consulta analítica).
  • drFatura: número da Superintendência Estadual da fatura (ex: 00010).
  • itemFatura: item da fatura (ex: 001).

GET /v1/faturas/divergências – Consulta divergências tarifárias do faturamento em aberto.

Parâmetros obrigatórios:

  • contrato: número do contrato comercial.
  • dr: número da Superintendência Estadual do contrato.
  • dataInicial: Data inicial do período (formato DD-MM-YYYY).
  • dataFinal: Data final do período (formato DD-MM-YYYY).

Status dos processamentos

Finalidade: Consulta e busca dos resultados dos processamentos assíncronos (extratos analíticos e prévias).

Endpoints

GET /v1/processamentos/{idProcessamento} – Consulta o status do processamento.

Parâmetros obrigatórios:

  • idProcessamento: ID da solicitação, obtido como resposta do POST /v1/previas ou POST /v1/faturas/{fatura}/analitico.

GET /v1/processamentos/{idProcessamento}/file – Download do arquivo processado. O arquivo (CSV) permanece disponível por 7 dias. Só deve ser utilizado se o status for SUCESSO.

Parâmetros obrigatórios:

  • idProcessamento: ID da solicitação.

6. Exemplos de Integração

6.1 Exemplos requisições

Os exemplos a seguir demonstram o fluxo de consulta de faturas e o processo assíncrono para obtenção do extrato analítico.

  • Consultar as faturas geradas entre 01/09/2025 e 30/09/2025 para o contrato 9987654321 da DR de Minas Gerais (20):

Requisição

curl -X 'GET' \
  ' https://api.correios.com.br/faturas/v1/faturas?contrato=9987654321&dr=20&dataInicial=01-09-2025&dataFinal=30-09-2025' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [TOKEN]'

Resposta (Retorna uma lista de faturas encontradas)

[
    {
      "id": 3469379,
      "contrato": "9987654321",
      "status": "Paga",
      "vencimento": "2025-09-11",
      "valor": 1938.96,
      "itemFatura": "001",
      "tipoDocumento": "RE",
      "dataFechamento": "2025-08-20",
      "tipoPagamento": "10",
      "lote": "ECTRM0000000000000"
    },
    {
      "id": 3497318,
      "contrato": "9987654321",
      "status": "Em aberto",
      "vencimento": "2025-10-13",
      "valor": 1240.14,
      "itemFatura": "001",
      "tipoDocumento": "RE",
      "dataFechamento": "2025-09-20",
      "tipoPagamento": "0",
      "lote": " ECTRM0000000000000"
    }
]
  • Solicitar o extrato analítico da fatura 1234567 (processo assíncrono):

Requisição

curl -X 'GET' \
  ' https://api.correios.com.br/faturas/v1/faturas/1234567/analitico?tipoDocumento=RE&drFatura=00020&itemFatura=001' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [TOKEN]'

Resposta (Retorna o ID do processamento)

{
    "id": "12a123a1-1234-1234-123a-123a123ab1a",
    "tipoProcessamento": "EXTRATO_ANALITICO",
    "status": "SOLICITADO",
    "dataSolicitacao": "2025-10-06T14:06:25",
    "parametros": {
      "tipoDocumento": "RE",
      "drFatura": "00020",
      "idFatura": "1234567",
      "itemFatura": "001"
    }
}
  • Consultar o status de processamento (recibo 12a123a1-1234-1234-123a-123a123ab1a):

Requisição

curl -X 'GET' \
  ' https://api.correios.com.br/faturas/v1/processamentos/12a123a1-1234-1234-123a-123a123ab1a' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [TOKEN]'

Resposta (Status SUCESSO indica que o arquivo está pronto para download)

{
    "id": "12a123a1-1234-1234-123a-123a123ab1a",
    "tipoProcessamento": "EXTRATO_ANALITICO",
    "status": "SUCESSO",
    "dataFimProcessamento": "2025-10-06T14:06:26",
    "nomeArquivo": "extrato-analitico-12a123a1-1234-1234-123a-123a123ab1a.csv",
    "tiporquivo": "text/csv"
}
  • Baixar o CSV da fatura (após o status SUCESSO):

Requisição

curl -X 'GET' \
  ' https://api.correios.com.br/faturas/v1/processamentos/12a123a1-1234-1234-123a-123a123ab1a/file' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [TOKEN]'

Resposta (Retorna o conteúdo do arquivo CSV)

Correios Empresas - Extrato analitico de fatura
Nº DA FATURA;CNPJ;RAZAO SOCIAL;CONTRATO;SE DO CONTRATO;CENTRO DE CUSTO;STATUS;DATA VENCIMENTO;DATA FECHAMENTO;CODIGO DO CLIENTE;DATA PAGAMENTO
1234567;21261100000000;EMPRESA DE TESTE;9900000000;SE/SPI;EMPRESA DE TESTE;Paga;2025-08-11;2025-07-20;00000000;2025-08-11
 
CARTAO POSTAGEM;TITULAR CARTAO;CODIGO SERVICO;SERVICO;DATA POSTAGEM;SERVICOS ADICIONAIS;UNIDADE POSTAGEM;CEP DESTINATARIO;ETIQUETA;DOCUMENTO;PESO;VALOR UNITARIO;DESCONTO;QUANTIDADE;VALOR LIQUIDO;VALOR DECLARADO
00000000;EMPRESA DE TESTE;03298;PAC CONTRATO AG;2025-06-23;-;00000000 AGENCIA DE TESTE;00000000;EN000000000BR;0500000000;350;25,14;0;1;25,14;88,34
... (dados de exemplo)
 
TOTALIZACAO POR SERVICO
CODIGO SERVICO;DESCRICAO SERVICO;QUANTIDADE;VALOR SERVICO;DESCONTO;VALOR LIQUIDO
04227;CORREIOS MINI ENVIOS CTR AG;1;22,08;0;22,08
03298;PAC CONTRATO AG;20;546,19;0;546,19
03220;SEDEX CONTRATO AG;33;935,62;0;935,62
 
TOTALIZACAO FATURA
DESCRICAO;QUANTIDADE;VALOR
Servicos de ciclos anteriores;0;0
Servicos do ciclo atual;54;1.503,89
Complementacao financeira (cota minima);" ";0
Restituicao da complementacao financeira (cota minima);" ";0
Encargos;" ";0
Creditos;" ";0
Debitos;" ";21
Descontos;" ";0
Credito remanescente;" ";0
Total da Fatura;54;1.524,89

6.2 Casos de Uso Comuns

  • Conferir faturas
  • Conferir prévias de faturas
  • Conferir divergências de faturas
  • Se antecipar ao valor previsto das faturas, por meio das prévias de faturas
  • Gerar relatórios detalhados de gastos com os Correios

7. Ambientes Disponíveis

7.1 Ambiente de Homologação

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

É necessário criar uma conta no Meu Correios de homologação, vinculada aos mesmos dados do CNPJ já existente em produção, no endereço: https://meucorreioshom.correios.com.br/

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

7.2 Ambiente de Produção

O acesso em produção é liberado após os passos definidos no item 3.2 deste manual.

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 e não os repassar indiscriminadamente, utilizar sempre protocolo HTTPS e manter atualizada a aplicação.

Caso use uma empresa contratada para desenvolver sua aplicação, recomendamos fazer uso da subdelegação por chave de acesso, já citada neste manual. Tal chave precisa ser revogada ao término do desenvolvimento/contrato.

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.

9. Suporte e Contato

9.1 Canais de Suporte Técnico

9.2 Processo de Abertura de Chamados

O processo geral de abertura de chamados consiste em:

    1. Acessar a página dos Correios;
    2. Ir até o final da página e localizar Suporte ao cliente com contrato:

Sumário do Manual de uso da API Faturas-img3.png

3. Na tela seguinte, clicar em Sistemas Comerciais:

Sumário do Manual de uso da API Faturas-img4.png

4. Na próxima tela, selecionar Correios Web Services / APIs e depois Problemas com a integração:

Sumário do Manual de uso da API Faturas-img5.png

5. Preencher os dados do formulário e clicar em Enviar. É extremamente importante se valer do campo Arquivo até 10MB para anexar as evidências dos problemas encontrados, como imagens, arquivos JSON de requisição e resposta, entre outros. Se necessário, compacte os arquivos num único arquivo ZIP.

Sumário do Manual de uso da API Faturas-img6.png

6. O chamado foi aberto. Será recebido um e-mail de confirmação e a resposta será recebida também por e-mail.

Além da abertura de chamado, também é possível utilizar o contato telefônico com a Central de Atendimento dos Correios, informando o problema enfrentado.

Para os clientes com contato comercial junto aos Correios, não é necessário abertura de chamado. Basta contatar o gestor comercial do contrato e enviar as evidências dos problemas encontrados, nos mesmos moldes do processo de abertura de chamados.

Para clientes que contrataram outras empresas, como TMS, ERP, plataformas de e-commerce, entre outros, e são essas empresas que desenvolveram a integração, o chamado deve ser aberto na empresa contratada. Caso a empresa afirme que o problema é nos Correios, será necessário que a empresa forneça os dados necessários para abertura do chamado, conforme descrito no processo de abertura de chamados, ou essa empresa deve tratar diretamente com os Correios.

É fundamental que sempre sejam enviadas anexar as evidências dos problemas encontrados, como imagens, arquivos JSON de requisição e resposta, entre outros. Essa informação é essencial para a análise do problema por parte dos Correios.

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: https://cws.correios.com.br
DR Diretória Regional, nome antigo das Superintendências Estaduais, órgãos responsáveis pela gestão dos Correios em âmbito Estadual.
HTTPS Hypertext Transfer Protocol Secure: é a versão segura do protocolo HTTP, que utiliza a criptografia SSL/TLS para proteger os dados trocados entre o navegador de um usuário e um site. Ao contrário do HTTP, o HTTPS garante a confidencialidade, a integridade e a autenticidade da comunicação, impedindo que terceiros interceptem ou alterem informações sensíveis.
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, funcionando com base na premissa "quem o possui, tem acesso", sem necessidade de identificação adicional. Ele é tipicamente usado na autenticação de APIs através do protocolo OAuth 2.0, onde é incluído no cabeçalho da requisição HTTP 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 API e da respectiva documentação

Data Evento Versão Responsável Observações
06/10/2025 Criação 1.0 Correios -