← API documentatie

Facturen API

Inhoud
GET /invoices

Facturen ophalen

Geeft een gepagineerde lijst van facturen. Alle filters zijn optioneel.

ParameterBeschrijving
invoice_numberZoekt op (een deel van) het factuurnummer.
statusdraft, sent, paid of overdue.
date_from, date_toFactuurdatum tussen twee datums. Geef beide mee.
total_amount_min, total_amount_maxTotaalbedrag tussen twee bedragen. Geef beide mee.
page, page_sizePaginering, standaard 15 per pagina.
Verzoek
curl "https://financial.gyvex.com/api/invoices?status=sent&page_size=25" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"
GET /invoices/{invoice}

Factuur ophalen

Geeft één factuur met de factuurregels. Voeg ?customer toe om ook de klantgegevens mee te krijgen.

Verzoek
curl "https://financial.gyvex.com/api/invoices/42?customer" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"
Antwoord 200 (ingekort)
{
  "id": 42,
  "invoice_number": "2026-0042",
  "date": "2026-11-18",
  "due_date": "2026-12-02",
  "status": "sent",
  "customer_id": 7,
  "project_id": null,
  "total_amount": 242.00,
  "items": [
    {
      "description": "Websiteonderhoud",
      "quantity": 2,
      "unit_price": 100.00,
      "vat_percentage": 21,
      "total": 242.00
    }
  ]
}
POST /invoice/store

Factuur aanmaken

Maakt een factuur met een of meer regels. Het totaalbedrag en de regeltotalen worden automatisch berekend.

VeldVerplichtBeschrijving
invoice_numberJaFactuurnummer (tekst).
dateJaFactuurdatum.
due_dateJaVervaldatum.
customer_idJaID van een van uw klanten.
statusJadraft, sent, paid of overdue.
project_idNeeID van een project.
itemsJaLijst met factuurregels (zie hieronder).
items[].descriptionJaOmschrijving van de regel.
items[].quantityJaAantal, minimaal 0.01.
items[].unit_priceJaPrijs per eenheid, excl. btw.
items[].vat_percentageNeeBtw-percentage, 0 tot 100.
Verzoek
curl -X POST "https://financial.gyvex.com/api/invoice/store" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "2026-0042",
    "date": "2026-11-18",
    "due_date": "2026-12-02",
    "customer_id": 7,
    "status": "sent",
    "items": [
      {
        "description": "Websiteonderhoud",
        "quantity": 2,
        "unit_price": 100,
        "vat_percentage": 21
      }
    ]
  }'

Bij succes ontvangt u status 201 met de aangemaakte factuur, inclusief id en regels.

PUT /invoice/{invoice}/update

Factuur bijwerken

Werkt een bestaande factuur bij. Alle factuurvelden zijn optioneel, maar als u items meestuurt, vervangen die alle bestaande regels. Geef elke regel daarom volledig mee, inclusief description, quantity, unit_price en total.

Anders dan bij aanmaken berekent het systeem bij bijwerken het totaal niet zelf. Stuur total per regel en, bij wijzigingen, total_amount voor de factuur dus zelf mee.

Verzoek
curl -X PUT "https://financial.gyvex.com/api/invoice/42/update" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2026-12-16",
    "total_amount": 363.00,
    "items": [
      {
        "description": "Websiteonderhoud",
        "quantity": 3,
        "unit_price": 100,
        "vat_percentage": 21,
        "total": 363.00
      }
    ]
  }'
POST /invoice/{invoice}/mark-paid

Factuur als betaald markeren

Zet de status van een factuur op paid. Regels en bedragen blijven ongewijzigd. Opnieuw aanroepen bij een betaalde factuur doet niets. Een factuur met status draft kan niet als betaald worden gemarkeerd (status 422).

Verzoek
curl -X POST "https://financial.gyvex.com/api/invoice/42/mark-paid" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"
GET /invoice/{invoice}/pdf

Factuur-PDF ophalen

Genereert de PDF van een factuur. De PDF zit als tekst in het veld pdf van het JSON-antwoord.

Antwoord 200
{
  "status": "success",
  "pdf": "..."
}
POST /invoice/{invoice}/send

Factuur per e-mail versturen

Zet een e-mail met de factuur-PDF als bijlage klaar voor de klant van de factuur. Hiervoor moeten uw e-mailinstellingen zijn geactiveerd en moet de klant een e-mailadres hebben, anders volgt status 422. Bij succes volgt status 202.

Parameter Beschrijving
subject Onderwerp, optioneel.
body Berichttekst, optioneel.
Verzoek
curl -X POST "https://financial.gyvex.com/api/invoice/42/send" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Uw factuur", "body": "Bijgaand uw factuur."}'
Antwoord 202
{
  "status": "queued",
  "recipient": "john.doe@example.com"
}
DELETE /invoice/{invoice}

Factuur verwijderen

Verwijdert een factuur. Bij succes volgt status 204 zonder inhoud.

Verzoek
curl -X DELETE "https://financial.gyvex.com/api/invoice/42" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"

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.