Push API-overzicht

Met de Push API kun je transacties vanuit andere systemen naar Budgero sturen terwijl alles end-to-end versleuteld blijft. Je genereert een token, versleutelt de payload met jouw werkruimtesleutel, en stuurt deze via een POST naar het push-endpoint over HTTPS.

Snelle installatie

1. Ga naar Instellingen → Integraties → Push API en genereer een Push API-token.
2. Exporteer jouw werkruimte-versleutelingssleutel (Budgero slaat deze nooit op de server op).
3. Maak een JSON-payload aan (zie formaat hieronder), versleutel deze met AES-256-GCM, codeer deze als Base64, en stuur deze via een POST naar het push-endpoint met jouw bearer-token.
4. Voeg optioneel een message_id toe zodat nieuwe pogingen worden ontdubbeld.
5. Volg de wachtrijstatistieken in de app of via de API om de verwerking te bevestigen.

Endpoint- en payloadspecificatie

• Endpoint: POST /api/v1/push (gebruik jouw basis-URL; standaard is https://my.budgero.app)
• Authenticatie: Authorization: Bearer <push-api-token>
• Body-velden:
  • encrypted_payload (string, Base64): met AES-GCM versleutelde JSON-payload (IV + ciphertext + auth-tag).
  • message_id (string, optioneel): door de client gegenereerd id om nieuwe pogingen te ontdubbelen.

Vorm van de ontsleutelde payload (vóór versleuteling)

{  "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"}

Geldwaarden zijn gehele milli-eenheden (1/1000 van een valuta-eenheid), dus 42,50 wordt verzonden als 42500. Voeg altijd "v": 2 toe; oudere payloads zonder dit worden behandeld als formaat 1 (decimale bedragen) en bijgewerkt bij import, maar nieuwe integraties moeten formaat 2 verzenden. De Python SDK regelt zowel de formaatvlag als de conversie voor je.

Vandaag ondersteunde bewerking

• transactions.add — stuur inkomsten of uitgaven. Gebruik inflow voor inkomsten en outflow voor uitgaven (slechts één mag niet-nul zijn). Geef je bestaande budget-, rekening- en categorie-ID's op.

Versleutelingsvereisten

• Algoritme: AES-256-GCM
• IV: 12 bytes (voeg toe vóór ciphertext)
• Auth tag: 16 bytes (voeg toe na ciphertext)
• Codering: Base64 van IV + ciphertext + tag
• Sleutel: Je werkruimte-versleutelingssleutel (geëxporteerd uit Instellingen).

Python SDK-snelstart

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)

SDK-helpers:

• get_queue() — items in afwachting weergeven

• get_queue_stats() — aantal in afwachting/verwerkt/mislukt

• clear_queue() — items in afwachting wissen (of alle met een vlag)

• Deduplicatie: Geef een stabiele message_id op bij het opnieuw proberen om dubbele invoer te voorkomen.

• Wachtrij-inzicht: Controleer wachtrijstatistieken in de app of via /push/queue en /push/stats om levering te verifiëren.

• Tokenhygiëne: Roteer/regenereer bij blootstelling. Schakel uit of trek in vanuit Instellingen indien nodig.

• Sleutelhygiëne: Houd de token/sleutel buiten versiebeheer.

  

  Gebruik omgevingsvariabelen (bijv. BUDGERO_PUSH_TOKEN, BUDGERO_SPACE_KEY) of de geheime beheerder van je besturingssysteem, beperk bestandsrechten en vermijd ze te loggen.

• Transport: Gebruik altijd HTTPS zodat de bearer-token en metadata beschermd blijven.

• Toegangsbeheer: Beperk wie de token/sleutel kan lezen. Behandel ze als inloggegevens met scope tot je budget.

• Foutafhandeling: Bij 409 met message_id, behandel het als een gedupliceerde poging. Bij 401/403, regenereer/schakel de token in. Monitor wachtrijfouten en wis of plaats opnieuw in de wachtrij indien nodig.