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

Regras por categoria

Define, por categoria de produto, o prazo de devolução, a exigência de fotos e a aprovação automática.

Nem todo produto se devolve do mesmo jeito. Um perfume lacrado pode ter prazo curto e aprovação automática por arrependimento; um eletrônico pode exigir fotos do defeito. A regra por categoria guarda essas políticas, uma por categoria. Ler a lista exige acesso a pedidos; criar, alterar e excluir exigem manage_returns ou manage_orders.

Quando o item devolvido pertence a uma categoria com regra, require_photos ligado impede o cliente de abrir a devolução daquele item sem enviar pelo menos uma foto, e as opções de aprovação automática passam a valer para ele.

Listar regras

Devolve todas as regras, ordenadas pelo nome da categoria. Sem paginação.

GET/api/v1/admin/returns/rulesAdmin

Lista as regras de devolução por categoria

Sem parâmetros.

Exemplo de requisição

bash

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

Resposta

200Regras retornadas

json

{
  "rules": [
    {
      "id": "4a952e2c-5048-4f48-8287-cd9ea3fb8993",
      "category_id": "a8e4a184-5432-4a39-aad2-4f3430d3e5c2",
      "category_name": "Perfumes",
      "window_days": 7,
      "require_photos": false,
      "auto_approve_regret": true,
      "auto_approve_defect_with_ai": false
    }
  ]
}

Sem nenhuma regra, rules vem null.

Campos da resposta

rules[].iduuid

Id da regra.

rules[].category_iduuid

Categoria à qual a regra se aplica. Há no máximo uma regra por categoria.

rules[].category_namestring

Nome da categoria.

rules[].window_daysinteger

Prazo, em dias, da política da categoria. Nunca menor que 7. Veja o aviso abaixo sobre onde ele é aplicado.

rules[].require_photosboolean

Se exige foto de evidência para abrir a devolução.

rules[].auto_approve_regretboolean

Se aprova sozinha devoluções que a análise das fotos classifica como arrependimento ou item diferente do esperado. Só age quando há fotos analisadas.

rules[].auto_approve_defect_with_aiboolean

Se permite aprovar sozinha devoluções por defeito ou dano de transporte quando a análise das fotos é confiável e o valor do item é baixo.

Erros

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

Criar ou atualizar uma regra

POST e PUT fazem exatamente a mesma coisa: gravam a regra da categoria, criando se não existir e substituindo se existir. Não há identificador na URL; a chave é category_id. Envie sempre os quatro campos de política, porque a gravação é completa.

POST/api/v1/admin/returns/rulesAdmin

Cria ou atualiza a regra de uma categoria

Corpo da requisição

category_iduuidobrigatório

Categoria da regra.

window_daysintegerobrigatório

Prazo em dias, no mínimo 7 (garantia do Código de Defesa do Consumidor, art. 49). Valor menor é recusado.

require_photosbooleanpadrão: false

Exige foto de evidência.

auto_approve_regretbooleanpadrão: false

Aprova sozinha as devoluções por arrependimento.

auto_approve_defect_with_aibooleanpadrão: false

Permite aprovação automática de defeito pela triagem das fotos.

PUT/api/v1/admin/returns/rulesAdmin

Cria ou atualiza a regra de uma categoria (igual ao POST)

Mesmo corpo, mesma resposta e mesmos erros do POST. Existe para clientes que preferem PUT em gravações idempotentes.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/returns/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": "a8e4a184-5432-4a39-aad2-4f3430d3e5c2",
    "window_days": 15,
    "require_photos": true,
    "auto_approve_regret": false,
    "auto_approve_defect_with_ai": false
  }'

Resposta

200Regra gravada

json

{
  "id": "4a952e2c-5048-4f48-8287-cd9ea3fb8993",
  "category_id": "a8e4a184-5432-4a39-aad2-4f3430d3e5c2",
  "window_days": 15,
  "require_photos": true,
  "auto_approve_regret": false,
  "auto_approve_defect_with_ai": false
}

O status é 200 mesmo quando a regra é criada (não 201). O nome da categoria (category_name) só aparece na lista.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid_body","detail":"..."}`
400	`category_id` vazio	`{"error":"rule_invalid","detail":"category_id is required"}`
400	`window_days` menor que 7	`{"error":"rule_invalid","detail":"window_days must be at least 7 (CDC Art. 49)"}`
400	`category_id` que não existe ou não é UUID	`{"error":"rule_invalid","detail":"..."}`

Excluir uma regra

Remove a regra; a categoria volta a seguir a política geral da loja. A chamada é tolerante: excluir um id que não existe também responde sucesso.

DELETE/api/v1/admin/returns/rules/{ruleId}Admin

Remove a regra de uma categoria

Parâmetros de caminho

ruleIduuidobrigatório

Id da regra (o id da lista, não o category_id).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/returns/rules/4a952e2c-5048-4f48-8287-cd9ea3fb8993" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra removida

json

{ "ok": true }

Erros

Status	Quando	Corpo
500	Falha interna, ou `ruleId` que não é UUID	`{"error":"rule_delete_failed","detail":"..."}`

Veja também

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

Regras por categoria

Define, por categoria de produto, o prazo de devolução, a exigência de fotos e a aprovação automática.

Listar regras

Devolve todas as regras, ordenadas pelo nome da categoria. Sem paginação.

GET/api/v1/admin/returns/rulesAdmin

Lista as regras de devolução por categoria

Sem parâmetros.

Exemplo de requisição

bash

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

Resposta

200Regras retornadas

json

{
  "rules": [
    {
      "id": "4a952e2c-5048-4f48-8287-cd9ea3fb8993",
      "category_id": "a8e4a184-5432-4a39-aad2-4f3430d3e5c2",
      "category_name": "Perfumes",
      "window_days": 7,
      "require_photos": false,
      "auto_approve_regret": true,
      "auto_approve_defect_with_ai": false
    }
  ]
}

Sem nenhuma regra, rules vem null.

Campos da resposta

rules[].iduuid

Id da regra.

rules[].category_iduuid

Categoria à qual a regra se aplica. Há no máximo uma regra por categoria.

rules[].category_namestring

Nome da categoria.

rules[].window_daysinteger

Prazo, em dias, da política da categoria. Nunca menor que 7. Veja o aviso abaixo sobre onde ele é aplicado.

rules[].require_photosboolean

Se exige foto de evidência para abrir a devolução.

rules[].auto_approve_regretboolean

Se aprova sozinha devoluções que a análise das fotos classifica como arrependimento ou item diferente do esperado. Só age quando há fotos analisadas.

rules[].auto_approve_defect_with_aiboolean

Se permite aprovar sozinha devoluções por defeito ou dano de transporte quando a análise das fotos é confiável e o valor do item é baixo.

Erros

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

Criar ou atualizar uma regra

POST/api/v1/admin/returns/rulesAdmin

Cria ou atualiza a regra de uma categoria

Corpo da requisição

category_iduuidobrigatório

Categoria da regra.

window_daysintegerobrigatório

Prazo em dias, no mínimo 7 (garantia do Código de Defesa do Consumidor, art. 49). Valor menor é recusado.

require_photosbooleanpadrão: false

Exige foto de evidência.

auto_approve_regretbooleanpadrão: false

Aprova sozinha as devoluções por arrependimento.

auto_approve_defect_with_aibooleanpadrão: false

Permite aprovação automática de defeito pela triagem das fotos.

PUT/api/v1/admin/returns/rulesAdmin

Cria ou atualiza a regra de uma categoria (igual ao POST)

Mesmo corpo, mesma resposta e mesmos erros do POST. Existe para clientes que preferem PUT em gravações idempotentes.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/returns/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": "a8e4a184-5432-4a39-aad2-4f3430d3e5c2",
    "window_days": 15,
    "require_photos": true,
    "auto_approve_regret": false,
    "auto_approve_defect_with_ai": false
  }'

Resposta

200Regra gravada

json

{
  "id": "4a952e2c-5048-4f48-8287-cd9ea3fb8993",
  "category_id": "a8e4a184-5432-4a39-aad2-4f3430d3e5c2",
  "window_days": 15,
  "require_photos": true,
  "auto_approve_regret": false,
  "auto_approve_defect_with_ai": false
}

O status é 200 mesmo quando a regra é criada (não 201). O nome da categoria (category_name) só aparece na lista.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid_body","detail":"..."}`
400	`category_id` vazio	`{"error":"rule_invalid","detail":"category_id is required"}`
400	`window_days` menor que 7	`{"error":"rule_invalid","detail":"window_days must be at least 7 (CDC Art. 49)"}`
400	`category_id` que não existe ou não é UUID	`{"error":"rule_invalid","detail":"..."}`

Excluir uma regra

Remove a regra; a categoria volta a seguir a política geral da loja. A chamada é tolerante: excluir um id que não existe também responde sucesso.

DELETE/api/v1/admin/returns/rules/{ruleId}Admin

Remove a regra de uma categoria

Parâmetros de caminho

ruleIduuidobrigatório

Id da regra (o id da lista, não o category_id).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/returns/rules/4a952e2c-5048-4f48-8287-cd9ea3fb8993" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra removida

json

{ "ok": true }

Erros

Status	Quando	Corpo
500	Falha interna, ou `ruleId` que não é UUID	`{"error":"rule_delete_failed","detail":"..."}`