Envios e rastreamento
Consulte os envios da empresa e os eventos registrados para a etiqueta atual.
As consultas retornam apenas envios da conta autenticada. Rascunhos, registros excluídos e dados removidos por privacidade não são expostos.
Listar envios
Os exemplos de cURL usam Bash, com as variáveis de ambiente configuradas em primeiros passos.
curl --request GET \
--url "https://veolog.com.br/api/v1/$VEOLOG_API_ALIAS/shipments?limit=20" \
--header "Accept: application/json" \
--header "User-Token: $VEOLOG_API_TOKEN" \
--header "User-Secret-Key: $VEOLOG_API_SECRET"A lista aparece em data, com identificação, referência externa, transportadora, serviço, situação e datas, em ordem decrescente de ID. Guarde os IDs como strings.
Filtros disponíveis: stage, situation, tracking_code, source_system e source_ref. Quando combinados, todos precisam corresponder. A comparação é exata e diferencia maiúsculas de minúsculas. stage aceita preparation, transit ou completed; confira todas as situações na referência.
Paginação
O limite padrão é 20 registros; limit aceita de 1 a 100. Na primeira chamada, omita cursor. Enquanto pagination.has_more for true, copie pagination.next_cursor para o parâmetro cursor da próxima chamada, preservando conta e filtros. Trate o cursor como um valor opaco e codifique-o na URL.
Depois de guardar o cursor recebido em VEOLOG_NEXT_CURSOR, continue a listagem sem filtros do exemplo anterior:
curl --get \
--url "https://veolog.com.br/api/v1/$VEOLOG_API_ALIAS/shipments" \
--data-urlencode "limit=20" \
--data-urlencode "cursor=$VEOLOG_NEXT_CURSOR" \
--header "Accept: application/json" \
--header "User-Token: $VEOLOG_API_TOKEN" \
--header "User-Secret-Key: $VEOLOG_API_SECRET"Pare quando has_more for false; nesse caso, next_cursor será null. Não envie cursor vazio nem reutilize um cursor em outra consulta. No rastreamento, a mesma regra usa data.pagination, mantendo o mesmo envio.
Detalhar um envio
Use GET /api/v1/{alias}/shipments/{id} com o identificador obtido na lista. O objeto data inclui os campos da listagem, package com peso em gramas e dimensões em centímetros, e origin/destination com CEP, cidade e UF. Dados indisponíveis podem ser null; veja o exemplo completo na referência do detalhe.
As respostas não expõem documentos pessoais, contatos ou endereços completos. Um ID inexistente ou pertencente a outra conta retorna 404.
Entender situação e status
| Campo | Onde aparece | Significado |
|---|---|---|
stage | Lista e detalhe | Etapa: preparation, transit ou completed |
situation | Lista e detalhe | Situação operacional, como ready_to_post, awaiting_pickup ou delivery_not_completed |
data.status | Rastreamento | Status atual normalizado do envio; pode ser null quando desconhecido |
data.events[].status | Rastreamento | Status daquele evento; também pode ser null |
Os status de rastreamento são in_transit, delivered, returned, not_delivered, delivery_suspended, damaged e canceled. O vocabulário difere das situações: por exemplo, “não entregue” usa delivery_not_completed em situation e not_delivered em status.
Use os campos estruturados nas regras da integração e trate null como informação desconhecida. O status atual não precisa ser igual ao status do primeiro evento da página consultada.
Acompanhar o rastreamento
Use GET /api/v1/{alias}/shipments/{id}/tracking. A resposta traz tracking_code, status, last_event_at e events dentro de data, com paginação em data.pagination. O endpoint aceita limit e cursor; veja uma resposta com eventos na referência de rastreamento.
As consultas leem os eventos já registrados pela Veolog. Uma chamada GET não dispara atualização na transportadora. Se ainda não houver eventos disponíveis, data.events será uma lista vazia. Isso não obriga tracking_code ou status a serem null: esses campos podem já ser conhecidos.
Por exemplo, um envio com código e status conhecidos, ainda sem eventos disponíveis, pode retornar:
{
"request_id": "f875e9ea022597f7c9267fe13f5134a07",
"data": {
"tracking_code": "AA123456789BR",
"status": "in_transit",
"last_event_at": null,
"events": [],
"pagination": {
"next_cursor": null,
"has_more": false
}
}
}last_event_at é a data do evento datado mais recente de todo o histórico da etiqueta atual, independentemente da página consultada. Não representa o horário desta chamada nem da última sincronização com a transportadora. Pode ser null mesmo com eventos, se nenhum tiver data disponível.
Cada evento contém id, status, description, location e event_at. A descrição é um resumo padronizado para apresentação ao usuário. Localização e data podem ser null; quando presentes, a localização informa município/UF e a data inclui o fuso horário. Preserve a ordem retornada pela API, inclusive quando houver eventos sem data.
Retomar após mudança de etiqueta
O histórico corresponde à transportadora e ao código da etiqueta atual, sem misturar eventos de etiquetas substituídas. Uma troca pode interromper a paginação de duas formas:
| Resposta | O que aconteceu | Como continuar |
|---|---|---|
409, código shipment_changed | A identificação do rastreio mudou durante a requisição | Reinicie o rastreamento sem cursor |
422, código invalid_query, com details.field igual a cursor | O cursor é inválido ou pertence a outro contexto; isso inclui uma etiqueta trocada entre páginas | Confira conta, envio e parâmetros; descarte o cursor anterior e reinicie sem cursor |
Após uma troca de etiqueta, reconstrua o histórico atual sem misturar eventos da anterior. Outros erros 422 podem apontar um parâmetro diferente em details.field; corrija esse parâmetro antes de repetir a chamada.
Updated about 1 month ago