tracking-correios
Módulo para consulta do rastreio de pacotes do Correios. Acessa diretamento a API do Correios (SRO).
Instalação
Requer Node.js e npm instalados.
$ npm install --save tracking-correiosDepois importe no seu código:
// via require do Node.js
const TrackingCorreios = require('tracking-correios')
// ou via ES6
import TrackingCorreios from 'tracking-correios'Consulta de eventos do código de rastreio
Para consultas de um único código:
// passando como string
TrackingCorreios.track( 'DU897123996BR' )
.then(console.log)
// ou como Array
TrackingCorreios.track( [ 'DU897123996BR' ] )
.then(console.log)
> [ {
"numero":"DU897123996BR",
"sigla":"DU",
"nome":"ENCOMENDA E-SEDEX",
"categoria":"E-SEDEX",
"evento": [ {
"tipo":"BDE",
"status":"01",
"data":"12/12/2016",
"hora":"19:06",
"descricao":"Objeto entregue ao destinatário",
"recebedor":"",
"documento":"",
"comentario":"",
"local":"CEE BAURU",
"codigo":"17034972",
"cidade":"Bauru",
"uf":"SP"
}, { ... }, { ... }, { ... }
]
} ]Exemplo de código válido, porém sem rastreio
TrackingCorreios.track([ 'SB231363632BR' ])
.then(console.log)
> [ {
numero: 'SB231363632BR',
erro: 'Objeto não encontrado na base de dados dos Correios.'
} ]Para consultas de vários códigos simultâneos:
TrackingCorreios.track([ 'DU897123996BR', 'PN273603577BR', 'DU910139445BR' ])
.then(console.log)
> [
{ numero: 'DU897123996BR',
sigla: 'DU',
nome: 'ENCOMENDA E-SEDEX',
categoria: 'E-SEDEX',
evento: [ {...}, [Object], [Object], [Object], [Object], [Object] ] },
{ numero: 'PN273603577BR',
sigla: 'PN',
nome: 'ENCOMENDA PAC (ETIQ LOGICA)',
categoria: 'ENCOMENDA PAC',
evento: [ [Object], [Object], [Object], [Object], [Object], [Object] ] },
{ numero: 'DU910139445BR',
sigla: 'DU',
nome: 'ENCOMENDA E-SEDEX',
categoria: 'E-SEDEX',
evento: [ [Object], [Object], [Object], [Object], [Object] ] }
]O método track validará automaticamente os objetos, removendo os inválidos:
TrackingCorreios.track([ 'DU897123996BR', 'invalido' ])
.then(console.log)
> [ {
"numero":"DU897123996BR",
"sigla":"DU",
"nome":"ENCOMENDA E-SEDEX",
"categoria":"E-SEDEX",
"evento": [...]
} ]Se não tiver nenhum objeto válido a Promise rejeitará com TrackingError:
TrackingCorreios.track('invalido')
.catch(console.log)
> {
[TrackingError: Erro ao validar os objetos.]
name: 'TrackingError',
message: 'Erro ao validar os objetos.',
type: 'validation_error',
errors:
[ { message: 'Nenhum objeto válido para pesquisa.',
service: 'objects_validation' } ]
}Se não quiser filtrar, use a configuração filter:
TrackingCorreios.track('invalido', { filter: false })
.catch(console.log)
> [ {
numero: 'invalido',
erro: 'Objeto não encontrado na base de dados dos Correios.'
} ]O método track retorna uma Promise, portanto o tratamento de erros deve ser feito pelo .catch. Exemplo de API fora do ar:
TrackingCorreios.track('DU897123996BR')
.then(console.log)
.catch(console.log)
> {
[TrackingError: Erro ao se conectar ao o serviço dos Correios.]
name: 'TrackingError',
message: 'Erro ao se conectar com o serviço dos Correios.',
type: 'system',
errors:
[ { message: 'Ocorreu um erro ao se conectar ao serviço dos Correios: request to https://webservice.correios.com.br/service/rastro failed, reason: connect ECONNREFUSED webservice.correios.com.br',
service: 'service_error' } ]
}Pode também passar um objeto de configuração como segundo parâmetro.
// Valores padrão:
TrackingCorreios.track('DU897123996BR', {
username: "ECT",
password: "SRO",
filter: true,
type: "L",
result: "T",
language: "101",
limit: 5000
})Os parâmetros username, password, type, result e language serão enviados a API dos Correios.
O parâmetro limit indica a quantidade máxima de objetos a ser enviado por requisição. Se passar 8 mil objetos e o limite for 5 mil, o módulo fará duas requisições. Se passar mil objetos e o limite for 1, fará mil requisições.
O parâmetro filter indica se deve realizar a filtragem de pacotes válidos antes de acessar a API do Correios.
As requisições não são paralelas, serão realizadas uma após a outra. A Promise só resolverá quando todas as requisições terminarem.
ATENÇÃO!
O usuário padrão do sistema é ECT. Esse é um usuário de testes, por isso tem algumas limitações (#15, #5). Só é possível fazer a consulta de 1 código por vez, e também só 1 evento é retornado. Para adquirir um usuário com mais permissões, é necessário ter um contrato com os Correios: http://www.correios.com.br/solucoes-empresariais/comercio-eletronico/sistema-de-rastreamento-de-objetos.
Validação de objetos
Esse módulo expõe três métodos auxiliares para validação de objetos.
-
isValid: verifica se o tracking é válido seguindo as regras do Correios. -
filter: retorna somente os objetos válidos. -
validate: retorna um objeto com os itens válidos e inválidos.
Exemplos:
isValid:
TrackingCorreios.isValid('DU897123996BR')
> true
TrackingCorreios.isValid(['DU897123996BR'])
> false
TrackingCorreios.isValid('AAAAA')
> false
TrackingCorreios.isValid()
> falseVerifica um único objeto por vez. Valida as iniciais também com as conhecidas do correios (veja category). Retorna um boolean.
filter:
TrackingCorreios.filter( 'DU897123996BR' )
> [ 'DU897123996BR' ]
TrackingCorreios.filter( [ 'DU897123996BR' ] )
> [ 'DU897123996BR' ]
TrackingCorreios.filter( [ 'DU897123996BR', 'PN273603577BR', 'DU910139445BR' ] )
> [ 'DU897123996BR', 'PN273603577BR', 'DU910139445BR' ]
TrackingCorreios.filter([ 'DU897123996BR', 'invalid' ])
> [ 'DU897123996BR' ]
TrackingCorreios.filter([ 'invalid', 'AAAA' ])
> [ ]
TrackingCorreios.filter( { } )
> [ ]Sempre retornará um Array, independente se houver ou não itens válidos.
validate:
TrackingCorreios.validate( 'DU897123996BR' )
> { valid: [ 'DU897123996BR' ], invalid: [ ] }
TrackingCorreios.validate( [ 'DU897123996BR' ] )
> { valid: [ 'DU897123996BR' ], invalid: [ ] }
TrackingCorreios.validate( [ 'DU897123996BR', 'PN273603577BR', 'DU910139445BR' ] )
> {
valid: [ 'DU897123996BR', 'PN273603577BR', 'DU910139445BR' ],
invalid: [ ]
}
TrackingCorreios.validate([ 'DU897123996BR', 'invalid' ])
> {
valid: [ 'DU897123996BR' ],
invalid: [ 'invalid' ]
}
TrackingCorreios.validate([ 'invalid', 'AAAA' ])
> {
valid: [ ],
invalid: [ 'invalid', 'AAAA' ]
}
TrackingCorreios.validate( { } )
> {
valid: [ ],
invalid: [ { } ]
}Sempre retornará um objeto com os campos valid e invalid.
Categoria do Objeto
O módulo expõe um método para retornar a categoria do objeto: category. Exemplo:
TrackingCorreios.category('DU897123996BR')
> 'e-SEDEX'
TrackingCorreios.category(['PN273603577BR'])
> 'PAC'
TrackingCorreios.category(['AA123123123BR'])
> undefined
TrackingCorreios.category('AAAAA')
> undefined
TrackingCorreios.category()
> undefinedSe não for um código de rastreio válido, retornará undefined.
Inspiração
Arquitetura inspirada no módulo cep-promise de Filipe Deschamps. Queria aprender mais sobre encadeamento de Promises, funções pequenas e vários outros assuntos que ele aborda nesse vídeo, por isso decidi desenvolver esse módulo.