# Guion del vídeo, para comentar o para lo que necesites. # Es una PROYECCIÓN del nuestro: lleva el contenido —qué se dice, qué se ve, en # qué orden y cuánto dura— y no la maquinaria que lo convierte en vídeo. id: herramientas-simulador-api title: 'El simulador como API: contrato, plano de control y webhooks' audience: Desarrollador que va a manejar el simulador de SPIDI programáticamente, sin navegador objetivo: > Al terminar, el espectador distingue qué parte del simulador es contrato que existe en producción y qué parte es andamiaje que desaparece, sabe forzar los dos fases desde el plano de control, conoce las cabeceras y los reintentos con los que llega un webhook, y entiende por qué una entrega loopback no prueba nada de su código. cta: 'Siguiente: ''El simulador desde su consola'' o ''Conducir el ciclo''.' target_duration_s: 285 storyboard: - 'n': 90 on_screen: Para quien integra a mano narracion: >- Una nota antes de entrar. El simulador es la herramienta de quien integra a mano: si le pides la integración a tu agente de inteligencia artificial, él usa esto mismo por debajo y no necesitas saberlo. Sigue aquí si quieres manejarlo tú, o si estás depurando algo que ya escribiste. visual: 'El simulador en el centro; dos manos lo usan: la de un desarrollador y la de un agente.' duracion_s: 19 - 'n': 1 on_screen: El simulador, sin navegador narracion: >- El simulador es un sandbox hosteado que emula el contrato de la API Productos de SPIDI: la máquina de estados de la sesión, la acreditación a dos fases y los avisos firmados. Y se maneja entero por HTTP, sin abrir un navegador. Eso es lo que vamos a ver: qué superficie expone, qué hace con cada llamada, y qué garantías te da. visual: >- Un sandbox en la nube cerrado por un candado, con una consola de comandos al lado en vez de un navegador. duracion_s: 24 - 'n': 2 on_screen: Contrato · Andamiaje narracion: >- Antes que nada, la distinción que más caro sale ignorar. El simulador expone dos superficies mezcladas en el mismo host, y solo una existe en producción. El login y las rutas del API de productos son contrato: viajan contigo. Todo lo demás —la consola, el plano de control, la página de pago, el alta rápida— es andamiaje que desaparece el día que apuntes a producción. visual: >- Una frontera vertical parte la pantalla: a la izquierda, rutas marcadas con un sello de permanencia; a la derecha, rutas marcadas con un icono de andamio. duracion_s: 25 - 'n': 3 on_screen: Andamiaje en producción = rotura narracion: >- Y esa distinción tiene una consecuencia práctica. Úsalo desde tus pruebas, nunca desde el código que vas a desplegar. Una llamada al plano de control colada en la ruta de integración no falla hoy: falla el día del estreno, que es cuando menos te apetece. visual: >- Un bloque de código de integración con una línea del plano de control resaltada en rojo y una señal de peligro. duracion_s: 17 - 'n': 4 on_screen: token de API · token de consola · webhook_secret narracion: >- Con la frontera clara, hablemos de credenciales. El alta te entrega tres piezas de una vez. El token de API abre las rutas del producto y el plano de control. El token de consola abre las lecturas de la consola y tus receptores, y nada más. Y unas credenciales de login, para que ejercites el camino de autenticación que en producción es obligatorio. Cruzar los dos tokens devuelve un cuatrocientos uno, y ese error significa token equivocado, no token inválido. El alta te da además el secreto de webhook, que no viaja en ninguna petición: es con el que verificas la firma de los avisos que recibes. visual: >- Dos llaves de distinto color, cada una abriendo una puerta distinta; una tercera pieza, un sello, aparte y sin puerta. duracion_s: 41 - 'n': 5 on_screen: Forzar el desenlace narracion: >- Ya con tu token, el plano de control es lo que el entorno en vivo no te deja: llevar la sesión adonde tú digas. La fase 1 admite pagado, fallido o expirado; el segundo, acreditado o acreditación fallida. Y hay una trampa que cuesta tardes: forzar el pago por el plano de control no programa la acreditación. Si fuerzas la fase 1 y te sientas a esperar el aviso de acreditación, no llega. Fuerza también el segundo. visual: >- Una palanca de dos posiciones etiquetadas como primer y segunda fase, con cinco desenlaces saliendo de ella. duracion_s: 30 - 'n': 6 on_screen: spidi-signature · spidi-timestamp · idempotency-key narracion: >- Y cuando le toca avisarte, el simulador manda el sobre con tres cabeceras. La firma es un sello HMAC-SHA256 calculado sobre la marca de tiempo, un punto, y el cuerpo crudo, byte a byte: si tu framework parsea el JSON y tú lo vuelves a serializar para verificar, la comparación falla aunque el contenido sea el mismo. Guarda el cuerpo sin tocar. Van también esa marca de tiempo, que entra en el cálculo, y la clave de idempotencia. visual: Un sobre saliendo hacia un servidor, con tres etiquetas de cabecera pegadas encima. duracion_s: 30 - 'n': 7 on_screen: Reintentos · esperas crecientes · rendición narracion: >- Si tu servidor no contesta, el simulador no se rinde a la primera: reintenta, con esperas crecientes y un tiempo máximo por intento. Agotados los intentos, el simulador se rinde y lo deja anotado. Ojo con una cosa: el ritmo del simulador está puesto para que veas la secuencia entera en segundos, no para que copies sus tiempos. No escribas lógica que dependa de cuántos intentos hay ni de cuánto esperan: diseña para recibir el mismo aviso un número indeterminado de veces. Lo que sí puedes dar por bueno es la forma —hay reintentos, hay límite y hay rendición—. Y la clave de idempotencia no cambia entre reintentos: por eso deduplicar por ella es lo que evita que le cargues el pago dos veces a tu cliente. visual: >- Varios intentos en línea con esperas crecientes entre ellos, y al final una bandera de rendición registrada en un cuaderno. duracion_s: 49 - 'n': 8 on_screen: loopback · direct · relay narracion: >- Queda la trampa más difícil de detectar. El simulador clasifica cada URL de aviso sola: si apunta a sus propios receptores, la entrega es loopback, y ahí el que contesta es él mismo. Todo sale en verde y no se ejecutó ni una línea de tu código: ni tu verificación de firma, ni tu deduplicación, ni tu manejo de errores. Si el destino es local o privado va por el relay; cualquier otro host va directo. Si todo te sale bien y el enrutado dice loopback, no has probado tu integración. visual: >- Un bucle que sale del simulador y vuelve a entrar en él, marcado en gris, frente a dos flechas que sí salen hacia un servidor propio. duracion_s: 35 - 'n': 9 on_screen: Programático o con la consola narracion: >- Eso es el simulador como API: te basta con HTTP para conducirlo entero. Si además quieres verlo con una interfaz delante, tiene una consola, y esa es otra página. Sigue con conducir el ciclo para el camino paso a paso. visual: >- Cierre de marca; una flecha apunta hacia dos caminos, uno con una terminal y otro con una pantalla de consola. duracion_s: 15