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

Alterar, desativar e histórico

Altera os dados de um vale, desativa e lista onde ele foi usado.

Depois de emitido, o vale só muda em poucos campos: destinatário, mensagem, validade, estado e dono. O valor e o código ficam fixos.

Alterar um vale

Altera destinatário, mensagem, validade, estado e dono do vale. Só os campos enviados mudam. O valor e o código não podem ser alterados depois da emissão: o vale pode já ter saldo gasto e o código pode já ter circulado.

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

Altera os dados de um vale

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.

Corpo da requisição

statusstring
activedisabledused
active, disabled ou used.
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
Nova validade, RFC 3339.
vendor_iduuid
Passa o vale para outro seller.

Exemplo de requisição

Resposta

200Vale alterado

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 envio de amount, code ou created_by{"error":"immutable_field","detail":"o campo \"amount\" não pode ser alterado por este endpoint: ..."}
500Corpo sem nenhum campo alterável, id inexistente ou que não é UUID{"error":"failed to update gift certificate","detail":"no fields to update"}
Mensagens em português

A explicação do erro immutable_field vem em português no campo detail, como o servidor a devolve. Ela indica o que fazer: desativar o vale e emitir outro.

`status: used` esgota o vale

used grava o estado de esgotado (F), que não zera o saldo. Para encerrar um vale use a rota de desativar, abaixo.

Desativar um vale

Passa o vale para D (desativado) e ele deixa de ser aceito no checkout. O saldo e o histórico permanecem. Não tem corpo.

PUT/api/v1/admin/gift-certificates/{id}/disableAdmin

Desativa 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

Resposta

200Vale desativado

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"}
500Vale inexistente ou id que não é UUID{"error":"failed to disable gift certificate","detail":"gift certificate not found"}

Histórico de uso

Lista cada vez que o vale abateu um pedido, com o valor e a data. Quando o pedido é cancelado ou estornado, o uso é revertido: ganha refunded_at e o valor volta para o saldo.

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

Lista os pedidos em que o vale foi usado

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

Resposta

200Usos devolvidos

Campos da resposta

recordsarray
Usos, do mais recente ao mais antigo.
records[].iduuid
Identificador do uso.
records[].certificate_iduuid
Vale.
records[].order_iduuid
Pedido abatido.
records[].amount_usedinteger
Valor abatido, em centavos.
records[].created_atstring
Quando foi usado.
records[].refunded_atstring | null
Quando o uso foi revertido. null se continua valendo.
records[].log_idstring
Cópia de id, para clientes da plataforma antiga.
records[].gift_cert_iduuid
Cópia de certificate_id.
records[].amount_used_strstring
amount_used como texto decimal.
records[].timestampinteger
created_at em segundos Unix.
totalinteger
Quantidade de usos.

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"}
500id que não é UUID ou falha na consulta{"error":"failed to list usage","detail":"..."}
Vale inexistente devolve lista vazia

Para um UUID que não existe a resposta é 200 com records: [], não 404.

Veja também

  • Emitir e consultar vales
  • Visão geral dos vales
Anterior
Emitir e consultar vales
Próxima
Carteiras de crédito
Nesta página
  • Alterar um vale
  • Exemplo de requisição
  • Resposta
  • Erros
  • Desativar um vale
  • Exemplo de requisição
  • Resposta
  • Erros
  • Histórico de uso
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X PUT "$BASE_URL/api/v1/admin/gift-certificates/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2027-03-31T23:59:59-03:00",
    "message": "Parabéns!"
  }'
bash
curl -X PUT "$BASE_URL/api/v1/admin/gift-certificates/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/disable" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/gift-certificates/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/usage" \
  -H "Authorization: Bearer $TOKEN"
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": "Parabéns!",
  "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
}
json
{
  "id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
  "code": "GC-ZLCC-UULU-UHUP",
  "amount": 5000,
  "balance": 5000,
  "status": "D",
  "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
}
json
{
  "records": [
    {
      "id": "ae831726-ceae-49b4-93f7-3974cf237548",
      "certificate_id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
      "order_id": "00fd1798-7189-4e58-aa9a-af7cfe93221f",
      "amount_used": 5000,
      "created_at": "2026-07-12T19:49:32.506284Z",
      "refunded_at": "2026-07-12T19:50:21.081224Z",
      "log_id": "ae831726-ceae-49b4-93f7-3974cf237548",
      "gift_cert_id": "ffdb1863-1392-48b8-932a-01a79223fd1a",
      "amount_used_str": "50.00",
      "timestamp": 1783885772
    }
  ],
  "total": 1
}