Referencia da API · v1

API de Rastreio

API REST que devolve JSON. Use-a para criar encomendas, registar eventos de rastreio e consultar o estado de entrega a partir de qualquer aplicacao.

URL base https://rastrelonacional.com/api/v1

Autenticacao

O endpoint de rastreio publico nao exige autenticacao. Todos os outros exigem a chave de API no cabecalho Authorization.

Authorization: Bearer rp_test_8f2a4c6e9b1d3a7f5e0c2b8d4f6a1c3e

Chave de demonstracao. Num ambiente real seria emitida por cliente e revogavel.

Estados de uma encomenda

Valor	Significado
`posted`	Objeto postado
`in_transit`	Em transito
`out_for_delivery`	Saiu para entrega
`delivered`	Entregue
`exception`	Tentativa de entrega
`returned`	Em devolucao

Rastrear (publico)

GET /track/{code}

Devolve a encomenda e o historico de eventos. Nao requer autenticacao.

Exemplo

curl https://rastrelonacional.com/api/v1/track/RP482910375BR

Resposta

{
  "code": "RP482910375BR",
  "status": "out_for_delivery",
  "status_label": "Saiu para entrega",
  "recipient": "Mariana Alves",
  "service": "Expresso 24h",
  "origin": "Sao Paulo / SP",
  "destination": "Rio de Janeiro / RJ",
  "eta": "2026-06-17",
  "events": [
    {
      "status": "out_for_delivery",
      "status_label": "Saiu para entrega",
      "location": "Rio de Janeiro / RJ",
      "description": "Objeto saiu para entrega ao destinatario",
      "timestamp": "2026-06-16 11:20:00"
    }
  ]
}

Listar encomendas 🔒

GET /shipments

Lista todas as encomendas.

Exemplo

curl https://rastrelonacional.com/api/v1/shipments \
  -H "Authorization: Bearer rp_test_8f2a4c6e9b1d3a7f5e0c2b8d4f6a1c3e"

Resposta

{ "data": [ { "code": "RP482910375BR", "status": "out_for_delivery", ... } ] }

Criar encomenda 🔒

POST /shipments

Cria uma encomenda. Se code for omitido, e gerado automaticamente. Um primeiro evento e registado com base no status inicial.

Corpo do pedido

{
  "recipient": "Joao Silva",
  "service": "Standard",
  "origin": "Lisboa",
  "destination": "Porto",
  "status": "posted",
  "eta": "2026-06-20"
}

Exemplo

curl -X POST https://rastrelonacional.com/api/v1/shipments \
  -H "Authorization: Bearer rp_test_8f2a4c6e9b1d3a7f5e0c2b8d4f6a1c3e" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"Joao Silva","origin":"Lisboa","destination":"Porto"}'

Resposta

{ "code": "RP7391028461BR", "status": "posted", "events": [ ... ] }

Consultar encomenda 🔒

GET /shipments/{code}

Devolve uma encomenda especifica.

Exemplo

curl https://rastrelonacional.com/api/v1/shipments/RP482910375BR \
  -H "Authorization: Bearer rp_test_8f2a4c6e9b1d3a7f5e0c2b8d4f6a1c3e"

Resposta

{ "code": "RP482910375BR", "status": "out_for_delivery", ... }

Atualizar encomenda 🔒

PATCH /shipments/{code}

Atualiza campos da encomenda (destinatario, servico, origem, destino, eta, status).

Corpo do pedido

{ "status": "delivered", "eta": "2026-06-16" }

Exemplo

curl -X PATCH https://rastrelonacional.com/api/v1/shipments/RP482910375BR \
  -H "Authorization: Bearer rp_test_8f2a4c6e9b1d3a7f5e0c2b8d4f6a1c3e" \
  -H "Content-Type: application/json" \
  -d '{"status":"delivered"}'

Resposta

{ "code": "RP482910375BR", "status": "delivered", ... }

Adicionar evento 🔒

POST /shipments/{code}/events

Regista um evento no historico. O status da encomenda passa a refletir o evento.

Corpo do pedido

{
  "status": "in_transit",
  "location": "Coimbra",
  "description": "Objeto em transito"
}

Exemplo

curl -X POST https://rastrelonacional.com/api/v1/shipments/RP482910375BR/events \
  -H "Authorization: Bearer rp_test_8f2a4c6e9b1d3a7f5e0c2b8d4f6a1c3e" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_transit","location":"Coimbra"}'

Resposta

{ "code": "RP482910375BR", "status": "in_transit", "events": [ ... ] }

Eliminar encomenda 🔒

DELETE /shipments/{code}

Elimina a encomenda e o seu historico.

Exemplo

curl -X DELETE https://rastrelonacional.com/api/v1/shipments/RP482910375BR \
  -H "Authorization: Bearer rp_test_8f2a4c6e9b1d3a7f5e0c2b8d4f6a1c3e"

Resposta

{ "deleted": true, "code": "RP482910375BR" }