API atual/Referência completa/Devoluções

Logística reversa

Emite ou reemite a autorização de postagem de uma devolução, cancela a autorização e consulta o rastreio de volta.

Logística reversa é o transporte do produto de volta à loja. Para o cliente não pagar frete nem precisar de etiqueta própria, a loja pede ao transportador uma autorização de postagem: um código e uma etiqueta que o cliente leva à agência. Estas três rotas controlam essa autorização. Em geral a emissão acontece sozinha na aprovação (se o módulo de devoluções estiver configurado para isso); use as rotas para repetir uma emissão que falhou, cancelar uma autorização ou acompanhar o rastreio.

Emitir a logística reversa

Pede (ou pede de novo) a autorização de postagem ao transportador e devolve os dados dela. Use quando reverse_status ficou failed, ou quando a emissão automática está desligada e você quer emitir sob demanda. A chamada é síncrona: espera o transportador responder. Em caso de sucesso, o reverse_status vira authorized; o envio de devolução associado também é autorizado.

POST/api/v1/admin/returns/{id}/reverseAdmin

Emite ou reemite a autorização de logística reversa

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/reverse" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Autorização emitida

json

{
  "reverse_status": "authorized",
  "reverse_authorization_code": "PLP-8841-2209",
  "reverse_label_url": "https://exemplo.com/etiquetas/PLP-8841-2209.pdf"
}

Campos da resposta

reverse_statusstring

Situação da logística reversa depois da emissão (authorized em caso de sucesso).

reverse_authorization_codestring

Código de autorização de postagem do transportador.

reverse_label_urlstring

Link da etiqueta que o cliente imprime.

Erros

Status	Quando	Corpo
502	O transportador falhou, recusou ou não está configurado; ou a devolução não existe. O `reverse_status` fica `failed` quando a falha vem do transportador	`{"error":"reverse_failed","detail":"..."}`
404	A devolução foi emitida, mas não foi possível lê-la de volta	`{"error":"return_not_found"}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Cancelar a logística reversa

Cancela uma autorização que ainda não foi postada. Se o transportador permite cancelamento remoto, a plataforma tenta cancelar lá também; uma falha remota é registrada, mas não impede o cancelamento local. A chamada é idempotente: cancelar uma autorização já cancelada devolve sucesso.

DELETE/api/v1/admin/returns/{id}/reverseAdmin

Cancela a autorização de logística reversa

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/reverse" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Autorização cancelada

json

{
  "reverse_status": "cancelled",
  "reverse_authorization_code": "PLP-8841-2209"
}

Campos da resposta

reverse_statusstring

cancelled.

reverse_authorization_codestring

Código da autorização cancelada.

Erros

Status	Quando	Corpo
409	O objeto já foi postado, está em trânsito ou foi entregue	`{"error":"reverse_already_posted","detail":"reverse already posted; cannot cancel"}`
404	Devolução inexistente	`{"error":"return_not_found","detail":"return not found"}`
400	Não há autorização ativa (`reverse_status` vazio ou `none`)	`{"error":"reverse_cancel_failed","detail":"no active reverse authorization to cancel"}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Rastreio de volta

Devolve a linha do tempo do objeto devolvido, do mais antigo para o mais novo, alimentada pelo acompanhamento do transportador. Use para mostrar "postado", "em trânsito", "entregue" ao atendente. Quando o objeto chega à loja, a plataforma avança a devolução para item_received sozinha (e, se o módulo estiver configurado para reembolso automático na chegada, até refunded).

GET/api/v1/admin/returns/{id}/reverse-eventsAdmin

Linha do tempo do rastreio da logística reversa

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/reverse-events" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Eventos de rastreio

json

{
  "events": [
    {
      "status": "posted",
      "description": "Objeto postado",
      "location": "São Paulo/SP",
      "occurred_at": "2026-10-12T13:05:00Z"
    },
    {
      "status": "delivered",
      "description": "Objeto entregue ao remetente",
      "location": "Campinas/SP",
      "occurred_at": "2026-10-15T16:40:00Z"
    }
  ]
}

Sem eventos (ou com id inexistente), events vem null e o status é 200.

Campos da resposta

eventsarray

Eventos em ordem cronológica crescente.

events[].statusstring

Situação informada pelo transportador.

events[].descriptionstring

Texto do evento.

events[].locationstring

Local do evento.

events[].occurred_atstring

Quando ocorreu, RFC 3339.

Erros

Status	Quando	Corpo
500	Falha interna, ou `id` que não é UUID	`{"error":"reverse_events_failed","detail":"..."}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Veja também

API atual/Referência completa/Devoluções

Logística reversa

Emite ou reemite a autorização de postagem de uma devolução, cancela a autorização e consulta o rastreio de volta.

Emitir a logística reversa

POST/api/v1/admin/returns/{id}/reverseAdmin

Emite ou reemite a autorização de logística reversa

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/reverse" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Autorização emitida

json

{
  "reverse_status": "authorized",
  "reverse_authorization_code": "PLP-8841-2209",
  "reverse_label_url": "https://exemplo.com/etiquetas/PLP-8841-2209.pdf"
}

Campos da resposta

reverse_statusstring

Situação da logística reversa depois da emissão (authorized em caso de sucesso).

reverse_authorization_codestring

Código de autorização de postagem do transportador.

reverse_label_urlstring

Link da etiqueta que o cliente imprime.

Erros

Status	Quando	Corpo
502	O transportador falhou, recusou ou não está configurado; ou a devolução não existe. O `reverse_status` fica `failed` quando a falha vem do transportador	`{"error":"reverse_failed","detail":"..."}`
404	A devolução foi emitida, mas não foi possível lê-la de volta	`{"error":"return_not_found"}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Cancelar a logística reversa

DELETE/api/v1/admin/returns/{id}/reverseAdmin

Cancela a autorização de logística reversa

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/reverse" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Autorização cancelada

json

{
  "reverse_status": "cancelled",
  "reverse_authorization_code": "PLP-8841-2209"
}

Campos da resposta

reverse_statusstring

cancelled.

reverse_authorization_codestring

Código da autorização cancelada.

Erros

Status	Quando	Corpo
409	O objeto já foi postado, está em trânsito ou foi entregue	`{"error":"reverse_already_posted","detail":"reverse already posted; cannot cancel"}`
404	Devolução inexistente	`{"error":"return_not_found","detail":"return not found"}`
400	Não há autorização ativa (`reverse_status` vazio ou `none`)	`{"error":"reverse_cancel_failed","detail":"no active reverse authorization to cancel"}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`

Rastreio de volta

GET/api/v1/admin/returns/{id}/reverse-eventsAdmin

Linha do tempo do rastreio da logística reversa

Parâmetros de caminho

iduuidobrigatório

Id da devolução.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns/2f495c2f-dab7-4580-8004-54e39fa56c75/reverse-events" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Eventos de rastreio

json

{
  "events": [
    {
      "status": "posted",
      "description": "Objeto postado",
      "location": "São Paulo/SP",
      "occurred_at": "2026-10-12T13:05:00Z"
    },
    {
      "status": "delivered",
      "description": "Objeto entregue ao remetente",
      "location": "Campinas/SP",
      "occurred_at": "2026-10-15T16:40:00Z"
    }
  ]
}

Sem eventos (ou com id inexistente), events vem null e o status é 200.

Campos da resposta

eventsarray

Eventos em ordem cronológica crescente.

events[].statusstring

Situação informada pelo transportador.

events[].descriptionstring

Texto do evento.

events[].locationstring

Local do evento.

events[].occurred_atstring

Quando ocorreu, RFC 3339.

Erros

Status	Quando	Corpo
500	Falha interna, ou `id` que não é UUID	`{"error":"reverse_events_failed","detail":"..."}`
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`