Tipos de tarjeta y qué operación usar

El grupo cards de la API tiene 23 operaciones, y varias hacen cosas parecidas con nombres parecidos: add-stamp, add-point, add-scores, add-visit, add-purchase. Cuál corresponde depende del tipo de tarjeta contra el que estás llamando.

Elegir mal no da error de validación: da un programa de lealtad que acredita lo que no corresponde. Por eso esta página existe.

El id de la ruta es el número de serie de la tarjeta, no el id de la plantilla ni el del cliente. Lo devuelve GET /api/v2/cards en el campo id, con el formato 430556-818-972.

Los ocho tipos

Los nombres son los del selector de app.dardo.ai/cards/create, tal cual aparecen en pantalla.

Tipo	Para qué sirve
Estampilla	Sellos hasta llegar a un premio. El clásico "comprá 9, el 10 va de regalo". Ver tarjeta de estampilla
Premio	Programa de puntos con una escalera de niveles de recompensa. Ver tarjeta de premio
Afiliación	Club de socios con niveles y cobro recurrente. Es el único tipo que cobra dinero de forma nativa. Ver tarjeta de afiliación
Descuento	Porcentaje de descuento que sube por niveles según el gasto acumulado. Ver tarjeta de descuento
Devolución de dinero	Devuelve un porcentaje de cada compra como saldo, también por niveles de gasto. Ver devolución de dinero
Cupón	Beneficio de un solo uso para captar al cliente nuevo. Al canjearse puede transformarse en otra tarjeta. Ver cupón
Suscripción	Paquete de visitas prepagas que se descuentan por uso. No cobra de forma recurrente — eso es Afiliación. Ver tarjeta de suscripción
Tarjeta de regalo	Saldo monetario prepago que un cliente le regala a otro. Ver tarjeta de regalo

La matriz: qué operación usar en cada tipo

Leé la columna "Base" antes de usar la fila. El spec de la API no declara a qué tipo aplica cada operación: ninguna de las 23 tiene una descripción que lo diga. Lo que está marcado como inferencia es una lectura razonada del modelo de datos y de la mecánica del producto, no una afirmación de la API.

Tipo	Acreditar	Canjear o descontar	Base
Estampilla	`add-stamp`	`subtract-stamp` · `receive-reward`	Respaldado: el saldo devuelve `numberStampsTotal` y `stampsBeforeReward`
Premio	`add-point` o `add-scores`	`receive-reward`	Respaldado para el canje: `receive-reward` recibe un `id` que sale de `availableRewardTiers`. La acreditación, inferencia
Afiliación	`set-membership-tier`	—	Respaldado: el cuerpo pide `tierId`, `period` (`day`/`week`/`month`/`year`) y `autoRenewal`, que son exactamente los niveles y períodos de este tipo
Descuento	`add-purchase`	—	Inferencia: el porcentaje lo calcula la tarjeta según el gasto acumulado, no se acredita a mano
Devolución de dinero	`add-purchase` para registrar el gasto · `add-point` o `add-scores` para el saldo devuelto	`subtract-point` o `subtract-scores`	Inferencia
Cupón	— (nace con su valor)	`redeem-coupon`	Respaldado: la tarjeta expone `couponRedeemed`, y hay un evento de webhook `couponRedeemed`
Suscripción	`add-stamp` o `add-visit`	`subtract-visit` o `subtract-stamp`	Inferencia: por dentro este tipo se configura con vocabulario de sellos, y el saldo devuelve `currentNumberOfUses`
Tarjeta de regalo	`add-transaction-amount`	`subtract-transaction-amount`	Inferencia: es el único tipo con saldo monetario

Cada operación de acreditar tiene su espejo para restar: subtract-stamp, subtract-point, subtract-scores, subtract-visit, subtract-purchase, subtract-reward, subtract-transaction-amount. Sirven para corregir una carga equivocada.

Lo que no pudimos confirmar

add-point y add-scores hacen cosas distintas y el spec no dice cuál es cuál. La única diferencia visible es el tipo de dato: points acepta decimales, scores es un entero. El saldo de la tarjeta devuelve dos contadores compatibles con esa distinción —balance (decimal) y bonusBalance (entero)— pero nada en la especificación los vincula.

Lo mismo pasa con add-visit frente a add-purchase: ambos podrían disparar la regla de acumulación de la tarjeta, y el spec no lo aclara.

Si tu integración acredita saldo real, confirmá el par correcto antes de salir a producción: escribinos a soporte@dardo.ai con el tipo de tarjeta y el templateId, y te decimos cuál corresponde. Probar contra una tarjeta sin activar es la otra forma de resolverlo: se pueden emitir hasta 10 tarjetas antes de activarla, y el saldo se lee con GET /api/v2/cards/{id} después de cada llamada.

`add-reward` y `subtract-reward`

Ajustan la cantidad de recompensas disponibles sin tocar los sellos ni los puntos que las generaron —el saldo lo expone como numberRewardsUnused—. Aplican a los tipos que tienen recompensas: Estampilla y Premio. (Inferencia.)

Operaciones que aplican a cualquier tipo

Estas seis no dependen del tipo de tarjeta:

Operación	Qué hace
`GET /api/v2/cards`	Lista las tarjetas emitidas
`POST /api/v2/cards`	Emite una tarjeta. Requiere `templateId` y `customerId`
`GET /api/v2/cards/{id}`	Trae una tarjeta por su número de serie
`PATCH /api/v2/cards/{id}`	Edita los `customFields` de la tarjeta
`DELETE /api/v2/cards/{id}`	Borra la tarjeta
`POST /api/v2/cards/{id}/set-expiration-date`	Fija el vencimiento. Los ocho tipos tienen fecha de vencimiento de la tarjeta

Los dos campos que casi siempre conviene mandar

Todas las operaciones de acreditar y descontar aceptan dos campos opcionales además del valor:

{
  "stamps": 1,
  "purchaseSum": 4500,
  "comment": "Mostrador - turno tarde"
}

purchaseSum es el monto de la compra. Queda en el historial y se consulta después en GET /api/v2/operations. En los ajustes de la tarjeta, Cantidad de compra al cobrar viene activado por defecto, así que mandalo siempre salvo que lo hayas desactivado a propósito.
comment es texto libre. El ajuste Comentar al acumular viene desactivado; si lo activás, conviene que tu integración lo complete.

Los nombres en inglés no coinciden con el panel

Cuando creás plantillas por API, el campo type usa valores en inglés que no son la traducción del rótulo que ves en pantalla. Esta equivalencia está verificada contra la plataforma:

Rótulo en el panel	`type` en la API
Estampilla	`stamp`
Premio	`reward`
Afiliación	`membership`
Descuento	`discount`
Devolución de dinero	`cashback`
Cupón	`coupon`
Suscripción	`subscription`
Tarjeta de regalo	`certificate`

Tres de esos valores confunden si los leés literal:

membership es Afiliación, el tipo que cobra suscripciones recurrentes.
subscription es Suscripción, que a pesar del nombre no cobra nada de forma recurrente: es un paquete de visitas prepagas.
certificate es Tarjeta de regalo, no un certificado de ningún tipo.

Hay un cuarto caso, en la respuesta y no en el pedido: el objeto customerSubscription de una tarjeta trae un membershipTierId, así que corresponde a Afiliación y no al tipo Suscripción. (Inferencia, apoyada en ese campo.)

Antes de escribir el código

Varios ajustes se congelan al activar la tarjeta, y no se pueden volver atrás. El formulario de emisión —qué datos le pedís al cliente— es uno de ellos en los ocho tipos, y es justo lo que tu integración va a llenar. Definilo antes de activar. Ver qué queda cerrado al activar.

El detalle de cada una de las 23 operaciones, con su cuerpo y sus respuestas, está en la referencia de Tarjetas.

Tipos de tarjeta y qué operación usar

On this page