# 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: empezar-conceptos-base title: 'Conceptos base: el modelo mental de un pago con SPIDI' audience: Desarrollador que va a integrar SPIDI y necesita el modelo mental antes de tocar código objetivo: > Al terminar, el espectador tiene la cadena entera y en orden: el destino, la sesión, el enlace, cuánto vive, las dos fases y cómo se entera de cada una. Cada idea se apoya solo en la anterior. Se lleva las dos que más ahorran: que puede entregar en `paid`, y que el `status` nunca refleja la fase 2. cta: 'Siguiente: el tutorial ''Recibe tu primer pago''.' target_duration_s: 351 storyboard: - 'n': 1 on_screen: El modelo mental de un pago narracion: >- Antes de escribir una línea de código conviene tener el modelo mental de un pago con SPIDI. Aquí está entero y en orden, y cada idea usa solo la anterior: ninguna aparece de la nada. visual: Título; debajo, seis eslabones vacíos en fila que se irán llenando a lo largo del vídeo. duracion_s: 13 - 'n': 2 on_screen: '1 · A dónde va el dinero: el destino' narracion: >- Empieza por una decisión que hay que tomar antes de recibir el primer pago: a dónde va a llegar el dinero. Eso es un destino, y en la API se llama acuerdo. Es un juego de reglas que dice cómo recibes: a qué cuenta bancaria tuya se acredita, qué métodos de pago aceptas, y si lo que llegue ahí se reparte con otros. visual: >- Una cuenta bancaria con un juego de reglas colgando: métodos aceptados, cuenta de destino, si se reparte. duracion_s: 24 - 'n': 3 on_screen: Se define una vez y se reutiliza narracion: >- Y esto es lo que más se malentiende: un destino se define una vez y se reutiliza. No creas uno por pago. Creas uno por cada forma distinta de recibir que tenga tu negocio, y después lo usas en todos los pagos que vayan ahí. Cada destino tiene su identificador, y es lo que dice, en cada pago, por dónde lo enruta SPIDI. visual: >- Un destino y muchas flechas de pagos entrando por él; al lado, varios destinos distintos para casos distintos. duracion_s: 24 - 'n': 4 on_screen: '2 · Cómo inicias un pago: la sesión' narracion: >- Con tus destinos definidos, recibir un pago es abrir una sesión de pago, y la creas con una sola llamada. Una sesión tiene dos partes. Primero, por dónde lo enrutas: pones el identificador del destino, y con eso ya está dicho a qué cuenta va el dinero y qué métodos aceptas. Y después, los datos de este pago: cuánto y en qué moneda lo fijas, a quién se lo pides y por qué concepto, y a dónde vuelve la persona al terminar. visual: >- Una sesión partida en dos mitades: arriba el identificador del destino, abajo los datos del pago. duracion_s: 32 - 'n': 5 on_screen: '3 · Qué te devuelve: el enlace de pago' narracion: >- Sobre la moneda, un apunte que decide cómo montas tu catálogo: fijas el precio en la moneda que uses, y la liquidación es siempre en bolívares. Y la respuesta trae dos cosas que te importan: una URL de pago, que es la pantalla donde tu cliente va a pagar, y un status que arranca en pendiente. visual: >- La respuesta con dos piezas resaltadas: la URL de pago y un status en pendiente; al lado, un precio en dólares que se liquida en bolívares. duracion_s: 22 - 'n': 6 on_screen: Úsala tal cual viene; no la construyas narracion: >- Esa URL es lo único que tu cliente necesita ver, y cómo se la pones delante es tu decisión: un botón en tu web, un enlace que le envías, o un código QR. Pero guárdala tal cual viene: armarla a mano lleva a un enlace que no da error, y que acaba en una pantalla plausible donde el pago se pierde sin que nadie se entere. visual: >- La URL puesta delante del cliente de tres formas; al lado, una armada a mano llevando a una pantalla plausible pero equivocada. duracion_s: 25 - 'n': 7 on_screen: 4 · Cuánto tiene que vivir ese enlace narracion: >- Ahí está la decisión que conviene tomar bien: cuánto tiene que vivir ese enlace. Si tu cliente está delante, decidiendo ahora, solo tiene que durar lo que dure la compra: unos minutos, y eso es un Botón. Si el pago va a esperar, tiene que seguir vivo hasta una fecha que pones tú, y eso es una Solicitud. Y ojo: la URL de un Botón también es una URL, así que se puede mandar por WhatsApp, y morirse antes de que la abran. visual: 'Un mismo enlace con un dial de duración: minutos a un lado, una fecha de calendario al otro.' duracion_s: 32 - 'n': 8 on_screen: Un pago ocurre en dos fases visual: Lámina de sección, sin voz. duracion_s: 3 - 'n': 9 on_screen: Fase 1 · El pago narracion: >- Hasta aquí, cómo se pide un pago. Ahora, qué le pasa al dinero — y aquí está el detalle que confunde a todo integrador: una transacción no es un evento, son dos. La primera fase es el pago. Tu cliente paga y el dinero sale de sus manos. No queda en poder de SPIDI: entra en una cuenta propia del banco, y el banco es su custodio. Tu cliente ya no puede echarse atrás, y la sesión pasa a pagado. visual: >- El dinero saliendo de las manos del pagador y entrando en una cuenta del banco, con un candado de custodia. duracion_s: 31 - 'n': 10 on_screen: Y aquí ya puedes entregar narracion: >- De ahí sale lo más útil de todo esto: en cuanto la sesión llega a pagado, puedes entregar. No esperes a la segunda fase para habilitar tu servicio o despachar tu producto. Y el motivo no es una promesa, es el mecanismo: el dinero está en un banco y el banco lo custodia. visual: Un paquete saliendo del almacén con el sello 'pagado', sin esperar a nada más. duracion_s: 20 - 'n': 11 on_screen: Fase 2 · La acreditación narracion: >- La segunda fase es la acreditación: el dinero se mueve desde esa cuenta del banco hasta la tuya, o hasta las de tus receptores si el destino se bifurca. Aquí se aplica la comisión del banco, y por eso lo que se acredita es el monto neto. Tarda entre uno y dos minutos, no segundos. visual: >- El dinero moviéndose de la cuenta del banco a la tuya, con una porción que se descuenta por el camino. duracion_s: 21 - 'n': 12 on_screen: Cómo te enteras de cada fase visual: Lámina de sección, sin voz. duracion_s: 3 - 'n': 13 on_screen: La sesión es el registro de la transacción narracion: >- Con las dos fases claras, queda cómo te enteras. Y hay una idea que lo ordena todo: la sesión es el registro de la transacción, y las dos fases se ven ahí. Una sola consulta te da el estado completo. El campo status te dice la fase uno. Y receiver_credits, dentro de la misma respuesta, te dice la fase dos. visual: >- Una ficha de sesión que contiene las dos fases dentro: el status arriba, receiver_credits abajo. duracion_s: 23 - 'n': 14 on_screen: El aviso es el atajo, no la única fuente narracion: >- El aviso no es la única fuente: es el atajo. Llega firmado a tu URL de webhook y te avisa en cuanto ocurre, así no tienes que preguntar. Pero si no lo tienes montado, no te quedas fuera: consultas la sesión. visual: >- Un sobre firmado llegando a un endpoint que responde con un check; al lado, la consulta como camino alternativo. duracion_s: 16 - 'n': 15 on_screen: El status nunca refleja la fase 2 narracion: >- Y una advertencia que ahorra horas: tras pagado, el status se queda en pagado. No existe un estado acreditado. Si sondeas esperándolo, esperas para siempre. Lo que cambia es que receiver_credits deja de venir nulo: es otro bucle y otra condición de salida. visual: Un bucle de sondeo esperando un estado que no llega nunca, junto al campo que sí cambia. duracion_s: 17 - 'n': 16 on_screen: Guarda el identificador de cada sesión narracion: >- Y de ahí sale un hábito que conviene coger ya: guarda el identificador de cada sesión. Si tu servidor estuvo caído, SPIDI reintenta y luego se rinde, sin reenvío. No hay forma de listar tus sesiones, así que ese identificador es tu única llave de vuelta. visual: >- Un servidor caído, un aviso que se pierde, y una llave con el identificador de sesión abriendo la consulta. duracion_s: 18 - 'n': 17 on_screen: Las dos reglas de oro narracion: >- De toda la cadena salen dos reglas de oro. La primera: el estado real lo manda tu backend, no la redirección del navegador; que tu cliente vuelva a tu URL de éxito no significa que te pagaron. Y la segunda: pagado es el pago, y la acreditación es cuándo lo ves en tu cuenta. Ya tienes el mapa entero. Ahora ponlo en práctica y recibe tu primer pago de prueba. visual: 'Dos carteles con un check: el backend manda, y pagado no es acreditado.' duracion_s: 27