API v2
Visão geral da API /api/v2, uma superfície administrativa enxuta com envelope data/meta, usada por integrações que não precisam da API de administração completa.
A API v2 (/api/v2) é uma superfície REST de administração enxuta. Todas as respostas seguem o mesmo envelope, todos os erros seguem o mesmo formato e as listas aceitam os mesmos parâmetros de paginação e de projeção de campos. Integradores a usam para ler e manter cupons, devoluções, sellers (lojistas) e assinaturas de webhook sem aprender um contrato extenso.
Esta seção documenta quatro recursos da v2: cupons, devoluções, sellers e webhooks. A v2 tem outros recursos (produtos, pedidos, clientes), que não fazem parte desta seção.
Como funciona
Uma chamada típica tem três passos: obter o token de administrador, chamar o recurso e tratar o envelope.
- Obtenha o token
Autentique-se como administrador e guarde o token de acesso (JWT). Veja Autenticação. O login tem limite de requisições: reutilize o token.
- Escolha a loja
Em produção a loja vem do domínio (
https://minhaloja.io.venddor.com.br). Em ambientes de teste você também pode enviar o cabeçalhoX-Tenant-ID. - Chame o recurso
Use os caminhos desta seção. Em listas, leia
data(os itens) emeta.pagination(página atual e total).
Conceitos-chave
O envelope
Sucesso com um item:
{ "data": { "id": 79, "code": "TESTE10" } }Sucesso com lista:
{
"data": [ { "id": 79, "code": "TESTE10" } ],
"meta": { "pagination": { "page": 1, "per_page": 20, "total": 38, "total_pages": 2 } }
}Remoções (DELETE) respondem 204 sem corpo.
Paginação
| Parâmetro | Padrão | Limite |
|---|---|---|
page | 1 | Valor menor que 1 vira 1. |
per_page | 20 | De 1 a 100. Acima de 100 vira 100. Zero ou negativo vira 20. |
Mais detalhes em Convenções.
Projeção de campos
?fields=id,code,is_active devolve só essas chaves de cada item. Nomes que não existem são ignorados. Não vale para a resposta de criação nem de edição.
Erros
Os erros desta superfície têm sempre code (para o seu código decidir), message (para uma pessoa ler, em inglês) e, às vezes, details.
| Status | code | Quando |
|---|---|---|
| 400 | bad_request | Corpo inválido, campo obrigatório ausente, id mal formado. |
| 404 | not_found | O recurso não existe. |
| 409 | conflict | Duplicidade (código de cupom, e-mail ou slug de seller). |
| 422 | margin_floor | O desconto levaria produtos abaixo da margem mínima da loja. |
| 422 | refused_by_store | Uma regra da própria loja recusou a alteração. |
| 500 | internal_error | Falha inesperada. details traz uma descrição curta. |
Falhas de autenticação e de permissão vêm de uma camada anterior e têm formato simples: {"error":"missing authorization header"} (401) e {"error":"insufficient permissions"} (403). Trate os dois formatos.
Um id numérico 0 ou negativo em qualquer parte do caminho responde 400 {"error":"invalid id parameter"} antes de chegar ao recurso.
Endpoints
| Método | Caminho | Para quê | Auth | Página |
|---|---|---|---|---|
| GET | /api/v2/coupons | Listar cupons com filtros | admin | Cupons: consulta |
| GET | /api/v2/coupons/{id} | Ler um cupom | admin | Cupons: consulta |
| POST | /api/v2/coupons | Criar um cupom | admin | Cupons: escrita |
| PUT | /api/v2/coupons/{id} | Alterar um cupom | admin | Cupons: escrita |
| DELETE | /api/v2/coupons/{id} | Apagar um cupom | admin | Cupons: escrita |
| GET | /api/v2/returns | Listar devoluções | admin | Devoluções |
| GET | /api/v2/returns/{id} | Ler uma devolução | admin | Devoluções |
| POST | /api/v2/returns | Abrir uma devolução pela equipe | admin | Devoluções |
| GET | /api/v2/vendors | Listar sellers | admin | Sellers |
| GET | /api/v2/vendors/{id} | Ler um seller | admin | Sellers |
| POST | /api/v2/vendors | Cadastrar um seller | admin | Sellers |
| PUT | /api/v2/vendors/{id} | Alterar um seller | admin | Sellers |
| GET | /api/v2/webhooks | Listar assinaturas de webhook | admin | Webhooks |
| GET | /api/v2/webhooks/{id} | Ler uma assinatura | admin | Webhooks |
| POST | /api/v2/webhooks | Criar uma assinatura | admin | Webhooks |
| DELETE | /api/v2/webhooks/{id} | Remover uma assinatura | admin | Webhooks |
Erros comuns
- Mandar o JWT de um seller ou de um cliente. A v2 só aceita administrador: o resultado é
403 {"error":"insufficient permissions"}. - Tratar
valuede cupom percentual como porcentagem.value: 10é 0,10%, não 10%. Para 10% envie1000. - Esperar
datanum erro de autenticação. O 401 e o 403 vêm no formato simples, sem o envelopeerror.code. - Usar um UUID no cupom. O id de cupom é um inteiro (
79). Um texto qualquer responde400 coupon id must be a positive integer. - Reenviar
POSTsem checar duplicidade. Cupom repetido responde 409; webhook criado duas vezes vira duas assinaturas e o evento chega duas vezes. - Guardar o segredo do webhook só depois. O segredo completo aparece uma única vez, na resposta da criação.