API documentatie

Facturen automatiseren met de e-facturatie API

Maak facturen, offertes en klanten aan en haal ze op vanuit uw eigen webshop, CRM of ERP. Een eenvoudige REST API met JSON, inbegrepen bij Premium zonder extra kosten.

Werkt u met Laravel? Gebruik dan onze Laravel package.

Eenvoudig te koppelen

REST en JSON. Elke ontwikkelaar begrijpt het binnen enkele minuten.

Veilig

Verbinding via HTTPS en persoonlijke API-sleutel die u zelf kunt vernieuwen.

Inbegrepen bij Premium

Geen extra kosten of credits voor het gebruik van de API.

Inhoud

Introductie

Met de Gyvex Financial API beheert u uw facturen, offertes en klanten vanuit uw eigen software. Alle endpoints werken met JSON en zijn bereikbaar via HTTPS.

Basis-URL
https://financial.gyvex.com/api
Premium vereist. De API is gratis te gebruiken, maar alleen beschikbaar met een actief Premium-account. Bekijk de prijzen.

Snel starten

  1. Zorg voor een Premium-account.
  2. Kopieer uw API-sleutel onder Instellingen → API.
  3. Stuur uw sleutel mee als Bearer token, zoals hieronder.
Voorbeeld: facturen ophalen
curl "https://financial.gyvex.com/api/invoices" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"

Authenticatie

Elk verzoek moet uw persoonlijke API-sleutel bevatten in de Authorization-header. Alleen gegevens van uw eigen account zijn toegankelijk.

Headers
Accept: application/json
Authorization: Bearer UW_API_SLEUTEL
Content-Type: application/json
  • Behandel uw sleutel als een wachtwoord: bewaar hem server-side en gebruik hem nooit in browsercode of een publieke repository.
  • Is uw sleutel gelekt? Genereer onder Instellingen → API een nieuwe. De oude werkt dan niet meer.
  • De sleutel kan ook als queryparameter api_token worden meegestuurd. Dat raden wij af, omdat URL's in logbestanden terechtkomen.

Verzoeken en antwoorden

  • Stuur bij POST en PUT een JSON-body mee met Content-Type: application/json.
  • Datums gebruiken het formaat JJJJ-MM-DD. Bedragen zijn getallen met een punt als decimaalteken (12.50).
  • Het btw-percentage van een regel (vat_percentage) geeft u op als 21 of 0.21. Beide betekenen 21%.
  • Het totaalbedrag en de regeltotalen berekent het systeem zelf, inclusief btw.

Paginering

Lijsten zijn gepagineerd. Gebruik page voor de pagina en page_size voor het aantal resultaten per pagina (standaard 15). Het antwoord bevat de resultaten in data, plus metagegevens zoals current_page, last_page, per_page en total.

Gepagineerd antwoord (ingekort)
{
  "current_page": 1,
  "data": [ { "id": 42, "invoice_number": "2026-0042" } ],
  "last_page": 3,
  "per_page": 15,
  "total": 38
}

Foutcodes en limieten

StatusBetekenis
200Gelukt.
201Aangemaakt. De nieuwe factuur, offerte of klant staat in het antwoord.
202Geaccepteerd. De actie staat in de wachtrij, bijvoorbeeld het versturen van een e-mail.
204Verwijderd. Het antwoord heeft geen inhoud.
401API-sleutel ontbreekt of is ongeldig.
403Geen Premium-account, of u mag deze factuur, offerte of klant niet gebruiken.
404De opgevraagde gegevens bestaan niet.
409Conflict. De actie kan niet, bijvoorbeeld een klant verwijderen die nog facturen of offertes heeft.
422Validatiefout. De invoer is onvolledig of ongeldig, zie errors in het antwoord.
429Te veel verzoeken. Probeer het over een minuut opnieuw.
Voorbeeld: validatiefout (422)
{
  "code": 422,
  "message": "Validation failed",
  "errors": {
    "invoice_number": ["The invoice number field is required."]
  }
}

Limiet: maximaal 60 verzoeken per minuut per account. Bij overschrijding ontvangt u status 429.

Hulp nodig bij uw koppeling?

Maak een ticket aan via "Mijn Gyvex" in uw dashboard. Met Premium krijgt u priority support, met reactie binnen 24 uur.