Punto de venta

El caso es siempre el mismo: se cierra una venta en tu sistema de cobro, el cliente está identificado, y esa compra tiene que sumar en su tarjeta de fidelidad sin que nadie toque un botón extra. Esta página es cómo se hace.

Las dos vías

Dardo expone dos caminos distintos para acreditar una compra desde un sistema externo. No son intercambiables: usan autenticación diferente, modelos de datos diferentes y unidades diferentes.

Vía A — el grupo "Punto de venta"

Es la vía diseñada explícitamente para esto. La descripción de accrue lo dice: realiza una acción de acumulación sobre una compra; se requiere el teléfono, el mail o el número de serie de la tarjeta del cliente para encontrar o registrar una tarjeta de fidelidad. Y el objeto Check que recibe tiene campos que solo tienen sentido en un salón: propina, servicio, hora de apertura y de cierre de la mesa.

POST /api/v2/marketplace/resolve-credentials

Dado cualquiera de los credenciales de una instalación, te devuelve el paquete completo. El caso de uso que da la especificación: en el webhook de un servicio, o a nivel de la aplicación, puede que solo tengas el identificador del comercio y necesites obtener el token de la API.

curl -X POST 'https://api.dardo.ai/api/v2/marketplace/resolve-credentials' \
  -H 'X-App-Token: EL_TOKEN_DE_TU_APP' \
  -H 'Content-Type: application/json' \
  -d '{
    "names": ["apiToken", "companyId"],
    "credentials": [
      { "name": "merchantId", "value": "resto-centro-001" }
    ]
  }'

Responde con credentials, el mismo formato de pares name / value.

POST /api/v2/marketplace/accrue

El endpoint central de la vía.

* Ninguno de los tres figura como obligatorio en el esquema, pero la descripción de la operación dice que uno de los tres es necesario para encontrar o registrar la tarjeta. La validación la hace el servidor.

El objeto Check

Los dos últimos son campos de paso: la especificación aclara que se almacenan como dato crudo. No los uses para calcular nada.

Cada elemento de selections es un Selection:

id y groupId son lo que habilita reglas del tipo "esta promoción suma doble" o "el delivery no acumula". Sin ellos, el ticket entero se trata como un monto plano.

curl -X POST 'https://api.dardo.ai/api/v2/marketplace/accrue' \
  -H 'X-App-Token: EL_TOKEN_DE_TU_APP' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionId": "pos-2026-09-07-004512",
    "phone": "+5491168421793",
    "firstName": "Marina",
    "lastName": "Ferreyra",
    "credentials": [
      { "name": "merchantId", "value": "resto-centro-001" }
    ],
    "check": {
      "amount": 1875000,
      "currency": "ARS",
      "taxAmount": 325413,
      "tipAmount": 187500,
      "discountAmount": 0,
      "serviceAmount": 0,
      "externalTransactionId": "TCK-889231",
      "checkOpenedAt": "2026-09-07T21:14:02-03:00",
      "checkClosedAt": "2026-09-07T22:47:38-03:00",
      "selections": [
        {
          "id": "SKU-MILA-NAP",
          "groupId": "GRP-PRINCIPALES",
          "displayName": "Milanesa napolitana",
          "price": 745000,
          "quantity": 2,
          "totalPrice": 1490000
        },
        {
          "id": "SKU-MALBEC-750",
          "groupId": "GRP-BEBIDAS",
          "displayName": "Malbec 750ml",
          "price": 385000,
          "quantity": 1,
          "totalPrice": 385000
        }
      ]
    }
  }'

Ese ticket es de $18.750,00 con $1.875,00 de propina. Mirá los ceros: eso es lo que significa "centavos".

La respuesta trae el transactionId que mandaste y un array results, con un resultado por cada tarjeta afectada. Cada uno incluye isSuccess, errorMessage, serialNumber, checkAmount, accrualAmount, accruedValue, operationId, createdAt y reversedAt.

POST /api/v2/marketplace/reverse

Revierte una acumulación previa usando su transactionId. Es lo que usás cuando se anula un ticket ya cerrado.

curl -X POST 'https://api.dardo.ai/api/v2/marketplace/reverse' \
  -H 'X-App-Token: EL_TOKEN_DE_TU_APP' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionId": "pos-2026-09-07-004512",
    "credentials": [
      { "name": "merchantId", "value": "resto-centro-001" }
    ]
  }'

Devuelve la misma estructura que accrue, con reversedAt cargado en los results.

Errores de la Vía A

Es el único grupo de la API que declara respuestas de error además del 200:

El formato es errors, un array de textos. No es un objeto con código: parsealo en consecuencia.

Vía B — la API estándar

Es la API que ya tenés habilitada con tu clave de plan Business. No requiere ningún alta adicional. El flujo es explícito y en dos pasos: buscás la tarjeta, y operás sobre su id.

Cuál usar

El flujo completo, paso a paso

Escenario: se cierra una mesa con un consumo de $18.750,00. El cliente se identificó con su teléfono.

curl -G 'https://api.dardo.ai/api/v2/cards' \
  -H 'X-API-Key: TU_CLAVE_API' \
  --data-urlencode 'customerPhone=+5491168421793' \
  --data-urlencode 'templateId=1187'

{
  "responseId": "3f1a8b04-6d27-4c9e-9a15-2b8e7c04d913",
  "createdAt": "2026-09-07T22:47:39-03:00",
  "code": 200,
  "meta": { "totalItems": 1, "itemsPerPage": 30, "currentPage": 1 },
  "data": [
    {
      "id": "430556-818-972",
      "companyId": 1842,
      "templateId": 1187,
      "customerId": "9c4e1f80-5a3b-4d72-8e16-7f2a9b350c48",
      "type": "reward",
      "status": "active",
      "customer": {
        "id": "9c4e1f80-5a3b-4d72-8e16-7f2a9b350c48",
        "phone": "+5491168421793",
        "email": "marina.ferreyra@gmail.com",
        "firstName": "Marina",
        "surname": "Ferreyra",
        "externalUserId": "POS-CLI-4471",
        "segments": []
      },
      "balance": {
        "balance": 340.0,
        "numberRewardsUnused": 0,
        "numberStampsTotal": null,
        "stampsBeforeReward": null
      },
      "availableRewardTiers": [],
      "installLink": "https://...",
      "createdAt": "2026-03-14T19:02:11-03:00"
    }
  ]
}

curl -X POST 'https://api.dardo.ai/api/v2/cards/430556-818-972/add-purchase' \
  -H 'X-API-Key: TU_CLAVE_API' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 18750.00,
    "comment": "Ticket TCK-889231 - mesa 12 - sucursal Centro"
  }'

{
  "responseId": "b72d5e91-0c48-4a36-bf19-6d3e8a17c250",
  "createdAt": "2026-09-07T22:47:41-03:00",
  "code": 200,
  "data": {
    "id": "430556-818-972",
    "templateId": 1187,
    "customerId": "9c4e1f80-5a3b-4d72-8e16-7f2a9b350c48",
    "type": "reward",
    "balance": {
      "balance": 527.5,
      "numberRewardsUnused": 1,
      "stampsBeforeReward": null
    },
    "updatedAt": "2026-09-07T22:47:41-03:00"
  }
}

curl -G 'https://api.dardo.ai/api/v2/operations' \
  -H 'X-API-Key: TU_CLAVE_API' \
  --data-urlencode 'cardId=430556-818-972' \
  --data-urlencode 'startDate=2026-09-07' \
  --data-urlencode 'endDate=2026-09-07'

Límites de monto

La especificación declara techos en dos de los campos de acumulación, y en el resto no declara ninguno:

Idempotencia: no existe

Con lo que hay hoy, la deduplicación es responsabilidad tuya. El patrón defensivo:

1. Llevá una tabla local de pendientes. Cada acreditación se registra con el número de ticket de tu sistema como clave y un estado: pendiente, enviada, confirmada, fallida.
2. Nunca reintentes a ciegas. Ante un tiempo de espera agotado, consultá primero GET /api/v2/operations filtrando por cardId y por la fecha de hoy, y buscá tu número de ticket en el campo comment antes de reenviar.
3. Escribí el número de ticket en comment siempre. Es el único campo de texto libre disponible y es lo único que hace posible el chequeo del punto 2. Tené en cuenta que GET /api/v2/operations no filtra por comment: vas a tener que traer las operaciones del día de esa tarjeta y buscar del lado tuyo.
4. Backoff exponencial y cola, nunca reintento inmediato en un bucle.
5. Conciliación nocturna contra GET /api/v2/operations para detectar duplicados o faltantes que se hayan colado igual.

La Vía A está mejor parada en este punto: AccrueInput.transactionId es obligatorio y es la llave que usa reverse, y Check.externalTransactionId está descripto como el identificador de transacción externo del sistema de punto de venta. Que el transactionId sea la llave de reversa sugiere que el servidor lo persiste e indexa. Aun así, la especificación no declara qué pasa si mandás dos accrue con el mismo transactionId, así que tampoco ahí podemos prometerte idempotencia por escrito.

Sucursales

El campo locationId aparece en cuatro lugares de la especificación, y la dirección importa:

Es decir: el único lugar donde locationId se puede escribir es el alta o la edición de un gerente. Ninguno de los endpoints de acumulación lo acepta en el cuerpo del pedido, ni los de la Vía B ni accrue en la Vía A —ni en la raíz ni dentro del Check—.

En el flujo normal eso funciona solo: quien escanea desde la app está logueado como gerente de su sucursal, y la operación queda asociada a esa sucursal. Pero una integración que se autentica con la clave API no tiene gerente: la clave es de la cuenta, no de una persona ni de un local.

Qué hacer mientras tanto: poné el identificador de sucursal en el comment de cada acreditación, con un formato estable, por ejemplo "CENTRO | TCK-889231". No es consultable por filtro y no alimenta ninguna métrica nativa, pero el dato queda registrado y lo podés extraer después con GET /api/v2/operations.

Y escribinos a soporte@dardo.ai antes de arrancar si tenés varias sucursales. Es una decisión de arquitectura que conviene resolver al principio, no después de seis meses de operaciones sin sucursal asignada.

purchaseSum

purchaseSum es un campo opcional que aceptan prácticamente todos los endpoints de acumulación de la Vía B: los add-... y subtract-... de monto, puntos, sellos, visitas, puntajes y premios, además de add-purchase y receive-reward. Está declarado como número decimal y admite nulo.

Del otro lado, Operation.purchaseSum figura como campo obligatorio en la salida: se persiste en cada operación. O sea, es el campo con el que le contás a Dardo cuánta plata movió una operación, más allá de cuántos puntos o sellos otorgó.

Dónde se nota: en un canje. Cuando un cliente usa un beneficio, la operación resta sellos o premios pero no declara por sí sola cuánto valía lo que se llevó. purchaseSum es donde lo informás.

curl -X POST 'https://api.dardo.ai/api/v2/cards/430556-818-972/subtract-reward' \
  -H 'X-API-Key: TU_CLAVE_API' \
  -H 'Content-Type: application/json' \
  -d '{
    "rewards": 1,
    "comment": "Canje: postre de cortesia - ticket TCK-889244",
    "purchaseSum": 4200.00
  }'

¿Ya hay un conector para tu sistema?

Antes de escribir código, vale la pena mirar si tu sistema de cobro ya tiene un conector nativo. Eso no está en la especificación —es información de tu cuenta, en vivo— y se consulta con una sola llamada:

curl 'https://api.dardo.ai/api/v2/external-services' \
  -H 'X-API-Key: TU_CLAVE_API'

Ese endpoint lista los servicios externos disponibles para tu cuenta, las claves que cada uno requiere para conectarse, y si ya está conectado. Los otros tres del mismo grupo son GET /api/v2/external-services/{code} para ver el estado de uno puntual, PUT para conectarlo o actualizarlo, y DELETE para desconectarlo.

Antes de dar fecha de entrega

• Confirmá el templateId de tu tarjeta de fidelidad con GET /api/v2/templates.
• Confirmá el type de esa tarjeta: determina qué endpoint de acumulación usar. Ver Tipos de tarjeta.
• Probá contra una tarjeta inactiva antes de tocar tu programa real.
• Escribí el número de ticket en comment en todas las llamadas. Es tu única vía de deduplicación.
• Implementá la tabla de pendientes, el backoff y la conciliación nocturna antes de salir a producción, no después del primer duplicado.
• Si tenés varias sucursales, resolvé el tema de locationId con soporte primero.
• Confirmá la unidad de purchaseSum con soporte antes de mandarlo.

Ver también