Panoramica
L'API di fatturazione e pagamenti ti permette di inviare a Bugalou i dati di fatture e pagamenti da sistemi di fatturazione esterni. È ideale per le aziende di servizi (architetti, consulenti, freelance, liberi professionisti) che vogliono automatizzare i promemoria di pagamento e monitorare lo stato delle fatture in un'unica dashboard. La REST API è disponibile con il piano Enterprise. Per autenticarti ti serve una chiave API.
Autenticazione
Includi la tua chiave API in ogni richiesta:
X-API-Key: bg_live_your_key_hereAuthorization: Bearer bg_live_your_key_here
Inviare i dati di una fattura
Usa l'endpoint dell'API degli ordini con i campi specifici per le fatture:
POST https://app.bugalou.com/api/v1/orders
X-API-Key: bg_live_your_key_here
Content-Type: application/json
{
"platform": "custom",
"orderNumber": "INV-2026-042",
"orderStatus": "processing",
"customerEmail": "klant@bedrijf.nl",
"customerName": "Architectenbureau De Groot",
"items": [
{"name": "Ontwerp woning - fase 1", "quantity": 1, "price": "2500.00"},
{"name": "Bouwtechnisch advies", "quantity": 3, "price": "150.00"}
],
"total": "2950.00",
"currency": "EUR",
"paymentStatus": "pending",
"invoiceNumber": "INV-2026-042",
"invoiceUrl": "https://mijn-boekhouding.nl/facturen/INV-2026-042.pdf"
}
Aggiornare lo stato del pagamento
Quando arriva un pagamento, aggiorna lo stato inviando lo stesso numero di fattura/ordine:
POST https://app.bugalou.com/api/v1/orders
X-API-Key: bg_live_your_key_here
Content-Type: application/json
{
"platform": "custom",
"orderNumber": "INV-2026-042",
"orderStatus": "delivered",
"paymentStatus": "paid",
"paymentMethod": "bankoverschrijving",
"amountPaid": "2950.00"
}
L'ordine viene creato o aggiornato (upsert): aggiorna il record esistente quando orderNumber + platform corrispondono.
Riferimento dei campi della fattura
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
platform | string | Sì | Usa “custom” o il nome del tuo strumento di fatturazione |
orderNumber | string | Sì | Numero della fattura (per esempio “INV-2026-042”) |
orderStatus | string | Sì | “processing” (inviata), “delivered” (pagata), “cancelled” |
customerEmail | string | No | Indirizzo email del cliente |
customerName | string | No | Nome del cliente o dell'azienda |
items | JSON array | No | Servizi/prodotti: [{name, quantity, price}] |
total | string | No | Totale della fattura |
currency | string | No | “EUR”, “USD”, ecc. |
paymentStatus | string | No | “pending”, “paid”, “overdue”, “refunded” |
paymentMethod | string | No | “bankoverschrijving”, “iDEAL”, “Tikkie” |
invoiceNumber | string | No | Riferimento della fattura |
invoiceUrl | string | No | Link al PDF della fattura |
amountPaid | string | No | Importo effettivamente pagato |
Idee per le automazioni
- Promemoria di pagamento: invia un messaggio WhatsApp o un'email quando una fattura è scaduta
- Conferma di pagamento: ringrazia automaticamente il cliente quando
paymentStatuspassa a “paid” - Panoramica mensile: usa l'API per sincronizzare le fatture e vedere lo stato dei pagamenti in un'unica dashboard
Per chi è?
- Architetti e studi di progettazione che monitorano le fatture dei progetti
- Freelance e liberi professionisti che gestiscono la fatturazione ai clienti
- Consulenti che inviano promemoria di pagamento
- Qualsiasi azienda di servizi che usa strumenti come Moneybird, Exact o una fatturazione personalizzata
Formato della risposta
Successo: {"success": true, "order": {...}}
Errore: {"error": "Invalid or expired API key"} (401/403)