API – 6. Verwerking

Deze sectie beschrijft hoe Facturalia je data interpreteert en verwerkt bij het aanmaken van een factuur. Handig om verrassingen te voorkomen.

Datums & tijdzone

• Formaat: JJJJ-MM-DD.
• Tijdzone: Europe/Brussels
• Vervaldatum: due_date = date + due_days.

Nummering

• Automatisch nummeren: laat invoice.number weg → Facturalia kent automatisch een volgend factuurnummer toe.
• Overnemen: stuur invoice.number mee → moet uniek per account zijn.
  Bij hergebruik:
  • Identieke payload → we geven dezelfde factuur terug (replay).
  • Afwijkende payload → 409 Conflict.

BTW (tarieven & vrijstellingen)

• Toegestane tarieven: 0, 6, 12, 21
• Vrijstelling:
  • invoice.vat_exemption_code geldt voor de hele factuur

Valuta & taal

• Valuta: standaard EUR.
• Taal: nl / fr / en.

Klantselectie/aanmaak

• Je kunt een klant identificeren via customer_id, vat_number of name.
• Als er geen bestaande klant wordt gevonden en je levert basisgegevens (minstens name), kan Facturalia een nieuwe klant aanmaken met de aangeleverde velden (street, postal_code, city, country, email, …).

Producten & lijnen

• product_code: verwijst naar een bestaand product in je account.
• Verplichte velden per lijn: product_code, quantity (> 0), unit_price (≥ 0), vat_rate.

Betaalstatus

• invoice.is_paid: 0/1 (of boolean).
  Indien 1 wordt de huidige datum geregistreerd als betaaldatum.

BTW Vrijstelling

• invoice.vat_exemption_code
• Weglaten indien geen vrijstelling of verlaagd tarief
• Anders:
  • 1 (Werken in onroerende staat (0% medecontractant))
  • 2 (Intracommunautaire leveringen)
  • 3 (Intracommunautaire diensten)
  • 4 (Kleine onderneming)
  • 6 (Verlaagd btw-tarief 6% voor woningen)
  • 7 (Export via EU (art.41))
  • 8 (OSS)
  • 9 (Verlaagd btw-tarief 12% ikv sociaal beleid)
  • 10 (Verlaagd btw-tarief 6% voor schoolgebouwen)
  • 11 (Export niet EU (art.39))
  • 12 (Verlaagd btw-tarief 6% voor afbraak en heropbouw)
  • 13 (Vrijstelling obv Art. 44)
  • 14 Verlaagd btw-tarief 6% voor personen met handicap

Layout & huisstijl

• layout (int, optioneel) — ID van de lay-out in Facturalia voor deze factuur.
  • Als niet opgegeven, wordt de standaardlay-out van het account gebruikt.
  • Validatie: de lay-out moet bestaan en tot jouw account behoren; anders 422 invalid_layout.
  • Opmerking: dit beïnvloedt enkel de opmaak/PDF (geen totalen).

Automatisch verzenden

• autosend (0/1, optioneel) — als 1, wordt de factuur na aanmaak automatisch verzonden.
  • Routing: indien zender én klant op Peppol → verzending via Peppol, anders via e-mail.
  • Tijdstip: verzending gebeurt asynchroon na 201 Created.
  • Idempotency: een replay van dezelfde creatie verzendt niet opnieuw; status blijft ongewijzigd (zie hoofdstuk 3).
  • Foutscenario’s:
    • Vooraf detecteerbare fouten (bv. onbestaande email_tpl of ontbrekend klant-e-mailadres) → 422 validation_error.
    • Runtime-fouten tijdens de asynchrone verzending (SMTP/Peppol down) zetten de factuur op send_failed; de API-response blijft 201. (Een retry-endpoint volgt in een latere versie.)

Responsevelden
Na totals bevat de factuur:

"autosend": {
  "autosend_status": "SENT",      // SENT, NOT_SENT, SENDING_ERROR, SENDING_PENDING
  "autosend_channelused": "NONE", // NONE | EMAIL | PEPPOL
  "autosend_error": ""
}

Lifecycle

• Als invoice.autosend = 0 of niet gezet → autosend_status = NOT_SENT, channelused = "NONE".
• Als invoice.autosend = 1:
  • Bij asynchrone verzending direct na creatie kan autosend_status = SENDING_PENDING zijn zolang de verzending nog niet verwerkt is (in wachtrij).
    Na verwerking wordt dit SENT (verzonden) of SENDING_ERROR (fout).
  • Bij direct slagen: autosend_status = SENT en channelused = "EMAIL" of "PEPPOL".
  • Bij fout: autosend_status = SENDING_ERROR en autosend_error bevat een korte beschrijving (bv. SMTP-fout, ontbrekend e-mailadres, Peppol niet beschikbaar).

Kanaalkeuze
Indien zender én klant Peppol-capabel → PEPPOL, anders EMAIL.

Idempotency
Replays van dezelfde creatie verzenden niet opnieuw. De autosend-waarden blijven wat ze waren (bv. 20 of 30).

E-mailtemplate

• email_tpl (int, optioneel) — ID van de e-mailtemplate voor e-mailverzending.
  • Alleen van toepassing als de route e-mail is (niet bij Peppol).
  • Als niet opgegeven → standaard e-mailtemplate.
  • Validatie: template moet bestaan en aan het account toebehoren; anders 422 invalid_email_template.

Verzendkosten

Verzendkosten worden in Facturalia behandeld als een gewone factuurlijn. Gebruik een product (bijv. SHIPPING of VERZEND) met het gewenste btw-tarief en zet per factuur de eenheidsprijs naar het juiste bedrag.
Voorbeeldlijn:

{ "product_code": "SHIPPING", "quantity": 1, "unit_price": 7.90, "vat_rate": 21, "detail": "Verzendkosten" }

Validatie & limieten

• Maximale precisie: quantity en unit_price tot 4 decimalen toegestaan; totalen op 2 decimalen.
• Lengtes (aanbevelingen):
  invoice.number ≤ 50 tekens, customer.name ≤ 200, detail ≤ 1000.

PDF-generatie

• PDF wordt asynchroon gegenereerd na 201 Created.

Foutafhandeling (kruisverwijzing)

• Bij validatiefouten → 422 met details.{pad} per veld.
• Bij duplicate identifiers (invoice.number/external_id/Idempotency-Key) met afwijkende payload → 409.

Tip voor integrators: test altijd met eenzelfde payload + identieke identifier (of Idempotency-Key) om je retry-gedrag te verifiëren; controleer dat je geen dubbele facturen creëert.