VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Vales-presente

Emitir e consultar vales

Lista, consulta e emite vales-presente.

Um vale-presente (gift certificate) é crédito pré-pago identificado por um código. O cliente digita o código no checkout e o valor abate o pedido; o que sobra continua no vale, até esgotar ou expirar.

Listar vales

Lista os vales emitidos, do mais recente ao mais antigo.

GET/api/v1/admin/gift-certificatesAdmin

Lista os vales-presente

Autenticação: Authorization: Bearer <token> de um administrador. Requer os módulos promotions e gift-certificates ativos. Leitura: view_promotions, view_gift_certificates (ou os equivalentes manage_). Escrita: manage_gift_certificates ou manage_promotions.

Parâmetros de consulta

statusstring
activedisabledusedADF
active, disabled, used (esgotado) ou a letra A, D, F.
searchstring
Trecho do código, do e-mail do destinatário ou do nome de quem presenteia.
vendor_iduuid
Só os vales de um seller.
marketplace_onlyboolean
true, 1 ou yes lista só os vales da loja inteira (sem seller). Ignorado se vendor_id vier.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
De 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/gift-certificates?status=active&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vales devolvidos
json
{
  "certificates": [
    {
      "id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
      "code": "GC-ZLCC-UULU-UHUP",
      "amount": 5000,
      "balance": 5000,
      "status": "A",
      "recipient_email": "ana.souza@example.com",
      "recipient_name": "Ana Souza",
      "from_name": "Equipe da Loja",
      "message": "Feliz aniversário!",
      "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "created_at": "2026-07-12T19:48:19.102787Z",
      "updated_at": "2026-07-12T19:50:21.081224Z",
      "gift_cert_id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
      "gift_cert_code": "GC-ZLCC-UULU-UHUP",
      "amount_str": "50.00",
      "balance_str": "50.00",
      "timestamp": 1783885699
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

certificatesarray
Vales da página.
certificates[].iduuid
Identificador do vale.
certificates[].vendor_iduuid
Seller dono do vale. Omitido quando o vale é da loja inteira.
certificates[].codestring
Código que o cliente digita no checkout, em maiúsculas. Único.
certificates[].amountinteger
Valor original, em centavos.
certificates[].balanceinteger
Saldo restante, em centavos.
certificates[].statusstring
ADF
Letra: A ativo, D desativado, F esgotado (usado até zerar).
certificates[].recipient_emailstring
E-mail de quem recebe o vale.
certificates[].recipient_namestring
Nome de quem recebe.
certificates[].from_namestring
Nome de quem presenteia.
certificates[].messagestring
Mensagem do presente.
certificates[].created_byuuid
Administrador que emitiu. Omitido se desconhecido.
certificates[].used_atstring
Primeiro uso. Omitido se nunca usado.
certificates[].expires_atstring
Validade, RFC 3339. Omitido se não expira.
certificates[].created_atstring
Emissão.
certificates[].updated_atstring
Última alteração.
certificates[].gift_cert_iduuid
Cópia de id, para clientes da plataforma antiga.
certificates[].gift_cert_codestring
Cópia de code, para clientes da plataforma antiga.
certificates[].amount_strstring
amount como texto decimal ("50.00").
certificates[].balance_strstring
balance como texto decimal.
certificates[].timestampinteger
created_at em segundos Unix.
totalinteger
Total com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"gift-certificates"} / {"error":"insufficient privileges","required":"manage_promotions"}
500vendor_id que não é UUID ou falha na consulta{"error":"failed to list gift certificates","detail":"..."}
`certificates` pode vir `null`

Sem nenhum vale, a lista pode vir null em vez de []. Trate os dois.

Consultar um vale

Devolve um vale pelo identificador.

GET/api/v1/admin/gift-certificates/{id}Admin

Consulta um vale-presente

Autenticação: Authorization: Bearer <token> de um administrador. Requer os módulos promotions e gift-certificates ativos. Leitura: view_promotions, view_gift_certificates (ou os equivalentes manage_). Escrita: manage_gift_certificates ou manage_promotions.

Parâmetros de caminho

iduuidobrigatório
Identificador do vale.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/gift-certificates/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vale devolvido
json
{
  "id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
  "code": "GC-ZLCC-UULU-UHUP",
  "amount": 5000,
  "balance": 5000,
  "status": "A",
  "recipient_email": "ana.souza@example.com",
  "recipient_name": "Ana Souza",
  "from_name": "Equipe da Loja",
  "message": "Feliz aniversário!",
  "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
  "created_at": "2026-07-12T19:48:19.102787Z",
  "updated_at": "2026-07-12T19:50:21.081224Z",
  "gift_cert_id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
  "gift_cert_code": "GC-ZLCC-UULU-UHUP",
  "amount_str": "50.00",
  "balance_str": "50.00",
  "timestamp": 1783885699
}

Campos da resposta

iduuid
Identificador do vale.
vendor_iduuid
Seller dono do vale. Omitido quando o vale é da loja inteira.
codestring
Código que o cliente digita no checkout, em maiúsculas. Único.
amountinteger
Valor original, em centavos.
balanceinteger
Saldo restante, em centavos.
statusstring
ADF
Letra: A ativo, D desativado, F esgotado (usado até zerar).
recipient_emailstring
E-mail de quem recebe o vale.
recipient_namestring
Nome de quem recebe.
from_namestring
Nome de quem presenteia.
messagestring
Mensagem do presente.
created_byuuid
Administrador que emitiu. Omitido se desconhecido.
used_atstring
Primeiro uso. Omitido se nunca usado.
expires_atstring
Validade, RFC 3339. Omitido se não expira.
created_atstring
Emissão.
updated_atstring
Última alteração.
gift_cert_iduuid
Cópia de id, para clientes da plataforma antiga.
gift_cert_codestring
Cópia de code, para clientes da plataforma antiga.
amount_strstring
amount como texto decimal ("50.00").
balance_strstring
balance como texto decimal.
timestampinteger
created_at em segundos Unix.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"gift-certificates"} / {"error":"insufficient privileges","required":"manage_promotions"}
404Vale inexistente{"error":"gift certificate not found"}
500id que não é UUID ou falha interna{"error":"failed to get gift certificate","detail":"..."}

Emitir um vale

Emite um vale com o valor e o saldo iguais. O cliente usa o código no checkout e o saldo vai baixando a cada compra. Um vale da loja inteira vale para qualquer item; um vale de um seller (vendor_id) só abate os itens daquele seller.

POST/api/v1/admin/gift-certificatesAdmin

Emite um vale-presente

Autenticação: Authorization: Bearer <token> de um administrador. Requer os módulos promotions e gift-certificates ativos. Leitura: view_promotions, view_gift_certificates (ou os equivalentes manage_). Escrita: manage_gift_certificates ou manage_promotions.

Corpo da requisição

amountintegerobrigatório
Valor do vale, em centavos, maior que zero.
codestring
Código desejado. Removidos os espaços e posto em maiúsculas. Se omitido, a plataforma gera um no formato GC-XXXX-XXXX-XXXX. Já existente: erro.
recipient_emailstring
E-mail de quem recebe.
recipient_namestring
Nome de quem recebe.
from_namestring
Nome de quem presenteia.
messagestring
Mensagem do presente.
expires_atstring
Validade, RFC 3339 (2027-01-31T23:59:59-03:00). Omitido: não expira.
vendor_iduuid
Limita o vale a um seller. Omitido: vale para a loja inteira.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/gift-certificates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "recipient_email": "ana.souza@example.com",
    "recipient_name": "Ana Souza",
    "from_name": "Equipe da Loja",
    "message": "Feliz aniversário!",
    "expires_at": "2027-01-31T23:59:59-03:00"
  }'

Resposta

201Vale emitido
json
{
  "id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
  "code": "GC-ZLCC-UULU-UHUP",
  "amount": 5000,
  "balance": 5000,
  "status": "A",
  "recipient_email": "ana.souza@example.com",
  "recipient_name": "Ana Souza",
  "from_name": "Equipe da Loja",
  "message": "Feliz aniversário!",
  "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
  "created_at": "2026-07-12T19:48:19.102787Z",
  "updated_at": "2026-07-12T19:50:21.081224Z",
  "gift_cert_id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
  "gift_cert_code": "GC-ZLCC-UULU-UHUP",
  "amount_str": "50.00",
  "balance_str": "50.00",
  "timestamp": 1783885699
}

Campos da resposta

iduuid
Identificador do vale.
vendor_iduuid
Seller dono do vale. Omitido quando o vale é da loja inteira.
codestring
Código que o cliente digita no checkout, em maiúsculas. Único.
amountinteger
Valor original, em centavos.
balanceinteger
Saldo restante, em centavos.
statusstring
ADF
Letra: A ativo, D desativado, F esgotado (usado até zerar).
recipient_emailstring
E-mail de quem recebe o vale.
recipient_namestring
Nome de quem recebe.
from_namestring
Nome de quem presenteia.
messagestring
Mensagem do presente.
created_byuuid
Administrador que emitiu. Omitido se desconhecido.
used_atstring
Primeiro uso. Omitido se nunca usado.
expires_atstring
Validade, RFC 3339. Omitido se não expira.
created_atstring
Emissão.
updated_atstring
Última alteração.
gift_cert_iduuid
Cópia de id, para clientes da plataforma antiga.
gift_cert_codestring
Cópia de code, para clientes da plataforma antiga.
amount_strstring
amount como texto decimal ("50.00").
balance_strstring
balance como texto decimal.
timestampinteger
created_at em segundos Unix.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"gift-certificates"} / {"error":"insufficient privileges","required":"manage_promotions"}
400Corpo inválido ou amount menor ou igual a zero (a mensagem diz amount_bps, mas o campo é amount){"error":"amount_bps must be positive"}
500Código já existente, vendor_id inválido ou falha ao gravar{"error":"failed to create gift certificate","detail":"..."}
O valor é em centavos

amount: 5000 é um vale de R$ 50,00, não de R$ 5.000,00. O servidor não manda o vale por e-mail: a entrega ao destinatário é com você.

Veja também

  • Alterar, desativar e histórico
  • Visão geral dos vales
Anterior
Vales-presente
Próxima
Alterar, desativar e histórico
Nesta página
  • Listar vales
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um vale
  • Exemplo de requisição
  • Resposta
  • Erros
  • Emitir um vale
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também