Public API

Developer API

Gebruik de publieke /api/v1 API om documenten aan te maken voor ondertekening via DebiSign.

Authenticatie

Alle publieke endpoints starten met /api/v1 en vereisen een API-key in de header X-Api-Key.

Base URL: https://your-domain.example.com/api/v1
Header:   X-Api-Key: your-api-key

Requests zonder API-key of met een ongeldige API-key worden geweigerd met 401 Unauthorized.

Configuratie endpoints

Gebruik deze read-only endpoints om de ID's op te halen die nodig kunnen zijn bij het aanmaken van documenten.

Endpoint	Beschrijving
GET`/api/v1/config/devices`	Geeft de beschikbare devices van de company terug.
GET`/api/v1/config/users`	Geeft gebruikers terug met enkel publieke velden zoals ID, naam, e-mailadres en status.
GET`/api/v1/config/emailtemplates`	Geeft e-mailtemplates terug zonder template-inhoud of interne configuratie.

GET /api/v1/config/devices

[
  {
    "Id": "33333333-3333-3333-3333-333333333333",
    "Name": "Front desk",
    "Receiver": "DEVICE1"
  }
]

GET /api/v1/config/users

[
  {
    "Id": "22222222-2222-2222-2222-222222222222",
    "DisplayName": "Jane Doe",
    "Email": "jane.doe@example.com"
  }
]

GET /api/v1/config/emailtemplates

[
  {
    "Id": "11111111-1111-1111-1111-111111111111",
    "Name": "Document to sign"
  }
]

Document endpoints

Documenten oplijsten

Geeft documenten terug die gekoppeld zijn aan de company van de API-key.

GET /api/v1/documents?isSigned=false&dtStartDate=2026-01-01&dtEndDate=2026-01-31&page=1&pageSize=50

Filter	Type	Opmerking
`isSigned`	boolean	Optioneel. Filter op ondertekend of niet ondertekend.
`dtStartDate`	date	Optioneel. Startdatum voor de creatiedatum.
`dtEndDate`	date	Optioneel. Einddatum voor de creatiedatum.
`page`	integer	Optioneel. Standaard `1`.
`pageSize`	integer	Optioneel. Standaard `50`, maximum `100`.

{
  "Documents": [
    {
      "Id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "ExternalReference": "ERP-2026-0001",
      "Name": "contract.pdf",
      "CreatedAt": "2026-01-10T09:30:00",
      "IsSigned": false,
      "SignedAt": null
    }
  ],
  "Page": 1,
  "PageSize": 50
}

Document aanmaken

Maakt een nieuw PDF-document aan. Als RecipientEmail en ID_TEMPLATE_TO_SIGN ingevuld zijn, wordt meteen de e-mail voor ondertekening verzonden. ID_TEMPLATE_SIGNED wordt gebruikt voor de e-mail na ondertekening.

POST /api/v1/documents
Content-Type: application/json
X-Api-Key: your-api-key

{
  "ExternalReference": "ERP-2026-0001",
  "Name": "contract.pdf",
  "PdfBase64": "JVBERi0xLjQK...",
  "UserId": "22222222-2222-2222-2222-222222222222",
  "DeviceId": "33333333-3333-3333-3333-333333333333",
  "ID_TEMPLATE_TO_SIGN": "44444444-4444-4444-4444-444444444444",
  "ID_TEMPLATE_SIGNED": "55555555-5555-5555-5555-555555555555",
  "RecipientName": "Jane Doe",
  "RecipientEmail": "jane.doe@example.com",
  "RecipientLanguage": "N",
  "CallbackUrl": "https://example.com/debisign/callback"
}

Veld	Verplicht	Beschrijving
`Name`	Ja	Bestandsnaam of documentnaam.
`PdfBase64`	Ja	Base64-inhoud van een geldig PDF-bestand. Een data-URL prefix wordt ook aanvaard.
`ExternalReference`	Nee	Eigen referentie uit het externe pakket.
`UserId`	Nee	ID van een gebruiker binnen dezelfde company.
`DeviceId`	Nee	ID van een device binnen dezelfde company.
`ID_TEMPLATE_TO_SIGN`	Nee	E-mailtemplate voor de uitnodiging tot ondertekening. Vereist samen met `RecipientEmail` om bij creatie een mail te verzenden.
`ID_TEMPLATE_SIGNED`	Nee	E-mailtemplate voor de mail nadat het document ondertekend is.
`EmailTemplateId`	Nee	Alias voor `ID_TEMPLATE_TO_SIGN`.
`RecipientEmail`	Nee	Moet een geldig e-mailadres zijn wanneer ingevuld.
`RecipientName`	Nee	Naam van de ontvanger.
`RecipientLanguage`	Nee	Taalcode voor de ontvanger. Gebruik dezelfde codes als intern: N voor Nederlands, F voor Frans en E voor Engels.
`CallbackUrl`	Nee	Wordt gevalideerd indien meegestuurd, maar de effectieve callback URL wordt centraal ingesteld via `/Settings/API` en niet per document opgeslagen.

{
  "Id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "ExternalReference": "ERP-2026-0001",
  "Status": "created",
  "CreatedAt": "2026-01-10T09:30:00",
  "SignUrl": "https://your-domain.example.com/Sign/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}

Documentdetails opvragen

GET /api/v1/documents/{id}

{
  "Id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "ExternalReference": "ERP-2026-0001",
  "Name": "contract.pdf",
  "CreatedAt": "2026-01-10T09:30:00",
  "IsSigned": false,
  "SignedAt": null,
  "PdfUrl": "/api/v1/documents/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/pdf",
  "SignUrl": "https://your-domain.example.com/Sign/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}

PDF downloaden

GET /api/v1/documents/{id}/pdf

Geeft enkel de PDF-inhoud terug met content type application/pdf. Documenten van een andere company geven 404 Not Found terug.

CallbackUrl

De effectieve callback URL wordt ingesteld per company via /Settings/API. Wanneer een document ondertekend wordt, verstuurt DebiSign een document.signed notificatie naar deze publieke HTTPS-url. Lokale adressen, loopback-adressen en private IP-ranges worden geweigerd.

{
  "event": "document.signed",
  "documentId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "externalReference": "ERP-2026-0001",
  "signedAt": "2026-01-10T10:15:00",
  "pdfUrl": "https://your-domain.example.com/api/v1/documents/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/pdf",
  "signUrl": "https://your-domain.example.com/Sign/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}

Error responses

Status	Wanneer
`400 Bad Request`	Ongeldige input, bijvoorbeeld ontbrekende `Name`, ongeldige `PdfBase64`, ongeldig e-mailadres of een ID die niet bij de company hoort.
`401 Unauthorized`	Ontbrekende of ongeldige API-key.
`404 Not Found`	Document niet gevonden, of niet toegankelijk voor de company van de API-key.
`500 Internal Server Error`	Onverwachte serverfout.

{
  "Message": "RecipientEmail bevat geen geldig e-mailadres."
}

Security

Bewaar API-keys nooit in client-side code of publieke repositories.
Gebruik altijd HTTPS.
Alle configuratie- en documentgegevens zijn company-scoped op basis van de API-key.

Support

Contacteer DebiSign via dev@debisign.be met de gebruikte endpoint, timestamp, request-ID indien beschikbaar en een korte omschrijving van het probleem.