Rastrear Pedido

Consulte o rastreamento completo de um pedido pertencente ao produtor autenticado.

http

GET /api/v1/pedidos/{id}/rastreamento

Importante

A requisição exige Authorization: Bearer SEU_TOKEN e a permissão listar_pedido_api. O pedido precisa pertencer à conta do token. Um pedido inexistente e um pedido de outro produtor recebem a mesma resposta, sem revelar dados de outra conta.

Observação

{id} aceita o ID interno do pedido ou o código de transação (codigo_transacao) de um pedido criado por esta API — o mesmo identificador aceito por GET /api/v1/pedidos/{id}. Os comandos de ciclo de vida (aprovar, cancelar, pausar, retomar) aceitam apenas o ID numérico.

Resumo ou linha do tempo completa

Endpoint	Use quando
`GET /api/v1/pedidos/{id}`	Você precisa dos dados do pedido e de um resumo compacto do rastreamento atual.
`GET /api/v1/pedidos/{id}/rastreamento`	Você precisa do rastreamento atual e da linha do tempo completa de eventos.

O endpoint de rastreamento retorna eventos únicos em ordem cronológica, do mais antigo para o mais recente. Eventos repetidos recebidos da transportadora são consolidados antes da resposta.

Consultar rastreamento

GET

bash

curl --request GET \
  --url 'https://ev.paylog.cash/api/v1/pedidos/64913/rastreamento' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

http

GET /api/v1/pedidos/64913/rastreamento HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN

Resposta `200`

json

{
  "code": 200,
  "pedido_id": 64913,
  "rastreamento": {
    "codigo": "AD123456789BR",
    "transportadora": {
      "codigo": "correios",
      "nome": "Correios"
    },
    "servico": "SEDEX",
    "url_rastreamento": "https://ev.paylog.cash/rastreio/AD123456789BR",
    "url_transportadora": "https://rastreamento.correios.com.br/app/index.php?objetos=AD123456789BR",
    "status": {
      "codigo": 30,
      "descricao": "Em trânsito"
    },
    "comprovante_entrega": null,
    "eventos": [
      {
        "codigo_evento": "PO-001",
        "ocorrido_em": "2026-07-22T14:10:00-03:00",
        "status": {
          "codigo": 20,
          "descricao": "Objeto Postado"
        },
        "descricao": "Objeto postado.",
        "detalhe": null,
        "sub_status": null,
        "localizacao": {
          "cidade": "Jundiaí",
          "uf": "SP"
        },
        "recebido_por": null,
        "unidade": null,
        "unidade_destino": null,
        "retirada": null
      },
      {
        "codigo_evento": "TR-002",
        "ocorrido_em": "2026-07-23T10:30:00-03:00",
        "status": {
          "codigo": 30,
          "descricao": "Em trânsito"
        },
        "descricao": "Objeto em transferência.",
        "detalhe": "Encaminhado para a unidade de distribuição.",
        "sub_status": null,
        "localizacao": {
          "cidade": "São Paulo",
          "uf": "SP"
        },
        "recebido_por": null,
        "unidade": {
          "tipo": "Unidade de Tratamento",
          "endereco": {
            "cidade": "São Paulo",
            "uf": "SP"
          }
        },
        "unidade_destino": {
          "tipo": "Unidade de Distribuição",
          "nome": "CDD Bela Vista",
          "codigo": "CDD-01310",
          "endereco": {
            "cidade": "São Paulo",
            "uf": "SP"
          }
        },
        "retirada": null
      }
    ]
  }
}

jsonc

{
  "code": 200, // Sempre: código HTTP repetido no corpo.
  "pedido_id": 64913, // Sempre: ID do pedido consultado.
  "rastreamento": { // Objeto completo, ou null quando o pedido ainda não possui rastreamento.
    "codigo": "AD123456789BR", // Sempre no objeto: código público de rastreamento.
    "transportadora": { // Pode ser null quando a transportadora ainda não foi identificada.
      "codigo": "correios", // Código público e estável da transportadora.
      "nome": "Correios" // Nome apresentado ao usuário.
    },
    "servico": "SEDEX", // Nullable: serviço contratado.
    "url_rastreamento": "https://ev.paylog.cash/rastreio/AD123456789BR", // Nullable: página pública de rastreamento da Paylog, igual para todas as transportadoras. Null enquanto não houver código.
    "url_transportadora": "https://rastreamento.correios.com.br/app/index.php?objetos=AD123456789BR", // Nullable: página da própria transportadora, quando existir.
    "status": { // Nullable: situação mais recente normalizada pela Paylog.
      "codigo": 30,
      "descricao": "Em trânsito"
    },
    "comprovante_entrega": null, // Nullable: só existe depois que a transportadora envia o comprovante. Ver a seção abaixo.
    "eventos": [ // Sempre no objeto: eventos únicos, do mais antigo para o mais recente. Lista vazia quando ainda não há eventos.
      {
        "codigo_evento": "PO-001", // Nullable: identificador público informado pela transportadora.
        "ocorrido_em": "2026-07-22T14:10:00-03:00", // Nullable: data e hora do evento em ISO 8601.
        "status": { // Nullable: status normalizado desse evento.
          "codigo": 20,
          "descricao": "Objeto Postado"
        },
        "descricao": "Objeto postado.", // Nullable: mensagem principal da transportadora.
        "detalhe": null, // Nullable: informação complementar.
        "sub_status": null, // Nullable: classificação complementar da transportadora.
        "localizacao": { // Sempre: cidade e UF podem ser null.
          "cidade": "Jundiaí",
          "uf": "SP"
        },
        "recebido_por": null, // Nullable: pessoa que recebeu o objeto.
        "unidade": null, // Nullable: unidade de origem ou processamento; tem sempre "tipo" e "endereco" quando presente.
        "unidade_destino": null, // Nullable: próxima unidade; chaves sem valor são OMITIDAS do objeto.
        "retirada": null // Nullable: endereço, prazo e código para retirada quando aplicável.
      }
    ]
  }
}

Observação

A resposta não expõe IDs internos de rastreio, eventos ou transportadoras. codigo_evento é o identificador público recebido da transportadora e pode ser null.

Observação

url_rastreamento é a página pública de rastreamento da Paylog (https://ev.paylog.cash/rastreio/{codigo}): funciona com qualquer transportadora e qualquer código, não exige login e mostra a linha do tempo normalizada junto com as imagens do comprovante de entrega. É o link para enviar ao cliente final. A página da própria transportadora, quando existir, continua disponível em url_transportadora — algumas transportadoras não oferecem uma URL por código, e nesses casos esse campo vem null.

Atenção

Campos vazios são omitidos dentro de unidade, unidade_destino e retirada.endereco, não enviados como null. Em unidade_destino, apenas as chaves com valor (tipo, nome, codigo, endereco) aparecem; se nenhuma tiver valor, o objeto inteiro vira null. O mesmo vale para os campos de endereço (logradouro, numero, complemento, bairro, cidade, uf, cep, pais): um endereço sem nenhum campo preenchido vira null. Sempre use uma leitura tolerante a chaves ausentes. As chaves de primeiro nível do evento (codigo_evento, ocorrido_em, status, descricao, detalhe, sub_status, localizacao, recebido_por, unidade, unidade_destino, retirada) estão sempre presentes, com null quando não há valor.

Exemplo: aguardando retirada

Quando o objeto está disponível em uma agência ou ponto de retirada, o evento usa o código 60 e inclui retirada. O endereço, a data limite e o código da lista vêm dos mesmos dados usados pelo Webhook v2, com nomes de campos em português nesta API v1:

json

{
  "code": 200,
  "pedido_id": 64913,
  "rastreamento": {
    "codigo": "AA123456789BR",
    "transportadora": {
      "codigo": "correios",
      "nome": "Correios"
    },
    "servico": "SEDEX",
    "url_rastreamento": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR",
    "status": {
      "codigo": 60,
      "descricao": "Aguardando Retirada"
    },
    "eventos": [
      {
        "codigo_evento": "LDI",
        "ocorrido_em": "2026-07-22T10:10:00-03:00",
        "status": {
          "codigo": 60,
          "descricao": "Aguardando Retirada"
        },
        "descricao": "Objeto aguardando retirada no endereço indicado",
        "detalhe": null,
        "sub_status": null,
        "localizacao": {
          "cidade": "São Paulo",
          "uf": "SP"
        },
        "recebido_por": null,
        "unidade": {
          "tipo": "Agência dos Correios",
          "endereco": {
            "logradouro": "Avenida Central",
            "numero": "100",
            "bairro": "Centro",
            "cidade": "São Paulo",
            "uf": "SP",
            "cep": "01000-000"
          }
        },
        "unidade_destino": null,
        "retirada": {
          "tipo_unidade": "Agência dos Correios",
          "logradouro": "Avenida Central",
          "numero": "100",
          "bairro": "Centro",
          "cidade": "São Paulo",
          "uf": "SP",
          "cep": "01000-000",
          "retirar_ate": "2026-07-29",
          "codigo_lista": "408161154094"
        }
      }
    ]
  }
}

Comprovante de entrega

Depois que a transportadora confirma a entrega, ela pode enviar o comprovante. Quando isso acontece, comprovante_entrega deixa de ser null:

json

{
  "comprovante_entrega": {
    "imagem_url": "https://cdn.paylog.cash/tracking/9f3a1c2b.../4c7be0a1....jpg",
    "assinatura_url": "https://cdn.paylog.cash/tracking/9f3a1c2b.../b2c3d4e5....webp",
    "recebido_por": "Michael porteiro",
    "signatario": "porteiro"
  }
}

Campo	Nulo?	Descrição
`imagem_url`	não	Foto da entrega ou do recibo assinado.
`assinatura_url`	sim	Imagem da assinatura eletrônica, quando a transportadora coleta uma.
`recebido_por`	sim	Nome de quem recebeu o objeto.
`signatario`	sim	Quem assinou (por exemplo `porteiro`), quando informado.

Observação

Cada transportadora envia um conjunto diferente. A J&T Express envia as duas imagens (foto da entrega e assinatura) mais o signatário. Os Correios enviam apenas a foto do recibo e o nome do recebedor — nesse caso assinatura_url e signatario vêm null. O objeto inteiro é null até a primeira imagem ser capturada, o que costuma acontecer algumas horas depois do evento de entrega. Sempre trate cada campo como opcional.

Pedido sem rastreamento

Um pedido válido que ainda não possui código de rastreamento retorna 200:

json

{
  "code": 200,
  "pedido_id": 64913,
  "rastreamento": null
}

Já um pedido que possui código de rastreamento mas ainda não recebeu nenhum evento da transportadora devolve o objeto com eventos como lista vazia — nunca null:

json

{
  "code": 200,
  "pedido_id": 64913,
  "rastreamento": {
    "codigo": "AD123456789BR",
    "transportadora": {
      "codigo": "correios",
      "nome": "Correios"
    },
    "servico": "PAC",
    "url_rastreamento": null,
    "status": null,
    "eventos": []
  }
}

Erros

Status	Quando
`401`	Token ausente, inválido ou revogado; pedido inexistente; ou pedido pertencente a outra conta.
`403`	Token sem a permissão `listar_pedido_api`.
`500`	Falha inesperada ao consultar o rastreamento.

Um pedido inexistente e um pedido de outra conta produzem exatamente o mesmo corpo, sem revelar se o pedido existe:

json

{
  "code": 401,
  "message": "Não autorizado"
}

Já o 401 de token ausente, inválido ou revogado vem da camada de autenticação e usa o corpo padrão, sem code:

json

{
  "message": "Unauthenticated."
}

#Resumo ou linha do tempo completa

#Consultar rastreamento

#Resposta 200

#Exemplo: aguardando retirada

#Comprovante de entrega

#Pedido sem rastreamento

#Erros

Resumo ou linha do tempo completa

Consultar rastreamento

Resposta `200`

Exemplo: aguardando retirada

Comprovante de entrega

Pedido sem rastreamento

Erros