API-integratie: omgevingen, verplichte velden en veldtoewijzingen

Test- en productieomgeving, verplichte velden bij POST /invoices, datastructuur voor inkomende en uitgaande facturen, veldtoewijzingen en al gekoppelde systemen.

Dit artikel beantwoordt de meest gestelde vragen over het koppelen van uw eigen systemen aan de faktoora-API. Foutmeldingen en HTTP-statuscodes worden apart beschreven in het artikel Foutafhandeling in de API, de volledige lijst met BT-velden in het artikel Welke BT-velden ondersteunt de faktoora-API? en de verplichte velden voor XRechnung in het artikel Welke gegevens moet een XRechnung minimaal bevatten?.

Test- en productieomgeving

De faktoora-API is beschikbaar onder twee aparte basis-URL's:

Productieomgeving: https://api.faktoora.com/api/v1
Demo-/testomgeving: https://api.demo.faktoora.com/api/v1

Beide omgevingen zijn zelfstandige instanties met eigen accounts en gegevens. De API-sleutel wordt telkens in de accountinstellingen van de betreffende omgeving aangemaakt en in de header X-API-KEY meegestuurd (zie Waarom worden mijn API-aanroepen met 401 afgewezen?). Voor de overstap van test- naar productiegebruik wijzigt u de basis-URL in https://api.faktoora.com/api/v1 en gebruikt u de sleutel die in het productieaccount is aangemaakt.

Factuur aanmaken: POST /invoices

Voor het Invoice-object zelf zijn volgens het schema alleen de volgende velden in principe verplicht:

format: uitvoerformaat, bijv. simple, zf:1, zf:2, xrechnung, peppol
issueDate: factuurdatum (BT-2)
invoiceNumber: factuurnummer (BT-1)
invoiceTypeCode: factuurtype, bijv. 380 voor een handelsfactuur (BT-3)
invoiceItems: minstens één factuurregel
buyer: de koper

Binnen buyer en seller zijn naam en volledig adres (street, postcode, city, country) verplicht zodra u het betreffende blok meestuurt. Elke regel in invoiceItems heeft een id en een product-object met name, quantity, unitCode, price en taxes nodig. De volledige, formaatafhankelijke lijst met verplichte velden voor format: xrechnung vindt u in het artikel Welke gegevens moet een XRechnung minimaal bevatten?.

Factuur opvragen: werkwijze

Het aanmaken van facturen via POST /invoices verloopt asynchroon: de response is 202 Accepted met een faktooraId, de factuur zelf wordt op de achtergrond gegenereerd. Een directe GET /invoices/{faktooraId} meteen daarna kan met 404 mislukken, omdat de verwerking nog loopt.

De juiste werkwijze:

POST /invoices versturen en de faktooraId uit de 202-response opslaan.
De verwerkingsstatus controleren via GET /invoices/{faktooraId}/status of wachten op de geregistreerde webhook (zie Webhook).
Pas daarna GET /invoices/{faktooraId} aanroepen. Het endpoint levert het kant-en-klare bestand direct als application/pdf of application/xml (geen JSON-object met metadata).

Details over de mogelijke statuscodes vindt u in het artikel Foutafhandeling in de API.

Veldtoewijzingen

Orderreferentie (Order Reference)

Op factuurniveau zijn er twee verschillende referentievelden:

orderNumber op het Invoice-object: verwijzing naar de bijbehorende bestelling (BT-14).
invoiceItems[].product.orderNumber: orderreferentie op het niveau van de afzonderlijke regel; volgens de API-beschrijving niet toegestaan voor format: xrechnung.

Daarnaast bestaat buyerReference.IssuerAssignedID als orderreferentie van de koper (BT-13), niet te verwarren met buyerReference.buyerReferenceId: dat is de referentie van de koper, of bij publieke opdrachtgevers de Leitweg-ID (BT-10).

Bij het opvragen van factuurgegevens via de import-endpoints (zie hieronder) heet het overeenkomstige veld references.orderReferenceId (BT-13) of references.orderNumber voor het bestelnummer van de koper. De veldnamen verschillen dus tussen het aanmaken (POST /invoices) en het opvragen van geïmporteerde facturen.

Bestelnummer: kop- of regelniveau?

Beide zijn mogelijk en onafhankelijk van elkaar: orderNumber op het Invoice-object verwijst naar de bestelling op kopniveau (BT-14), invoiceItems[].product.orderNumber verwijst naar een bestelling op het niveau van de afzonderlijke regel. Voor xrechnung is alleen het kopniveau toegestaan.

Contactpersoon van de koper

De contactpersoon bij de koper legt u vast via buyer.definedTradeContact:

firstName / lastName: naam van de contactpersoon (BT-56)
departmentName: afdeling (BT-56-0)
phone: telefoonnummer (BT-57-00)
email: e-mailadres (BT-58-00)

Dit staat los van buyer.phone/buyer.email (BT-57/BT-58), die het algemene contact van het kopende bedrijf weergeven.

DirectDebitMandateID

directDebitMandateID (SEPA-incassomachtiging, BG-19/BT-89) hoort bij het object specifiedTradePaymentTerms, niet bij specifiedTradeSettlementPaymentMeans. Wordt het veld per ongeluk in het blok voor betaalmiddelen (payment means) in plaats van in het blok voor betalingsvoorwaarden (payment terms) meegegeven, dan wordt het niet in de XML overgenomen, omdat het daar geen gedefinieerd schemaveld is. Ontbreekt de DirectDebitMandateID in de gegenereerde XML, controleer dan eerst of het veld in de specifiedTradePaymentTerms-array staat.

Betaalwijzecodes voor PayPal en creditcard

Het veld specifiedTradeSettlementPaymentMeans[].typeCode (BT-81) gebruikt de codelijst UNTDID 4461. Beschikbaar zijn onder meer 10 (contant), 20 (cheque), 30 (overboeking), 42 (betaling op bankrekening), 48 (kaartbetaling), 49 (incasso), 57 (doorlopende opdracht), 58 (SEPA-overboeking), 59 (SEPA-incasso), 97 (rapportage) en de stringcode ZZZ (vrij gedefinieerd). Er is geen aparte code voor PayPal.

Creditcard: typeCode: 48. Voor deze code zijn bovendien cardNumber (verplicht) en optioneel holderName toegestaan; beide velden zijn alleen bij typeCode: 48 toegestaan.
PayPal: omdat UNTDID 4461 geen specifieke code voor PayPal kent, gebruikt u typeCode: "ZZZ" (vrij gedefinieerd) en beschrijft u de betaalwijze in het vrije tekstveld information, bijv. "Betaling via PayPal".

Datastructuur van de interface voor inkomende en uitgaande facturen

Voor geïmporteerde facturen, zowel inkomende (/import/incoming) als uitgaande (/import/outgoing), levert de API dezelfde basisstructuur, verdeeld in afzonderlijk op te vragen deelresources:

content/summary: overzicht (status, bedragen, formaat)
content/seller / content/buyer: gegevens van verkoper en koper
content/lineitems: factuurregels
content/taxes: belastinggegevens per belastingcategorie (taxable, rate, amount, category)
content/paymentterms: betalingsvoorwaarden, incl. directDebitMandateID en dueDateTime
content/paymentmeans: betaalmiddelen (typeCode, information, paymentReference)
content/delivery: leveringsgegevens
content: alle bovenstaande deelresources samen in één response
attachments / attachment/{attachmentId}/file: bijlagen van de import
status: verwerkingsstatus van de import
validation / validation/pdf: validatieresultaat

De import zelf verloopt asynchroon: een POST /import/incoming levert 202 Accepted met een importId voordat het parsen en valideren is afgerond. Vraag GET /import/incoming/{importId}/status op totdat overallStatus niet meer pending is, voordat u de content-endpoints uitleest.

Bij uitgaande geïmporteerde facturen (/import/outgoing) bevat content bovendien een references-blok met de referentienummers voor het hele document: orderNumber (bestelnummer van de koper), orderReferenceId (BT-13), buyerReferenceId (BT-10), shippingOrderNumber, supplierNumber, contractNumber, assignmentNumber en mandateReference (kenmerk van de SEPA-machtiging).

Terugkerende facturen

Terugkerende facturen worden in de interface van faktoora ingesteld; de stapsgewijze handleiding vindt u in het artikel Terugkerende facturen. Via de API is hiervoor het lees-endpoint GET /recurring-invoices beschikbaar: het levert de aangemaakte schema's (naam, frequentie, start-/einddatum, status, nextExecutionDate, gekoppeld factuursjabloon). Een endpoint om een schema via de API aan te maken of te wijzigen is in de API-referentie niet gedocumenteerd.

Bestandsuitwisseling: SFTP, FTP en WebDAV

Voor de uitwisseling van factuurbestanden via een map kunt u in de workflows een bestandsverbinding instellen. Als protocol zijn FTP, SFTP en WebDAV beschikbaar. U stelt dit in via de interface, niet via de API: de API-referentie bevat hiervoor geen endpoints.

Daarnaast zijn er nog twee manieren om een voorliggend systeem te koppelen:

Programmatisch via de API: factuurgegevens gestructureerd aanmaken met POST /invoices, of al gegenereerde e-factuurbestanden uploaden met POST /import/incoming of het overeenkomstige endpoint voor uitgaande facturen.
Per e-mail: zie Facturen ontvangen via uw eigen mailserver.

DATEV-integratie: omgaan met verschilbedragen

Bij de DATEV-export vereffent faktoora afrondingsverschillen tussen de som van de afzonderlijke factuurregels en het geconsolideerde factuurbedrag automatisch: wijkt de som van de regelbedragen af van het geconsolideerde bedrag, dan wordt het verschil verrekend met het bedrag van de eerste regel in de DATEV-grootboekexport, zodat de som van de geëxporteerde regels exact overeenkomt met het totale factuurbedrag.

Al geïntegreerde systemen

In de code en in bestaande kennisbankartikelen zijn koppelingen aangetoond met: DATEV, Xero, weclapp, HubSpot, Monday, PipeDrive en Bexio. Daarnaast bestaat er een Stripe-koppeling die Stripe-facturen en -klanten als facturen in faktoora synchroniseert; het automatisch aanmaken in het XRechnung-formaat is daarmee niet gedocumenteerd. Het uitvoerformaat van een factuur bepaalt u nog steeds zelf via het veld format of de accountinstellingen.

Was dit nuttig?