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

Motivos de devolução

Lista, cria, altera e exclui os motivos que o cliente escolhe ao pedir uma devolução.

Os motivos são a lista de opções que aparece para o cliente ao abrir uma devolução: "Produto com defeito", "Chegou danificado", "Desisti da compra". Cada motivo tem um nome em inglês (name), um nome em português (name_pt_br) e uma posição na lista. Os quatro endpoints abaixo gerenciam essa lista. Ler exige acesso a pedidos; criar, alterar e excluir exigem manage_returns ou manage_orders.

Listar motivos

Devolve todos os motivos, ativos e inativos, ordenados por position e depois por nome. Sem paginação.

GET/api/v1/admin/returns/reasonsAdmin

Lista os motivos de devolução

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns/reasons" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Motivos retornados

json

{
  "reasons": [
    {
      "id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
      "name": "Defective product",
      "name_pt_br": "Produto com defeito",
      "position": 1,
      "is_active": true,
      "created_at": "2026-03-18T08:55:07.148645Z"
    },
    {
      "id": "b20ae1b7-3ed4-4a47-86c7-278c1ed20c6b",
      "name": "Changed my mind",
      "name_pt_br": "Desisti da compra",
      "position": 4,
      "is_active": true,
      "created_at": "2026-03-18T08:55:07.148645Z"
    }
  ]
}

Campos da resposta

reasonsarray

Lista de motivos. Vazia ([]) quando não há nenhum.

reasons[].iduuid

Id do motivo.

reasons[].namestring

Nome em inglês.

reasons[].name_pt_brstring

Nome em português do Brasil. Pode ser vazio.

reasons[].positioninteger

Posição de exibição, em ordem crescente.

reasons[].is_activeboolean

Se o motivo é oferecido ao cliente.

reasons[].created_atstring

Criação, RFC 3339 em UTC.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`
500	Falha interna	`{"error":"failed to list reasons","detail":"..."}`

Criar um motivo

Adiciona uma opção à lista. O motivo nasce ativo.

POST/api/v1/admin/returns/reasonsAdmin

Cria um motivo de devolução

Corpo da requisição

namestringobrigatório

Nome em inglês. Vazio é recusado.

name_pt_brstring

Nome em português. Se vazio, fica vazio: a plataforma não copia o inglês.

positionintegerpadrão: 0

Posição na lista.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/returns/reasons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Missing parts", "name_pt_br": "Peças faltando", "position": 6}'

Resposta

201Motivo criado

json

{
  "id": "34f68990-33a5-4a03-9e57-82ff5ec3be16",
  "name": "Missing parts",
  "name_pt_br": "Peças faltando",
  "position": 6,
  "is_active": true,
  "created_at": "2026-10-11T22:00:00Z"
}

Os campos são os da lista acima.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`name` vazio	`{"error":"name is required"}`
500	Falha interna, ou o par `name` + `name_pt_br` já existe (o banco impõe unicidade do par)	`{"error":"failed to create reason","detail":"..."}`

Alterar um motivo

Troca os campos do motivo. É uma substituição: name, name_pt_br e position são regravados com o que você enviar (o que faltar vira vazio ou 0), então envie sempre os três. is_active é o único campo opcional.

PUT/api/v1/admin/returns/reasons/{id}Admin

Altera um motivo de devolução

Parâmetros de caminho

iduuidobrigatório

Id do motivo.

Corpo da requisição

namestringobrigatório

Nome em inglês. Vazio é recusado.

name_pt_brstring

Nome em português. Se omitido, é apagado.

positioninteger

Posição. Se omitida, vira 0.

is_activebooleanpadrão: true

Se omitido, o motivo fica ativo, mesmo que estivesse inativo.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/returns/reasons/34f68990-33a5-4a03-9e57-82ff5ec3be16" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Missing parts", "name_pt_br": "Peças faltando", "position": 6, "is_active": false}'

Resposta

200Motivo alterado

json

{
  "id": "34f68990-33a5-4a03-9e57-82ff5ec3be16",
  "name": "Missing parts",
  "name_pt_br": "Peças faltando",
  "position": 6,
  "is_active": false,
  "created_at": "2026-10-11T22:00:00Z"
}

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`name` vazio	`{"error":"name is required"}`
400	Motivo inexistente, id que não é UUID, ou o par `name` + `name_pt_br` já existe em outro motivo	`{"error":"failed to update reason","detail":"reason not found"}`

Excluir um motivo

Remove o motivo de vez, mas só se nenhuma devolução o usa. Para tirar da lista um motivo já usado, desative-o (is_active: false).

DELETE/api/v1/admin/returns/reasons/{id}Admin

Exclui um motivo de devolução

Parâmetros de caminho

iduuidobrigatório

Id do motivo.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/returns/reasons/34f68990-33a5-4a03-9e57-82ff5ec3be16" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Motivo excluído

json

{ "message": "reason deleted" }

Erros

Status	Quando	Corpo
400	Motivo inexistente, id que não é UUID, ou motivo já usado por alguma devolução (o banco não deixa apagar)	`{"error":"failed to delete reason","detail":"reason not found"}`

Veja também

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

Motivos de devolução

Lista, cria, altera e exclui os motivos que o cliente escolhe ao pedir uma devolução.

Listar motivos

Devolve todos os motivos, ativos e inativos, ordenados por position e depois por nome. Sem paginação.

GET/api/v1/admin/returns/reasonsAdmin

Lista os motivos de devolução

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/returns/reasons" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Motivos retornados

json

{
  "reasons": [
    {
      "id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
      "name": "Defective product",
      "name_pt_br": "Produto com defeito",
      "position": 1,
      "is_active": true,
      "created_at": "2026-03-18T08:55:07.148645Z"
    },
    {
      "id": "b20ae1b7-3ed4-4a47-86c7-278c1ed20c6b",
      "name": "Changed my mind",
      "name_pt_br": "Desisti da compra",
      "position": 4,
      "is_active": true,
      "created_at": "2026-03-18T08:55:07.148645Z"
    }
  ]
}

Campos da resposta

reasonsarray

Lista de motivos. Vazia ([]) quando não há nenhum.

reasons[].iduuid

Id do motivo.

reasons[].namestring

Nome em inglês.

reasons[].name_pt_brstring

Nome em português do Brasil. Pode ser vazio.

reasons[].positioninteger

Posição de exibição, em ordem crescente.

reasons[].is_activeboolean

Se o motivo é oferecido ao cliente.

reasons[].created_atstring

Criação, RFC 3339 em UTC.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"returns"}`
500	Falha interna	`{"error":"failed to list reasons","detail":"..."}`

Criar um motivo

Adiciona uma opção à lista. O motivo nasce ativo.

POST/api/v1/admin/returns/reasonsAdmin

Cria um motivo de devolução

Corpo da requisição

namestringobrigatório

Nome em inglês. Vazio é recusado.

name_pt_brstring

Nome em português. Se vazio, fica vazio: a plataforma não copia o inglês.

positionintegerpadrão: 0

Posição na lista.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/returns/reasons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Missing parts", "name_pt_br": "Peças faltando", "position": 6}'

Resposta

201Motivo criado

json

{
  "id": "34f68990-33a5-4a03-9e57-82ff5ec3be16",
  "name": "Missing parts",
  "name_pt_br": "Peças faltando",
  "position": 6,
  "is_active": true,
  "created_at": "2026-10-11T22:00:00Z"
}

Os campos são os da lista acima.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`name` vazio	`{"error":"name is required"}`
500	Falha interna, ou o par `name` + `name_pt_br` já existe (o banco impõe unicidade do par)	`{"error":"failed to create reason","detail":"..."}`

Alterar um motivo

PUT/api/v1/admin/returns/reasons/{id}Admin

Altera um motivo de devolução

Parâmetros de caminho

iduuidobrigatório

Id do motivo.

Corpo da requisição

namestringobrigatório

Nome em inglês. Vazio é recusado.

name_pt_brstring

Nome em português. Se omitido, é apagado.

positioninteger

Posição. Se omitida, vira 0.

is_activebooleanpadrão: true

Se omitido, o motivo fica ativo, mesmo que estivesse inativo.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/returns/reasons/34f68990-33a5-4a03-9e57-82ff5ec3be16" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Missing parts", "name_pt_br": "Peças faltando", "position": 6, "is_active": false}'

Resposta

200Motivo alterado

json

{
  "id": "34f68990-33a5-4a03-9e57-82ff5ec3be16",
  "name": "Missing parts",
  "name_pt_br": "Peças faltando",
  "position": 6,
  "is_active": false,
  "created_at": "2026-10-11T22:00:00Z"
}

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`name` vazio	`{"error":"name is required"}`
400	Motivo inexistente, id que não é UUID, ou o par `name` + `name_pt_br` já existe em outro motivo	`{"error":"failed to update reason","detail":"reason not found"}`

Excluir um motivo

Remove o motivo de vez, mas só se nenhuma devolução o usa. Para tirar da lista um motivo já usado, desative-o (is_active: false).

DELETE/api/v1/admin/returns/reasons/{id}Admin

Exclui um motivo de devolução

Parâmetros de caminho

iduuidobrigatório

Id do motivo.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/returns/reasons/34f68990-33a5-4a03-9e57-82ff5ec3be16" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Motivo excluído

json

{ "message": "reason deleted" }

Erros

Status	Quando	Corpo
400	Motivo inexistente, id que não é UUID, ou motivo já usado por alguma devolução (o banco não deixa apagar)	`{"error":"failed to delete reason","detail":"reason not found"}`