tc

tracking-correios

Módulo para consulta do rastreio de pacotes do Correios - API SRO

Showing:

Popularity

Downloads/wk

69

GitHub Stars

94

Maintenance

Last Commit

10mos ago

Contributors

10

Package

Dependencies

3

Size (min+gzip)

38.5KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

tracking-correios

Build Status npm

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

Depois 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()
> false

Verifica 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()
> undefined

Se 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.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial