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 (sal + IV + texto cifrado + etiqueta de autenticación; consulta Requisitos de cifrado).
  • 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. Usa "cleared": true si la transacción ya se ha liquidado en el banco; si se omite, se añade como no liquidada.
• Coincidencias con movimientos registrados a mano: un transactions.add enviado que se parece a una transacción que registraste tú (misma cuenta y dirección, importe y fecha dentro de Ajustes → Transacciones duplicadas, 1 % y ±7 días por defecto) no se añade dos veces. Espera en la lista por revisar de la cuenta: Emparejar conserva tu movimiento y lo marca como confirmado, y Añadir como nueva añade exactamente lo enviado. Las transferencias y las transacciones divididas siempre se añaden directamente.

Requisitos de cifrado

• Algoritmo: AES-256-GCM
• Sal: 32 bytes = SHA-256 de los 32 bytes sin codificar de tu clave de cifrado del espacio (anteponer al IV)
• IV: 12 bytes (después de la sal, antes del texto cifrado)
• Etiqueta de autenticación: 16 bytes (añadir después del texto cifrado)
• Codificación: Base64 de sal + IV + texto cifrado + etiqueta
• Clave: Tu clave de cifrado del espacio (exportada desde Ajustes). Decodifica el valor exportado de Base64 antes de calcular su hash o usarlo como clave AES; utiliza el resumen SHA-256 de 32 bytes sin codificar como sal.

El prefijo de sal es obligatorio: el cliente lo compara con el SHA-256 de su propia clave del espacio antes de descifrar (comparación en tiempo constante en mutation-crypto.ts). El servidor acepta un payload sin sal (HTTP 202, encolado), pero el procesamiento falla en el cliente y el elemento queda en la cola con el estado failed — la transacción nunca llega al presupuesto, aunque se haya aceptado. El SDK de Python ya antepone la sal automáticamente; solo afecta a los clientes desarrollados manualmente a partir de la especificación anterior.

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.