Factuurgeneratie-API
Genereer programmatisch professionele factuur-PDF's vanaf uw eigen server — geschikt voor interne systemen, marktplaatsen of uw eigen SaaS-product.
1. Authenticatie#
Maak een API-sleutel aan op app.invosend.com/settings/api-keys. Een betaald werkruimteplan en eigenaarsrol zijn vereist.
Verstuur de sleutel als Bearer-token in de Authorization-header bij elk verzoek:
Authorization: Bearer isk_live_xxxxxxxxxxxxxxxxxxxxxxxx403. Sleutels worden ook geweigerd als de werkruimte een gratis plan heeft, is opgeschort of is verlopen.2. Endpoint#
Basis-URL: https://app.invosend.com
Machineleesbare API-beschrijving: OpenAPI 3.1 en Postman collection. Importeer een van beide in Postman, Insomnia of een SDK-generator.
3. Aanvraagbody#
Volledig verzoekvoorbeeld:
curl -X POST https://app.invosend.com/api/invoices/generate-external \
-H "Authorization: Bearer isk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"customer_name": "Acme Corp",
"customer_email": "billing@acme.com",
"items": [
{ "description": "Consulting Services", "quantity": 2, "price": 500, "tax_rate": 11 }
],
"discount_total": 50,
"currency": "EUR",
"notes": "Thank you for your business."
}'Voorbeeld van een terugkerende factuur (de eerste nu, daarna elke maand één, in totaal 6):
curl -X POST https://app.invosend.com/api/invoices/generate-external \
-H "Authorization: Bearer isk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"customer_name": "Acme Corp",
"customer_email": "billing@acme.com",
"items": [
{ "description": "Monthly retainer", "quantity": 1, "price": 2500 }
],
"currency": "EUR",
"recurring_interval": "monthly",
"recurring_count": 6
}'Idempotency-Key-header toe (1-255 tekens, bijvoorbeeld een UUID die u per factuur genereert). Als het eerste verzoek is gelukt, geeft de nieuwe poging hetzelfde antwoord terug met de header Idempotent-Replayed: true, zonder nog een factuur te maken of nog een tegoed te gebruiken (credits_remaining is de waarde van de eerste aanroep). Sleutels worden 24 uur per werkruimte bewaard. Alleen geslaagde antwoorden worden opgeslagen, dus een mislukt verzoek kunt u met dezelfde sleutel opnieuw proberen.4. Antwoord#
200 OK betekent dat de factuur is aangemaakt en de PDF is gegenereerd:
{
"data": {
"id": "cjld2cjxh0000qzrmn831i7rn",
"invoice_number": "INV-1-202609-0016",
"pdf_url": "https://cdn.invosend.com/company/1/pdf/Invoice_INV_1_202609_0016_UNPAID_0da2beeabb.pdf",
"credits_remaining": 24,
"is_recurring": false,
"template": {
"id": "k3p9x2m7c0000abcd1234efgh",
"name": "Classic",
"source": "system_default"
}
}
}credits_remaining is null wanneer de werkruimte een onbeperkt quotum heeft. id identificeert deze factuur voor de onderstaande aanvullende endpoints. Facturen die via deze API zijn aangemaakt, verschijnen ook in de factuurlijst van de werkruimte en gebruiken dezelfde factuurnummerreeks als handmatig aangemaakte facturen. Factuurnummers hebben de vorm INV-{workspace-id}-{JJJJMM}-{volgnummer}. Bij een terugkerende factuur bevat het antwoord ook een recurring-object: schedule_id, interval, occurrences, next_issue_date, end_date. recurring.schedule_id is de id die u met de terugkerende endpoints hieronder gebruikt.5. Foutcodes#
6. Rate limit#
X-RateLimit-Limit en X-RateLimit-Remaining. API-quota van de workspace worden per lidmaatschapsabonnement in Invosend ingesteld. Meer productievolume nodig? Neem contact met ons op via uw workspace-account. Ingetrokken sleutels tellen niet mee voor de sleutellimiet.7. Aanvullende endpoints#
Dezelfde API-sleutel kan ook facturen lezen en beheren die via generate-external zijn aangemaakt:
payment_gateway (en optioneel payment_account) in bij generate-external en stuurt u uw klant de openbare betaalpagina van de factuur: https://app.invosend.com/p/invoice/{id}, met de id die de API teruggeeft. Daar betaalt de klant via de gekoppelde gateway en wordt de factuur automatisch als betaald gemarkeerd. De checkout wordt door die pagina afgehandeld; er is geen apart openbaar checkout-endpoint om aan te roepen.8. Webhooks#
Registreer in plaats van te pollen een HTTPS-URL: Invosend stuurt er een POST-verzoek met JSON-body naartoe wanneer een factuur verandert. Voeg endpoints toe via Instellingen > Webhooks (eigenaar van de werkruimte, abonnement met API-toegang, maximaal 5 endpoints). Elk endpoint heeft een eigen handtekeninggeheim, dat maar één keer wordt getoond.
Gebeurtenissen worden verstuurd voor facturen die in het dashboard en via deze API zijn gemaakt. Sjablonen van terugkerende reeksen worden nooit verstuurd.
Elke gebeurtenis heeft dezelfde envelop. data.object is de factuur, in dezelfde vorm als GET /api/invoices/external/:id; statusgebeurtenissen bevatten ook data.previous_status:
{
"id": "evt_9f2c1b7a4e3d5c6b8a1f0e2d",
"object": "event",
"type": "invoice.paid",
"created": "2026-10-01T09:30:12.000Z",
"data": {
"object": {
"id": "cjld2cjxh0000qzrmn831i7rn",
"invoice_number": "INV-1-202610-0007",
"customer_name": "Acme Corp",
"customer_email": "billing@acme.com",
"currency": "USD",
"subtotal": 500,
"discount_total": 0,
"tax_rate": 0,
"tax_amount": 0,
"amount": 500,
"amount_paid": 500,
"amount_credited": 0,
"amount_received": 500,
"invoice_status": "paid",
"is_archived": false,
"is_recurring": false,
"recurring_interval": "none",
"issue_date": "2026-10-01T02:15:40.000Z",
"due_date": "2026-10-15",
"paid_at": "2026-10-01T09:30:11.000Z",
"pdf_url": "https://cdn.invosend.com/company/1/pdf/Invoice_INV_1_202610_0007_PAID.pdf",
"pdf_status": "ready"
},
"previous_status": "unpaid"
}
}Elk verzoek bevat deze headers. Om het te controleren berekent u een HMAC-SHA256 van {t}.{ruwe body} met het geheim van het endpoint en vergelijkt u dat met v1; weiger het verzoek als t ouder is dan 5 minuten:
POST /your/webhook/url
Content-Type: application/json
Invosend-Event: invoice.paid
Invosend-Delivery: evt_9f2c1b7a4e3d5c6b8a1f0e2d
Invosend-Signature: t=1790847012,v1=5b1d...e9a2
// Node.js
import crypto from "crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(parts.t + "." + rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}2xx-status. Anders wordt het tot 7 keer opnieuw geprobeerd (na 1 minuut, 5 minuten, 30 minuten, 2 uur, 6 uur, 12 uur en 24 uur). Een endpoint dat blijft falen wordt uitgeschakeld en u krijgt een melding. Een gebeurtenis kan meer dan eens of in andere volgorde binnenkomen: negeer duplicaten via de id van de gebeurtenis en beschouw invoice_status als leidend. Bezorglogboeken worden 30 dagen bewaard en elke gebeurtenis kunt u opnieuw versturen via Instellingen > Webhooks.9. Beperkingen#
Deze API is bewust beperkt tot factuurgeneratie en lichte factuurbeheer. Het volgende is nog niet beschikbaar:
- Webhooks omvatten alleen aangemaakte, betaalde, achterstallige en geannuleerde facturen. Andere wijzigingen, zoals bewerken of archiveren, worden niet verstuurd: lees de huidige status met
GET /invoices/external/:id. - De factuur die met elk verzoek wordt aangemaakt, wordt niet per e-mail verstuurd: deze API genereert alleen de pdf, dus het bezorgen bij uw klant is aan u (of gebruik het dashboard). Uitzondering zijn terugkerende reeksen: elke vervolgfactuur die de planner genereert, wordt automatisch naar
customer_emailgestuurd. - Geen bewerking van een factuur na aanmaak — alleen de status en archiveringsstatus kunnen via deze API worden gewijzigd.
- Ondersteuning voor betaalgateways vereist dat de gateway al is verbonden in het dashboard; deze API koppelt deze alleen aan de factuur, het verbindt geen gateway op zichzelf.
- Een terugkerende reeks kan via de API worden gepauzeerd, hervat, verlengd, anders gepland en komende herhalingen kunnen worden overgeslagen, maar de inhoud (regels, klant, bedragen) kan niet worden bewerkt en de reeks kan niet via de API worden verwijderd; doe dat in het dashboard.
Veelgestelde vragen#
Hoe krijg ik een Invosend API-sleutel?
Maak een account aan op app.invosend.com, upgrade de werkruimte naar een betaald plan, open dan Settings > API Keys en klik op Generate key. De ruwe sleutel wordt slechts één keer getoond bij het aanmaken.
Hoeveel kost elke aanroep van de factuurgeneratie-API?
Elke succesvolle aanvraag trekt 1 factuurtegoed af van uw werkruimtesaldo. Het gebruikt dezelfde factuurtegoedpool als facturen die via het dashboard zijn aangemaakt.
Wat is de rate limit voor deze API?
De rate limit van de workspace volgt de configuratie van uw betaalde abonnement. In de sectie Rate Limit hierboven staat de actuele limiet per abonnement.