Reintentos e idempotencia

POST /integrations/discounts/apply y POST /integrations/consumptions exigen el encabezado Idempotency-Key:

• Genera un UUID nuevo por operación (por ejemplo, uno al aplicar y otro al notificar) y guárdalo junto al ticket.
• Si la llamada falla por red, timeout o 5xx, reintenta con la misma llave y el mismo cuerpo: COME devuelve el resultado original y no duplica la autorización ni el consumo.
• Reintenta con espera exponencial (por ejemplo 1 s, 2 s, 4 s) y un máximo de intentos. No reintentes 400, 401, 403, 404 ni 409 sin corregir la causa.

import { randomUUID } from 'node:crypto'

const idempotencyKey = randomUUID() // guárdalo con el ticket antes de llamar
await fetch(`${baseUrl}/api/v1/integrations/consumptions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getToken()}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({ authorizationCode, reference, consumptionDate: new Date().toISOString() }),
})

Datos personales

La integración maneja la identificación de personas. Cumple la Ley 172-13 de protección de datos personales:

• Pide la identificación solo en el momento del canje y úsala solo para llamar a COME.
• No la guardes en tu sistema más allá de lo necesario para la operación. Para conciliar, guarda authorizationCode, el code del consumo y tu reference.
• Nunca pongas identificaciones, tokens ni API keys en URLs, logs o mensajes de error.
• COME solo devuelve datos mínimos (displayName y empresa) para confirmar con el cliente.
• En pruebas usa exclusivamente datos ficticios.

Operación

• Tiempo de espera: usa un timeout razonable (por ejemplo 10 s) y, si COME no responde, cobra sin descuento o reintenta; nunca apliques el descuento sin autorización.
• Conciliación: los consumos notificados aparecen en Consumos del portal de comercios. Compáralos con tus tickets usando reference y authorizationCode.
• Credenciales: una por sistema o sucursal, guardadas en un gestor de secretos, con rotación periódica. Ver Autenticación.
• Catálogos: identification-types cambia muy poco: cachéalo por 24 horas.