Tidvis Sign Public API

Hurtigstart

Base URL: https://tidvis.se/api/public/v1. Alle kall bruker JSON. Public API er del av Enterprise-planen.

1. 1. Opprett en API-klient under Sign → Innstillinger → API og lagre client_id og client_secret.
2. 2. Bytt dem mot et access_token via OAuth2 client credentials.
3. 3. Opprett en avtale, last opp en PDF, legg til deltakere og send.

curl -X POST https://tidvis.se/api/public/v1/oauth/access-token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"tvc_...","client_secret":"tvs_..."}'

Autentisering

OAuth2 client credentials. Bytt client_id+client_secret mot en JWT som er gyldig i 1 time. Send Authorization: Bearer <access_token> på alle påfølgende kall.

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-06-07T13:00:00.000Z"
}

Avtaler

curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Arbeidsavtale Anna","expires_in_days":14,"bankid_required":true}'

Deltakere

{
  "name": "Anna Andersson",
  "email": "anna@example.com",
  "role": "signer"
}

PDF-dokumenter

# JSON / base64
curl -X PUT https://tidvis.se/api/public/v1/agreements/$ID/documents/main \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"avtale.pdf","content_base64":"JVBERi0..."}'

# Eller binært
curl -X PUT https://tidvis.se/api/public/v1/agreements/$ID/documents/main \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @avtale.pdf

Livssyklus

{"action": "send"}   // eller "cancel"

BankID

Du kan kreve svensk BankID-signering per avtale. Sett bankid_required: true ved opprettelse (eller via PATCH før sending). Når avtalen sendes signerer hver deltaker med BankID på mobil eller desktop i stedet for å tegne sin signatur.

curl -X POST https://tidvis.se/api/public/v1/agreements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Arbeidsavtale Anna",
    "bankid_required": true
  }'

{
  "id": "agr_...",
  "status": "draft",
  "bankid_required": true,
  "document": { "uploaded": false, "sha256": null },
  "participants": []
}

{
  "event": "agreement.signed",
  "agreement_id": "agr_...",
  "participant": { "id": "p_...", "email": "anna@example.com" },
  "signature": {
    "method": "bankid",
    "signer_name": "Anna Andersson",
    "signed_at": "2026-06-11T08:42:11.000Z"
  }
}

Webhooks

Tidvis leverer hendelser til din URL via POST JSON. Hvert kall er signert med HMAC-SHA256 i headeren X-Tidvis-Signature: sha256=<hex> basert på din signing_secret og raw body. Mislykkede leveranser forsøkes på nytt med eksponentiell backoff i opptil 24t.

{
  "client_id": "<api_client uuid>",
  "url": "https://din-app.no/webhooks/tidvis",
  "events": ["agreement.sent","agreement.signed","agreement.completed"]
}

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const given = (header || "").replace(/^sha256=/, "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(given));
}

Feilkoder

Rate-grenser

Standardgrense: 60 kall/minutt per klient og 600/time for opplastinger. Ved overskridelse får du 429 rate_limited med Retry-After-header. Trenger du mer? Kontakt oss.