Padrões Técnicos de Comunicação - STER

Padrões Técnicos de Comunicação

API - STER

Sumário

1. Introdução

Este documento tem por objetivo a definição das especificações e dos critérios técnicos necessários à integração entre os sistemas dos CONTRATANTES e/ou parceiros dos CORREIOS na prestação de serviços com a utilização do STER - Sistema de Serviços de Terceiros dos CORREIOS.

A integração ocorre via API REST, por meio da qual as aplicações e/ou serviços proprietários dos CONTRATANTES realizam o envio e recebimento das informações relacionadas ao serviço executado, registrando as informações importantes para o cumprimento do contrato entre as empresas.

2. API RESTful

API (Application Programming Interface) é o termo utilizado para designar a camada de uma aplicação que disponibiliza recursos a serem utilizados por outras aplicações/sistemas, abstraindo-se detalhes de implementação, regras específicas e restrições para utilização de tais recursos.

REST (Representational State Transfer) é considerado um modelo ou conjunto de conceitos e padrões utilizados na construção de uma API baseada em comunicação via rede (HTTP). Um serviço web, sendo projetado sob a referência e boas práticas do modelo REST, é considerado um serviço RESTful.

3. Integração CORREIOS x CONTRATANTE

O STER oferece duas modalidades para a prestação do serviço do parceiro na rede dos Correios, devendo-se optar pelo cenário que melhor se adequar à plataforma, a fim de se evitar customizações e/ou evoluções sistêmicas que podem interferir no funcionamento de serviços previamente contratados e estabelecidos:

3.1. Formulário Interno (Dinâmico) dos Correios:

Criação de um formulário responsável pela captação e envio de informações para o sistema da CONTRATANTE através de uma API disponibilizada pelos mesmos. A API do parceiro deve estar preparada para receber, além dos parâmetros específicos para os campos da tela, o número do protocolo STER.

3.1.png

3.2. Aplicação/Sistema do Contratante:

O atendente dos CORREIOS é redirecionado para uma página ou aplicação específica do serviço do CONTRATANTE e, mediante sucesso na prestação do serviço, tal aplicação deve fazer requisição a API dos Correios (STER) para registrar a transação e possibilitar finalização do atendimento. Estando em conformidade, o número do protocolo STER é retornado.

3.2.png

Para serviços cujo cenário utiliza formulários ou aplicações externas (de propriedade da CONTRATANTE), o STER adiciona, à URL da aplicação do parceiro, um parâmetro de controle dos CORREIOS denominado “codigoCorreios”. Esse parâmetro é requerido posteriormente para utilização da API STER de registro do atendimento.

4. Especificação da API REST STER – Serviços/Recursos/Funcionalidades

A documentação da API do STER foi produzida e disponibilizada a partir do Swagger, framework open source que auxilia os desenvolvedores no desenho, especificação e documentação de APIs e segue a iniciativa Open API, que busca a padronização de APIs REST. Essa especificação basicamente descreve os recursos de APIs, como endpoints, parâmetros de entrada, objetos de retorno, códigos HTTP, métodos de autenticação, entre outros.

Abaixo os links para a especificação da API STER conforme o ambiente:

PRODUÇÃO:

https://cws.correios.com.br/ buscar por 288 – STER Rest

HOMOLOGAÇAO (TESTES):

https://cwshom.correios.com.br/ buscar por 288 – STER Rest

Ao acessar os endereços da documentação item 13, as credenciais de autorização para visualização serão exigidas.

5. O Parâmetro Código Correios (codigoCorreios): Dados de Identificação da Unidade Prestadora, Atendente e Autenticação em Sistemas de Terceiros

• O parâmetro “codigoCorreios” é formado por um conjunto de informações criptografadas que, ao ser transformado para sua forma aberta, gera um trecho de código JSON contendo os seguintes dados de exemplo:

MfjQG76YyBxcOGFJCbuhkz6E2BLvN5Zd8YV-j5KzNd7rjwHsd4Ss1wkxVNV5-VKNPwCHG9axUUm8WRu0Den_LXnyd50V33Go_dDcGMulSGYWAt1fCCRWzWNMojBVPqEOahcm5xnPwUY3Wwquh2XqEU0OCQJxI-2aJCiL8ccI6EiTXbM-wOWMN0Xn8G0enU37Z5KiIlfFCzxaFzdDaNB8J2Dt5zrDVcxbqhon6EF6OfvXUzsx7DLzy3Jv2GoFzKAzSmY0iNAVo-7ls9ZWtc677hn6S6KHlalWsC2eqx2z7okrYy5hcWhWoo6Sqx1fAPlJO-xcCyO4Y6pTy1OUqkyr46BmUOqOIGWh94KFONC-086T8VF7NI42jmeINa0azEeLWWWWW

Obs.: esse código não poderá ser utilizado, pois os códigos são gerados somente no momento do atendimento e detêm tempo restrito para utilização.

Exemplo de Código Correios:

Exemplo de Código Correios aberto (unidade própria/matrícula e CPF):

{
"ateNu": 119482,
"servicoTerceiro": 3102,
"numeroCaixa": 1143890,
"mcmcuAgencia": "00011574",
"tipoAgencia": "Propria",
"codigoAgencia": "22300015",
"cpf": "27492710534",
"matricula": "80834574",
"chave": "Y29ycmVpb3M6bVZZVVJMJGs=", (somente para serviços com codificação de usuário e senha)
"nome": "ALDA BOHANA BANDEIRA DE MELO",
"siglaLotacao": "AC CENTRAL DE CAMPO GRANDE",
"time": 1704891359190,
"cep": "79002970",
"cidade": "CAMPO GRANDE",
"uf": "MS"
}

Exemplo de Código Correios aberto (unidade terceirizada/matrícula e CPF):

{
"ateNu": “97545”,
"servicoTerceiro": “681”,
"numeroCaixa": “1131758”,
"mcmcuAgencia": "00234640",
"tipoAgencia": "Terceirizada"
"codigoAgencia": "00234640",
"cpf": "12312312387",
"matricula": "80808080",
"chave": "Y29ycmVpb3M6bVg2VzzMJGs=", (somente para serviços com codificação de usuário e senha)
"nome": "FULANO BELTRANO DE CICLANO",
"siglaLotacao": "AGF CENTRO",
"time": 1628110906222
"cep": "79002970",
"cidade": "CAMPO GRANDE",
"uf": "MS"
}

Descrição dos parâmetros:

• ateNu: Identificador de controle dos Correios;
• servicoTerceiro: Identificador interno aos Correios;
• numeroCaixa: Número identificador do terminal onde foi prestado o serviço;
• mcmcuAgencia: Identificador da unidade onde foi prestado o serviço;
• tipoAgencia: Indicador do tipo da unidade onde foi prestado o serviço;
• codigoAgencia: Código secundário da unidade onde foi prestado o serviço;
• cpf: CPF de identificação do atendente;
• matricula: Número da matrícula que identifica o atendente. Para atendentes funcionários dos Correios em agências próprias;
• chave: Quando especificado, usuário e senha codificados em “base 64” utilizados para realização de autenticação no sistema do cliente. No seguinte padrão: “usuário:senha”;
• nome: Nome do(a) atendente;
• siglaLotacao: Identificação da lotação do atendente nas unidades dos Correios;
• Time: Tempo em milissegundos que representa o momento em que foi feita a requisição. Esta informação pode ser utilizada para incrementar a segurança nas requisições, adicionando tempo de expiração do link.
• cep: CEP da unidade de atendimento (novo)
• cidade: Nome da cidade da unidade de atendimento (novo)
• uf: Unidade da Federação da unidade de atendimento (novo)

Os Correios, mediante manifestação da necessidade do cliente em obter ou armazenar estas informações, disponibilizam um recurso da API STER que realiza a decriptografia das informações.

5.1. Serviço Destinado a Decriptografia do Código Correios

A API do STER possui um recurso cujo objetivo é decifrar o parâmetro “codigoCorreios” e ter acesso aos parâmetros referentes ao atendimento que está sendo realizado.

Para tal fim, executar uma requisição do tipo GET, passando os parâmetros “Número do Contrato” e “Código Correios” no path do endereço. Lembrando que, para conseguir utilizar a API é necessário credenciais de autorização e o número do contrato é fornecido pelos Correios.

5.2. Especificação do Serviço e Composição da URL

5.2.1. Layout dos campos da requisição

Item Campo Descrição Tipo Ocorrência Tamanho Observações
1 numerocontrato Número do Contrato com os Correios. C 1-1 12 -
2 chaveCorreios Parâmetro “codigoCorreios” enviado na URL do sistema do parceiro C 1-1 De 300 a 700. O tamanho do valor contido no campo pode variar conforme a composição das informações que estão criptografadas. 

Exemplo de formação da URL:

https://apphom.correios.com.br/ster/api/v1/atendimentos/numerocontrato/9912320209/chaveCorreios/MfjQG76YyBwnGuAbumklkpPpd8QX23nKyGHpiTOZ_m-gpbIJKTjPD5VPVlo9A6Yn8XD4EhXK3TeypqhQhOtfkAPJ14Ocxjl1K39coSi0w76O-YeUfbAt_aPYZ4mUoxraY4kW2bGiJFfEkxiaiktfYRmJsdZwAjDW5Y6Fd_ymszLMminWNSz0Yum7tQ3b-IzQeBnvjNyix0sOeJ8BWO1Si97oxejC9jyRrl6yqmmGwTXbaLFlw1kNrJOHiCWoOx-Q3MhWaYViwxaVg4vFBz8DOlTsri8aDNHGVCT5SPWaZ40sOC0_TqjK-O1IDqAhnDHhS9BOFPKp3ur0YpByQOd7mu7Lu7Ko-tqcP-nsZzFbHePXFnRoKP6bj5alo0Z18ZD-YCJAgz8NaEC2pFvbUBSXm0c5fefV8pgQEfF3b8nT_9KZKpxoBZQ4yA

6. Número do Protocolo STER – Formato

Ano (2 dígitos) + ID da CONTRATANTE (2 dígitos) + Sequencial (10 dígitos). Totalizando 14 dígitos.
Exemplo: 24010000000001;
• O número do protocolo identifica unicamente um atendimento.

7. Formas de Integração – Tipos de solução

7.1. Modelo do Processo de Atendimento Utilizando Infraestrutura dos Correios – FORMULÁRIO INTERNO CORREIOS

Nesse tipo de solução, o atendente executa o atendimento com a utilização do formulário interno do sistema STER, associado ao serviço que está sendo prestado, e após captação das informações, as envia via Webservice (API) a CONTRATANTE.

fluxo_ster.jpg

7.1.1. API para Integração com Formulários Dinâmicos dos Correios

A CONTRATANTE deverá disponibilizar uma API REST, que trafegue JSON, contendo um ENDPOINT para registrar e/ou validar os atendimentos realizados no ambiente dos Correios. Na submissão do formulário, será disparado um POST, enviando os dados captados pelo formulário no corpo da requisição.

7.1.2. Layout dos campos da requisição

O serviço deve conter, respectivamente, um atributo para receber o valor de cada campo do formulário dinâmico e ainda, o número do Protocolo STER.

Campo Descrição Tipo Ocorrência Tamanho Decimal Observações
Campos do Formulário dinâmico Deve haver um atributo para cada campo da tela de atendimento do serviço C 1-N Exemplo:
Campo na tela = CPF do usuário.
Parâmetro = cpfUsuario.
numeroProtocolo Número do Protocolo gerado para o atendimento C 1-1 14 Conforme formato especificado no item 5. Esse campo será enviado pelo STER e deverá ser armazenado pelo Cliente.

Exemplo da formação da requisição:

POST /api/cliente/registraAtendimento HTTP/1.1
Host: hostCliente
Content-Type: application/json
cache-control: no-cache
{
"campo1": "string",
"campo2": "string",
"campoN": "string",
"protocolo": "string"
}

7.1.3. Layout dos campos da resposta

Como resposta, dentre as informações específicas de cada serviço, os campos abaixo especificados são requeridos para que o sistema STER possa extrair as informações necessárias para concretização e registro da transação. Observação: Em decorrência de integrações pré-existentes com outros sistemas, tais campos devem obedecer a nomenclatura exata especificada na tabela abaixo.

Campo Descrição Tipo Ocorrência Tamanho Decimal Observações
codigo_retorno Código que identifica o retorno à requisição, confirmando o sucesso ou não da operação. N 1-1 2 Enviar “00” para sucesso e, diferente disto, para fluxos de exceção ou alternativos.
descricao_retorno Mensagem condizente com o sucesso, validação dos dados ou insucesso da operação. C 1-1 1-255 -
valor Valor total cobrado no atendimento, relativo a todos os serviços. (opcional) C 0-1 8 2 Composto por até 10 dígitos sendo 2 posições reservadas para casas decimais. Retirar os caracteres “.” (ponto) e “,” (vírgula das casas decimais).
Ex: (tarifa manual): R$ 48681,50 = “4868150”
Ex: (tarifa ERP): “”
texto_ticket Texto customizado para impressão do ticket com os serviços realizados no site da CONTRATANTE. (opcional) C 0-1 500 Formato para o texto do Ticket:
- Tamanho da linha = 50 caracteres;
- Caractere delimitador da quebra de linha “+”.
- Codificação UTF-8
chave_cliente Identificador (chave) do registro no sistema do cliente. (opcional) C 0-1 30 Ex.: número do pedido, número do título, serial do chip, RENACH, Proposta, Número do documento, protocolo ANATEL, etc.

Exemplo das informações que devem ser retornadas:

{ "codigo_retorno": "string", "descricao_retorno": "string", "valor": "string", "texto_ticket": "string", "chave_cliente": "string" }

Exemplo da formação da resposta: (HTTP STATUS 200 OK).

{ "codigo_retorno": "string", "descricao_retorno": "string", }

Sugestão para string da “descrição_retorno”: "Operação realizada com sucesso."

Exemplo da formação da resposta: (HTTP STATUS 400 Bad Request).

{ "codigo_retorno": "string", "descricao_retorno": "string", }

Sugestão para string da “descrição_retorno”: "Mensagem negocial de exceção tratada.”

Exemplo da formação da resposta: (HTTP STATUS 500 Internal Server Error).

{ "codigo_retorno": "string", "descricao_retorno": "string", }

Sugestão para string da “descrição_retorno”: " Falha no processamento.”

Uma operação disponibilizada na API do STER pode ser utilizada como exemplo ou modelo para a API que será contruída. Sua especificação pode ser acessada no Swagger, no endpoint abaixo:

• /v1/atendimentos/simulaPrestacaoServico

POST /ster/api/v1/atendimentos/simulaPrestacaoServico HTTP/1.1

Host: apps.correios.com.br

Content-Type: application/json

cache-control: no-cache

{

"campo1": "Campo 1",

"campo2": "Campo 2",

"sucesso": "00",

"protocolo": "24090000001000"

}

7.2. Modelo do Processo de Atendimento Utilizando Infraestrutura Externa aos Correios – Site da CONTRATANTE

Para esta solução o atendente dos Correios é redirecionado para uma aplicação proprietária da CONTRATANTE, onde executa todo o processo de atendimento. Ao concluir o atendimento, mediante SUCESSO na operação, o sistema deve realizar requisição POST a API do STER para registro da transação no sistema dos CORREIOS que, por sua vez, retorna o número do protocolo de atendimento.

7.2.png

7.2.1. Layout dos campos da requisição

Endpoint para o registro das informações do atendimento: /v1/atendimentos/registra

Item Campo Descrição Tipo Ocorrência Tamanho Decimal Observações
1 codigoCorreios Deve ser recuperado do parâmetro repassado na URL. C 1-1 De 300 a 700 Conforme formato especificado no item 5.
2 valorServico Valor total cobrado no atendimento, relativo a todos os serviços C 0-1 8 2 Composto por 10 dígitos sendo 2 posições reservadas para casas decimais.
Ex: (tarifa manual): R$ 48681,50 = “4868150”
Ex: (tarifa ERP): “”
3 numeroIdentificacaoCliente Identificação do usuário atendido pelo serviço. Ex.: CPF, CNPJ. C 0-1 14

Sem caracteres especiais:

(“.”, “-” ou “/”).
4 quantidade Quantidade de serviços realizados no site da CONTRATANTE C 1-N 3
5 chaveCliente Identificador (chave) do registro no sistema do cliente. C 0-1 30

Ex.: número do pedido, número do título, Proposta e etc.

6 textoTicket Texto customizado para impressão do ticket com os serviços realizados no site da CONTRATANTE. C 0-1 500

Formato para o texto do Ticket:

- Tamanho da linha = 50 caracteres;

- Caractere delimitador da quebra de linha “+”.

- Codificação UTF-8

Exemplo da formação da requisição:

POST /ster/api/v1/atendimentos/registra HTTP/1.1
Host: hostCliente
Content-Type: application/json
cache-control: no-cache
{
"codigoCorreios":"MfjQG76YyBwq0PUq_-lDedCxutdFjl0611i92AV76-ZYFbS-PQ-ZfsKQwpfNosSNjSOFCNvcujjj5- qReBqoIEjByvU9BbKueTEvWkwXODFXmc0WORScJL_D3jR5bvhmboBZ2Aeq7Vh0sSzYZhhfpVO0dwrVbMPR2yDfz-0I3yYNTWtWzftgSum5ud3w9UBg9u7Co-dfVJXGh3Sv19MCOS3PysHoH4aBEESuO6aSmwRb8iYj4_REYV7qb_EV1HtITLcy264yfSRx8vBobJ_ufdbxHzAgjfk6BxzEB_IUynwhQd48jgXM5-G2EKI5WbQIks2sPFwgvz9pTAs17l6etjNU0y8gxhD7wYFFrlpI4uKtJmEwP1opERs63_eMsCX",
"valorServico":"4458",
"numeroIdentificacaoCliente":"9912123456",
"quantidade":"1",
"chaveCliente":"ASL-0293651/18",
"textoTicket":"Texto adicional no ticket"
}

7.2.2. Layout dos campos da resposta

Ao realizar o registro das informações do atendimento com sucesso, o número do protocolo é retornado, caso contrário, uma mensagem descrevendo o motivo da falha e seu respectivo código são retornados.

Item Campo Descrição Tipo Ocorrência Tamanho Decimal Observações
1 codigo Código que identifica o retorno à requisição, confirmando o sucesso ou não da operação. N 1-1 3
2 mensagem Mensagem condizente com o sucesso, validação dos dados ou insucesso da operação C 1-1 1-255
3 numeroProtocolo Número do Protocolo gerado para o atendimento N 1-1 14

Conforme formato especificado no item 6.

Exemplo da formação da resposta: (HTTP STATUS 200 OK)

{
"codigo": “0”,
"mensagem": "Operação realizada com sucesso.",
"protocolo": 24010123456789
}

Exemplo da formação da resposta: (HTTP STATUS 400 Bad Request)

{
"codigo": “400”,
"mensagem": "Parâmetro obrigatório: CóDIGO DOS CORREIOS."
}

Exemplo da formação da resposta: (HTTP STATUS 500 Internal Server Error)

{
"codigo": “500”,
"mensagem": "Falha no processamento. Registro foi revertido e novo atendimento deve ser iniciado."
}

8. Processo de Confirmação do Atendimento

Conforme a modalidade adotada para a integração Correios-Parceira, partes do atendimento acontecem em momentos e localizações diferentes. O processo de atendimento inicia no STER, passa pelo site e/ou serviço da CONTRATANTE e é concluído no sistema SARA – Sistema de Automação da Rede de Atendimento dos Correios. Para garantir a integridade da informação em todas as pontas do processo de venda/prestação do serviço, é necessário seguir um dos passos abaixo para viabilizar a consistência na integração entre as aplicações:

1. A CONTRATANTE pode agendar um processo de conciliação diária (após as 22h, horário de fechamento das últimas agências), e utilizar a API do STER para verificar a situação atual do atendimento na base de dados dos Correios. Esse método permite consultar todos os atendimentos realizados no dia, com sua respectiva situação. Caso a situação seja “FINALIZADO” o atendimento deve ser confirmado na base de dados da CONTRATANTE. Se a situação for “CANCELADO” ou “ESTORNADO”, o mesmo não deve ser confirmado;

2. A CONTRATANTE deve disponibilizar um serviço REST com um recurso (endpoint) “confirmarAtendimento” para ser chamado sempre que o atendimento for finalizado no sistema SARA. Essa confirmação pode ser positiva ou negativa e deve seguir o seguinte layout de interface:

8.1. Layout dos campos da requisição

Item Campo Descrição Tipo Ocorrência Tamanho Observações
1 numeroProtocolo Número do Protocolo gerado para o atendimento N 1-1 14 Conforme formato especificado no item 5
2 codigoConfirmacao Código que define se a confirmação é positiva ou negativa N 1-1 2

00 = Confirmado
99 = Não Confirmado

Exemplo da formação da resquisição:

POST /api/confirmarAtendimento HTTP/1.1
Host: hostCliente.com.br
Content-Type: application/json
cache-control: no-cache
{
"numeroProtocolo": "24070000184742"
"codigoConfirmacao": "00",
}

8.2. Layout dos campo da resposta

Item Campo Descrição Tipo Ocorrência Tamanho Decimal Observações
1 codigo Código que garante sucesso no processo de confirmação da transação. C 0-1 20 Este código somente deve ser retornado mediante sucesso na requisição da confirmação.

Exemplo da formação da resposta: (HTTP STATUS 200 OK)

{
"codigo": “strig”
}

Exemplo da formação da resposta: (HTTP STATUS 400 Bad Request)

{

"codigo": “”

}

9. Pré-requisitos para Integração

Quando o formulário for externo (sistema Web ou necessidade de validações via serviço no ambiente tecnológico da CONTRATANTE), a CONTRATANTE:

• Deve utilizar o protocolo HTTPs em todas as URLs e solicitar o certificado de segurança válido dos CORREIOS;

• Uma vez que o usuário que está operando o sistema, um atendente dos CORREIOS, já se encontra certificado e autenticado na plataforma de atendimento, o sistema de propriedade do CONTRATANTE não poderá exigir nova autenticação. Quando necessária, deverá ocorrer de forma automática e com a utilização das credenciais enviadas no parâmetro “codigoCorreios”, que será única para os CORREIOS, logo, utilizada para todos os acessos. O item 10 deste documento trata a aborda questões sobre a segurança na comunicação entre os CORREIOS e a CONTRATANTE.

• Deve possibilitar a exibição e/ou impressão do número do protocolo de atendimento STER mediante sucesso no atendimento para efeito de confirmação pelo atendente;

• A CONTRATANTE deve disponibilizar um webservice para receber a confirmação de que a operação foi finalizada no ambiente dos Correios. Tal serviço será chamado pelo STER após conclusão do atendimento no sistema SARA. Não será considerada finalizada uma transação realizada apenas no ambiente da CONTRATANTE;

• Deve viabilizar a utilização dos formulários na rede de atendimento dos CORREIOS. Para que essa premissa seja alcançada, faz-se necessário minimizar o tráfego de informações, utilizando recursos de compactação de conteúdo e evitando a utilização de imagens, códigos script e demais recursos que consumam excessivamente a banda de comunicação. No quesito desempenho, uma requisição satisfatória deve trafegar aproximadamente 100KB de conteúdo por requisição;

• Deve realizar conciliações diárias/mensais de transações;

• Deve possibilitar que a aplicação/site seja suportada pelo navegador Mozilla Firefox;

• Deve prover um ambiente de homologação integrado aos Correios, com massa de dados compatíveis para a realização de testes do serviço. Este ambiente deve simular o ambiente de produção da solução tecnológica da CONTRATANTE. Deverá estar disponível durante toda a vigência do contrato.

Observação: A aprovação do sistema no ambiente de homologação é pré-requisito para a implantação em ambiente de produção.

10. Conexão e Segurança

10.png

Toda comunicação entre os servidores dos CORREIOS e do CONTRATANTE deve utilizar um canal seguro, provido com o uso de HTTPS(TLS1.2 ou superior), onde os dados trafegam criptografados e autenticados por meio de um certificado válido de ambos os lados. Desta forma, fica garantido ao CONTRATANTE que o acesso é proveniente dos CORREIOS, não se fazendo necessária uma autenticação pelos atendentes dos Correios para acesso ao formulário.

Configurações necessárias para integração entre as aplicações:

• Incluir certificado dos CORREIOS na relação de confiança do servidor onde serão disponibilizados os formulários para acesso do STER. Para ambiente de testes (homologação), solicitar aos CORREIOS o(s) arquivo(s) contendo a cadeia de certificação. Para ambiente produtivo, o mesmo pode ser adquirido diretamente através do mecanismo de exportação do certificados do navegador;

• Configurar o acesso ao formulário próprio com HTTPS(TLS1.2 ou superior) e exigir na conexão o certificado válido dos CORREIOS.

• Todos os CONTRATANTES serão cadastrados no sistema Meu Correios e receberão suas respectivas credencias (usuário / senha) com as permissões de acesso aos serviços. Estas credenciais são exigidas para acessar tanto a documentação, quanto a URL dos serviços e recursos de integração com o STER (Sistema de Serviços de Terceiros).

Nota: Meu Correios – Solução corporativa para autenticar usuários e tratar as autorizações de acesso a componentes e/ou sistemas.

• As APIs e serviços dos CORREIOS realizam gravação de LOG com objetivo de controlar e rastrear a utilização dos serviços disponibilizados, identificando as principais informações das requisições para eventuais consultas e estatísticas.

11. Métodos de autenticação

O STER pode utilizar dois métodos de autenticação para acessar os serviços do parceiro:

  • Basic Auth

O STER irá acessar os recursos do parceiro através de uma requisição HTTP que possui o header “Authorization” contendo usuário e senha.

Exemplo do header:

Authorization Basic (usuário e senha codificados em Base64)

  • Bearer Token

O STER irá acessar os recursos do parceiro de acordo com o fluxo “Client Credentials” especificado no framework “OAuth2”. A requisição HTTP para o “Authorization Server” terá o parâmetro “grant_type=cliente_credentials”. A requisição HTTP para o recurso terá o header “Authorization” contendo um token fornecido pelo “Authorization Server” do parceiro.

O “Authorization Server” do parceiro deverá retornar em sua resposta pelo menos os campos “access_token” e “expires_in”.

Descrição dos campos:

“access_token”: deverá conter o token gerado pelo “Authorization Server” do parceiro.

“expires_in”: deverá conter o tempo em segundos que o token permanecerá válido.

Exemplo da resposta: Neste caso, o token ficará válido por 12 horas.

{

access_token: “string do token”,

expires_in: “43200”

}

Exemplo do header:

Authorization Bearer (string do token)

12. Cadastro de Usuários no MeuCorreios (Pessoa Jurídica)

12.1. Realizar o cadastro no ambiente de homologação e/ou produção do Meu Correios, por meio dos endereços a seguir:

► Homologação: https://meucorreioshom.correios.com.br/app/

► Produção: https://meucorreios.correios.com.br/app/

12.2. Clicar em “Fazer Cadastro” e seguir os passos para realizar o cadastro. Lembrando que o acesso as API's pode ser restrito a clientes de contrato;

12.2.png

13. Gerar código de acesso da API

13.1 Após realizar o cadastro no Meu Correios, deve acessar, o endereço dos Correios Web Services (conforme link dos ambientes abaixo). Ao acessar o link a página abaixo será exibida:

► Homologação: https://cwshom.correios.com.br

► Produção: https://cws.correios.com.br

13.1.png

13.2. Representado pelas três linhas horizontais (botão de hambúrguer), permite abrir o menu lateral no qual permite acessar as opções:

13.2.1. Documentação, Gestão de acesso a API e Ajuda (1);
13.2.2. Menu de acesso ao perfil e Sair do ambiente (2);

13.3. Dashboard ou tela de acesso as API(s)(3).

13.3.1. Para gerar o código de acesso a(s) API(s), deve acessar o menu lateral (abrir pelo botão de hambúrguer) e clicar na opção (1) Gestão de acesso a APIs; (2) Informe a senha utilizada no portal Meu Correios (3) Clique no botão para gerar ou regerar o código de acesso.

13.3.png

13.4. Dado que o cliente já possua um código de acesso, o sistema exibirá uma mensagem de confirmação antes de emitir o novo (5) Clique em "Sim" para prosseguir.

13.4.png

13.5. O código de acesso gerado será exibido como na imagem abaixo. Copie e guarde para utilizar na geração do token.

13.5.png

14. Utilizando as API's

14.1. A tela principal do CWS, é semelhante à figura abaixo:

14.1.png

14.2. O CWS permite realizar os primeiros testes após a emissão do código de acesso a(s) API(s).
14.3. A tela permite gerar a chave de acesso (token) (1); Para conhecer as API(s) que são acessíveis, ao clicar na barra de pesquisa (2), abre a lista de APIs; e (3) a documentação da API.

14.3.png

14.3.1. O código de acesso a(s) API(s) e o gerador de token

14.3.1.1. É necessário emitir o código de acesso para que seja possível gerar o token (essa ação garantirá que o acesso foi habilitado para o novo MeuCorreios cadastrado);

14.3.2. Gerando o token

14.3.2.1. Clicar na opção “Credenciais”, como mostra a figura abaixo:

14.3.2.1.png

14.3.2.2. Vai abrir a janela para inserir os dados necessários para incluir os dados de autenticação, que é o código de acesso da API (1).

14.3.2.3. Preenchido basta gerar o token (2), o token gerado (3) não será utilizado na integração com o Sistema de Serviços de Terceiros - STER, ele apenas garante que o acesso foi habilitado para o novo MeuCorreios cadastrado.

14.3.2.3.png

Data da última atualização: 10/01/2024