Atualizar rastreio de entrega
Defina ou atualize o rastreio de entrega em uma transação paga.
id da transação. Autentique com a API key da sua empresa (Bearer, API key ou Basic auth). Depois de definido, o rastreio aparece em Consultar transação nos campos de entrega da transação.
Campos da requisição
O corpo é JSON com campos em snake_case:| Campo | Tipo | Obrigatório | Restrições |
|---|---|---|---|
tracking_code | string | Sim | Sem espaços nas pontas, 1–255 caracteres, sem caracteres de controle ASCII. |
delivery_status | enum | Não | Um de waiting, in_transit, delivered. Padrão in_transit no primeiro envio. |
tracking_url | string | null | Não | Sem espaços nas pontas, máx. 255 caracteres, deve começar com http:// ou https://. |
tracking_company | string | null | Não | Sem espaços nas pontas, 1–64 caracteres. |
Omitir vs. null
- Omita um campo opcional para manter o valor atual inalterado.
- Envie
nullemtracking_urloutracking_companypara limpar um valor definido anteriormente. - Quando
delivery_statusé omitido, o status atual é preservado na atualização, ou assumein_transitna primeira vez que o rastreio é definido. - Uma entrega já marcada como
deliverednão pode voltar parawaitingouin_transit(retorna409).
Idempotência e concorrência
PUT é idempotente — repetir a mesma requisição produz o mesmo estado de entrega. Para concorrência otimista, envie o ETag da transação no header If-Match; um ETag desatualizado retorna 412 Precondition Failed.
Erros
| Status | Significado |
|---|---|
400 | Requisição malformada. |
401 | Credenciais ausentes ou inválidas. |
404 | Transação não encontrada para esta empresa. |
409 | Transição de status inválida (ex.: reverter uma entrega delivered). |
412 | ETag do If-Match não confere. |
422 | Validação falhou (restrições de campo não atendidas). |
429 | Limite de requisições excedido. |
Exemplo
GET /v2/transactions/{id}.Autorizações
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Parâmetros de caminho
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Corpo
Carrier tracking code for the shipment. Required.
1 - 255"BR123456789BR"
Delivery status of the shipment. One of waiting, in_transit, or delivered. When omitted, the existing status is preserved on update, or defaults to in_transit on the first update.
waiting, in_transit, delivered "in_transit"
Public URL where the buyer can track the shipment. Must start with http:// or https://. Send null to clear a previously set value; omit to leave it unchanged.
255"https://tracking.carrier.com/BR123456789BR"
Name of the carrier handling the shipment. Send null to clear a previously set value; omit to leave it unchanged.
1 - 64"Correios"

