Van jouw software
naar een handtekening.

Toegang tot jouw werkruimte

De eigenaar of beheerder maakt bij Dashboard → Integraties een sleutel aan. Kies alleen de benodigde rechten. De sleutel werkt zolang hij niet is verlopen of ingetrokken, de maker nog toegang heeft als eigenaar of beheerder en de werkruimte een actief Onbeperkt-pakket heeft.

Authorization: Bearer oh_live_JOUW_SLEUTEL
Accept: application/json

Basis-URL: http://localhost:8888/api/v1. Bewaar de sleutel op je server; gebruik hem niet in browsercode. Productieverkeer gaat via HTTPS. Iedere sleutel kan maximaal 60 aanvragen per minuut doen. De headers X-RateLimit-Limit en X-RateLimit-Remaining tonen de limiet.

Datums zoals created_at en signed_at gebruiken de tijdzone Europe/Amsterdam. PDF-pagina’s hebben afmetingen in punten (72 punten per inch).

1. Upload een PDF

Gebruik multipart/form-data met een titel en bestand. De PDF mag maximaal 10 MB en 50 pagina’s bevatten en mag niet met een wachtwoord beveiligd zijn. Je hebt het recht documents:write nodig.

curl -X POST 'http://localhost:8888/api/v1/documents' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Idempotency-Key: crm-offerte-1042-upload' \
  -F 'title=Offerte 1042' \
  -F 'document=@offerte.pdf;type=application/pdf'

Het antwoord bevat data.id, data.revision, pagina-afmetingen en de status draft. Er is nog niets verstuurd.

2. Plaats ontvangers en velden

PATCH /documents/{id}/layout vervangt de volledige lijst ontvangers en velden. Stuur de laatste revision mee. De revision in het antwoord gebruik je bij de volgende wijziging of verzending. Maximaal 10 ontvangers met unieke e-mailadressen en 100 velden.

{
  "revision": 0,
  "recipients": [{
    "key": "r-klant1042", "name": "Robin de Vries",
    "email": "robin@example.nl"
  }],
  "fields": [{
    "id": "f-sign1042a", "type": "signature", "role": "signer",
    "recipientKey": "r-klant1042", "page": 1,
    "x": 0.12, "y": 0.70, "w": 0.40, "h": 0.12,
    "label": "Handtekening", "required": true, "fontSize": 12
  }]
}

Stuur deze JSON met Content-Type: application/json, Bearer-authenticatie en een nieuwe Idempotency-Key. Coördinaten x/y/w/h zijn fracties van de pagina tussen 0 en 1, gemeten vanaf linksboven; het volledige veld moet binnen de pagina passen.

Veldtypen: text, name, date, checkbox en signature. Met role: "sender" kun je eigen tekst vooraf invullen via value; gebruik daarvoor type text en recipientKey: null. Voor overige velden verwijst recipientKey naar een ontvanger. Een handtekening is altijd verplicht.

Minimale breedte × hoogte: handtekening 150 × 68 punten, vinkje 14 × 14, overige velden 45 × 22. Sleutels beginnen met r- of f-, gevolgd door 8–36 letters, cijfers of streepjes.

3. Verstuur en volg de status

POST /documents/{id}/send met {"revision": 1} zet het concept vast en plaatst per ontvanger een uitnodiging in de Mailgun-wachtrij. Hiervoor is documents:send nodig. Iedere ontvanger moet een handtekeningveld hebben. Een succesvolle aanvraag bevestigt het klaarzetten, niet de ontvangst van de e-mail.

Volg via GET /documents/{id} de status draft → ready → sent/viewed → signed. Controleer bijvoorbeeld iedere 30–60 seconden; er zijn nog geen uitgaande webhooks. Ontvangers gebruiken de persoonlijke link in hun e-mail om te tekenen.

Bij signed is GET /documents/{id}/file?variant=signed beschikbaar. Dit antwoord is een PDF-bestand. proof_code verwijst naar de verificatiepagina /controleren?code=…. Er wordt geen PDF-bijlage verstuurd. De bestands-URL vereist je Bearer-sleutel en is bedoeld voor je server.

Automatisch herinneren: PATCH /documents/{id}/reminders met {"enabled": true, "interval_days": 3, "max": 3}. Kies 1–14 dagen en maximaal 1–5 herinneringen. Het schema stopt bij ondertekening of een verlopen link.

Gebruik een opgeslagen sjabloon

Bewaar een concept als sjabloon in de PDF-editor. GET /templates geeft de beschikbare sjablonen met hun roles. Gebruik iedere roles[].key om nieuwe ontvangers toe te wijzen. Voor lezen is templates:read nodig; voor gebruiken templates:use.

POST /templates/12/documents
{
  "title": "Nieuwe opdracht voor Robin",
  "recipients": {
    "r-ROL_UIT_HET_SJABLOON": {
      "name": "Robin de Vries", "email": "robin@example.nl"
    }
  }
}

Het resultaat is een nieuw concept met nieuwe veld- en ontvangersleutels. Bewerk het indien nodig en verstuur vervolgens met de revision uit het antwoord. Ook deze POST vereist een Idempotency-Key.

Alle endpoints

Documentlijsten ondersteunen limit (1–100; standaard 25), status en before. Gebruik next_before uit het antwoord voor de volgende pagina; null betekent dat er geen volgende pagina is. Events tonen de laatste 100 gebeurtenissen, nieuwste eerst.

Fouten en veilig opnieuw proberen

Iedere POST en PATCH vereist een Idempotency-Key van 8–100 letters, cijfers, dubbele punten, streepjes of underscores. Gebruik één unieke waarde per wijziging. Herhaal na een verbindingsfout dezelfde aanvraag met dezelfde sleutel: je krijgt het opgeslagen antwoord terug, met Idempotency-Replayed: true, zonder een tweede document of uitnodiging te maken.

Een andere inhoud of route met dezelfde sleutel geeft 409. Als een aanvraag nog wordt gecontroleerd, wacht dan; maak geen nieuwe sleutel voor dezelfde actie. Na een definitieve validatiefout kun je de inhoud corrigeren en met een nieuwe sleutel proberen.

{"error":{"code":409,"message":"Het document is in een ander venster gewijzigd. Vernieuw deze pagina."}}

• 400 / 422 — ongeldige JSON, velden of ontbrekende Idempotency-Key.
• 401 / 403 — ontbrekende sleutel, onvoldoende rechten of geen actief pakket.
• 404 — niet beschikbaar binnen jouw werkruimte.
• 409 — versieconflict of een aanvraag die al wordt verwerkt.
• 413 / 415 — aanvraag te groot of verkeerd inhoudstype.
• 429 — limiet bereikt; wacht het aantal seconden in Retry-After.
• 500 — verwerking mislukt; bewaar de aanvraagcode voor onderzoek.