ROKI Connect para n8n
=====================

Dos nodos:

  ROKI Connect          crea enlaces de pago, consulta, lista, anula y reembolsa.
  ROKI Connect Trigger  arranca un flujo cuando ROKI avisa que entro un pago.

Con eso ROKI queda conectado a todo lo demas que ya usas: una hoja, un correo, WhatsApp, tu
sistema propio. En vez de un conector por plataforma, uno que habla con todas.


INSTALAR
--------

En tu n8n, Configuracion > Community nodes > Instalar, y pone:

    n8n-nodes-roki-connect

Si tu n8n corre en Docker y no deja instalar nodos de la comunidad, copia la carpeta dentro de
~/.n8n/custom/ y reinicia.


CONFIGURAR LA LLAVE
-------------------

Credenciales > Nueva > "ROKI Connect API".

  Llave Secreta   la de la pestana Integracion API del portal de ROKI.

El entorno NO se elige aparte: lo decide el prefijo de la llave. sk_test_ va contra el sandbox y
sk_live_ cobra de verdad. Un selector separado es la forma mas facil de creer que estas cobrando
cuando no, o al reves.

Apreta "Probar" antes de guardar: pide un solo pago y te dice si la llave sirve.


EL DISPARADOR: EL PASO QUE HAY QUE HACER A MANO
-----------------------------------------------

ROKI no tiene una ruta para registrar webhooks por API, asi que la URL se pega una vez en el
portal. Suena peor de lo que es, porque encaja: el portal tiene DOS webhooks, uno de sandbox y uno
de produccion, y n8n te da DOS URLs.

    URL de prueba (la que aparece mientras el panel escucha)  ->  webhook de SANDBOX
    URL de produccion (la que aparece con el flujo activo)    ->  webhook de PRODUCCION

Se registran una vez cada una, en la suya, y no se toca mas. Mientras armas el flujo, ROKI te
manda los avisos de sandbox a la URL de prueba; cuando lo activas, los de produccion van a la de
produccion.

En cada webhook, el portal te devuelve un SECRETO DE FIRMA. Ese va en una credencial aparte,
"ROKI Connect Webhook". Es a proposito que sea otra credencial: un flujo que solo escucha avisos
no tiene por que ver la llave con la que se cobra.


LO QUE EL DISPARADOR HACE POR VOS
---------------------------------

  - Comprueba la firma de cada aviso sobre el cuerpo crudo, en tiempo constante, y descarta los
    que llegan con mas de cinco minutos de viejos. Un aviso que no cuadra no dispara nada.
  - Descarta las reentregas. ROKI reintenta cuando duda si llegaste a recibir el aviso; sin esto,
    el mismo pago dispara tu flujo dos veces: dos correos, dos facturas, dos despachos.
  - Te deja filtrar por tipo de evento y por como empieza la referencia, para cuando varios
    sistemas comparten la misma cuenta de ROKI.


COSAS QUE VALE LA PENA SABER
----------------------------

El monto va en LEMPIRAS CON DECIMALES, nunca en centavos. 25.50 son veinticinco lempiras con
cincuenta.

La llave de idempotencia hace que reintentar no cobre dos veces. Si la dejas vacia, el nodo la
arma sola con la referencia y el monto: reintentar devuelve el mismo pago, y cambiar el monto crea
uno nuevo. Que es lo que corresponde en los dos casos.

Para anular y para reembolsar se usa el transaction_id, que es un UUID. No es el id numerico del
pago: con ese, ROKI contesta 404 y parece que la transaccion no existe.

Anular es siempre por el total - el API no acepta un monto - y conviene mas que reembolsar
mientras la transaccion no haya liquidado: una anulacion no le aparece al cliente en su estado de
cuenta.

El vencimiento del enlace se manda en hora de Honduras. El nodo convierte lo que le des, asi que
podes usar una fecha de n8n sin pensarlo.


PROBAR
------

    node plugins/n8n/probar.mjs

Corre el codigo de los dos nodos contra el sandbox real, sin instalar n8n: crea un cobro, comprueba
el cuerpo que se manda, la idempotencia, la conversion de hora, y las firmas del disparador -
incluidas las que tienen que rechazarse.
