API – 2. Authenticatie

De Facturalia API gebruikt Bearer API keys. Elke request moet je key meesturen in de Authorization-header.

Header

Authorization: Bearer <JOUW_API_KEY>
Content-Type: application/json

Let op de spatie na Bearer.

Sleutels verkrijgen & beheren

• Live key: je kan zelf API keys aanmaken in Facturalia via Extra > Modules > API
• Scopes: per key kunnen rechten ingesteld worden. Voor dit endpoint is (indien geactiveerd) invoices:create vereist.
• Prefix: keys zien er uit als fac_live_….

Voorbeelden

cURL

curl -X POST https://www.facturalia.be/api/v1/invoices \
  -H "Authorization: Bearer <JOUW_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": { "date": "2025-09-26", "due_days": 30, "language": "nl" },
    "customer": { "name": "ABCD BV" },
    "lines": [{ "product_code": "CONS-001", "quantity": 1, "unit_price": 120.0, "vat_rate": 21 }]
  }'

Postman

• Authorization tab → Type Bearer Token → plak je key.
• Of in Headers: Authorization: Bearer <JOUW_API_KEY>.

JavaScript (fetch)

await fetch('https://www.facturalia.be/api/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    invoice: { date: '2025-09-26', due_days: 30, language: 'nl' },
    customer: { name: 'ACME BV' },
    lines: [{ product_code: 'CONS-001', quantity: 1, unit_price: 120.0, vat_rate: 21 }]
  })
});

Foutcodes bij authenticatie

401 Unauthorized – ontbrekende/ongeldige key

{
  "error": {
    "code": "unauthorized",
    "message": "Authorization header ontbreekt of ongeldig."
  }
}

403 Forbidden – key geldig, maar vereiste scope ontbreekt

{
  "error": {
    "code": "forbidden",
    "message": "Scope ontbreekt: invoices:create"
  }
}

Beveiligingsrichtlijnen

• Altijd HTTPS (geen plain HTTP).
• Bewaar keys veilig (niet in code repositories).
• Rotate keys periodiek; verwijder oude/inactieve keys.
• Log nooit volledige keys.
• Rate limiting (zie aparte sectie).

Tip (duplicaten vermijden): je kunt een Idempotency-Key header of een eigen external_id in de body gebruiken. Dit is optioneel maar aanbevolen bij automatische retries. (Details in de volgende sectie.)