Visión general de la Push API

La Push API te permite enviar transacciones a Budgero desde otros sistemas manteniendo todo cifrado de extremo a extremo. Generas un token, cifras el payload con la clave de tu espacio y lo envías mediante POST al endpoint de push por HTTPS.

Configuración rápida

1. En Ajustes → Integraciones → Push API, genera un token de Push API.
2. Exporta la clave de cifrado del espacio (Budgero nunca la almacena en el servidor).
3. Crea un payload JSON (consulta el formato más abajo), cífralo con AES-256-GCM, codifícalo en Base64 y envíalo mediante POST al endpoint de push con tu token bearer.
4. Opcionalmente, incluye un message_id para que los reintentos se dedupliquen.
5. Supervisa las estadísticas de la cola en la app o a través de la API para confirmar el procesamiento.

Endpoint y especificación del payload

• Endpoint: POST /api/v1/push (usa tu URL base; el valor predeterminado es https://my.budgero.app)
• Auth: Authorization: Bearer <push-api-token>
• Campos del body:
  • encrypted_payload (string, Base64): payload JSON cifrado con AES-GCM (IV + texto cifrado + etiqueta de autenticación).
  • message_id (string, opcional): ID generado por el cliente para deduplicar reintentos.

Estructura del payload descifrado (antes del cifrado)

{  "v": 2,  "op": "transactions.add",  "args": {    "accountId": 1,    "categoryId": 5,    "budgetId": 1,    "date": "2024-11-27",    "inflow": 0,    "outflow": 42500,    "memo": "API push",    "payee": "Vendor",    "transferId": ""  },  "message_id": "optional-unique-id"}

Los valores monetarios son milunidades enteras (1/1000 de una unidad de moneda), por lo que 42.50 se envía como 42500. Incluye siempre "v": 2; los payloads antiguos sin este campo se tratan como formato 1 (importes decimales) y se actualizan al importar, pero las integraciones nuevas deberían enviar el formato 2. El SDK de Python gestiona tanto el indicador de formato como la conversión por ti.

Operación soportada actualmente

• transactions.add — envía un ingreso o gasto. Usa inflow para ingresos y outflow para gastos (solo uno debe ser distinto de cero). Proporciona los IDs existentes de tu presupuesto, cuenta y categoría.

Requisitos de cifrado

• Algoritmo: AES-256-GCM
• IV: 12 bytes (anteponer al texto cifrado)
• Etiqueta de autenticación: 16 bytes (añadir después del texto cifrado)
• Codificación: Base64 de IV + texto cifrado + etiqueta
• Clave: Tu clave de cifrado del espacio (exportada desde Ajustes).

Inicio rápido del SDK de Python

from budgero import BudgeroClientclient = BudgeroClient(    api_key="your-push-token",    encryption_key="your-space-key",    base_url="https://my.budgero.app",)result = client.add_transaction(    account_id=1,    category_id=5,    budget_id=1,    date="2024-11-27",    outflow=42.50,    memo="Example push",    payee="API Demo",)print("Queued id:", result.queue_id)

Funciones auxiliares del SDK:

• get_queue() — lista los elementos pendientes

• get_queue_stats() — recuentos de pendientes/procesados/fallidos

• clear_queue() — borra los elementos pendientes (o todos con un flag)

• Desduplicación: Proporciona un message_id estable al reintentar para evitar inserciones duplicadas.

• Visibilidad de la cola: Comprueba las estadísticas de la cola en la aplicación o mediante /push/queue y /push/stats para verificar la entrega.

• Higiene del token: Rota/regenera si se ha expuesto. Desactívalo o revócalo desde Ajustes cuando sea necesario.

• Higiene de la clave: Mantén el token/clave fuera del control de versiones.

  

  Usa variables de entorno (p. ej., BUDGERO_PUSH_TOKEN, BUDGERO_SPACE_KEY) o el gestor de secretos de tu sistema operativo, restringe los permisos de archivo y evita registrarlos en logs.

• Transporte: Usa siempre HTTPS para que el token de portador y los metadatos permanezcan protegidos.

• Control de acceso: Restringe quién puede leer el token/clave. Trátalos como credenciales con alcance en tu presupuesto.

• Gestión de errores: En un 409 con message_id, trátalo como un reintento desduplicado. En 401/403, regenera/activa el token. Supervisa los fallos de la cola y borra o vuelve a encolar según sea necesario.