VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Cupons, vales, pagamentos e NF-e

Vales-presente do seller

Emite e gerencia vales-presente cujo saldo vale apenas nos produtos do seller.

Mesmo modelo dos cupons, mas com saldo: o cliente pode usar parte do valor numa compra e o resto em outra. O vale emitido pelo seller só abate itens do próprio seller.

Dinheiro em centavos

amount e balance são centavos. Os campos amount_str e balance_str repetem o valor como texto decimal por compatibilidade.

Status em letra

Você envia o nome, a resposta devolve a letra: "disabled" vira "D".

Listar vales-presente

Um vale-presente é um crédito pré-pago em um código. O cliente usa o saldo em compras e o desconto recai só nos itens deste seller. Lista todos os vales do seller, sem paginação.

GET/api/v1/vendor/gift-certificatesSeller

Vales-presente do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/gift-certificates" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vales
json
{
  "certificates": [
    {
      "id": "f3c86a45-22ea-45b4-b246-0c2e90607c56",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "code": "GC-2U7B-PA9Z-KTAD",
      "amount": 20000,
      "balance": 17000,
      "status": "A",
      "recipient_email": "ana.lima@example.com",
      "recipient_name": "Ana Lima",
      "from_name": "Loja Exemplo",
      "message": "Parabéns!",
      "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
      "used_at": "2026-10-12T20:02:59Z",
      "expires_at": "2027-10-01T00:00:00Z",
      "created_at": "2026-10-11T23:59:23Z",
      "updated_at": "2026-10-12T20:02:59Z",
      "gift_cert_id": "f3c86a45-22ea-45b4-b246-0c2e90607c56",
      "gift_cert_code": "GC-2U7B-PA9Z-KTAD",
      "amount_str": "200.00",
      "balance_str": "170.00",
      "timestamp": 1783814363
    }
  ],
  "total": 1
}

Campos da resposta

certificatesobject[]

Vales.

iduuid
Id do vale.
vendor_iduuid
Seller dono. Sempre o seu.
codestring
Código de resgate, em maiúsculas, único. Gerado no formato GC-XXXX-XXXX-XXXX se não enviado.
amountinteger
Valor original, em centavos.
balanceinteger
Saldo restante, em centavos. Diminui a cada uso.
statusstring
ADEF
Letra: A ativo, D desativado, E expirado, F esgotado (usado).
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
Usuário que criou. Omitido se desconhecido.
used_atstring
Primeiro uso, RFC 3339. Omitido se nunca usado.
expires_atstring
Validade, RFC 3339. Omitido = não expira.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
gift_cert_id, gift_cert_code, amount_str, balance_str, timestampmixed
Campos de compatibilidade com a API antiga (id e código repetidos, valores como texto decimal "200.00" e um carimbo Unix). Não use em integrações novas.
totalinteger
Quantidade.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Criar vale-presente

Emite um vale com saldo igual ao valor. Nasce A (ativo). Esta rota não cobra nada de ninguém: é o seller que emite o crédito. Não há envio de e-mail pela API.

POST/api/v1/vendor/gift-certificatesSeller

Emitir um vale-presente

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

amountintegerobrigatório
Valor em centavos. Maior que zero.
codestring
Código desejado. Vazio gera um. Convertido para maiúsculas.
recipient_emailstring
E-mail de quem recebe.
recipient_namestring
Nome de quem recebe.
from_namestring
Nome de quem presenteia.
messagestring
Mensagem.
expires_atstring
Validade, RFC 3339.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/gift-certificates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 20000,
  "recipient_email": "ana.lima@example.com",
  "recipient_name": "Ana Lima",
  "from_name": "Loja Exemplo",
  "message": "Parabéns!",
  "expires_at": "2027-10-01T00:00:00Z"
}'

Resposta

201Vale emitido
json
{
  "id": "f3c86a45-22ea-45b4-b246-0c2e90607c56",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "code": "GC-2U7B-PA9Z-KTAD",
  "amount": 20000,
  "balance": 17000,
  "status": "A",
  "recipient_email": "ana.lima@example.com",
  "recipient_name": "Ana Lima",
  "from_name": "Loja Exemplo",
  "message": "Parabéns!",
  "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "used_at": "2026-10-12T20:02:59Z",
  "expires_at": "2027-10-01T00:00:00Z",
  "created_at": "2026-10-11T23:59:23Z",
  "updated_at": "2026-10-12T20:02:59Z",
  "gift_cert_id": "f3c86a45-22ea-45b4-b246-0c2e90607c56",
  "gift_cert_code": "GC-2U7B-PA9Z-KTAD",
  "amount_str": "200.00",
  "balance_str": "170.00",
  "timestamp": 1783814363
}

Campos da resposta

iduuid
Id do vale.
vendor_iduuid
Seller dono. Sempre o seu.
codestring
Código de resgate, em maiúsculas, único. Gerado no formato GC-XXXX-XXXX-XXXX se não enviado.
amountinteger
Valor original, em centavos.
balanceinteger
Saldo restante, em centavos. Diminui a cada uso.
statusstring
ADEF
Letra: A ativo, D desativado, E expirado, F esgotado (usado).
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
Usuário que criou. Omitido se desconhecido.
used_atstring
Primeiro uso, RFC 3339. Omitido se nunca usado.
expires_atstring
Validade, RFC 3339. Omitido = não expira.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
gift_cert_id, gift_cert_code, amount_str, balance_str, timestampmixed
Campos de compatibilidade com a API antiga (id e código repetidos, valores como texto decimal "200.00" e um carimbo Unix). Não use em integrações novas.

Erros

StatusQuandoCorpo de exemplo
400JSON inválido ou amount menor ou igual a zero.{"error":"amount must be positive"}
500Falha ao gravar, inclusive quando o code já existe (hoje não vira 400).{"error":"failed to create gift certificate","detail":"..."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Ver vale-presente

Devolve um vale do seller.

GET/api/v1/vendor/gift-certificates/{id}Seller

Detalhe de um vale-presente

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id do vale-presente.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/gift-certificates/f3c86a45-22ea-45b4-b246-0c2e90607c56" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vale
json
{
  "id": "f3c86a45-22ea-45b4-b246-0c2e90607c56",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "code": "GC-2U7B-PA9Z-KTAD",
  "amount": 20000,
  "balance": 17000,
  "status": "A",
  "recipient_email": "ana.lima@example.com",
  "recipient_name": "Ana Lima",
  "from_name": "Loja Exemplo",
  "message": "Parabéns!",
  "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "used_at": "2026-10-12T20:02:59Z",
  "expires_at": "2027-10-01T00:00:00Z",
  "created_at": "2026-10-11T23:59:23Z",
  "updated_at": "2026-10-12T20:02:59Z",
  "gift_cert_id": "f3c86a45-22ea-45b4-b246-0c2e90607c56",
  "gift_cert_code": "GC-2U7B-PA9Z-KTAD",
  "amount_str": "200.00",
  "balance_str": "170.00",
  "timestamp": 1783814363
}

Campos da resposta

iduuid
Id do vale.
vendor_iduuid
Seller dono. Sempre o seu.
codestring
Código de resgate, em maiúsculas, único. Gerado no formato GC-XXXX-XXXX-XXXX se não enviado.
amountinteger
Valor original, em centavos.
balanceinteger
Saldo restante, em centavos. Diminui a cada uso.
statusstring
ADEF
Letra: A ativo, D desativado, E expirado, F esgotado (usado).
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
Usuário que criou. Omitido se desconhecido.
used_atstring
Primeiro uso, RFC 3339. Omitido se nunca usado.
expires_atstring
Validade, RFC 3339. Omitido = não expira.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
gift_cert_id, gift_cert_code, amount_str, balance_str, timestampmixed
Campos de compatibilidade com a API antiga (id e código repetidos, valores como texto decimal "200.00" e um carimbo Unix). Não use em integrações novas.

Erros

StatusQuandoCorpo de exemplo
404O vale não existe ou não é do seller.{"error":"gift certificate not found"}
500id não é um UUID válido (hoje 500, a mensagem está em detail).{"error":"failed to get gift certificate","detail":"o valor \"xyz\" não é um uuid válido..."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Atualizar vale-presente

Altera só os campos enviados: situação, dados do presente e validade. Não dá para mudar o valor nem o saldo. Para cancelar um vale, mande status: "disabled". Corpo sem nenhum campo conhecido é recusado.

PUT/api/v1/vendor/gift-certificates/{id}Seller

Alterar dados ou situação do vale

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id do vale-presente.

Corpo da requisição

statusstring
activedisabledexpiredusedADEF
Nova situação. Aceita o nome ou a letra; used vira F.
recipient_emailstring
E-mail de quem recebe.
recipient_namestring
Nome de quem recebe.
from_namestring
Nome de quem presenteia.
messagestring
Mensagem.
expires_atstring
Nova validade, RFC 3339.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/gift-certificates/f3c86a45-22ea-45b4-b246-0c2e90607c56" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "disabled"
}'

Resposta

200Vale atualizado
json
{
  "id": "f3c86a45-22ea-45b4-b246-0c2e90607c56",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "code": "GC-2U7B-PA9Z-KTAD",
  "amount": 20000,
  "balance": 17000,
  "status": "D",
  "recipient_email": "ana.lima@example.com",
  "recipient_name": "Ana Lima",
  "from_name": "Loja Exemplo",
  "message": "Parabéns!",
  "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "used_at": "2026-10-12T20:02:59Z",
  "expires_at": "2027-10-01T00:00:00Z",
  "created_at": "2026-10-11T23:59:23Z",
  "updated_at": "2026-10-12T20:02:59Z",
  "gift_cert_id": "f3c86a45-22ea-45b4-b246-0c2e90607c56",
  "gift_cert_code": "GC-2U7B-PA9Z-KTAD",
  "amount_str": "200.00",
  "balance_str": "170.00",
  "timestamp": 1783814363
}

Campos da resposta

iduuid
Id do vale.
vendor_iduuid
Seller dono. Sempre o seu.
codestring
Código de resgate, em maiúsculas, único. Gerado no formato GC-XXXX-XXXX-XXXX se não enviado.
amountinteger
Valor original, em centavos.
balanceinteger
Saldo restante, em centavos. Diminui a cada uso.
statusstring
ADEF
Letra: A ativo, D desativado, E expirado, F esgotado (usado).
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
Usuário que criou. Omitido se desconhecido.
used_atstring
Primeiro uso, RFC 3339. Omitido se nunca usado.
expires_atstring
Validade, RFC 3339. Omitido = não expira.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
gift_cert_id, gift_cert_code, amount_str, balance_str, timestampmixed
Campos de compatibilidade com a API antiga (id e código repetidos, valores como texto decimal "200.00" e um carimbo Unix). Não use em integrações novas.

Erros

StatusQuandoCorpo de exemplo
404O vale não existe ou não é do seller.{"error":"gift certificate not found"}
500Nenhum campo reconhecido para atualizar, ou id malformado. A mensagem fica em detail.{"error":"failed to update gift certificate","detail":"no fields to update"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Excluir vale-presente

Apaga o vale de vez, mesmo com saldo. Para só invalidar, use PUT com status: "disabled".

DELETE/api/v1/vendor/gift-certificates/{id}Seller

Excluir um vale-presente

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id do vale-presente.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/gift-certificates/f3c86a45-22ea-45b4-b246-0c2e90607c56" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vale excluído
json
{
  "message": "gift certificate deleted"
}

Erros

StatusQuandoCorpo de exemplo
404O vale não existe ou não é do seller.{"error":"gift certificate not found"}
500id não é um UUID válido (hoje 500, a mensagem está em detail).{"error":"failed to delete gift certificate","detail":"o valor \"xyz\" não é um uuid válido..."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Veja também

  • Cupons
  • Visão geral
Anterior
Cupons do seller
Próxima
Formas de pagamento do seller
Nesta página
  • Listar vales-presente
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar vale-presente
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver vale-presente
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar vale-presente
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir vale-presente
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também