VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
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

Resposta

200Regras retornadas

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

StatusQuandoCorpo
401 / 403Sem token, sem privilégio, ou módulo desligado{"error":"module_disabled","module":"returns"}
500Falha 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

Resposta

200Regra gravada

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

Erros

StatusQuandoCorpo
400Corpo que não é JSON{"error":"invalid_body","detail":"..."}
400category_id vazio{"error":"rule_invalid","detail":"category_id is required"}
400window_days menor que 7{"error":"rule_invalid","detail":"window_days must be at least 7 (CDC Art. 49)"}
400category_id que não existe ou não é UUID{"error":"rule_invalid","detail":"..."}
Aprovação automática e prazo

A aprovação automática age só quando a devolução tem fotos analisadas, quando o valor do item é baixo (limite padrão de R$ 200,00, configurável no módulo) e nunca em caso suspeito de abuso. Ela aprova sem definir refund_amount, que continua em 0: para reembolsar essa devolução será preciso um valor, e estas rotas não permitem processá-la de novo. Além disso, na abertura da devolução o prazo é conferido pela configuração geral de devoluções da loja (dias desde a entrega); o window_days desta regra é guardado, mas hoje não entra nessa conferência.

O prazo mínimo é de lei

O Código de Defesa do Consumidor dá 7 dias para o arrependimento em compra à distância. A API não deixa configurar menos que isso.

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

Resposta

200Regra removida

Erros

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

Veja também

  • Motivos
  • Decisões
Anterior
Motivos de devolução
Próxima
Devoluções e contestações
Nesta página
  • Listar regras
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar ou atualizar uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/returns/rules" \
  -H "Authorization: Bearer $TOKEN"
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
  }'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/returns/rules/4a952e2c-5048-4f48-8287-cd9ea3fb8993" \
  -H "Authorization: Bearer $TOKEN"
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
    }
  ]
}
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
}
json
{ "ok": true }