CuentoraCuentora

Documentación de la API de Agentes

Conecta tu Cuentora a Hermes, ChatGPT, Claude y más

¿Cómo funciona?

Cuentora ofrece una API abierta y optimizada para que cualquier inteligencia artificial o script pueda interactuar con tus datos en lenguaje natural. Al habilitar una API Key, estás abriendo la puerta a consultas rápidas en chat de voz, atajos del sistema y registros automatizados desde cualquier lugar.

Prompt para tu Agente Inteligente

Copia y pega este prompt directamente en Claude Code, ChatGPT, Hermes o tu herramienta de automatización para instruirla sobre cómo usar Cuentora. **Por seguridad, no pegues tu API Key en texto plano dentro del prompt; configúrala como variable de entorno o secreto en tu agente:**

Actúa como mi asistente financiero personal integrado con Cuentora. Tu tarea es gestionar mis finanzas usando mi API Key. Para conectarte, usa la URL base de la API: `https://cuentora.com/api/v1` Esquema de API OpenAPI completo disponible en: `https://cuentora.com/api/v1/schema` Debes enviar mi API Key en el header: `Authorization: Bearer <MI_API_KEY_DESDE_SECRETOS_O_ENV>` Endpoints disponibles para usar: 1. GET /balances -> Consulta de patrimonio total consolidado y listado de cuentas. 2. GET /rates -> Consulta de tasas de cambio del día (BCV oficial, mercado paralelo y EUR) en JSON. 3. GET /budgets -> Ver límites y consumo de presupuestos mensuales. 4. GET /goals -> Ver metas de ahorro y progreso. 5. GET /deudas -> Ver deudas activas. 6. GET /movimientos -> Listar movimientos (acepta query params: ?limit=N&category=Nombre&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&tx_type=gasto|ingreso). 7. POST /movimientos -> Registrar ingresos/gastos (requiere scope "write"). 8. PUT /movimientos -> Editar movimientos (requiere scope "write"). 9. DELETE /movimientos?id=ID -> Eliminar movimientos (requiere scope "write"). 10. GET /cards?type=rates|summary|cobro -> Obtiene URLs de imágenes dinámicas PNG. Regla de Moneda Importante: - Cuando reportes balances o montos de cuentas en bolívares (VES), consulta el endpoint `GET /rates` para obtener la tasa BCV oficial actual (`bcv`). Realiza la conversión matemática VES / BCV para mostrar los saldos equivalentes en USD cuando sea necesario, y viceversa, manteniendo siempre al usuario informado de ambas cifras. - Cuando te pida registrar algo o ver mi estado, realiza las llamadas correspondientes en silencio y preséntame la información de forma clara.

Endpoints de la API v1

GET /api/v1/balancesScope: read

Obtiene patrimonio total consolidado (VES/EUR convertidos a USD usando la tasa BCV del día), ingresos, gastos y neto del mes actual, además de los saldos de cada cuenta vinculada.

GET /api/v1/ratesScope: read

Obtiene las tasas de cambio de bolívares por dólar (BCV oficial, paralelo) y el euro en bolívares en formato JSON para conversiones precisas.

GET /api/v1/budgetsScope: read

Lista los presupuestos configurados para el mes actual, detallando límites, consumo actual por categoría y montos disponibles.

GET /api/v1/goalsScope: read

Lista las metas de ahorro activas, mostrando montos objetivos, montos acumulados y fecha límite.

GET /api/v1/deudasScope: read

Lista las deudas pendientes por cobrar o pagar asociadas a los contactos del usuario.

GET /api/v1/movimientosScope: read

Lista los movimientos recientes. Permite filtros de búsqueda mediante query parameters opcionales: ?limit=N, ?category=Nombre, ?start_date=YYYY-MM-DD, ?end_date=YYYY-MM-DD y ?tx_type=gasto|ingreso.

POST /api/v1/movimientosScope: write

Registra un gasto o ingreso. Calcula y deduce los montos en bolívares e impacta el balance de la cuenta destino si se especifica.

PUT /api/v1/movimientosScope: write

Modifica los campos de una transacción (monto, concepto, cuenta). Reajusta de forma transparente los balances bancarios de las cuentas antigua y nueva.

DELETE /api/v1/movimientosScope: write

Elimina un movimiento por su ID (?id=ID) y revierte de forma automática su impacto financiero en la cuenta asociada.

GET /api/v1/cardsScope: read

Genera imágenes dinámicas premium en PNG de:

• type=rates -> Tasa del día.

• type=summary -> Resumen mensual de ingresos/gastos.

• type=cobro&amount=X -> Tarjeta de cobro en Bs. a tasa seleccionada.

Seguridad de tus API Keys

  • Cuentora encripta tus llaves usando hashes criptográficos irreversibles en la base de datos.
  • Usa el scope de **Lectura** a menos que necesites registrar datos desde el agente.
  • Nunca compartas tu API Key en repositorios públicos. Si sospechas una fuga, revócala de inmediato desde tu panel.
Ir a gestionar mis API Keys