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: [email protected].

Licença

Distribuído sob a licença MIT.