Tarjetas de regalo
Si el comercio vende , tu tienda en línea puede consultar su saldo y aceptarlas como pago en las ventas que registra por la API.
| Endpoint | Permiso |
|---|---|
GET /gift-cards/{code} | gift_cards:redeem |
POST /orders con giftCardCode | gift_cards:redeem y el permiso del tipo de venta (orders:write o layaways:write) |
En el panel, el permiso se llama Cobrar con tarjeta de regalo.
Los códigos que acepta la API
La API solo acepta los códigos de 16 caracteres que genera Zenci al emitir la tarjeta, como 7K3M-9QPX-2D4F-H8RT. Los guiones y los espacios se ignoran, y no importa si el cliente lo escribe en mayúsculas o en minúsculas.
Un código corto impreso o cualquier otro formato responde igual que un código que no existe: 404. Así nadie puede distinguir un código mal escrito de uno que no es del comercio.
Límite de intentos
Como el código es lo único que protege el saldo, cada clave tiene 10 intentos por minuto con tarjetas de regalo. Cuentan juntos las consultas de saldo y las ventas pagadas con tarjeta de regalo. Al superarlo, la respuesta es 429 con code: "rate_limited" (Too many gift card attempts for this API key. Retry in a minute.).
Ese límite es aparte del general de 600 peticiones por minuto de la .
Consultar el saldo
GET /gift-cards/{code}curl https://api.zenci.app/public/v1/gift-cards/7K3M9QPX2D4FH8RT \
-H "Authorization: Bearer $ZENCI_API_KEY"{
"code": "••••H8RT",
"status": "active",
"spendable": true,
"balance": "25.00",
"currency": "PAB",
"expiresAt": "2027-06-30T04:59:59.000Z"
}| Campo | Descripción |
|---|---|
code | El código enmascarado: solo los últimos 4 caracteres |
status | issued, active, depleted (sin saldo), blocked, voided (anulada) o expired (vencida) |
spendable | true si se puede pagar con ella ahora: activa, con saldo y sin vencer |
balance | Saldo disponible |
currency | Moneda del saldo |
expiresAt | Fecha de vencimiento, o null si no vence |
Usa spendable para decidir si ofreces la tarjeta como pago. El saldo puede cambiar entre la consulta y la venta, porque el cliente también puede usarla en la tienda física.
Pagar con una tarjeta de regalo
- Busca en la forma de pago de tarjeta de regalo (
kind: "gift_card"). Solo aparece si tu clave tienegift_cards:redeem. - Agrega un pago con ese
paymentMethodId, el monto que se cubre con la tarjeta y el código engiftCardCode.
{
"items": [
{ "sku": "MB-029-CRU-38", "quantity": "1" }
],
"payments": [
{
"paymentMethodId": "m9g3h7j1k5l8z2x6c0v4b8n2",
"amount": "25.00",
"giftCardCode": "7K3M-9QPX-2D4F-H8RT"
},
{ "paymentMethodId": "m7q1w5e9r3t6y0u4i8o2p6a0", "amount": "13.52" }
]
}- El monto tiene que ser exacto. La tarjeta de regalo no da vuelto: si el saldo no alcanza para todo, cubre el resto con otra forma de pago, como en el ejemplo.
- Cada tarjeta va una sola vez por venta. La misma tarjeta en dos pagos se rechaza con
400. giftCardCodesolo va con la forma de pago de tarjeta de regalo, y esa forma de pago siempre lo necesita. Si falta uno de los dos, la respuesta es400(giftCardCode goes only with the gift card payment method, and that method needs giftCardCode.).- Sirve en una venta (
type: "sale") y en el abono inicial de un apartado (type: "layaway"). Los abonos posteriores con no aceptan tarjeta de regalo.
En la factura electrónica, el pago con tarjeta de regalo se declara a la DGI con la forma de pago 07 «Tarjeta de Regalo».
Errores
| HTTP | code | Causa |
|---|---|---|
400 | validation_error | Un código con otro formato en POST /orders (Only the 16-character gift card codes generated by the system are accepted through the API), la misma tarjeta dos veces en la venta, o giftCardCode sin la forma de pago de tarjeta de regalo |
403 | forbidden | La clave no tiene gift_cards:redeem (This API key cannot charge gift cards…) |
404 | not_found | No hay ninguna tarjeta con ese código (No gift card with that code) |
409 | conflict | La tarjeta no tiene saldo suficiente, o está bloqueada, anulada o vencida |
429 | rate_limited | Más de 10 intentos con tarjetas de regalo en un minuto |
Si la tarjeta no alcanza o no se puede usar, la venta se rechaza: vuelve a consultar el saldo y pide otra forma de pago.
Siguientes pasos
- — Registra la venta con sus pagos.
- — Cómo las emite y administra el comercio.