API REST: facturación y pagos

Visión general

La API de facturación y pagos te permite enviar a Bugalou datos de facturas y pagos desde sistemas de facturación externos. Es ideal para empresas de servicios (arquitectos, consultores, autónomos, ZZP'ers) que quieren automatizar los recordatorios de pago y seguir el estado de las facturas en un único panel. Necesitas una clave de API para autenticarte.

Autenticación

Incluye tu clave de API en cada solicitud:

• X-API-Key: bg_live_your_key_here
• Authorization: Bearer bg_live_your_key_here

Enviar datos de facturas

Usa el endpoint de la API de pedidos con campos específicos de facturas:

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

Actualizar el estado del pago

Cuando llegue un pago, actualiza el estado enviando el mismo número de factura/pedido:

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

El pedido se inserta o actualiza (upsert): se actualiza el registro existente cuando coinciden orderNumber + platform.

Referencia de campos de facturas

Campo	Tipo	Obligatorio	Descripción
platform	string	Sí	Usa "custom" o el nombre de tu herramienta de facturación
orderNumber	string	Sí	Número de factura (p. ej. "INV-2026-042")
orderStatus	string	Sí	"processing" (enviada), "delivered" (pagada), "cancelled"
customerEmail	string	No	Dirección de email del cliente
customerName	string	No	Nombre del cliente o de la empresa
items	JSON array	No	Servicios/productos: [{name, quantity, price}]
total	string	No	Total de la factura
currency	string	No	"EUR", "USD", etc.
paymentStatus	string	No	"pending", "paid", "overdue", "refunded"
paymentMethod	string	No	"bankoverschrijving", "iDEAL", "Tikkie"
invoiceNumber	string	No	Referencia de la factura
invoiceUrl	string	No	Enlace al PDF de la factura
amountPaid	string	No	Importe realmente pagado

Ideas de automatización

• Recordatorio de pago: activa un WhatsApp o un email cuando una factura esté vencida
• Confirmación de pago: da las gracias automáticamente al cliente cuando paymentStatus cambie a "paid"
• Resumen mensual: usa la API para sincronizar facturas y ver el estado de los pagos en un único panel

¿Para quién es?

• Arquitectos y estudios de diseño que hacen seguimiento de las facturas de sus proyectos
• Autónomos y ZZP'ers que gestionan la facturación de sus clientes
• Consultores que envían recordatorios de pago
• Cualquier empresa de servicios que use herramientas como Moneybird, Exact o facturación personalizada

Formato de la respuesta

Éxito: {"success": true, "order": {...}}

Error: {"error": "Invalid or expired API key"} (401/403)