DINEG/SUCAN/DEDIG
Documentação de integração
|
Data |
Melhoria |
Versão |
|
18/03/2022 |
Criação |
1.0 |
Para facilitar o entendimento, listamos abaixo um pequeno glossário com os principais termos relacionados à pré-postagem.
|
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 |
Cartão que identifica um usuário como cliente de contrato dos Correios. |
|
Código do serviço |
Código dos serviços contratados pelo cliente junto aos Correios. Os códigos de serviços contratados 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. |
|
Token – 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. |
Este material foi desenvolvido para contribuir no planejamento e integração com os Correios em qualquer plataforma desejada pelo cliente.
Para quem deseja integrar com os Correios, existe o Correios API, no qual mostra quais componentes estão liberados para uso pelo cliente. Os componentes abordados neste material são APIs, desenvolvida em REST e utilizando o protocolo HTTP. Ou seja, será fornecida uma url base e com os verbos HTTP vão indicar qual ação está sendo requisitada pelo cliente.
Por fim a acesso ao Correios API é um dos benefícios da política comercial dos Correios.
O acesso as APIs, deve ser realizada pelo catálogo do Correios API. No catálogo o cliente poderá testar e acompanhar as mudanças quando houver. O catálogo está disponível no ambiente de Homologação e Produção:
Homologação: https://cwshom.correios.com.br/
Produção: https://cws.correios.com.br/
Conhecendo a tela do Correios Web Services:
Nome do cliente, lista de opções para acessar Meu Correios, sair do ambiente e outras configurações;
Botão hambúrguer, abre o menu lateral e permitirá acessar a documentação e gestão de acesso a componentes;
Barra de pesquisa e botão para gerar credenciais, a barra de pesquisa mostra uma lista de componentes no qual possui acesso. Já o botão Credenciais permite gerar o token ou “passe” para fazer as tentativas de requisições pelo site;
Aba do componente, o conteúdo de cada barra mostra o nome da API, versão e um link com o api-docs. Logo abaixo do título, ou do grupo, mostra o verbo da requisição. A clicar no verbo “POST”, abre um local no qual permite a realização de testes pelo navegador utilizando a funcionalidade “Try-it out”.
Ter um cadastro válido no Meu Correios;
Para acessar a API, utiliza-se uma senha definida para o componente, para criar a senha deve-se acessar o Correios API;
Ter contrato ativo de prestação de serviços de encomendas ou mensagens com os Correios;
Empresas que fornecem soluções em TI no segmento de logística. (como identificar e disponibilizar um acesso?)
As APIs dos Correios, possuem regras de acesso, sendo:
API Pública: onde todos enxergam a API;
API Restrita: o acesso é realizado a partir do cadastro do serviço no cartão de postagem.
Cada contrato tem sua particularidade para atender melhor cada cliente. Para visualizar as APIs liberadas no seu perfil, basta clicar na barra de pesquisa e visualizar o que está disponível.
Para que APIs Restritas fiquem visíveis, deve-se incluir os dados em:
Credenciais Usuário,
Senha,
Cartão de postagem,
Gerar Token e
Fechar.
Veja que agora aparecem as APIs:
Agência;
Endereço – CEP v3;
Prazo;
Preço;
Rastro.
Para o primeiro teste, será com a geração do Token, API sem restrição e necessária na geração de uma string codificada com os dados de autenticação e autorização para informar as APIs dos Correios.
Ao clicar no “POST”, aparecerá o sub-item Parameters e para habilitar o ambiente basta clicar no botão “Try it out”
Após clicar no botão a tela permitirá digitar o cartão de postagem (1) e clique em execute.
Ao executar, teremos a resposta do servidor, basta rolar a página para baixo até o sub-item Responses.
No item 1: Curl Comandos utilizados ou script de comandos, dentre ele está o verbo da requisição, neste caso “POST”; No item 2: URL de requisição;
No item 3: Code 201 – Created, onde o Corpo do retorno contém o retorno em JSON.
No corpo da requisição do token, teremos: ambiente, id, perfil, dados de contrato, validade do token e o token.
Ponto importante a ser observado, é com relação ao tempo de validade do
token.
Veja o retorno da requisição de exemplo:
|
postagem |
"id": "xxxxxxxxxx", "perfil": "PJ", "cnpj": "00000000000101", "cartaoPostagem": { "numero": "00xxxxxxx7", "contrato": "99xxxxxxxx", "dr": 10, "api": [ 93, 36, 83 ] }, "api": [ 93, 36, 54, 87 ], |
|
Validade do Token |
"emissao": "2022-03-18T10:26:51", "expiraEm": "2022-03-19T10:26:51", |
|
Token |
eyJhbGciOiJSUzUxMiJ9....... |
Explorando o final da página da aba do Token, encontraremos o Grupo Schemas, onde poderá visualizar as propriedades,
As APIs dos Correios foi desenvolvida com a tecnologia REST, além de padrão de mercado, permite escolher ou adotar qual a linguagem de programação poderá utilizar, 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.
A API dos Correios é uma arquitetura orientada a micro serviços permitindo desenvolver sistemas que sejam mais flexíveis, escaláveis e com manutenção mais simples.
Busca Agência
Como o volume de requisições poderá variar de 1 ou centenas de requisições, para obter uma resposta rápida do servidor dos Correios estamos adotando duas formas de requisição: a forma síncrona e a forma assíncrona.
A diferença entre síncrono e assíncrono:
Uma requisição síncrona, deve aguardar a finalização do processamento e somente poderá realizar uma nova solicitação após a resposta da requisição, esta ação, pode dar a sensação de congelamento da requisição.
Uma requisição assíncrona, o cliente envia uma requisição e recebe dados que permitem a consulta do status de processamento. Isso permite realizar novas requisições assíncronas, sem a necessidade de aguardar o fim do processamento das outras requisições. Ao fim poderá requisitar a coleta dos dados que foram processados.
Para iniciar os testes, sem uma ferramenta no qual consiga salvar o que foi desenvolvido, poderá gerar retrabalho. Para isso, neste manual, utilizaremos a ferramenta Postman que permite realizar a execução dos testes e o mais importante salvar o trabalho.
Além do download da ferramenta, poderá utilizar uma extensão pelo navegador Google Chrome, acrescentando a extensão do Postman. Existem outras ferramentas, tal como o Insomnia, utilize a ferramenta de sua preferência.
Esclarecemos que a adoção do Postman é apenas para fins didáticos, considerando que ela facilita o entendimento dos passos para acesso as APIs disponibilizadas pelos Correios.
A coleção permite que separe as APIs que será utilizada no decorrer do manual, poderá ser usado para separação do processo. Tal como: Geração de Token, Geração de Pré-Postagem, Geração de rótulo, etc. Clique no “+” e aparecerá uma coleção escrito “New Collection”.
Clique no “New Collection” e do lado direto clique no lápis ícone ao lado direito do nome.
Escreva o nome da coleção como “Geração de Token”.
Para criar uma requisição, após a criação de uma coleção, poderá clicar em “Add a request”.
Ao lado direito abre uma aba no qual poderá renomear para “Gerar token para o cartão de postagem”
Gerar token para o cartão de postagem
Item 1: abas de navegação;
Item 2: Nome da requisição e a qual coleção pertence; Item 3: Verbo e a url base;
Item 4: informações que podem ser adicionadas por parâmetros, dados de autorização, cabeçalho da requisição, corpo da requisição.
Item 5: botão Send, se pressionar a seta para baixo, poderá enviar e fazer o download do resultado;
Item 6: resposta da requisição.
É necessário utilizar as informações que estão no Correios API, para preencher os campos desta requisição:
Relembrando, nos passos anteriores vimos:
Acesso aos componentes: Login e senha de acesso aos componentes;
Endereço de requisição;
Verbo utilizado na requisição;
O corpo da requisição.
Para este primeiro exemplo, a imagem a seguir, mostra o (1) endereço principal que será utilizado, (2) o verbo e (3) endereço da requisição.
Desta forma o endereço que será utilizado na requisição é a junção do endereço principal (1) e o endereço da requisição (3). Exemplo: https://apihom.correios.com.br/token/v1/autentica/cartaopostagem.
No endereço de requisição e no verbo ficará assim:
No login e senha, clique na aba (1) Authorization, selecione em Type (2) “Basic Auth” e (3) preencha os dados de login e senha
Próximo passo é enviar os dados do cartão de postagem, clique em (1) Body,
(2) raw, (3) JSON e (4) copie o JSON do site Correios Web Services de homologação.
Clique em “Send” e veja o retorno:
Com base nesse passo a passo, poderá ser replicado a qualquer API.
O CEP (Código de Endereçamento Postal) é um conjunto numérico constituído de oito algarismos, que orienta e acelera o encaminhamento, o tratamento e a distribuição de objetos de correspondência, por meio da sua atribuição a localidades, logradouros, unidades dos Correios, serviços, órgãos públicos, empresas e edifícios. (Para saber mais: Tudo sobre CEP)
Sobre a documentação existente no Correios API, é que os testes poderão ser realizados na própria documentação:
Ou pelo Postman:
Neste exemplo, será utilizado o método que requer o valor para consultar o endereço de um CEP.
A url base é: 'https://apihom.correios.com.br/cep/ ' e que segundo a documentação será um GET : “/v1/endereços/{cep}”.
Observação: Por padrão o CEP é formado por 8 dígitos numéricos, mas para alguns endereços utilizamos o 0 (zero) a esquerda, exemplo: 01001001.
Para a requisição:
Teremos a resposta:
Em caso de exceção, há o retorno http 400 do servidor, tal como os seguintes exemplos:
Em caso de CEP Inexistente:
Em caso de digitar fora do padrão:
Neste exemplo foi usado o CEP: 01001-001, com o hífen. Porém o retorno informa a quantidade de caracteres e o formato de exemplo.
A API Busca Agência tem a funcionalidade de mostrar as agências por localidade. Há pesquisa por unidades e localidades.
Para utilizar a consulta das unidades, é necessário recuperar os dados de tipos de unidades e status.
Para a API Agência a base url: “https://apihom.correios.com.br/agencia”, e para o exemplo será utilizado um GET: “/v1/unidades” com parâmetros.
Exemplo da requisição:
Com o retorno:
Nesta pesquisa de exemplo, o atributo size informa quantos elementos por página, foi colocado na requisição um size= 50 ou seja 50 elementos por página, totalizando 145 páginas. Caso a mesma consulta for realizada para informar o conteúdo das demais páginas, basta informar no atributo page o valor de 0..144, se mantiver o size=50.
A busca do preço e prazo, estão separadas, para atender ao conceito de micro-serviços. Desta forma, são duas páginas no catálogo do Correios API.
API Prazo (35):
Para a base url: https://apihom.correios.com.br/prazo/ utilizando o GET:
/v1/nacional/{coproduto}
Temos o seguinte retorno:
Utilizando o Postman:
Para a base url: https://apihom.correios.com.br/prazo/ utilizando o POST:
/v1/nacional
Para obter o seguinte retorno:
Utilizando o Postman
API Preço
Para a base url: https://apihom.correios.com.br/preco utiliza-se o GET:
/v1/nacional/{codigoServico} Para a requisição:
Temos o seguinte retorno:
No Postman:
Para obter a precificação de até 5 simulações, será utilizado o POST. Para base url: https://apihom.correios.com.br/preco e com o POST: /v1/nacional
Obtendo o seguinte retorno:
"tpServAdicional": "V", "pcServicoAdicional": "0,79"
},
{
"coServAdicional": "001", "tpServAdicional": "A", "pcServicoAdicional": "7,00"
}
],
"peAdValorem": "0,0100",
"vlSeguroAutomatico": "21,00",
"qtAdicional": "0",
"pcFaixa": "10,14",
"pcFaixaVariacao": "10,14",
"pcProduto": "10,14",
"pcTotalServicosAdicionais": "7,79",
"pcFinal": "17,93"
},
{
"coProduto": "04162",
"pcBase": "9,73",
"pcBaseGeral": "10,14",
"peVariacao": "0,0000",
"pcReferencia": "10,14",
"vlBaseCalculoImposto": "17,93",
"nuRequisicao": "1",
"inPesoCubico": "N",
"psCobrado": "300", "servicoAdicional": [
{
"coServAdicional": "019", "tpServAdicional": "V", "pcServicoAdicional": "0,79"
},
{
"coServAdicional": "001", "tpServAdicional": "A", "pcServicoAdicional": "7,00"
}
],
"peAdValorem": "0,0100",
"vlSeguroAutomatico": "21,00",
"qtAdicional": "0",
"pcFaixa": "10,14",
"pcFaixaVariacao": "10,14",
"pcProduto": "10,14",
"pcTotalServicosAdicionais": "7,79",
"pcFinal": "17,93"
}]
No Postman
Esta API permite consultar o status do objeto dentro do fluxo postal. A aba desta API
será:
A exemplo das demais APIs, é utilizado um url base: https://apphom.correios.com.br/rastro com o GET: /v1/objetos/{codigoObjeto}
Realizando a requisição:
Obtendo o retorno:
"resultado": "Todos os Eventos", "objetos": [
{
"codObjeto": "DG049186226BR",
"tipoPostal": { "sigla": "DG",
"descricao": "ENCOMENDA SEDEX (ETIQ LOGICA)",
"categoria": "SEDEX"
},
"dtPrevista": "2022-03-11T20:58:00",
"modalidade": "F",
"peso": 0.5,
"formato": "Pacote", "eventos": [
{
"codigo": "BDE",
"tipo": "01",
"dtHrCriado": "2022-03-11T17:03:00",
"descricao": "Objeto entregue ao destinatário", "unidade": {
"tipo": "Unidade de Atendimento", "endereco": {
"uf": "AC",
"cidade": "XAPURI"
}
}
},
{
em tempo real ",
"codigo": "OEC",
"tipo": "03",
"dtHrCriado": "2022-03-11T17:02:45",
"descricao": "Objeto em rota de entrega",
"detalhe": "Aguarde envio de link para acompanhar a entrega
"unidade": {
"tipo": "Unidade de Tratamento", "endereco": {
"uf": "SP",
"cidade": "SAO PAULO"
}
}
},
{
"codigo": "RO",
"tipo": "01",
"dtHrCriado": "2022-03-11T17:02:35",
"descricao": "Objeto em trânsito", "detalhe": "Por favor, aguarde", "unidade": {
Este material foi desenvolvido para facilitar ao leitor que estava acostumado com o Web Services dos Correios, que havia um padrão SOAP XML e com a migração para REST poderá sentir falta de material explicativo que era fornecido para cada sistema. Com o Correios API, centralizamos as documentações e como a atualização é dinâmica recomenda-se que retorne com frequência.
Para todas as APIs citadas neste material, são as que estão liberadas para uso. Desta forma, caso tenham dúvidas referente a API o procedimento é entrar em contato com o Assistente Comercial de sua região ou Contrato.
Informações de atendimento poderão ser obtidas pelo nosso site: https://www.correios.com.br/falecomoscorreios/central-de-atendimento
