rastrojs

RastroJS

Biblioteca Node.js para consultar o andamento de encomendas. Atualmente, oferece suporte aos Correios e foi estruturada para receber outras transportadoras.

Este projeto não é oficial dos Correios e não utiliza o webservice oficial da empresa.

Instalação

npm install rastrojs

Uso

A função get recebe um objeto com as encomendas e, opcionalmente, as configurações de paralelismo e timeout. Para cada encomenda, informe o código de rastreio e a transportadora.

import { get, ShipmentCarrier } from 'rastrojs';

const shipments = await get({
  shipments: [
    {
    code: 'AA123456789BR',
    carrier: ShipmentCarrier.correios,
    },
    {
      code: 'BB123456789BR',
      carrier: ShipmentCarrier.correios,
    },
  ],
  parallelism: 2,
  timeout: 10_000,
});

console.log(shipments);

Em JavaScript com CommonJS:

const { get, ShipmentCarrier } = require('rastrojs');

const [shipment] = await get({
  shipments: [{
    code: 'AA123456789BR',
    carrier: ShipmentCarrier.correios,
  }],
});

Também é possível instanciar ou estender RastroJS quando a consulta fizer parte de uma classe da aplicação:

import {
  RastroJS,
  ShipmentCarrier,
  type Shipment,
  type ShipmentError,
} from 'rastrojs';

class Deliveries extends RastroJS {
  public all(): Promise<(Shipment | ShipmentError)[]> {
    return this.get({
      shipments: [{
        code: 'AA123456789BR',
        carrier: ShipmentCarrier.correios,
      }],
      parallelism: 2,
      timeout: 5_000,
    });
  }
}

Paralelismo e timeout

Opção	Tipo	Padrão	Descrição
shipments	Array<{ code, carrier }>	—	Encomendas a consultar.
parallelism	number	1	Quantidade de consultas processadas simultaneamente. As demais aguardam o próximo lote.
timeout	number	30000	Tempo máximo, em milissegundos, para cada consulta individual.

Por exemplo, parallelism: 5 consulta até cinco encomendas ao mesmo tempo. O valor de timeout é aplicado a cada requisição, e não limita a duração total do lote. Se uma consulta exceder esse período, o respectivo resultado será retornado como erro.

Transportadoras

Use o enum ShipmentCarrier para identificar a origem de cada código. No momento, a transportadora disponível é:

Valor	Transportadora
ShipmentCarrier.correios	Correios

Para os Correios, o código deve estar no formato AA123456789BR: duas letras, nove dígitos e duas letras, sempre em maiúsculas.

Resposta

get sempre retorna um array, mantendo uma resposta para cada item de shipments. Um resultado bem-sucedido segue a interface Shipment:

Campo	Tipo	Descrição
code	string	Código consultado ou retornado pela transportadora.
carrier	ShipmentCarrier	Transportadora usada na consulta.
type	string	Tipo/modalidade da encomenda.
isDelivered	boolean	Indica se a encomenda foi entregue.
postedAt	Date | null	Data de postagem, quando disponível.
updatedAt	Date | null	Data do evento mais recente.
expectedAt	Date | null	Data prevista de entrega, quando informada.
events	ShipmentEvent[]	Eventos de rastreamento da encomenda.

Cada item de events contém:

Campo	Tipo	Descrição
status	string	Situação registrada no evento.
createdAt	Date	Data e hora do evento.
observation	string	Observação ou unidade associada ao evento.
locale.city	string | null	Cidade do evento.
locale.region	string | null	UF/região do evento.

Exemplo:

[
  {
    code: 'AA123456789BR',
    carrier: 'correios',
    type: 'sedex',
    isDelivered: false,
    postedAt: new Date('2026-08-01T12:00:00.000Z'),
    updatedAt: new Date('2026-08-04T09:30:00.000Z'),
    expectedAt: new Date('2026-08-06T23:59:59.000Z'),
    events: [
      {
        status: 'objeto em trânsito',
        createdAt: new Date('2026-08-04T09:30:00.000Z'),
        observation: 'de unidade de tratamento',
        locale: { city: 'são paulo', region: 'sp' },
      },
    ],
  },
];

Erros

Quando não for possível obter uma encomenda, o item correspondente será um ShipmentError; a chamada não interrompe as demais consultas.

{
  code: '000',
  carrier: 'correios',
  error: 'Invalid shipment code/id',
}

Os erros atualmente retornados são:

Mensagem	Situação
Invalid shipment code/id	O código não corresponde ao formato aceito pela transportadora.
Failed to request shipment events	A consulta ao serviço de rastreamento não pôde ser concluída.
Shipment carrier not implemented	A transportadora informada ainda não possui implementação.

Contribuição

Consulte o guia de contribuição. Dúvidas e sugestões: tales.ferreira.luna@gmail.com.

Licença

Distribuído sob a licença MIT.