Integración de TPV · API de Digikart

Versión 1 · para proveedores de TPV, integradores y middleware

Esta API permite que un software de TPV envíe cada cobro a Digikart: la tarjeta de fidelización Apple Wallet / Google Wallet del cliente se abona (sello o puntos según el comercio) y se actualiza en su móvil en tiempo real, sin que el personal tenga que introducir nada.

1. Autenticación

Cada comercio de Digikart dispone de una clave de API generada desde su panel de control (Mi cuenta → Conexión con el TPV). Se envía en la cabecera HTTP:

Authorization: Bearer dk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La clave es propia de un comercio: solo puede abonar las tarjetas de ese comercio. El comerciante puede revocarla o regenerarla en cualquier momento.

2. Probar la conexión

GEThttps://digikart.fr/api/pos/ping

curl https://digikart.fr/api/pos/ping \
  -H "Authorization: Bearer dk_live_..."

→ { "ok": true, "business": "Bar Bichette", "mode": "points", "pointsRate": 1 }

mode vaut "stamps" (sellos: 1 visita = 1 sello) o "points" (puntos calculados a partir del importe del ticket).

3. Abonar una venta

POSThttps://digikart.fr/api/pos/transaction

Champ	Type	Description
`card`	string*	El identificador de la tarjeta del cliente: el contenido del código de barras / QR de su tarjeta Wallet (un número de serie, o una URL `/c/<serial>`, se aceptan ambos).
`phone`	string*	Alternativa al escaneo: el número de teléfono que el cliente indicó al instalar su tarjeta (útil para cajas y terminales sin lector 2D). Formatos aceptados: `06 12 34 56 78` o `+33612345678`. * `card` o `phone` : se requiere uno de los dos.
`amount`	number	Importe del ticket en euros. Obligatorio si el comercio está en modo puntos (es lo que determina los puntos). Opcional en modo sellos (se registra para las estadísticas del comerciante).
`transaction_id`	string	Identificador único del ticket en el TPV. Muy recomendable : garantiza la idempotencia (véase §4).

Ejemplo: comercio en modo puntos

curl -X POST https://digikart.fr/api/pos/transaction \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "card": "A1B2C3D4E5", "amount": 23.80, "transaction_id": "TICKET-20260715-0042" }'

→ {
    "ok": true, "mode": "points",
    "serial": "A1B2C3D4E5", "name": "Marie D.",
    "stamps": 61,            // solde de points après crédit
    "pointsAdded": 24,       // arrondi de 23,80 € × taux du commerce
    "rewardUnlocked": false,
    "claimable": null        // ou { threshold, reward } si un palier est atteint
  }

Ejemplo: comercio en modo sellos

curl -X POST https://digikart.fr/api/pos/transaction \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "card": "A1B2C3D4E5", "transaction_id": "TICKET-20260715-0043" }'

→ { "ok": true, "mode": "stamps", "stamps": 7, "stampsRequired": 10, "rewardUnlocked": false }

En cuanto llega la respuesta, la tarjeta Wallet del cliente se actualiza en su móvil (push de Apple / API de Google): nada más que hacer en el TPV.

4. Idempotencia (tickets reenviados)

Si se reenvía una transacción con un transaction_id ya procesado (reintento de red, webhook reenviado), Digikart no abona una segunda vez : se devuelve la respuesta original, con "duplicate": true. Usa el identificador de ticket de tu TPV, que se mantiene estable entre reintentos.

5. Errores

HTTP	`code`	Signification
400	`invalid_request`	Cuerpo de la solicitud no válido.
400	`amount_required`	El comercio está en modo puntos: `amount` es obligatorio.
401	`unauthorized`	Clave ausente, desconocida o revocada.
402	`subscription_required`	La suscripción de Digikart del comercio no está activa.
403	`wrong_merchant`	La tarjeta pertenece a otro comercio.
404	`card_not_found` / `phone_not_found`	Tarjeta desconocida, o ningún cliente con ese número en este comercio.
429	`too_soon` / `rate_limited`	Duplicado cercano sin `transaction_id`, o más de 120 solicitudes por minuto.

En caso de error no se escribe nada: la transacción puede reenviarse sin riesgo.

6. Recorrido típico en caja

El cliente muestra su tarjeta Digikart (Apple/Google Wallet): la caja escanea su código de barras.
Al cobrar, la caja llama a POST /api/pos/transaction con la tarjeta, el importe y el identificador del ticket.
La tarjeta del cliente se actualiza al instante en su móvil.

7. Contacto para integradores

Proveedor de TPV, integrador, middleware (HubRise, etc.): escríbenos a contact@digikart.fr : acompañamos con mucho gusto las integraciones.