Skip to content

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.

EndpointPermiso
GET /gift-cards/{code}gift_cards:redeem
POST /orders con giftCardCodegift_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 ​

http
GET /gift-cards/{code}
bash
curl https://api.zenci.app/public/v1/gift-cards/7K3M9QPX2D4FH8RT \
  -H "Authorization: Bearer $ZENCI_API_KEY"
json
{
  "code": "••••H8RT",
  "status": "active",
  "spendable": true,
  "balance": "25.00",
  "currency": "PAB",
  "expiresAt": "2027-06-30T04:59:59.000Z"
}
CampoDescripción
codeEl código enmascarado: solo los últimos 4 caracteres
statusissued, active, depleted (sin saldo), blocked, voided (anulada) o expired (vencida)
spendabletrue si se puede pagar con ella ahora: activa, con saldo y sin vencer
balanceSaldo disponible
currencyMoneda del saldo
expiresAtFecha 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 ​

  1. Busca en la forma de pago de tarjeta de regalo (kind: "gift_card"). Solo aparece si tu clave tiene gift_cards:redeem.
  2. Agrega un pago con ese paymentMethodId, el monto que se cubre con la tarjeta y el código en giftCardCode.
json
{
  "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.
  • giftCardCode solo 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 es 400 (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 ​

HTTPcodeCausa
400validation_errorUn 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
403forbiddenLa clave no tiene gift_cards:redeem (This API key cannot charge gift cards…)
404not_foundNo hay ninguna tarjeta con ese código (No gift card with that code)
409conflictLa tarjeta no tiene saldo suficiente, o está bloqueada, anulada o vencida
429rate_limitedMá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.

Documentación oficial de Zelta