Tidvis Sign API – REST & Webhooks för e-signering

Snabbstart

Base URL: https://tidvis.se/api/public/v1. Alla anrop använder JSON. Public API är en del av Enterprise-planen.

1. Skapa en API-klient under Sign → Inställningar → API och spara client_id och client_secret.
2. Hämta en access_token via OAuth2 client credentials.
3. Skapa ett avtal, ladda upp en PDF, lägg till deltagare och skicka.

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. Du byter client_id+client_secret mot en JWT som är giltig i 1 timme. Skicka Authorization: Bearer <access_token> på alla efterföljande anrop.

POST/oauth/access-token

Hämta en access token (1h TTL).

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

DELETE/oauth/access-token

Återkalla den aktuella token (kräver Authorization-header).

Avtal

POST/agreements

Skapa ett avtals-utkast (status: draft).

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

GET/agreements

Lista avtal. Stödjer ?status, ?limit, ?cursor.

GET/agreements/:id

Hämta ett avtal med deltagare och status.

GET/agreements/:id/events

Audit-trail (sent, viewed, signed, completed...).

GET/agreements/:id/download

Hämta signerad PDF (returnerar signed URL eller binärt innehåll).

Deltagare

POST/agreements/:id/participants

Lägg till en signatär (utkast-status).

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

PDF-dokument

PUT/agreements/:id/documents/main

Ladda upp huvuddokument. Stöd för application/pdf (binärt) eller JSON med base64.

# 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":"avtal.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 @avtal.pdf

Livscykel

POST/agreements/:id/lifecycle

Skicka eller avbryt ett avtal.

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

Webhooks

Tidvis levererar händelser till din URL via POST med JSON. Varje request är signerad med HMAC-SHA256 i headern X-Tidvis-Signature: sha256=<hex> baserat på din signing_secret och raw body. Vi retryar misslyckade leveranser med exponentiell backoff i upp till 24h.

POST/webhooks

Registrera en webhook.

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

GET/webhooks

Lista registrerade webhooks.

DELETE/webhooks/:id

Ta bort en webhook.

Händelser

agreement.sent
agreement.viewed
agreement.signed
agreement.completed
agreement.cancelled
agreement.expired

Verifiera signatur (Node.js)

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));
}

Felkoder

HTTP	Code	Betydelse
400	`invalid_request`	Felaktig input.
401	`unauthorized`	Saknad/ogiltig token.
402	`plan_required`	Kontot saknar Enterprise-plan. Innehåller `upgrade_url`.
403	`forbidden`	Saknar rättighet till resursen.
404	`not_found`	Resursen hittades inte.
409	`conflict`	Ogiltigt tillståndsbyte (t.ex. skicka redan skickat).
429	`rate_limited`	För många anrop.
500	`server_error`	Serverfel – försök igen.

Rate limits

Standardgräns: 60 requests/minut per klient och 600/timme för uppladdningar. Vid överskridning får du 429 rate_limited med Retry-After-header. Behöver du mer? Kontakta oss.

Tidvis Sign Public API