Gerencie o rastreamento das vendas físicas — status logístico, código e URL de rastreio, individualmente ou em massa via planilha.
Vendas com product_type: physical possuem um ciclo logístico próprio, independente
do status financeiro da cobrança. Uma cobrança captured pode estar pending na
entrega, e vice-versa — os dois status nunca se misturam.
O rastreamento usa o enum charge_shipping_status, distinto do status de pagamento:
| Status | Descrição |
|---|---|
pending | Venda física aguardando informações de envio |
shipped | Pedido despachado pelo merchant |
in_transit | Em trânsito com a transportadora |
delivered | Entregue ao comprador |
exception | Ocorrência reportada (extravio, avaria, travado na transportadora) |
returned | Devolvido ao merchant |
Vendas digitais (product_type: digital) não possuem rastreamento: a API rejeita
qualquer atualização com 422 CHARGE_NOT_PHYSICAL.
PATCH /v1/charges/{id}/shipping
Authorization: Bearer <token> (permissão charges.update){
"status": "shipped",
"tracking_code": "BR123456789BR",
"tracking_url": "https://rastreio.correios.com.br/BR123456789BR"
}A atualização é parcial: apenas os campos enviados são alterados. Charge de
outro merchant retorna 404 (indistinguível de uma cobrança inexistente — sem
vazamento de existência). Admins podem atualizar qualquer cobrança do próprio
gateway.
Respostas de erro principais:
| HTTP | Código | Motivo |
|---|---|---|
| 404 | NOT_FOUND | Cobrança não existe ou não pertence ao merchant |
| 422 | CHARGE_NOT_PHYSICAL | Venda digital não possui rastreamento |
| 400 | EMPTY_SHIPPING_UPDATE | Payload sem nenhum campo |
GET /v1/charges/shippings — lista vendas físicas com filtros: shipping_status,
has_tracking_code, fulfillment_state=pending_fulfillment (sem envio ainda),
período (date_from/date_to), busca (search) e paginação. Merchant vê
apenas as próprias vendas; admin pode filtrar por merchant_id.GET /v1/charges/shippings/summary — métricas: total de vendas físicas, com/sem
código, contagem por status e distribuição por merchant (top 10).O fluxo de planilha cobre o caso de uso principal: o merchant exporta as vendas que ainda precisam de rastreamento (sem código ou ainda não entregues), preenche a planilha offline e reimporta.
GET /v1/charges/shippings/export?scope=pending_fulfillment (padrão)
GET /v1/charges/shippings/export?scope=allRetorna CSV (text/csv) com as colunas:
| Coluna | Editável | Descrição |
|---|---|---|
charge_id | não | UUID da cobrança — chave de reconciliação da importação |
external_id | não | ID na adquirente |
created_at | não | Data da venda |
customer_name | não | Nome do comprador (identificação humana) |
amount / currency | não | Valor da venda |
charge_status | não | Status financeiro (apenas referência) |
shipping_status | sim | Status logístico |
tracking_code | sim | Código de rastreio (até 255 caracteres) |
tracking_url | sim | URL http(s) de rastreio |
Limite de 10.000 linhas por exportação.
POST /v1/charges/shippings/import
Content-Type: multipart/form-data
file: <planilha preenchida>Regras de processamento:
charge_id; a cobrança deve pertencer ao
merchant autenticado (linha de outro merchant = erro
cobrança não encontrada para este merchant, sem alterar nada).http(s) ou UUID malformado geram erro apenas
naquela linha; as demais são processadas normalmente.ignored (nenhuma alteração) —
reimportar o mesmo arquivo é seguro e idempotente.Resumo de retorno:
{
"data": {
"processed": 120,
"updated": 105,
"ignored": 8,
"errors": 7,
"details": [
{ "line": 14, "charge_id": "…", "outcome": "error", "reason"