Recomendaciones de implementación

Flujo completo

1. Integrador → IdP: POST /token (client_credentials). Devuelve access_token (15 min).
2. Integrador → API: POST /points-of-sale (una vez por vendedor). Devuelve uuid (point_of_sale_id).
3. Integrador → API: POST /payments/qr/{pos_uuid} (por cada venta). Devuelve qr_id, payload QR y expiración.
4. El integrador muestra el QR al pagador.
5. Integrador → API: GET /sse/notifications?topic=urn:{tenant}:intent_{qr_id}. Llega un evento SSE con el pago aprobado (reference_number).
   • Alternativa: GET /payments/intents/{qr_id}/sse → 204 = pendiente / 200 = pagado.
6. Integrador → API: GET /payments/authorizations/{reference_number}. Devuelve el detalle completo de la venta.

Recomendaciones

1. Gestión del token: implementá un cache con renovación anticipada (el token dura 15 minutos y no hay refresh token). Ante un 401, reintentá con un token nuevo.
2. Persistencia de identificadores: guardá point_of_sale_id (por vendedor) y qr_id (por venta). El qr_id es la clave que vincula la venta local con el pago recibido (tracking.payment_intent_uuid).
3. Estrategia de confirmación: priorizá SSE para una experiencia en tiempo real; usá el endpoint de estado (/intents/{qr_id}/sse) como respaldo ante desconexiones, y la lista de movimientos como conciliación batch (por ejemplo, un cierre diario por point of sale).
4. Expiración de QR dinámicos: controlá expires_at; si el QR expira sin pagarse, generá uno nuevo para reintentar el cobro.
5. Idempotencia y reintegros: verificá metadata.can_refund en el intent antes de habilitar devoluciones desde tu aplicación.