Você está na página 1de 24

Documento de Padrões Técnicos de Comunicação (v.3.

0) – STER

Padrões Técnicos de Comunicação


API – STER CORREIOS

Versão 3.0

1
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

Sumário

1. Introdução ....................................................................................................................................................................................................................................... 4
2. API RESTful ......................................................................................................................................................................................................................................... 4
3. Integração CORREIOS x CONTRATANTE .................................................................................................................................................................................. 4
4. Especificação da API REST STER – Serviços/Recursos/Funcionalidades ......................................................................................................................... 6
5. O Parâmetro Código Correios (codigoCorreios): Dados de Identificação da Unidade Prestadora, Atendente e Autenticação em
Sistemas de Terceiros ............................................................................................................................................................................................................................ 7
5.1. Serviço Destinado a Decriptografia do Código Correios .............................................................................................................................................. 8
5.2. Especificação do Serviço e Composição da URL ........................................................................................................................................................... 8
Layout dos campos da requisição ................................................................................................................................................................................................... 8
6. Número do Protocolo STER – Formato...................................................................................................................................................................................... 9
Exemplo: 19010000000001; .................................................................................................................................................................................................................. 9
7. Formas de Integração – Tipos de solução............................................................................................................................................................................ 10
7.1. Modelo do Processo de Atendimento Utilizando Infraestrutura dos Correios – FORMULÁRIO INTERNO CORREIOS ................................... 10
7.1.1. API para Integração com Formulários Dinâmicos dos Correios............................................................................................................................. 11
7.1.2. Layout dos campos da requisição ................................................................................................................................................................................. 11
7.1.3. Layout dos campos da resposta ..................................................................................................................................................................................... 12
7.2. Modelo do Processo de Atendimento Utilizando Infraestrutura Externa aos Correios – Site da CONTRATANTE ......................................... 14
7.2.1. Layout dos campos da requisição ................................................................................................................................................................................. 15

2
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

7.2.2. Layout dos campos da resposta ..................................................................................................................................................................................... 16


8. Processo de Confirmação do Atendimento ....................................................................................................................................................................... 18
 Layout dos campos da requisição ......................................................................................................................................................................................... 18
 Layout dos campos da resposta ............................................................................................................................................................................................. 19
9. Pré-requisitos para Integração................................................................................................................................................................................................. 20
10. Conexão e Segurança ........................................................................................................................................................................................................... 21
11. Cadastro de Usuários no IDCORREIOS ............................................................................................................................................................................... 23

3
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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.

Formulário STER API Parceiro

4
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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.

Sistema STER Sistema Parceiro API STER

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.

5
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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://apps.correios.com.br/static/swagger/?url=/ster/api/swagger.json
HOMOLOGAÇAO (TESTES):
https://apphom.correios.com.br/static/swagger/?url=/ster/api/swagger.json
Ao acessar os endereços da documentação, as credenciais de autorização para visualização serão exigidas. O item 11 deste
documento explica e ilustra como configurar a senha de acesso aos componentes de softwares dos Correios.
Disponibilizamos abaixo links para especificações “template” de serviços REST, que devem servir como balizadores para o
desenvolvimento da API que integra, de forma automatizada, com o formulário dos Correios.

• API para registrar os dados:


https://apps.correios.com.br/static/swagger/?url=/ster/specs/swagger-api-cliente-acao-form-dinamico-ster.json

• API para confirmação de pagamento:


https://apps.correios.com.br/static/swagger/?url=/ster/specs/swagger-api-confirmacao.json

6
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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:
Exemplo de Código Correios:

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

Exemplo de Código Correios aberto:


{"ateNu":44254,"servicoTerceiro":821,"numeroCaixa":1077412,"mcmcuAgencia":"00011574","tipoAgencia":"Propria","codigoAgencia":"22300015","cpf
":"12312312387","matricula":"80808080","nome":"FULANO BELTRANO DE CICLANO","siglaLotacao":"AC CENTRAL DE CAMPO GRANDE
","time":1518087560004}

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;
• nome: Nome do(a) atendente;

7
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

• siglaLotacao: Identificação da lotação do atendente nas unidades dos Correios;


• 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”;
• 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.
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.

Formação da URL:

https://apps.correios.com.br/ster/api/v1/atendimentos/numerocontrato/numeroContrato/chaveCorreios/parametroCodigoCorreios

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


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
O tamanho do valor contido no
campo pode variar conforme a
Parâmetro “codigoCorreios” enviado De 300 a
2 chaveCorreios C 1-1 composição das informações que
na URL do sistema do parceiro 500.
estão criptografadas. A valor
utilizado como possui 385 caracteres.

8
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

Exemplo de formação da URL:


https://apps.correios.com.br/ster/api/v1/atendimentos/numerocontrato/9912280636/chaveCorreios/MfjQG76YyBxJ2qaz4jM4H
ebRrYb0ida7HDizkPELvmJxXAa8kW7bFi12NJsH2gqIwNhtRbfJsSC7W9BNa8FAkpaSOHCc2V3HjMCHS5eWpz4lM7Hc1RmxqjS-Tsm-
x1PPdShs-
z3rH_IENqrkLgjlKhEzYFOnl0HGg_I3os35ypcB72cKS7vDlrEgDVBbBHqZ23AlPWkmId2zdPkuft6p18WdLo3TY3WDYvPqHiML4ODJ-
eESxLUAMPP0fEEFIVCKpgMxBhgogfG69B963rQ3uJF48-
0cePk0RRikEkYwahpMgHPY62F2UXeD4sSClZh2mhN5lfeJexvM3Y8TwHcCkoxuDxObd_raRk92qbiwkmSbf9IQEaNTdIGwk4nw3aEK

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: 19010000000001;

 O número do protocolo identifica unicamente um atendimento.

9
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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.

10
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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


Deve haver um atributo para cada Exemplo:
Campos do Formulário C 1-N
campo da tela de atendimento do Campo na tela = CPF do usuário.
dinâmico Parâmetro = cpfUsuario.
serviço
Número do Protocolo gerado para o Conforme formato especificado no item 5.
C 1-1 14
numeroProtocolo atendimento 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"
}

11
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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


Código que identifica o retorno à Enviar “00” para sucesso e, diferente disto,
N 1-1 2
codigo_retorno requisição, confirmando o sucesso para fluxos de exceção ou alternativos.
ou não da operação.
Mensagem condizente com o C 1-1 1-255
descricao_retorno sucesso, validação dos dados ou
insucesso da operação.

Valor total cobrado no Composto por até 10 dígitos sendo 2


atendimento, relativo a todos os posições reservadas para casas decimais.
valor C 0-1 8 2 Retirar os caracteres “.” (ponto) e “,” (vírgula
serviços. (opcional)
das casas decimais). Ex: R$ 48681,50 =
4868150

Formato para o texto do Ticket:


Texto customizado para impressão - Tamanho da linha = 50 caracteres;
texto_ticket do ticket com os serviços realizados C 0-1 400
- Caractere delimitador da quebra de linha
no site da CONTRATANTE. (opcional) “+”.
- Codificação UTF-8
Ex.: número do pedido, número do título,
chave_cliente Identificador (chave) do registro no C 0-1 30 serial do chip, RENACH, Proposta, Número
sistema do cliente. (opcional) 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" }

12
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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


{ "codigo": 0, "mensagem": "Operação realizada com sucesso" }

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


{ "codigo": 400, "mensagem": "Mensagem negocial de exceção tratada.” }

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


{ "codigo": 500, "mensagem": "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": "17090000001000"
}

13
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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.

14
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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


Deve ser recuperado do Conforme formato especificado
1 codigoCorreios parâmetro repassado na URL. C 1-1 50 no item 3.

Composto por 10 dígitos sendo 2


Valor total cobrado no
posições reservadas para casas
atendimento, relativo a todos os
2 valorServico C 0-1 8 2 decimais.
serviços.
Ex: R$ 48681,50 = 4868150

Sem caracteres especiais (“.” ou


3 numeroIdentificacaoCliente Identificação do usuário atendido C 0-1 14 “-”).
pelo serviço. Ex.: CPF, CNPJ.
Quantidade de serviços realizados
4 quantidade no site da CONTRATANTE C 1-N 2

Ex.: número do pedido, número


Identificador (chave) do registro do título, serial do chip, RENACH,
5 chaveCliente no sistema do cliente. C 0-1 30
Proposta e etc.

Formato para o texto do Ticket:


Texto customizado para impressão - Tamanho da linha = 50
do ticket com os serviços caracteres;
6 textoTicket realizados no site da C 0-1 400 - Caractere delimitador da
CONTRATANTE. quebra de linha “+”.
- Codificação UTF-8

15
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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-
JqReBqoIEjByvU9BbKueTEvWkwXODFXmc0WORScJL_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


Código que identifica o retorno à requisição, N 1-1 2
1 codigo confirmando o sucesso ou não da operação.
Mensagem condizente com o sucesso, validação dos C 1-1 1-255
2 mensagem dados ou insucesso da operação.

Número do Protocolo gerado para o atendimento N 1-1 14 Conforme formato


3 numeroProtocolo
especificado no item 5.

16
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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


{
"codigo": 0,
"mensagem": "Operação realizada com sucesso",
"protocolo": 19010123456789
}

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."
}

17
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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:
 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.
00 = Confirmado
2 codigoConfirmacao Código que define se a confirmação é positiva ou N 1-1 2 99 = Não Confirmado
negativa

Exemplo da formação da requisição


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

18
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

 Layout dos campos da resposta


Item Campo Descrição Tipo Ocorrência Tamanho Decimal Observações

Código que garante sucesso no Este código somente deve ser


1 codigo processo de confirmação da C 0-1 20 retornado mediante sucesso na
transação. requisição da confirmação.

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


{
"codigo": “123456789”
}

Exemplo da formação da resposta: (HTTP STATUS 400 BAD REQUEST)


{
"codigo": “”
}

19
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

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.

20
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

10. Conexão e Segurança

21
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

Toda comunicação entre os servidores dos CORREIOS e do CONTRATANTE deve utilizar um canal seguro, provido com o uso de
HTTPS(SSL3), 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.
Nota: SSL (Secure Socket Layer) - É um protocolo desenvolvido pela Netscape Communications Corporation para dar garantia à
transmissão de dados nas transações comerciais na Internet. Usando a criptografia da chave pública, o SSL fornece uma autenticação
ao servidor, uma criptografia para os dados e integridade de dados para as comunicações entre cliente e servidor.
No SSL2 apenas o servidor é autenticado, enquanto no SSL3 o usuário também deverá apresentar sua identificação para o servidor.
Por isso, optamos por usar o protocolo SSL3 para evitar que os atendentes necessitem autenticar (usuário e senha) a cada acesso.
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(SSL3) e exigir na conexão o certificado válido dos CORREIOS.
 Todos os CONTRATANTES serão cadastrados no sistema IDCorreios 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: IDCorreios – 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.

22
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

11. Cadastro de Usuários no IDCORREIOS


11.1. Realizar o cadastro no ambiente de homologação e/ou produção do idCorreios, por meio do endereço a seguir:

Homologação: https://apphom.correios.com.br/idCorreios

Produção: https://apps.correios.com.br/idCorreios
11.2. Clicar em “Cadastrar-se no idCorreios”;
11.3. Após o cadastro, autenticar utilizando o usuário e senha do idCorreios (enviados para o e-mail cadastrado);
11.4. Configurar a senha específica para acesso aos componentes (vide imagem abaixo). Para a autenticação exigida pelo componente,
apenas a senha irá mudar, o usuário é o mesmo da conta do idCorreios.

23
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS
Documento de Padrões Técnicos de Comunicação (v.3.0) – STER

Equipe responsável pela construção do documento

 Leandro Ribeiro Bosi – DECOR/VICOR

Data da última atualização: 28/05/2019

24
EMPRESA BRASILEIRA DE CORREIOS E TELÉGRAFOS