Stories in Ready

Correios Java SDK

Quer um resumo simples e prático? Visite a página oficial do SDK :)

Se mantenha atualizado sobre as novas vers├Áes, features novas e poss├şveis bugs (raros : P) atrav├ęs do nosso Twitter @correios_sdk

Correios Rastreio Java SDK.

Este SDK foi criado para facilitar a sua vida quando precisar fazer integra├ž├úo com os seguintes servi├žos dos Correios:

O SDK ├ę totalmente Free e Open Source! Como voc├¬ deve ter notado, usamos o GitHub, ent├úo sinta-se ├á vontade para fazer altera├ž├Áes necess├írias e abrir um Pull Request pra gente :)

O SDK não tem alguma funcionalidade que você deseja? Não se preocupe, basta criar uma issue explicando o que você gostaria e implementaremos pra você :)

Rastreio de Objetos

Veja como ├ę simples usar o SDK para Rastrear um objeto nos correios em 2 passos:

1 - Com as suas credenciais em mãos, instancie o seguinte objeto:

CorreiosCredenciais credenciais = new CorreiosCredenciais("seu-usuario", "sua-senha");

2 - Em seguida basta invocar o m├ętodo para retornar os Eventos do objeto desejado:

CorreiosRastreioApi correiosApi = new CorreiosRastreioClientApi(credenciais);

DetalhesRastreio pacoteRastreado =  correiosApi
    .buscaPacoteRastreadoUsandoOCodigo("codigo_do_seu_objeto")
    .emPortugues()
    .comTodosOsEventos()
    .getDetalhesRastreio();

O c├│digo do seu objeto deve ser algo parecido com DU500853238BR.

O c├│digo completo fica como o a seguir:

@Test
public void deveriaRetornarOsEventosAPartirDeUmTrackingCode() throws Exception {
    CorreiosCredenciais credenciais = new CorreiosCredenciais("seu-usuario", "sua-senha");
    
    CorreiosRastreioApi correiosApi = new CorreiosRastreioClientApi(credenciais);
    
    DetalhesRastreio pacoteRastreado =  correiosApi
        .buscaPacoteRastreadoUsandoOCodigo("codigo_do_seu_objeto")
        .emPortugues()
        .comTodosOsEventos()
        .getDetalhesRastreio();
        
    System.out.println(pacoteTraqueado);
}

Simples assim!

Note que usamos uma Fluent Interface que j├í indica pra voc├¬ quais m├ętodos devem ser invocados e nem deixa voc├¬ errar!

Buscando Uma Lista de Objetos

Tamb├ęm ├ę poss├şvel buscar mais de um Objeto atrav├ęs de uma lista de C├│digos, como ├ę mostrado a seguir:

@Test
public void deveriaRetornarOsEventosAPartirDeUmaListaDeTrackingCodes() throws Exception {
    CorreiosCredenciais credenciais = new CorreiosCredenciais("username", "password");
        
    CorreiosRastreioApi correiosApi = new CorreiosRastreioClientApi(credenciais);
        
    List<String> trackingCodes = new ArrayList<>();
    trackingCodes.add("DU500853237BR");
    trackingCodes.add("DU496842125BR");
        
    DetalhesRastreio detalhesComLista = correiosApi
        .buscaPacotesRastreadosPelaListaDeTrackings(trackingCodes)
        .emPortugues()
        .comTodosOsEventos()
        .getDetalhesRastreio();
        
    System.out.println(detalhesComLista);
}

Note que agora temos o objeto DetalhesRastreio, que por sua vez cont├ęm uma lista com todas as informa├ž├Áes que voc├¬ precisa! Awesome!

Informa├ž├Áes de Retorno

Os Correios enviam diversas informa├ž├Áes relacionadas ao objeto que est├í sendo pesquisado.

O objeto DetalhesRastreio ├ę respons├ível por guardar essas informa├ž├Áes. D├¬ uma olhadinha na documenta├ž├úo na Wiki ;)

Etiquetas dos Correios

O SIGEP Web, que ├ę o sistema dos Correios, gera etiquetas de endere├žamento padronizadas, com c├│digos de barra para o n├║mero de rastreamento e para o CEP, facilitando a leitura ├│tica destas informa├ž├Áes nas m├íquinas de triagem dos Correios, que realizam o roteamento automatizado das encomendas.

Voc├¬ tamb├ęm pode inserir a logomarca de sua loja virtual nas etiquetas.

Como funciona?

Este me╠ütodo retorna numerac╠ža╠âo de registro(s) dos Correios para futura postagem de objeto(s). O nu╠ümero de registro e╠ü o identificador do objeto no fluxo postal da ECT, sendo utilizado como chave para rastreamento, conhecido tamb├ęm como Tracking Code ou C├│digo de Postagem.

Com o atendimento da solicitac╠ža╠âo, o nu╠ümero de registro fica reservada para o CNPJ informado. Quando da preparac╠ža╠âo do objeto para postagem, cada nu╠ümero podera╠ü ser usado para gerac╠ža╠âo do ro╠ütulo de postagem.

O método contempla o pedido de um ou mais números, por exemplo:

  • Situac╠ža╠âo 1: Apo╠üs a finalizac╠ža╠âo de um processo (Ex: Compra de um produto na loja online), obter um nu╠ümero do registro da encomenda a ser postada.

  • Situac╠ža╠âo 2: Aguardar a finalizac╠ža╠âo de uma lista com N objetos a ser postada, solicitando em seguida, uma faixa de numerac╠ža╠âo.

  • Situac╠ža╠âo 3: Solicitar uma quantidade maior de etiquetas e gerencia╠ü-la localmente de acordo com os servic╠žos utilizados, com rotina de controle do estoque das etiquetas, consumindo a numerac╠ža╠âo deste estoque.

Recomendamos solicitar uma faixa de etiquetas conforme previsa╠âo de postagem do dia por servic╠žo (PAC, SEDEX, etc). Dessa forma quando se esgotar o estoque de etiquetas para o servic╠žo, efetuar nova solicitac╠ža╠âo.

Esse processo evita a depende╠éncia de solicitac╠ža╠âo on-line de etiquetas, permitindo um controle local no sistema cliente.

Para cada tipo de servic╠žo devera╠ü ser solicitada uma faixa de numerac╠ža╠âo.

Este método pode ser utilizado sob demanda, quantas vezes o cliente necessitar.

Solicitando Etiquetas usando o SDK

Passo 1 - Criando a Credencial

Precisamos criar as credenciais para a API da seguinte forma:

CorreiosCredenciais credenciais = new CorreiosCredenciais("seu-usuario", "sua-senha");

Passo 2 - Criando o Contrato da Empresa

Al├ęm das credenciais, voc├¬ precisa ter o n├║mero do seu contrato, n├║mero do cart├úo de postagem e o seu cnpj:

ContratoEmpresa contrato = new ContratoEmpresa(cnpj, numeroDoContrato, numeroDoCartaoDePostagem);

Passo 3 - Solicitando a Etiqueta via SDK

Agora com as Credenciais e o Contrato em mãos, basta usar a classe CorreiosApi, solicitando:

  • A quantidade desejada de etiquetas
  • O servi├žo de entrega desejado
CorreiosApi api = new CorreiosApi();
List<Etiqueta> etiquetas = api
    .etiquetas(credenciais)
    .solicita(2)
    .usandoServicoDeEntrega(SEDEX_COM_CONTRATO)
    .comContrato(contrato);

O c├│digo completo de teste poderia ser o seguinte:

public class CorreiosEtiquetaApiTest {

    private CorreiosCredenciais credenciais;
    private String cnpj = "123456789";
    private String numeroDoContrato = "321564987";
    private String numeroDoCartaoDePostagem = "654789123";

    @Before
    public void startUp() {
        credenciais = new CorreiosCredenciais("seu-usuario", "sua-senha");
    }

    @Test
    public void deveriaSolicitarEtiquetasAosCorreios() throws Exception {
        CorreiosApi api = new CorreiosApi();

        ContratoEmpresa contrato = new ContratoEmpresa(cnpj, numeroDoContrato, numeroDoCartaoDePostagem);

        List<Etiqueta> etiquetas = api
            .etiquetas(credenciais)
            .solicita(2)
            .usandoServicoDeEntrega(SEDEX_COM_CONTRATO)
            .comContrato(contrato);

        assertThat(etiquetas.size()).isGreaterThan(1);
    }

}

Baixando a dependência

Maven

<dependency>
  <groupId>br.com.correios</groupId>
  <artifactId>correios-java-sdk</artifactId>
  <version>{última-versão-desejada}</version>
  <type>pom</type>
</dependency>

Gradle

compile 'br.com.correios:correios-java-sdk:{{última-versão-desejada}}'

Autores

Alexandre Gama (@alexandregama)

Adriano Saturno (@saturno)

Eric Dallo (@ericdallo)

Gabriel Gomes (@gabriellimagomes)

Denis Schimidt (@denis-schimidt)

Douglas Campos (@douglascampos)

Lucas Nakano (@lucasnakano)

Suporte ou Contato

Est├í tendo algum problema no uso do SDK? Basta abrir uma issue indicando os passos do seu problema e responderemos o mais breve poss├şvel :)

CorreIOS Java Sdk

Correios Java SDK

CorreIOS Java Sdk Info

ÔşÉ Stars28
­čöŚ Homepageshipping7.github.io
­čöŚ Source Codegithub.com
­čĽĺ Last Update10 months ago
­čĽĺ Created6 years ago
­čÉ× Open Issues28
Ô׌ Star-Issue Ratio1
­čśÄ Authorshipping7