Skip to content

Latest commit

 

History

History
234 lines (154 loc) · 8.8 KB

README.md

File metadata and controls

234 lines (154 loc) · 8.8 KB
Raw

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 método retorna numeração de registro(s) dos Correios para futura postagem de objeto(s). O número de registro é 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 solicitação, o número de registro fica reservada para o CNPJ informado. Quando da preparação do objeto para postagem, cada número poderá ser usado para geração do rótulo de postagem.

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

  • Situação 1: Após a finalização de um processo (Ex: Compra de um produto na loja online), obter um número do registro da encomenda a ser postada.

  • Situação 2: Aguardar a finalização de uma lista com N objetos a ser postada, solicitando em seguida, uma faixa de numeração.

  • Situação 3: Solicitar uma quantidade maior de etiquetas e gerenciá-la localmente de acordo com os serviços utilizados, com rotina de controle do estoque das etiquetas, consumindo a numeração deste estoque.

Recomendamos solicitar uma faixa de etiquetas conforme previsão de postagem do dia por serviço (PAC, SEDEX, etc). Dessa forma quando se esgotar o estoque de etiquetas para o serviço, efetuar nova solicitação.

Esse processo evita a dependência de solicitação on-line de etiquetas, permitindo um controle local no sistema cliente.

Para cada tipo de serviço deverá ser solicitada uma faixa de numeraçã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 :)