REST API: fatturazione e pagamenti

Monitora fatture e pagamenti tramite la REST API. Ideale per aziende di servizi, freelance e sistemi di fatturazione personalizzati.

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_here
  • Authorization: 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

CampoTipoObbligatorioDescrizione
platformstringSìUsa “custom” o il nome del tuo strumento di fatturazione
orderNumberstringSìNumero della fattura (per esempio “INV-2026-042”)
orderStatusstringSì“processing” (inviata), “delivered” (pagata), “cancelled”
customerEmailstringNoIndirizzo email del cliente
customerNamestringNoNome del cliente o dell'azienda
itemsJSON arrayNoServizi/prodotti: [{name, quantity, price}]
totalstringNoTotale della fattura
currencystringNo“EUR”, “USD”, ecc.
paymentStatusstringNo“pending”, “paid”, “overdue”, “refunded”
paymentMethodstringNo“bankoverschrijving”, “iDEAL”, “Tikkie”
invoiceNumberstringNoRiferimento della fattura
invoiceUrlstringNoLink al PDF della fattura
amountPaidstringNoImporto 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 paymentStatus passa 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)

Non trovi quello che cerchi?

Chiedi direttamente a noi e riceverai una risposta personale.

Fai la tua domanda