1. Transações
Bestfy API
  • Sobre a Bestfy
    • Comece aqui
  • Webhooks
    • O que é um Webhook?
  • Status de transação
    • Status de Pagamento na Bestfy
  • Transações
    • Criar transações
      POST
    • Estornar transação
      POST
    • Buscar transação
      GET
    • Listar transações
      GET
    • Atualizar status de rastreio
      PATCH
  • Saldo
    • Buscar saldo
      GET
  • API Key
    • Validar API Key
      GET
  1. Transações

Atualizar status de rastreio

Developing
PATCH
https://api.bestfy.io/transaction/{financialTransactionId}/tracking
Use este endpoint para criar ou atualizar o rastreio de uma transação. Na primeira chamada,
cria a linha de entrega com os dados informados. Em chamadas subsequentes, avança o
status — trackingNumber e service são gravados apenas na criação e ignorados depois.

Autenticação#

x-api-key (obrigatório)
Chave da empresa para acesso público ao endpoint.

Regras de uso#

A transação deve existir e pertencer à empresa da API key.
O status avança apenas para frente no caminho linear:
PENDING_SHIPMENT > SHIPPED > IN_TRANSIT > OUT_FOR_DELIVERY > DELIVERED. Pular etapas é permitido.
RETURNED e LOST são terminais e podem ser alcançados de qualquer estado não-terminal (inclusive DELIVERED).
Nenhuma transição sai de RETURNED / LOST.
Idempotência: enviar o status atual novamente é no-op (não gera nova linha de histórico).
trackingNumber e service são write-once: gravados na criação da linha, ignorados em chamadas subsequentes.

Parâmetros da Requisição#

Path Params#

financialTransactionId (string, obrigatório)
Identificador da transação financeira.

Body#

status (string, obrigatório)
Novo status de rastreio. Valores aceitos:
PENDING_SHIPMENT — aguardando envio
SHIPPED — enviado
IN_TRANSIT — em trânsito
OUT_FOR_DELIVERY — saiu para entrega
DELIVERED — entregue
RETURNED — devolvido (terminal)
LOST — extraviado (terminal)
trackingNumber (string, opcional, máx. 120 caracteres)
Código de rastreio do pacote. Gravado apenas na primeira chamada — ignorado em chamadas posteriores.
service (string, opcional, máx. 60 caracteres)
Transportadora ou serviço de entrega responsável. Gravado apenas na primeira chamada — ignorado em chamadas posteriores.

Headers#

x-api-key (string, obrigatório)
Chave de autenticação da empresa.

Exemplo de Requisição#

Respostas#

204 No Content — Rastreio atualizada com sucesso.
400 Bad Request — Transição de status inválida (TRANSACTION_TRACKING_STATUS_TRANSITION_NOT_ALLOWED).
401 Unauthorized / 403 Forbidden — API key inválida ou ausente.
404 Not Found — Transação não encontrada.

Request

Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢204Entrega da transação atualizado com sucesso
This response does not have a body.
🟠400Transição de status de rastreio não permitida
🟠401API Key inválida ou ausente
🟠403API Key inválida ou ausente
🟠404Transação não encontrada
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request PATCH 'https://api.bestfy.io/transaction//tracking' \
--header 'User-Agent: <nome-do-projeto>' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "status": "SHIPPED",
    "service": "Correios",
    "trackingNumber": "AA12345678BR"
}'
Response Response Example
400 - Example 1
{}
Modified at 2026-05-14 20:31:55
Previous
Listar transações
Next
Buscar saldo
Built with