API-dokumentasjon

Kom i gang

1. Lag en testnøkkel under Konto → Utvikler. Testnøkler (sk_test_…) signerer mot testmiljøet: ekte signeringsflyt, men ingen betaling, ingen kvote og ingen ekte penger.
2. Last opp PDF-en med POST /v1/documents.
3. Opprett signeringen med POST /v1/signature_requests.
4. Registrer et webhook-endepunkt, så sier vi fra når dokumentet er ferdig signert.
5. Bytt til en live-nøkkel (sk_live_…) når alt virker.

Autentisering

Send nøkkelen som bearer-token. Hver nøkkel har et sett tilganger (scopes) — den kommer ikke til endepunkter den ikke har fått tilgang til, og en nøkkel kan aldri lage en ny nøkkel.

Authorization: Bearer sk_live_...

Idempotens

Send en Idempotency-Key på alle POST-kall. Faller nettet ut midt i et kall, kan du trygt prøve på nytt med samme nøkkel: du får det opprinnelige svaret tilbake i stedet for en ny signeringsforespørsel. Samme nøkkel med et annet innhold gir 422 — det er en feil hos deg, og vi skjuler den ikke.

curl https://esigner.no/api/v1/signature_requests \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "<fra POST /v1/documents>",
    "signers": [{ "name": "Ola Nordmann", "email": "ola@example.no" }],
    "useSubscription": true
  }'

Endepunkter

• POST/v1/documents

  Upload the PDF(s) to be signed

  multipart/form-data. Fields: ownerEmail, and one or more files (PDF). Returns the document id.

• GET/v1/events

  List events

  The same events delivered to your webhook endpoints, newest first. Useful for backfilling after downtime.

• POST/v1/signature_requests

  Create a signature request

  Sends the document to each signer for BankID/eID signing. Pass an Idempotency-Key header to make retries safe.

• GET/v1/signature_requests/{id}

  Retrieve a signature request

Full maskinlesbar spesifikasjon (OpenAPI 3.1): /api/v1/openapi.json

Webhooks

Vi POSTer hendelser til adressen din og signerer hver leveranse med Esigner-Signature: t=<unix>,v1=<hmac>. HMAC-en er over <t>.<rå body>, så en fanget melding ikke kan spilles av på nytt med et annet tidsstempel. Verifiser alltid før du stoler på innholdet.

Hendelser: document.completed, document.signing_failed, order.captured. Feiler en levering, prøver vi på nytt med økende mellomrom (1 min → 6 t). Svarer endepunktet ikke over tid, deaktiverer vi det og sier fra på e-post — hendelsene går ikke tapt, og du kan sende dem på nytt.

// Verifiser Esigner-Signature: t=<unix>,v1=<hmac>
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}