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.
https://financial.gyvex.com/api
Snel starten
- Zorg voor een Premium-account.
- Kopieer uw API-sleutel onder Instellingen → API.
- Stuur uw sleutel mee als Bearer token, zoals hieronder.
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.
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_tokenworden meegestuurd. Dat raden wij af, omdat URL's in logbestanden terechtkomen.
Verzoeken en antwoorden
- Stuur bij
POSTenPUTeen JSON-body mee metContent-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 als21of0.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.
{
"current_page": 1,
"data": [ { "id": 42, "invoice_number": "2026-0042" } ],
"last_page": 3,
"per_page": 15,
"total": 38
}
Foutcodes en limieten
| Status | Betekenis |
|---|---|
| 200 | Gelukt. |
| 201 | Aangemaakt. De nieuwe factuur, offerte of klant staat in het antwoord. |
| 202 | Geaccepteerd. De actie staat in de wachtrij, bijvoorbeeld het versturen van een e-mail. |
| 204 | Verwijderd. Het antwoord heeft geen inhoud. |
| 401 | API-sleutel ontbreekt of is ongeldig. |
| 403 | Geen Premium-account, of u mag deze factuur, offerte of klant niet gebruiken. |
| 404 | De opgevraagde gegevens bestaan niet. |
| 409 | Conflict. De actie kan niet, bijvoorbeeld een klant verwijderen die nog facturen of offertes heeft. |
| 422 | Validatiefout. De invoer is onvolledig of ongeldig, zie errors in het antwoord. |
| 429 | Te veel verzoeken. Probeer het over een minuut opnieuw. |
{
"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.