Pakket aanmaken

#Wat is een pakket

Een ondertekeningspakket is een logische groepering van één of meerdere PDF-documenten die elektronische handtekeningen vereisen van aangewezen individuen, binnen deze context aangeduid als contacten. Elk pakket functioneert als een alomvattende eenheid die de documenten en bijbehorende metadata voor het ondertekeningsproces onderhoudt.

#Pakket aanmaken (package create)

Door middel van onderstaande API aanroep kan een een nieuw pakket worden aangemaakt. 

curl -X POST '[base_url]/v1/packages' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_token_here' \
--data-raw '{
    "name": "Contract",
    "creator_email": "johndoe@somecompany.com",
    "contacts": [
        {
            "email": "firstguy@othercompany.com",
            "first_name": "First",
            "last_name": "Guy",
        },
        // additional contacts go here...
    ],
    "documents": [
        {
            "filename": "contract_1.pdf",
            "data": "base64 encoded pdf data"
        },
        // additional documents go here...
    ]
}'

#Velden

  1. name De naam van het ondertekenverzoek.
  2. creator_email Het e-mailadres van de maker van het ondertekenverzoek. vereist
  3. webhook_url De URL waar notificaties naartoe gestuurd worden bij updates van het ondertekenverzoek.
  4. return_url De URL waar de gebruiker naartoe gestuurd wordt na het ondertekenen.
  5. access Wie toegang heeft tot het ondertekenverzoek. Waarden: 'team' of 'admins' (default).
  6. meta_data Aanvullende metadata voor later gebruik.
  7. expires_at Verloopdatum van het ondertekenverzoek. Indien niet ingesteld, is de standaard 14 dagen.
  1. contacts.*.email Het e-mailadres. vereist
  2. contacts.*.mobile Het mobiele telefoonnummer indien 2-factor vereist.
  3. contacts.*.first_name De voornaam.
  4. contacts.*.last_name De achternaam.
  5. contacts.*.filling_group De ondertekenvolgorde van een contactpersoon.
  6. contacts.*.invite_by De uitnodigingsmethode. Waarden: 'none' of 'email' (default).
  7. contacts.*.meta_data Eventuele aanvullende metadata voor later gebruik.
  1. documents.*.filename De bestandsnaam van een document. vereist
  2. documents.*.data Base64-gecodeerde inhoud van een PDF-document. vereist
  3. documents.*.meta_data Eventuele aanvullende metadata voor later gebruik.

#De maker doorsturen

Na het aanmaken van een ondertekeningspakket via de API, wordt in de responsedata onder de meta sectie een redirect key meegeleverd. Deze key is essentieel voor het vervolgproces en wijst op de volgende stappen die de gebruiker moet ondernemen.

De API response zal een JSON-object zijn zoals het voorbeeld hieronder: 

{
    // rest of the response
    "meta": {
        "redirect": "url_the_user_needs_to_be_redirected_to"
    }
}

De URL vermeld onder de redirect key dient als de bestemming waar de gebruiker naartoe geleid moet worden na het succesvol aanmaken van een pakket. Deze URL leidt de gebruiker naar de editor weergave van het aangemaakte ondertekeningspakket. Binnen deze omgeving kan de gebruiker:

  1. Interactieve velden aan het document toevoegen.
  2. Velden positioneren waar de contacten (ondertekenaars) hun informatie kunnen invoeren.
  3. Handtekeningvelden en andere vereiste informatie configureren.
  4. De ondertekenaars uitnodigen.
Deze editor weergave is cruciaal voor het nauwkeurig voorbereiden van de documenten die ondertekend moeten worden. Het is dus van belang dat de gebruiker onmiddellijk na het aanmaakproces naar deze editor omgeleid wordt.

#Onderteken volgorde

In het proces van digitale documentondertekening is het optioneel om gebruik te maken van 'filling groups'. Deze invulgroepen kunnen worden toegepast om een gestructureerde volgorde van ondertekening vast te stellen. Elke ondertekenaar kan aan een specifieke groep worden toegewezen, wat invloed heeft op het moment waarop de uitnodiging tot ondertekening wordt verzonden. Het systeem is flexibel; ondertekenaars kunnen dezelfde groep delen of toegewezen worden aan verschillende groepen om sequentiële handtekeningen te faciliteren. 

{
    // rest of the request
    "contacts": [
        {
            "email": "contact@example.com",
            "invite_by": "none",
            "filling_group": 1
        }
        // additional contacts can be added here
    ],
    // rest of the request
}

In dit voorbeeld betekent "filling_group": 1 dat de ondertekenaar is ingedeeld in de eerste groep. Indien een ondertekenaar geen specifieke volgorde hoeft te volgen, kunnen alle ondertekenaars aan dezelfde groep worden toegewezen, bijvoorbeeld groep 1. Het is van belang om te begrijpen dat uitnodigingen voor de volgende groep pas worden verstuurd nadat alle ondertekeningen in de voorafgaande groep zijn voltooid. Dit mechanisme zorgt ervoor dat ondertekenaars alleen benaderd worden wanneer het hun beurt is. Indien alle ondertekenaars gelijktijdig mogen ondertekenen, kan de 'filling group'-functie op eenzelfde waarde worden ingesteld, waarmee het gelijktijdige proces wordt gefaciliteerd.

#Uitnodigingsmethode

Elk contact heeft een invite_by sleutel die bepaalt hoe de uitnodiging om actie te ondernemen wordt verstuurd. Er zijn twee mogelijke waarden voor deze sleutel: email of none.

Indien de waarde is ingesteld op email, zal het systeem automatisch een uitnodigingsemail naar het contact sturen. Dit is de standaard en meest gebruikte methode, omdat het zorgt voor een directe en eenvoudige manier om de ontvanger te bereiken en te activeren.

De waarde none wordt gebruikt in specifieke gevallen waarbij geen directe uitnodiging vereist is. Dit kan zijn wanneer een andere applicatie zelf de uitnodiging verstuurt o.b.v. de filling_urls die via de API kunnen worden opgehaald. Zie hiervoor de sectie pakket raadplegen.

De waarde 'none' mag alleen gebruikt worden door gevalideerde app registraties.
window.hljs.highlightAll();