Pular para o conteúdo principal
PUT
Update Delivery Tracking
Defina ou atualize as informações de rastreio de entrega em uma transação paga. Use na URL o UUID retornado como 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:
CampoTipoObrigatórioRestrições
tracking_codestringSimSem espaços nas pontas, 1–255 caracteres, sem caracteres de controle ASCII.
delivery_statusenumNãoUm de waiting, in_transit, delivered. Padrão in_transit no primeiro envio.
tracking_urlstring | nullNãoSem espaços nas pontas, máx. 255 caracteres, deve começar com http:// ou https://.
tracking_companystring | nullNãoSem espaços nas pontas, 1–64 caracteres.

Omitir vs. null

  • Omita um campo opcional para manter o valor atual inalterado.
  • Envie null em tracking_url ou tracking_company para limpar um valor definido anteriormente.
  • Quando delivery_status é omitido, o status atual é preservado na atualização, ou assume in_transit na primeira vez que o rastreio é definido.
  • Uma entrega já marcada como delivered não pode voltar para waiting ou in_transit (retorna 409).

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

StatusSignificado
400Requisição malformada.
401Credenciais ausentes ou inválidas.
404Transação não encontrada para esta empresa.
409Transição de status inválida (ex.: reverter uma entrega delivered).
412ETag do If-Match não confere.
422Validação falhou (restrições de campo não atendidas).
429Limite de requisições excedido.

Exemplo

O rastreio atualizado passa a aparecer em GET /v2/transactions/{id}.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de caminho

id
string<uuid>
obrigatório
Pattern: ^([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

application/json
tracking_code
string
obrigatório

Carrier tracking code for the shipment. Required.

Required string length: 1 - 255
Exemplo:

"BR123456789BR"

delivery_status
enum<string>

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.

Opções disponíveis:
waiting,
in_transit,
delivered
Exemplo:

"in_transit"

tracking_url
string | null

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.

Maximum string length: 255
Exemplo:

"https://tracking.carrier.com/BR123456789BR"

tracking_company
string | null

Name of the carrier handling the shipment. Send null to clear a previously set value; omit to leave it unchanged.

Required string length: 1 - 64
Exemplo:

"Correios"

Resposta

Success

success
boolean
obrigatório
requestId
string
obrigatório
data
object
obrigatório