Manual - Correios Log+

Manual de Uso da API Correios LOG+

Sumário

1. Apresentação

1.1. Objetivo do Manual

Este manual tem como objetivo orientar desenvolvedores e equipes técnicas na integração com a API de e-Fulfillment. Ele descreve os recursos disponíveis, padrões técnicos utilizados e boas práticas de integração.

1.2. Escopo da API

Essa API visa automatizar o processo de solicitação e envio de mercadorias, seja para um público interno, como produtos enviados de um centro de distribuição (CD) para filiais ou externo, onde o envio ocorre diretamente para o cliente final.

A API permite realizar operações relacionadas ao ciclo de pedidos e estoque, incluindo:

  • Consulta de estoque de produtos;
  • Consulta e criação de pedidos;
  • Envio do XML da Nota Fiscal associado a pedidos.

1.3. Público-Alvo

Este manual destina-se a desenvolvedores, analistas de sistemas, integradores e demais profissionais responsáveis pela implementação e manutenção da comunicação entre sistemas externos e a plataforma de e-Fulfillment.

2. Visão Geral da API

Uma API (Application Programming Interface) tem como principal objetivo a comunicação entre sistemas distintos, independentemente de suas tecnologias. Por meio dessa abordagem, duas aplicações podem utilizar uma linguagem comum, compreendida por ambos, possibilitando a adição de novas funcionalidades a uma aplicação, por meio da disponibilização de funções de sistemas externos.

2.1. Finalidade da API

Automatizar e padronizar a comunicação entre sistemas de vendas/ERP e a plataforma de fulfillment, reduzindo as chances de erros ou retrabalho e aumentando a eficiência operacional.

2.2. Funcionalidades Principais

  • Verificar disponibilidade de produtos em estoque;
  • Criar e consultar pedidos;
  • Associar documentos fiscais a pedidos criados.

2.3. Arquitetura e Tecnologias Utilizadas

Na API efulfillment, é utilizado o estilo arquitetural REST (Representational State Transfer), que utiliza o protocolo HTTP e seus métodos para manipular recursos, permitindo uma comunicação padronizada entre os sistemas envolvidos.

Para o trânsito de dados é utilizado o JSON (JavaScript Object Notation), sendo este um formato de texto leve e independente de linguagem de intercâmbio de dados estruturados.

2.4. Fluxo Geral de Integração

Para a utilização da API efulfillment, o cliente deve possuir:

  1. IdCorreios cadastrado para o CNPJ da empresa;
  2. Contrato junto aos Correios;
  3. Código de acesso às APIs.

O fluxo sugerido para a utilização da API efulfillment é:

manual correios log - imagem01.webp

3. Autenticação e Autorização

3.1. Métodos de Autenticação Suportados

O acesso à API efulfillment utiliza autenticação Basic, sendo utilizadas as seguintes credenciais:

  • Usuário: idCorreios da PJ do contrato;
  • Senha: código de acesso às APIs gerado no CWS.

Obs.: A autenticação do tipo Basic é uma codificação em base64, composto das seguintes informações:

  1. IdCorreios da PJ do contrato;
  2. Dois pontos (:); e
  3. Código de acesso às APIs.

Ex.: idCorreios:qazwsxedcrfvtgbyhnujmikolpqazswerfdxcvgt, se torna: aWRDb3JyZWlvczpxYXp3c3hlZGNyZnZ0Z2J5aG51am1pa29scHFhenN3ZXJmZHhjdmgt

3.1.1. Dados de autenticação em homologação

No ambiente de homologação, deverão ser utilizados os seguintes dados:

idCorreios Código de acesso às APIs Cartão de Postagem
hgimporthom 9QFAX2Sjr3uGB5OQRBhQvHSVG2uIzXxk1jgkr7jc 0073249300

3.2. Obtenção de Credenciais

As credenciais de acesso necessárias para a autenticação, são obtidas da seguinte forma:

  • Criação de login (idCorreios): criado no Meu Correios;
  • Código de acesso às APIs: gerado no Correios Web Services (CWS).

Obs.: O idCorreios pode ser verificado no CWS, ao tentar gerar um token de acesso nesse ambiente, clicando no botão 'Credenciais'. O valor descrito no campo 'Usuário' do modal que se abre, é o idCorreios do usuário.

3.3. Escopos e Permissões

Assim como as demais APIs presentes no CWS, a API efulfillment possui dois ambientes distintos, sendo eles: homologação e produção.

Como são ambientes distintos, suas URLs base também são diferentes:

Assim como suas URLs, suas credenciais também são distintas. Portanto, não há a possibilidade de utilização de credenciais de homologação em produção e vice-versa. Por mais que os ambientes sejam semelhantes, são distintos e por isso cada ambiente possui uma autenticação própria.

3.4. Exemplo de Requisição Autenticada

No exemplo abaixo, temos um exemplo de requisição de consulta de pedidos, onde é utilizado o verbo GET e uma URL de homologação.

curl -X 'GET' \
'https://apphom.correios.com.br/efulfillment/v1/pedidos/336979' \
-H 'accept: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...-Exw'

A resposta a essa chamada em caso de sucesso (status 200), segue a seguinte estrutura:

{
  "numeroPedido": 336979,
  "codigoArmazen": "00425009",
  "numero": "900774",
  "dataSolicitacao": "2025-08-25 08:00:03",
  "valorDeclarado": "null",
  "cartaoPostagem": "0077777777",
  "codigoServico": "39888",
  "cnpjTransportadora": "31234567000199",
  "itensPedido": [
    {
      "codigo": "AR1313",
      "quantidadeEstoque": "1",
      "codigoInformacao": "null"
    }
  ],
  "destinatario": {
    "nome": "Nome do Destinatário",
    "logradouro": "Rua Maria Cezarina França",
    "numeroEndereco": "100",
    "complemento": "Casa",
    "bairro": "Residencial Califórnia Garden",
    "cep": "37953356",
    "cidade": "São Sebastião do Paraíso",
    "uf": "MG",
    "ddd": "31",
    "telefone": "12345678",
    "email": "teste@email.com.br",
    "cnpj": "32345678000188"
  },
  "situacao": {
    "codigoSituacao": "A",
    "descricao": "Aprovado"
  }
}

E em caso de erro do cliente (status 400), a seguinte estrutura poderá ser observada:

{
  "msgs": [
    "Pedido não encontrado. "
  ],
  "date": "2025-09-22T16:51:38",
  "path": "uri=/efulfillment/v1/pedidos/336979",
  "causa": "ApiNegocioRuntimeException: Pedido não encontrado. ",
  "stackTrace": "br.com.correios.api.commons.exception.ApiNegocioRuntimeException: Pedido não encontrado. \n\tat br... \tat java.base/java.lang.Thread.run(Thread.java:1583)\n"
}

4. Padrões Técnicos Utilizados

4.1. Formato das Requisições e Respostas

  • Requisições: JSON (UTF-8)
  • Respostas: JSON (UTF-8)
  • Upload de NF-e: XML

4.2. 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, sendo:

  • 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:

  • 200 – Sucesso
  • 201 – Criado
  • 400 – Requisição inválida
  • 401 – Não autorizado
  • 404 – Não encontrado
  • 500 – Erro interno

5. Documentação dos Endpoints

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

Cada endpoint é documentado com: método, URL, parâmetros, corpo da requisição e exemplo de resposta.

As URLs base da API efulfillment são as seguintes:

5.2. Endpoints por Domínio Funcional ou por categoria

5.2.1. Produto

5.2.1.1. Consultar estoque de um produto

[GET] /v1/produtos/{sku}/estoque?armazem={ codArmazem }

Cabeçalhos:

Chave Valor esperado
Authorization Basic ****
Accept application/json
numeroCartaoPostagem String (10 caracteres)

Legenda dos valores esperados:

  • sku: código do produto cadastrado no armazém;
  • codArmazem: código do armazém onde está o produto;
  • numeroCartaoPostagem: cartão de postagem em que o pedido será faturado.
5.2.1.2. Consultar estoque de um produto em um determinado armazém

[GET] /v1/produtos/estoque?armazem={codArmazem}&produto={sku}

Cabeçalhos:

Chave Valor esperado
Authorization Basic ****
Accept application/json
numeroCartaoPostagem String (10 caracteres)
5.2.1.3. Versão/release atual do componente

[GET] /v1/produtos/versão

Cabeçalhos:

Chave Valor esperado
Authorization Basic ****
Accept application/json

5.2.2. Pedidos

5.2.2.1. Criar pedido

[POST] /v1/pedidos

Cabeçalho:

Chave Valor esperado
Authorization Basic ****
Accept application/json
Content-Type application/json
numeroCartaoPostagem String (10 caracteres)

Corpo da requisição:

Campo Tipo Descrição Obrigatório
codigoArmazem String (10) Código do armazém onde o pedido será criado. Em homologação, utilizar o armazém 00426980. S
numero String (12) Número do pedido para controle do cliente S
dataSolicitacao String (20) Data da solicitação do pedido S
valorDeclarado String (13) Valor a ser recebido em casos de problemas na entrega. Obrigatório para os serviços adicionais 019 ou 064. S
cartaoPostagem String Cartão de postagem onde será faturado o pedido S
codigoservico String Serviço escolhido para o pedido (PAC, SEDEX, etc). S

Exemplo de corpo da requisição:

{
  "codigoArmazem": "00425009",
  "numero": "1",
  "dataSolicitacao": "02/10/2025 08:00:03",
  "valorDeclarado": "",
  "cartaoPostagem": "0077777777",
  "codigoservico": "39888",
  "servicosAdicionais": [],
  "cnpjTransportadora": "34028316000103",
  "numeroPLP": "",
  "numeroSerie": "",
  "destinatario": {
    "nome": "José Bonifácio de Andrada e Silva",
    "logradouro": "Rua Maria Cezarina França",
    "numeroEndereco": "100",
    "complemento": "Casa",
    "bairro": "Residencial Califórnia Garden",
    "cep": "37953356",
    "cidade": "São Sebastião do Paraíso",
    "uf": "MG",
    "ddd": "31",
    "telefone": "12345678",
    "email": "teste@email.com.br",
    "cnpj": "34028316000103",
    "cpf": ""
  },
  "itensPedido": [
    {
      "codigo": "TKC463",
      "quantidade": "1"
    }
  ]
}
5.2.2.2. Consultar dados do pedido

[GET] /v1/pedidos/{numeroPedido}

Cabeçalhos:

Chave Valor esperado
Authorization Basic auth
Accept application/json
Content-Type application/json
numeroCartaoPostagem String (10 caracteres)
5.2.2.3. Consultar dados do pedido por período

[GET] /v1/pedidos?datainicio={dataInicio}&datafim={datafim}

Cabeçalhos:

Chave Valor esperado
Authorization Basic ****
Accept application/json
numeroCartaoPostagem String (10 caracteres)
5.2.2.4. Versão/release atual do componente

[GET] /v1/pedidos/versao

Chave Valor esperado
Authorization Basic ****
Accept application/json

5.2.3. Nota Fiscal

O XML da NF segue o formato padrão da Receita Federal e junto à estrutura desse XML, deverá ser inserida na tag <compra> a tag <xPed>, como o exemplo que segue. Nessa tag, deverá conter o número do pedido retornado na criação do pedido.

Ex.:

<nfeProc xmlns="http://www.portalfiscal.inf.br/nfe" versao="4.00">
<NFe xmlns="http://www.portalfiscal.inf.br/nfe">
<infNFe versao="4.00" Id="NFe00000000000000000000000000000000000000000000">
<compra>
<xPed>12547</xPed>
</compra>
...
</nfeProc>
5.2.3.1. Validar a estrutura do XML da NF

[POST] /v1/xmldanfepedido/verifica/schema/xml

Chave Valor esperado
Authorization Basic ****
Accept application/json
numeroCartaoPostagem String (10 caracteres)
Content-Type Application/x-www-form-urlencoded
5.2.3.2. Enviar o XML da NF

[POST] /v1/xmldanfepedido/xml

Chave Valor esperado
Authorization Basic ****
Accept application/json
Content-Type application/x-www-form-urlencoded
numeroCartaoPostagem String (10 caracteres)
codigoArmazem String (8 caracteres)

Observações:

  • Agendar este envio do arquivo XML para que ocorra, uma primeira vez, 30 minutos após a integração do pedido, e caso a resposta não seja de sucesso, enviar novamente em intervalos de 10 em 10 minutos por, no máximo, mais 6 vezes (60 minutos). Após estes envios, se ainda assim a resposta não for de sucesso, alertar aos clientes, pois poderá estar ocorrendo alguma inconsistência com a NFe.
  • Caso a transportadora seja os Correios, o CNPJ a ser informado é o 34028316000103 na tag <transporta> do XML da NFe.

6. Exemplos de Integração

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

Abaixo, segue um exemplo de requisição GET, de consulta de pedido por período na linguagem PHP:

Citação de Figura: Figura 02 - Exemplo de requisição GET em PHP.

E também, um exemplo de requisição POST, para verificar se o XML é válido.

Citação de Figura: Figura 03 - Exemplo de requisição POST em PHP.

7. Boas Práticas

7.1. Segurança na Integração

  • Utilizar sempre HTTPS;
  • Proteger chaves de API;
  • Não expor credenciais em códigos públicos.

7.2. Validação de Dados

Antes de criar um pedido, valide os dados enviados à API, como:

  • Validar os CEPs de origem e destino na API CEP (41); ou
  • Certificar-se de que o CPF/CNPJ informado seja válido.

Isso reduzirá a chance de erros e consequentemente o consumo de recursos de TI.

8. Suporte e Contato

8.1. Canais de Suporte Técnico

Demandas relacionadas às APIs dos Correios, devem ser direcionadas ao seu consultor comercial ou também via Fale Conosco, no site dos Correios.

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

8.2. Processo de Abertura de Chamados

Ao abrir um chamado, sempre que possível, informe o curl completo da requisição; tanto a requisição, quanto a resposta desta, para que possamos analisar o caso com a maior assertividade possível.

  • Ambiente (homologação ou produção);
  • Endpoint utilizado;
  • Payload da requisição (quando possível);
  • Código de erro retornado.

9. Anexos

9.1. Lista de Armazéns

Nome Código
Brasília/DF 00430112
Cajamar/SP 00426980
Cidade Nova/RJ 00430158
Contagem/MG 00425002
Curitiba/PR 00425009
Florianópolis/SC 00435017
Fortaleza/CE 00434971
Goiânia/GO 00437733
Indaiatuba/SP 00440918
Manaus/AM 00435120
Porto Alegre/RS 00435102
Recife/PE 00425007
Recife/PE 00435019
Salvador/BA 00435020
Serra/ES 0043892

9.2. Glossário de Termos Técnicos

Termo Descrição
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 O cartão de postagem deve pertencer ao usuário cadastrado no Meu Correios. O número do cartão de postagem é fornecido pelo representante Comercial dos Correios, após a celebração do contrato Múltiplo ou inclusão do Anexo do serviço à um contrato já existente.
Código do serviço Código dos serviços contratados pelo cliente junto aos Correios. Os códigos de serviços constam do contrato comercial que o cliente firmou com os 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.
Meu Correios Mecanismo de autenticação e autorização para acesso aos serviços que os Correios disponibilizam via internet.
Senha de componente Senha definida pelo usuário do Meu Correios que permite a um usuário utilizar os componentes disponibilizados pelos Correios.
URL Abreviação de Uniform Resource Locator - é o endereço de qualquer site na internet.