API v1
Registra gastos desde donde quieras
Chinola expone una API pequeña y estable para que otro programa registre movimientos en tus libretas: Telegram, WhatsApp, mensajes directos de Instagram, un formulario o una hoja de cálculo. La API no sabe de canales — solo recibe un movimiento y una etiqueta de origen—, así que añadir uno nuevo no toca la app.
Chinola no habla con WhatsApp ni con Instagram directamente, y es a propósito. Tu flujo (n8n, Make, un script) recibe el mensaje y llama a esta API. Si mañana Meta cambia las reglas de cualquiera de los dos, cambias el flujo y la app ni se entera.
1. Consigue una clave
En la app: Ajustes → Integraciones → Crear clave. Se muestra una sola vez, así que cópiala en ese momento. Empieza por chin_ y va en la cabecera de cada llamada. Necesitas plan Pro (ver planes).
authorization: Bearer chin_xxxxxxxxxxxxxxxxxxxxxxxx
Si una clave se filtra, revócala desde la misma pantalla: deja de funcionar al instante y no afecta a las demás.
2. Registra un movimiento
POST/api/v1/movimientos
curl -X POST https://chinola.fente.com.do/api/v1/movimientos \
-H "authorization: Bearer $CLAVE" \
-H "content-type: application/json" \
-d '{
"libreta": "Personal",
"concepto": "Colmado",
"monto": 450,
"tipo": "Gasto Variable",
"categoria": "Alimentación",
"fecha": "2026-09-03",
"origen": "whatsapp",
"idempotencia": "wamid.HBgM..."
}'
| Campo | Obligatorio | Qué es |
|---|---|---|
| concepto | sí | El texto que verás en la lista. |
| monto | sí | Número positivo. El signo lo pone el tipo. |
| libreta | no | Nombre o id. Sin él va a tu libreta más reciente. |
| tipo | no | Ingreso, Gasto Fijo, Gasto Variable o Ahorro. Por defecto, gasto variable. |
| categoria | no | Una de las de esa libreta. Si no coincide, cae en «Otros». |
| medio | no | cuenta:1 o tarjeta:2. Ajusta el saldo igual que la app. |
| fecha | no | AAAA-MM-DD. Por defecto, hoy. |
| origen | no | Etiqueta libre para saber de dónde vino: whatsapp, instagram, telegram… |
| idempotencia | recomendado | Un identificador único del mensaje. Léelo abajo. |
| adjunto | no | URL de la foto del recibo, si la tienes. |
La idempotencia no es opcional en la práctica
WhatsApp reintenta la entrega de un mensaje cuando no recibe confirmación a tiempo, y n8n reintenta el nodo cuando falla la red. Sin este campo, un reintento se convierte en un gasto duplicado. Manda el identificador del mensaje (wamid...) y Chinola devolverá el movimiento que ya creó, con "repetido": true, en vez de crear otro.
3. Consulta
GET/api/v1/libretas — tus libretas con sus categorías y medios de pago, para que el flujo sepa qué valores son válidos.
GET/api/v1/resumen?mes=2026-09 — ingresos, gastos y balance del mes por libreta. Útil para responder «¿cuánto llevo gastado?» por chat.
Errores
| Código | Qué pasó |
|---|---|
| 400 | Falta el concepto o el monto no es un número. |
| 401 | Clave inválida o revocada. |
| 402 | El plan de esa cuenta no incluye API. |
| 403 | Tu rol en esa libreta no permite registrar. |
| 404 | La libreta que pediste no existe o no es tuya. |
Cada llamada queda registrada. Si algo no cuadra, en el portal interno está el registro con la ruta, el resultado y el detalle.
Qué canal elegir
Los tres funcionan contra la misma API y con el mismo flujo; lo que cambia es lo que cuesta ponerlos en marcha.
| Canal | Qué hace falta | Límite a tener en cuenta |
|---|---|---|
| Telegram | Crear un bot con @BotFather y copiar su token. Nada más: ni empresa, ni verificación, ni revisión. | El bot solo puede escribirte después de que tú le mandes /start. |
| Cuenta de empresa en Meta, número dedicado, verificación del negocio y la Cloud API. | Fuera de las 24 h desde tu último mensaje solo puedes escribir con plantillas aprobadas. | |
| Cuenta profesional enlazada a una página de Facebook y permisos de mensajería. | Solo puedes responder dentro de las 24 h siguientes al mensaje. |
Si quieres esto andando esta semana, empieza por Telegram. Un bot se crea en dos minutos y no depende de que nadie apruebe nada. WhatsApp tiene más alcance, pero su puesta en marcha es un trámite, no un desarrollo. Y como la API no distingue canales, cambiar o sumar el otro después es duplicar un flujo, no rehacer nada.
El flujo de mensajería, paso a paso
Con n8n, que ya corre en el mismo servidor. El mismo flujo sirve para los tres: WhatsApp e Instagram entran por la Graph API de Meta y Telegram por su Bot API; solo cambia de dónde sacas el texto y el identificador del mensaje.
- Webhook — recibe el mensaje. Para Telegram, n8n trae nodo propio; para WhatsApp e Instagram va un webhook que mira el campo object del cuerpo.
- Filtro — comprueba que quien escribe eres tú: el número en WhatsApp, el id de la cuenta en Instagram, el chat.id en Telegram. Sin esto, cualquiera que adivine la URL registra gastos en tu libreta.
- Interpretar — de «colmado 450» saca concepto y monto. Un modelo de lenguaje lo hace mejor que una expresión regular en cuanto la gente escribe «450 en el colmado ayer».
- Si viene foto — pásala por un modelo de visión y saca monto, comercio y fecha del recibo.
- HTTP Request — POST a /api/v1/movimientos con la clave, el origen del canal y, en idempotencia, el identificador del mensaje (wamid en WhatsApp, mid en Instagram, message_id en Telegram).
- Responder — devuelve por el mismo chat lo que creó, para que se pueda corregir a tiempo.
Dos advertencias. El paso 2 no es un adorno: un webhook de n8n es una URL pública y, sin comprobar quién escribe, cualquiera con esa URL puede meter movimientos en tus libretas —y en Telegram basta con que alguien encuentre tu bot para escribirle—. Y en WhatsApp e Instagram solo puedes responder dentro de las 24 horas siguientes al mensaje, así que contesta en el momento y no en un proceso nocturno.
Estabilidad
Esto es v1. Se le añadirán campos, pero no se van a quitar ni a cambiar de significado los que ya están: un flujo que funciona hoy seguirá funcionando. Si algún día hiciera falta romper algo, saldrá una v2 y la v1 seguirá viva.