API

#Introductie

De API van Legalsign is zorgvuldig ontworpen met ontwikkelaars in gedachten, om de integratie van elektronische handtekeningfunctionaliteiten in hun applicaties te vereenvoudigen. Deze biedt een helder gestructureerde benadering voor het invoegen van digitale PDF-handtekeningsmogelijkheden in de bestaande workflows van de desbetreffende software.

#App registratie

Als ontwikkelaar heb je de keuze uit twee verschillende integratiemethoden, afhankelijk van de behoeften en het gebruiksscenario van je organisatie. Hieronder worden beide opties uitgelegd, zodat je kunt bepalen welke aanpak het beste aansluit bij je projectvereisten.

#Private app

Een Private App is een integratiemethode die uitsluitend is bedoeld voor gebruik binnen één specifieke organisatie. Deze benadering is geoptimaliseerd voor bedrijven die maatwerkoplossingen nodig hebben, zonder deze te delen met externe partijen.

Voor pakketten gegenereerd via een Private App integratie is het niet mogelijk om onderteken-URL's te genereren. Deze restrictie voorkomt dat ontwikkelaars in staat zijn om namens een ondertekenaar acties uit te voeren.

#Gevalideerde app

Een Gevalideerde App is een integratie die door het organisation van Legalsign is gecertificeerd en daardoor beschikbaar wordt gesteld voor gebruik door meerdere organisaties. Neem hiervoor contact op met support@legalsign.app.

#Webhook configuration

Bij de integratie van zowel een Private App als een Gevalideerde App met Legalsign is het noodzakelijk om tijdens het registratieproces een webhook endpoint op te geven. Dit endpoint is de bestemming waar de notificaties van onderteken-events worden afgeleverd. Je kunt ook een gedeeld geheim (shared secret) instellen dat door Legalsign wordt gebruikt om de webhook-notificaties digitaal te ondertekenen met een SHA512-hash, welke wordt meegezonden in een HTTP-header. Dit verhoogt de beveiliging door de integriteit en de authenticiteit van de ontvangen data te waarborgen.

#Base URL

De base URL voor alle API-aanroepen is: 

https://legalsign.app/api/external

Om een aanroep te doen richting de V1 versie van de Legalsign API, voeg je '/v1' toe aan het einde van de base URL: 

https://legalsign.app/api/external/v1

#API Key verkrijgen

Voor toegang tot de Legalsign API is een API-sleutel vereist. Deze sleutel moet als een 'Authorization' header worden meegezonden bij elke aanroep. Het formaat van de header is als volgt: 

Authorization: Token your_api_key

De API-sleutel kan verkregen worden via de instellingenpagina van je Legalsign-account. Na inloggen navigeer je naar 'Instellingen' > 'API en Webhooks' > 'API sleutel genereren'.

#Webhooks

Webhooks zijn HTTP callbacks die automatisch worden verstuurd naar het opgegeven endpoint, wanneer er een specifieke gebeurtenis plaatsvindt in je Legalsign-account. Bijvoorbeeld, wanneer een document is ondertekend of afgewezen. Dit maakt real-time integratie mogelijk zonder constant te hoeven pollen naar updates.

Het wordt sterk aangeraden om webhook verzoeken te valideren door middel van de sha512 signing hash. Dit zorgt ervoor dat de verzoeken werkelijk afkomstig zijn van Legalsign.

#Events

Legalsign's webhook systeem ondersteunt de volgende event typen:

  1. contact.invited Verzonden wanneer een ondertekenaar wordt uitgenodigd.
  2. contact.reminded Verzonden als er een herinnering naar een ondertekenaar wordt gestuurd.
  3. package.opened Verzonden wanneer een pakket voor het wordt geopend door een ondertekenaar.
  4. field.filled Verzonden wanneer een veld in een document is ingevuld.
  5. contact.finished Verzonden wanneer een ondertekenaar alle benodigde velden heeft gevuld.
  6. package.sealed Verzonden wanneer het pakket volledig voltooid is en verzegeld.

#Webhook payload

De webhook payload is een JSON object dat informatie bevat over het specifieke event. Hier is een voorbeeld van hoe de payload eruitziet voor een package.opened event: 

[
    {
        "package_uuid": "123e4567-e89b-12d3-a456-426655440000",
        "contact_uuid": "123e4567-e89b-12d3-a456-426655440001",
        "event": "package.opened",
        "created_at": "2023-11-08T12:00:00Z"
    }
]
Het contact_uuid kan null zijn indien het om een event gaat dat niet in de context van een contact wordt afgevuurd. Bijvoorbeeld package.sealed.

#Retry mechanisme

Legalsign zal proberen de webhook te bezorgen volgens het onderstaande schema. Als de server van de ontvanger geen 200 OK respons terugstuurt, zal Legalsign de poging herhalen na de aangegeven tijdsperioden in seconden:

  1. Onmiddellijk na het event (0 minuten).
  2. Na 1 minuut.
  3. Na 5 minuten.
  4. Na 10 minuten.
  5. Na 30 minuten.
  6. Na 60 minuten.
  7. Na 5 uur.
  8. Na 15 uur.
  9. Na 24 uur.

Om succesvol webhooks te ontvangen, moet uw server correct ingesteld zijn om HTTP POST-verzoeken te verwerken. Bij ontvangst van een webhook, moet uw server reageren met een 200 OK HTTP status code om aan te geven dat de payload met succes is ontvangen en verwerkt. Als er geen 200 OK response wordt ontvangen, zal Legalsign de leveringspogingen voortzetten volgens het bovenstaande schema.

#Webhook signature

Voor extra beveiliging worden Legalsign webhooks geleverd met een X-Signature header. Deze handtekening kan worden gebruikt om te verifiëren dat de ontvangen webhooks daadwerkelijk van Legalsign komen en niet gewijzigd zijn tijdens de overdracht. Wanneer je server een webhook ontvangt, kun je deze de handtekening in de X-Signature header controleren om er zeker van te zijn dat de payload legitiem is. Dit wordt gedaan door een verwachte handtekening te genereren aan de hand van de ontvangen payload en een geheim dat alleen bekend is bij Legalsign en uw server. 

// de shared secret die ook bekend is bij Legalsign
$secret = 'my_secret_value';

// de ontvangen payload als een string
$payload = file_get_contents('php://input');

// genereren van de HMAC hash (should match the value in the X-Signature header)
$signature = hash_hmac('sha512', $payload, $secret);

#Limieten

Er zijn limieten van toepassing op het gebruik van de Legalsign API om overbelasting van het systeem te voorkomen. Het maximum aantal verzoeken dat je kunt versturen is afhankelijk van het type account dat je hebt. Raadpleeg de documentatie voor meer informatie over deze limieten.

window.hljs.highlightAll();