Manual - Correios Web Service
Sumário
- 1 - O que é o Correios Web Services?
- 2 – Acessando o CWS
- 3 – Acessando a documentação das APIs
- 4 - Gerando código de acesso da API
- 5 - Subdelegando acesso
- 6 – Tratando as credenciais
- 7 - Utilizando as APIs
- 8 - Preparando o ambiente no Postman
- 9 - Atualizações do Manual
1 - O que é o Correios Web Services?
O Correios Web Services (CWS) é uma plataforma de serviços web que permite a integração direta com os sistemas dos Correios, oferecendo acesso a dados e funcionalidades que agregam valor aos produtos e serviços dos clientes. Por meio dessa integração, é possível obter informações mais precisas, como dados de endereçamento, otimizando processos e melhorando a experiência do usuário final.
O CWS é voltado para clientes dos Correios que desejam desenvolver soluções personalizadas em Tecnologia da Informação (TI), utilizando APIs (Application Programming Interfaces) para acessar os serviços disponíveis. O acesso às APIs pode ser aberto ou restrito, dependendo da funcionalidade e do tipo de autorização concedida ao cliente com contrato ativo.
A comunicação com o CWS é realizada por meio do protocolo HTTP (Hypertext Transfer Protocol), utilizando os padrões REST ou SOAP. As respostas são fornecidas nos formatos JSON ou XML, garantindo interoperabilidade e flexibilidade para integração com diferentes plataformas e frameworks.
No modelo REST, por exemplo, é fornecida uma URL base, e os verbos HTTP (GET, POST, PUT, DELETE) determinam a ação solicitada pelo cliente.
O acesso ao ambiente de homologação do CWS, utilizado para testes, é feito por meio do link: https://cwshom.correios.com.br. Esse ambiente requer login e senha específicos, fornecidos conforme a funcionalidade desejada.
Para utilizar o CWS, é necessário possuir um perfil no portal Meu Correios, acessível em: https://meucorreioshom.correios.com.br
2 – Acessando o CWS
Para acessar os serviços do CWS, é necessário realizar primeiramente o cadastro no portal Meu Correios.
2.1. Como cadastrar usuário pessoa jurídica
Para realizar o cadastro no Meu Correios, siga os passos abaixo:
- Acesse o link:
https://meucorreioshom.correios.com.br - Na tela de acesso conforme figura abaixo, clique na opção “Cadastrar”.
- Siga as instruções apresentadas para concluir o processo de registro.
Figura 1- Tela de acesso ao Meu Correios
Importante: O acesso a determinadas APIs pode ser restrito a clientes com contrato ativo com os Correios. Certifique-se de que seu perfil esteja devidamente vinculado ao contrato para garantir o acesso às funcionalidades desejadas.
2.2. Como acessar o CWS
Após realizar o cadastro no Meu Correios, o usuário deve acessar pelo endereço dos Correios Web Services: https://cwshom.correios.com.br/.
Ao acessar o link a página abaixo será exibida, clicar em “entrar” conforme figura a seguir:
Figura 2- Tela de acesso do CWS
Fornecer usuário e senha cadastrados no Meu Correios e clicar em “entrar”, conforme figura abaixo:
Figura 3 - Tela de login do CWS
Ao realizar o login no CWS, a tela inicial será abaixo será exibida conforme figura abaixo:
Figura 4- Tela inicial do CWS
1 - Esta opção é representada pelas três linhas horizontais no canto superior esquerdo da tela (ícone de hambúrguer (☰)) e permite abrir o menu lateral abaixo, no qual permite acessar as seguintes opções:
- Início: dá acesso às opções de informações iniciais do CWS como a documentação das últimas APIs pesquisadas;
- Documentação: dá acesso à documentação das APIs;
- Gestão de acesso a API’s: dá acesso a geração de código de acesso às APIs;
- Chaves de acesso: dá acesso a criação de chaves de acesso para subdelegação;
- Ajuda: dá acesso ao manual de ajuda do CWS disponível.
2 – Esta opção dá acesso ao Meu Correios, ao perfil do usuário logado, a abrir nova sessão ou sair do CWS.
3 – Tratamento de credenciais necessárias
4 - Dashboard ou tela de acesso as documentações das API(s).
3 – Acessando a documentação das APIs
Para acessar a documentação das APIs, clique na opção “Documentação”’ localizada no menu lateral esquerdo e digite o nome ou código da API para pesquisa no campo indicado conforme exemplo da figura a seguir:
Figura 5 - Documentação de APIs
Observação: Apenas as APIs autorizadas e/ou validadas para o usuário logado terão a respectiva documentação disponível para consulta.
4 - Gerando código de acesso da API.
Para gerar o código de acesso à API, siga os passos abaixo:
- Acesse o menu lateral clicando no ícone de hambúrguer (☰) no canto superior esquerdo da tela.
- Clique na opção "Gestão de acesso a APIs".
- Informe a senha utilizada no portal Meu Correios.
- Clique no botão "Gerar" ou "Regerar código de acesso", conforme necessário.
Figura 6 - Gestão de acesso a APIs
O código de acesso gerado será exibido como na figura abaixo. Copie e guarde para utilizar na geração do token, observando as instruções dadas na mensagem.
Figura 7 - Geração de código de acesso
Caso o cliente já possua um código de acesso, o sistema exibirá uma mensagem de confirmação antes de emitir o novo código conforme figura a seguir, clique em "Sim" para prosseguir, observando as instruções dadas na mensagem.
Figura 8 - Nova Geração de código de acesso
5 - Subdelegando acesso
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 subdelegação de acesso está disponível diretamente no painel de administração do CWS, no menu Chaves de Acesso, ou através do endereço https://cws.correios.com.br/chaves-acesso. O cliente com contrato interessado deverá seguir os passos abaixo:
- Acionar o menu Chaves de Acesso, ou acessar o endereço https://cws.correios.com.br/chaves-acesso, sendo que para esse acesso o cliente precisa ter usuário e senha Meu Correios, e clicar e “Criar nova Chave”
- Preencher os campos "Nome de identificação" e "Descrição" (usados para permitir a identificação da chave e seu permissionário) e selecionar, no campo "Expiração", o tempo de validade da autorização;
- Indicar as APIs que deseja liberar, selecionando uma das opções:
a) APIs restritas / autorizadas por idCorreios:Ligar ou desligar a opção de cada API disponível no painel conforme desejado e configurar se a API será habilitada para grupo específico e, se leitura ou acesso total.
Figura 11 - APIs restritas / autorizadas por idCorreios
b) APIs restritas por contrato
Caso desejar conceder acesso para todas as APIs de determinado contrato, deverá ser informado o número do contrato equivalente no respectivo espaço.
Desta forma, todas as APIs do contrato indicado aparecerão e poderão ser liberadas para operação do terceiro em nome do cliente dos Correios.
c) APIs restritas por cartão de postagem
Caso desejar conceder acesso para todas as APIs de determinado cartão de postagem, deverá ser informado o número do cartão de postagem equivalente no respectivo espaço.
Desta forma, todas as APIs do cartão indicado aparecerão e poderão ser liberadas para operação do terceiro em nome do cliente dos Correios.
- Após indicar todas as opções necessárias, deve clicar no botão "Criar nova chave" para que essa seja então criada e exibida ao usuário;
- A chave de acesso emitida conforme os procedimentos acima deverá ser utilizada para autenticar as requisições às APIs liberadas pelo cliente, sendo que essa chave deverá ser enviada no parâmetro "Authorization" do tipo "Bearer Token";
- Para alterar o escopo de liberação de uma chave de acesso anteriormente criada, basta clicar no botão “editar chave” conforme a seguir e realizar as alterações desejadas e confirmar a ação no botão “Alterar Chave”.
- Para revogar uma chave de acesso, o cliente deve acessar a página "https://cws.correios.com.br/chaves-acesso", localizar a chave que deseja cancelar e acionar o botão lixeira para "Revogar Chave" conforme a seguir:
Figura 9 - Menu Chave de acesso
Figura 10 - Descrevendo chaves de acesso
Observação: É possível conceder acesso até 180 dias. Ao término do prazo configurado, a chave de acesso concedida será automaticamente revogada.
Figura 12 - Criação de nova chave
Figura 13 - Alteração de chave de acesso
Figura 14- Chave de acesso gerada
Figura 15 - revogação de chave
Aparecerá uma mensagem de alerta conforme exemplo a seguir, e ao confirmar a ação, a chave de acesso será revogada e o acesso anteriormente concedido, não será mais permitido por meio desta chave.
Figura 17 - Alerta de revogação de chave
Observações:
Em todas as ações de gestão de chave (criação, edição e revogação), será enviado um e-mail para o cliente contratante conforme a seguir:
Figura 16 - e-mail gestão de chaves
Ressaltamos que todos os clientes interessados na utilização dessa funcionalidade devem realizar a subdelegação conforme as orientações fornecidas pelos Correios, com a devida atenção às questões de segurança e conformidade.
Use suas chaves com segurança, não compartilhe sua chave de API com outras pessoas, nem a exponha no navegador ou em outros códigos do lado do cliente.
6 – Tratando as credenciais
O desenvolvedor, de posse da chave de acesso recebida pelo cliente com contrato dos Correios, será responsável pela validação da chave de acesso e consulta da documentação das APIs autorizadas no CWS.
6.1. Validação da Chave de Acesso
- O desenvolvedor interessado deve acessar o CWS, e na tela “Início” ou “Documentação”, clicar no item “Credenciais”, lembrando que para esse acesso ele precisa ter Usuário e senha Meu Correios (https://meucorreios.correios.com.br/).
Figura 17 - Acesso às credenciais
Ao clicar em
, aparecerá a tela de credenciais de acesso com o campo “usuário” já preenchido com o usuário autenticado, não sendo possível alterar esta informação.
- Para validar uma chave de acesso recebida, o desenvolvedor deve selecionar o tipo de credencial: “Chave de acesso”, colar a chave de acesso recebida no campo "Chave de acesso"(campo obrigatório) e clicar em “Validar chave” conforme tela a seguir:
Figura 18 - credenciais de acesso
Observação:
- Chaves de Acesso expiradas ou revogadas não poderão ser validadas. Estas situações devem ser resolvidas diretamente com o cliente com contrato com os Correios.
6.2. Consulta da documentação de APIs autorizadas
- Ao validar a Chave de Acesso seguindo os passos anteriores, a documentação das respectivas APIs autorizadas estarão disponíveis na tela de “Documentação” para consulta, conforme exemplo a seguir:
Figura 19 - consulta documentação APIs autorizadas
- Selecione a API desejada e visualize a respectiva documentação:
Figura 20 - documentação de API
7 - Utilizando as APIs
Para acessar as URLs utilizadas para gerar token, siga os passos abaixo.
7.1. Entendendo os autenticadores
É necessário emitir o código de acesso para que seja possível gerar o token;
O gerador de token, ou chave de acesso, no qual permite gerar uma chave criptografada com dados válidos, é que autoriza o acesso aos dados da API e com prazo de validade.
Importante: Recursos que ainda estão em SOAP, utilizam somente as credenciais da API, o portal CWS não simula as requisições em SOAP, para isso, deve utilizar uma aplicação semelhante ao SOAPui. E para utilizar a tecnologia REST, deve utilizar as credenciais da API para gerar o token, e utilizar o token para realizar as requisições mais seguras.
7.2. Gerando o token
Para gerar o token, na tela principal, clicar na opção: .
A Autorização poderá ser realizada por “usuário/código de acesso”, por “contrato” ou por “cartão de postagem”, como mostra a figura abaixo:
Figura 21 - Tipos de autorização de acesso
Autorização por usuário ou código de acesso
Para prosseguir com a geração do token por usuário, devem ser preenchidos o código de acesso a API, assinalar o tipo de autorização “Apenas usuário/código de acesso” e clicar em “Gerar token”. Caso todas as informações estejam válidas, o token gerado será visualizado no campo assinalado, basta copiar e utilizá-lo.
Figura 22 - Token por usuário
Atenção: Todas as APIs autorizadas para o usuário informado serão acessadas por meio deste token gerado.
Autorização por Contrato
Para prosseguir com a geração do token por contrato, devem ser preenchidos o código de acesso a API, assinalar o tipo de autorização “Contrato” e clicar em “Gerar token”. Caso todas as informações estejam válidas, o token gerado será visualizado no campo assinalado, basta copiar e utilizá-lo.
Figura 23 - Token por contrato
Atenção: Todas as APIs autorizadas para o contrato informado serão acessadas por meio deste token gerado.
Autorização por Cartão de Postagem
Para prosseguir com a geração do token por cartão de postagem, devem ser preenchidos o código de acesso a API, assinalar o tipo de autorização “Cartão de Postagem” e clicar em “Gerar token”. Caso todas as informações estejam válidas, o token gerado será visualizado no campo assinalado, basta copiar e utilizá-lo.
Figura 24 - Token por cartão de postagem
7.3. Realizando os primeiros testes
A API – Token (5) permite a criação da chave criptografada para acesso a diversas Apis dos Correios e está liberada para o acesso a todos os usuários do CWS.
As imagens a seguir ilustram o padrão da tela, composto por três elementos principais:
(1) o título, acompanhado de um link para a documentação no formato JSON;
(2) as requisições verbais; e
(3) os schemas, que funcionam como um dicionário de dados, descrevendo a estrutura e os tipos de informações utilizados.
Figura 25 - Tela de documentação da API
Figura 26 - Tela de documentação da API
Ao clicar, por exemplo, no verbo POST, abre uma tela no qual permitirá a realização de testes no portal do CWS, sem a necessidade de instalação de outros softwares.
Figura 27 - Verbos API
Para executar a requisição, clicar no botão: 
conforme figura anterior.
Figura 28 - Corpo da Resposta ou Response body
Como o código de resposta foi 201, requisição realizada com sucesso, teremos um retorno da chave criptografada para uso em uma API. Além disso há também os dados referente ao Meu Correios do requisitante conforme preenchido na tela de credenciais.
É no corpo da resposta, conforme a seguir, que o desenvolvedor poderá aplicar a mesma chave para outras requisições porque sua vigência é de 24h. Além disso, verificar a quais sistemas o usuário com o perfil PJ, possui na lista de códigos de API e em qual ambiente está utilizando para fazer as requisições.
Importante: Caso o usuário saia dessa tela, será necessário informar novamente as credenciais de acesso para testar a API.
8 - Preparando o ambiente no Postman
Antes de iniciar os testes, é importante utilizar uma ferramenta que permita salvar as requisições desenvolvidas. A ausência desse recurso pode gerar retrabalho e dificultar a continuidade dos testes. Por esse motivo, neste manual utilizaremos o Postman, uma ferramenta que possibilita a execução dos testes e, principalmente, o salvamento das requisições realizadas.
O Postman pode ser baixado diretamente pelo site oficial: https://www.postman.com. Alternativamente, é possível utilizá-lo como extensão no navegador Google Chrome. Caso você já utilize outra ferramenta que permita configurar o verbo HTTP e a URL, não há problema — sinta-se à vontade para continuar com ela.
Ressaltamos que a escolha pelo Postman se deve à sua praticidade na homologação de APIs. No entanto, este manual não tem como objetivo ensinar o uso da ferramenta, mas apenas utilizá-la como apoio para os testes.
8.1. Conhecendo a Interface do postman
A interface do Postman é intuitiva e organizada em áreas funcionais que facilitam a criação, execução e análise de requisições. Abaixo, apresentamos os principais grupos e suas funcionalidades conforme figura a seguir:
Figura 29 - Interface do postman
- Abas de Navegação
Localizadas no topo da interface, permitem alternar entre diferentes requisições abertas. Cada aba representa uma requisição em edição ou execução. - Nome da Requisição e Coleção Associada
No canto superior esquerdo da aba da requisição, você pode visualizar e editar o nome da requisição. Abaixo, é exibido o nome da coleção à qual ela pertence, facilitando a organização. - Verbo HTTP e URL Base
Logo abaixo do nome da requisição, você encontrará:
- Um menu suspenso para selecionar o verbo HTTP (GET, POST, PUT, DELETE, etc.).
- Um campo para inserir a URL base da API que será testada.
Abaixo da URL, há várias abas que permitem configurar detalhes da requisição:
- Params: Adicione parâmetros de consulta (query string) à URL.
- Authorization: Configure o tipo de autenticação (Bearer Token, Basic Auth, etc.).
- Headers: Insira cabeçalhos personalizados, como Content-Type ou Authorization.
- Body: Defina o corpo da requisição, especialmente útil para métodos como POST e PUT. Pode ser em formato JSON, form-data, x-www-form-urlencoded, entre outros.
O botão “Send” executa a requisição. Ao clicar na seta ao lado do botão, você terá opções adicionais, como:
- “Send and Download”: Executa a requisição e permite baixar a resposta como arquivo.
A parte inferior da tela exibe a resposta retornada pela API, com diversas informações úteis:
- Status HTTP (ex: 200 OK, 404 Not Found)
- Tempo de resposta
- Tamanho da resposta
- Corpo da resposta (em JSON, XML, HTML, etc.)
- Headers da resposta
Você também pode visualizar a resposta em diferentes formatos e copiar os dados para análise ou documentação.
8.2. Criando uma coleção
As coleções permitem agrupar as APIs que serão utilizadas ao longo deste manual, como por exemplo: Geração de Token, Pré-Postagem, Geração de Rótulo, entre outras. Isso facilita a organização e o acesso às requisições.
Siga os passos abaixo para criar uma nova coleção:
- Clique no botão “+”localizado na barra lateral esquerda do Postman.
- Na seção de coleções, será exibida uma opção chamada “New Collection” conforme figura a seguir.
- Clique em “New Collection”para selecioná-la.
- Ao lado do nome da coleção, clique no ícone de lápis (ou rename) para editar e renomeie a coleção com o nome desejado, por exemplo: “Geração de Token”, conforme figura a seguir.
Figura 30 - Criando nova coleção no postman
Figura 31 - tela de edição da coleção no postman
8.3. Criando a requisição
Após criar a coleção, você pode adicionar uma nova requisição seguindo os passos abaixo:
- Clique em “Add a request”dentro da coleção que você criou conforme figura a seguir.
- Uma nova aba será aberta no lado direito da tela, permitindo configurar a requisição.
- Para facilitar a identificação, renomeie a requisição clicando no nome padrão e digitando, por exemplo: “Gerar token para o cartão de postagem”, conforme figura a seguir.
Figura 32 – Adicionando requisição no postman
Figura 33 - tela de edição da requisição no postman
8.4. Realizando a primeira requisição pelo POSTMAN
Agora que você tem acesso à documentação da API (como explicado no capítulo 3 – Acessando a documentação das APIs), para seguir o exemplo para “geração de token por cartão de postagem”, abaixo, detalhamos o processo com base nas informações obtidas anteriormente.
Relembrando os passos anteriores, identificamos:
- Credenciais de acesso: login e senha para autenticação nos componentes;
- Endpoint da requisição: o endereço completo da URL a ser utilizada;
- Verbo HTTP: o método apropriado para a requisição (ex: POST);
- Corpo da requisição (Body): os dados que devem ser enviados.
Configurando o endereço de requisição
No endereço de requisição e no verbo, incluir as informações conforme exemplo da figura a seguir:
Figura 34 - endereço de requisição
Configurando a autenticação básica
Siga os passos indicados na figura, e conforme a seguir:
- Acesse a aba "Authorization"da requisição.
- No campo "Type", selecione a opção "Basic Auth".
- Preencha os campos:
- Username: insira seu login de acesso.
- Password: insira o código de acesso gerado previamente.
Caso ainda não tenha o código de acesso, siga as instruções descritas no capítulo 4 - Gerando código de acesso da API. para obtê-lo.
Figura 35 - Autenticação básica no postman
Envie os dados do cartão de postagem. Para isso:
- Clique na aba “Body”
- Selecione a opção “raw”
- Escolha o formato “JSON”no menu suspenso à direita
- No campo de texto, insira o número do cartão de postagem, conforme exemplo da figura a seguir.
- Clicar em “Send” para obter a resposta da requisição.
Figura 36 - Inserindo parâmetros
9 - Atualizações do Manual
Manual atualizado em 04/08/2025, Departamento de Negócios e Plataformas Digitais.
Em caso de dúvidas ou para mais informações, contatar o Assistente Comercial de Tecnologia - ACOM TI da sua região.