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_..."}'

Én modell — API og plattform er samme avtale

Avtaler opprettet via API-et ligger i samme tabell og deler hele infrastrukturen med avtaler opprettet i web-UI-et:

• Vises direkte i plattformen under fanen Via integration i /app/sign/dokument.
• Kan åpnes, patches, purres og avbrytes både via API og i UI-et.
• Inngår i samme auto-påminnelses-cron, arkiv og 18-måneders retensjon som native-avtaler.
• Signeringslenken er alltid https://tidvis.se/sign/<token> — samme flyt som avtaler laget i plattformen.
• UI viser en Via {external_source}-badge (klikkbar når external_url er satt) så admin kan hoppe tilbake til CRM-posten.
• Send med sender i requesten så autosigneres avsenderen ved send — samme oppførsel som plattform-UI:et.

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}'

Poll signeringsstatus

Tidvis Sign har ingen egen /status-ressurs — GET /agreements/:id er pollingendepunktet. Responsen inneholder avtalens status samt participants[].status og signed_at per part, så du kan vise f.eks. "1 av 2 har signert" i ditt eget UI uten å vente på webhook.

Anbefaling: bruk webhooks (agreement.viewed, agreement.signed, agreement.completed) som primær kanal og fall tilbake på polling hvert 30. sekund når webhook ikke er et alternativ. Avtalestatus kan være draft, sent, partially_signed, completed, declined eller cancelled.

# Poll status og tell signerte
curl -s https://tidvis.se/api/public/v1/agreements/$ID \
  -H "Authorization: Bearer $TOKEN" \
  | jq '{
      status,
      signed: ([.participants[] | select(.status == "signed")] | length),
      total: (.participants | length),
      participants: [.participants[] | {name, email, status, signed_at}]
    }'

{
  "status": "partially_signed",
  "signed": 1,
  "total": 2,
  "participants": [
    { "name": "Anna Andersson", "email": "anna@example.com", "status": "signed",  "signed_at": "2026-06-17T09:14:22Z" },
    { "name": "Erik Eriksson",  "email": "erik@example.com",  "status": "viewed",  "signed_at": null }
  ]
}

Deltakere

{
  "name": "Anna Andersson",
  "email": "anna@example.com",
  "role": "signer",
  "job_title": "Daglig leder",
  "phone": "+4791234567",
  "personal_id_masked": "19800101-XXXX",
  "notifications_enabled": true
}

{ "reason": "Vilkårene er ikke akseptable" }

{
  "name": "Erik Eriksson",
  "email": "erik@example.com",
  "job_title": "Finansdirektør",
  "phone": "+4790123456",
  "message": "Henviser til Erik som håndterer signering."
}

{ "enabled": false }

{
  "body": "Hei, kan dere se gjennom vedlegg 2?",
  "sender_label": "Tidvis Sign Agent",
  "participant_id": "8a3..."
}

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"
  }
}

BankID-identifisering før åpning

Eget tillegg som tvinger mottakeren til å legitimere seg med BankID før dokumentet vises. Det er en gate foran selve PDF-en og er uavhengig av valgt signaturmetode — du kan altså kreve BankID-legitimering og fortsatt la signeringen skje med engangskode på e-post, klikk-signatur eller tegnet signatur. Kombineres gjerne med bankid_required: true når du vil ha både identifisering før åpning og BankID-signering ved undertegning.

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

{
  "id": "agr_...",
  "status": "draft",
  "bankid_required": false,
  "bankid_identify_required": true,
  "participants": []
}

{
  "event": "agreement.identified",
  "agreement_id": "agr_...",
  "participant": { "id": "p_...", "email": "anna@example.com" },
  "identification": {
    "method": "bankid",
    "signer_name": "Anna Andersson",
    "identified_at": "2026-06-12T10:21:04.000Z"
  }
}

Avtalegenerator

Bygg en AI-drevet avtalemal fra 2–10 eksempelavtaler og generer deretter nye avtaler med ett kall. Genererte avtaler kan lastes ned som DOCX ellersendes direkte til signering via Sign — i så fall får du tilbake en sign_document_id.

curl -X POST https://tidvis.se/api/public/v1/agreement-templates \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=Konsulentavtale" \
  -F "files=@eksempel1.pdf" \
  -F "files=@eksempel2.pdf" \
  -F "files=@eksempel3.docx"

{
  "values": {
    "kunde_navn": "Acme AS",
    "belop": 45000,
    "startdato": "2026-08-01"
  },
  "send_for_signing": true,
  "signature_method": "bankid",
  "recipients": [
    { "name": "Anna Andersen", "email": "anna@acme.no" }
  ]
}

Fullstendige request/response-skjemaer finnes i OpenAPI-referansen.

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.