Integrar Skip paso a paso (Spot & AAPD)

Una ruta paso a paso para llevar tu integración de cero a producción. Asume que integras primero Spot y luego AAPD. Todo se prueba primero en staging y solo se repite en producción tras pasar staging completo.

Cada fase enlaza a la referencia de endpoint y a la guía de producto correspondiente para el detalle fino.

Credenciales — qué necesita cada producto

Antes de empezar, ten claro qué credencial usa cada producto. Cómo obtenerlas: Obtener tus credenciales. Cuándo usar cada una: Conceptos → Autenticación.

Cuánto toma integrar

Tiempos referenciales para un equipo con un backend ya andando (donde agregar endpoints server-side y manejo de secretos) y un frontend capaz de embeber un iframe.

Buena parte del trabajo de AAPD reutiliza lo que ya construiste para Spot: la llamada al widget es la misma (solo agregas la orden y un parámetro), y el envío del gasto es el mismo endpoint (POST /api/spot/gastos, solo agregas skip_pay_order_id). Lo genuinamente nuevo en AAPD es leer los postMessage de pago y recibir el webhook.

---

Fase 0 · Credenciales y ambiente

• Recibe tus credenciales de staging.
  Las de producción llegan tras la primera prueba end-to-end exitosa en staging — ver Obtener tus credenciales.

• Guarda los secretos server-side.
  client_secret y webhook_secret van en env vars / secrets manager. public_key puede vivir en el browser.

• Apunta tus env vars a staging.
  Lista completa en Conceptos → Ambientes:

  SKIP_BACKEND_URL=https://staging.backend.getskip.ai/api
  SKIPPAY_API_URL=https://staging.pay.getskip.ai
  SPOT_WIDGET_URL=https://staging.spot.getskip.ai

• Confirma que tu key es de staging.
  Debe ser pk_test_*, no pk_live_*.

Fase 1 · Spot — Widget (onboarding de paciente)

Guía completa: Spot Widget. Contrato del endpoint: Generar widget token.

• Genera el token.
  Desde tu backend: POST /api/spot/widget?public_key=... → { widget_token, url }. Un 401 significa public_key incorrecta; arréglala antes de seguir.
• Embebe el iframe.
  Usa la url devuelta. Tu CSP permite frame-src https://staging.spot.getskip.ai. Mínimo 480×640.
• Deja que el widget resuelva su estado.
  Pide su estado solo y renderiza la pantalla correcta — para un RUT nuevo verás el registro (SPOT_USER_NEW). No gestionas estas pantallas.
• Registra un usuario.
  Llena el form dentro del iframe → onboarding completa.
• Escucha el postMessage.
  Validando event.origin, recibes SPOT_USER_CREATED con { user_id, rut }. Maneja también SPOT_WIDGET_CLOSED y SPOT_WIDGET_ERROR.
• Confirma server-side (recomendado).
  GET /api/spot/is_user_subscribed por RUT. El postMessage es señal de frontend, no autoridad.
• Prueba los casos borde.
  RUT ya registrado con otro email → RUT_OTHER_EMAIL (409); token expirado (>1h) → 410. Detalle en Spot Widget → Casos borde.

Fase 2 · Spot — Boletas (obligatorio para todo provider)

Guía completa: Boletas de Spot. Contrato del endpoint: Subir boleta.

Todo provider debe enviarnos las boletas: es el documento con el que Skip rinde el reembolso ante la ISAPRE. Sin boleta no hay rendición.

• Envía una boleta.
  POST /api/spot/gastos?public_key=... con la boleta y, si existe, la orden médica u otro comprobante asociado (PDF o imagen; 1–5 archivos, ≤2 MB c/u) → 200 con processed_files.
• Prueba el 404 esperado.
  Un RUT que aún no es beneficiario Skip devuelve 404 beneficiary_not_found. Tu backend guarda la boleta y reintenta cuando el paciente se registre.
• Correlaciona por RUT normalizado.
  Es la llave entre el paciente y sus boletas.
• Valida la idempotencia.
  Reenviar el mismo archivo no duplica el gasto.

Fase 3 · AAPD — Crear orden y widget de pago

Guía completa: AAPD Widget. Contrato del endpoint: Crear una orden.

• Crea la orden.
  POST /orders (server-side, Authorization: Bearer <client_secret>) → { hash }.
• Genera el widget token con order_token.
  POST /api/spot/widget?public_key=... con order_token=<hash>. Su presencia es lo que activa el flujo AAPD.
• Construye la URL del paciente.
  {url}&order_token=<hash>. Sin order_token el widget trata la sesión como un registro Spot normal.
• Embebe el iframe.
  480×820 desktop / 320×820 móvil; CSP frame-src https://staging.spot.getskip.ai.

Probar el flujo dentro del widget (solo staging). El widget corre end-to-end las pantallas de identidad → tarjeta → pago. Para probarlo sin datos reales:

• Salta la validación de identidad.
  En el paso de identidad, ingresa el número de serie 000000000 (nueve ceros). En staging esto marca la identidad como validada sin llamar al proveedor de financiamiento y deja continuar el flujo. Para simular un RUT bloqueado usa 000000001.
• Paga el 30% con una tarjeta de prueba.
  El pago corre contra el sandbox del proveedor de financiamiento (no es simulado localmente). Usa una tarjeta de prueba — una que aprueba y otra que rechaza. Números en docs.ventipay.com/docs/test-cards, o pídelos al equipo de Skip.
• Confirma la completitud.
  Al terminar el pago recibes por postMessage WIDGET_PAYMENT_SUCCESS (valida event.origin). Maneja también WIDGET_FORM_CLOSE si el paciente cierra.

Fase 4 · AAPD — Recibir el webhook de confirmación

Guía completa: Webhooks de AAPD. Verificación de firma: Verificación de firma (implementación en 5 lenguajes en Recetas).

Registrar el webhook no es requisito para probar el widget (Fase 3); puedes cablearlo después. El webhook es la confirmación autoritativa del pago: llega cuando el paciente completa el checkout, y es lo que tu backend debe esperar antes de dar la orden por pagada.

• Registra tu webhook_notification_url.
  Un endpoint HTTPS en tu backend, coordinado con el equipo de Skip; confirma tu webhook_secret.
• Verifica la firma.
  Tu endpoint lee el body crudo (antes de parsear JSON) y valida el HMAC-SHA256 en X-Gokeipay-Signature. Rechaza firmas inválidas.
• Responde 200 rápido.
  Devuelve 200 y procesa async. Ramifica según data.status.
• Verifica el status = paid.
  Confirma que recibes order.changed con status = paid.

• Maneja el abandono por ausencia.
  No llega ningún webhook si el paciente abandona a mitad de flujo o si se rechaza el préstamo — la orden queda en pending. Si dentro de tu ventana esperada no recibiste paid, trátalo como no-pagado o consulta GET /orders/{hash}.

Fase 5 · AAPD — Enviar el gasto (cierra el 30/70)

Contrato del endpoint: Enviar gasto.

El pago del 30% no cierra el flujo. Para que Skip presente el reembolso a la ISAPRE (y así cobre el 70%), tu backend debe enviarnos la boleta.

• Envía el gasto.
  POST /api/spot/gastos con la boleta (obligatoria) + su metadata (nombre, fecha, RUT emisor, RUT del médico, monto) + la orden médica si aplica o está disponible.
• Liga el gasto a la orden.
  Usa skip_pay_order_id = <hash>. Ese campo es lo que convierte la boleta en parte del flujo AAPD y gatilla la rendición.
• Confía en la idempotencia.
  Es idempotente por orden: reintentar es seguro y no duplica el gasto.

Staging ↔ producción de un vistazo

Mismo código y mismos endpoints; solo cambian las URLs base y las credenciales.

La producción se habilita solo después de una prueba end-to-end exitosa en staging.