Tidvis Sign Public API

Kopia av signerade avtal (completed_copy_emails)

Skicka completed_copy_emails (upp till 5 adresser) när avtalet skapas via POST /agreements eller quick-send. Varje adress får bekräftelsemejlet med den signerade PDF:en bifogad när avtalet är klart. Utelämnas fältet (null) ärvas kontots inställning under Inställningar → Kopia av signerade avtal till. Fältet returneras på GET /agreements/:id — se fälttabellerna ovan.

Låsa BankID till ett specifikt personnummer

Sätt signer_personal_number på en mottagare för att kräva att exakt den personen legitimerar sig och/eller signerar med BankID. Avvisas i BankID-appen om någon annan försöker. Kräver att avtalet har bankid_required: true och/eller bankid_identify_required: true. Fältet är write-only — det returneras aldrig i svar; använd personal_id_masked (t.ex. 19800101-XXXX) för visning.

{
  "title": "Anställningsavtal Anna",
  "bankid_required": true,
  "participants": [
    {
      "name": "Anna Andersson",
      "email": "anna@example.com",
      "signer_personal_number": "198001011234"
    }
  ]
}

Accepterat format: 10 eller 12 siffror, valfritt bindestreck (t.ex. 198001011234, 800101-1234). Luhn-valideras. Skickas personnummer utan att BankID är aktiverat på avtalet, eller om numret inte klarar Luhn-kontrollen, returneras 400 invalid_request.

Hur det fungerar

• Mottagaren får en personlig länk till sin e-postadress (samma som i participants[].email).
• En 6-siffrig engångskod skickas vid öppning av dokumentet, giltig i 15 minuter, max 5 försök.
• Identiteten bekräftas innan signaturen registreras; IP, user agent, tidpunkt och kodverifiering loggas i audit-trailen.
• Ingår på alla planer – ingen add-on eller styckkostnad.

Skapa OTP-avtal (default)

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

Webhook-payload vid OTP-signering

{
  "event": "agreement.signed",
  "delivery_id": "whd_...",
  "created_at": "2026-06-11T08:42:11.000Z",
  "agreement_id": "agr_...",
  "participant": { "id": "p_...", "email": "anna@example.com" },
  "signature": {
    "method": "otp_email",
    "signer_name": "Anna Andersson",
    "email": "anna@example.com",
    "code_verified_at": "2026-06-11T08:41:53.000Z",
    "signed_at": "2026-06-11T08:42:11.000Z",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ..."
  }
}

Krav

• Kontot måste ha planen Sign Pro och tillvalet BankID aktiverat.
• Pris: 100 BankID-signeringar ingår per månad, därefter 5 kr/signering enligt prislista.
• Saknar kontot tillvalet returnerar POST /agreements/:id/lifecycle med action: "send" felet 402 bankid_disabled.

Skapa BankID-avtal

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

Svar (förkortat):

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

Webhook-payload när BankID används

För avtal med bankid_required: true kompletteras agreement.signed-händelsen med ett signature-block. Av integritetsskäl exponeras varken personnummer, certifikat eller OCSP-svar via API:t eller webhooks.

{
  "event": "agreement.signed",
  "delivery_id": "whd_...",
  "created_at": "2026-06-11T08:42:11.000Z",
  "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"
  }
}

Fältet signature.method är alltid en av "otp_email" eller "bankid". Avtal med blandade deltagare loggar metoden per signatär.

Slå på vid skapande

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

Svar (förkortat):

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

Beteende för mottagaren

• När mottagaren öppnar länken visas en BankID-gate istället för PDF:en.
• Mottagaren måste starta BankID på mobil eller via QR-kod och bekräfta legitimering.
• Först därefter öppnas PDF:en och vald signaturmetod blir aktiv.
• "viewed"-händelsen loggas efter legitimeringen, inte vid första klicket på länken.

Krav och kostnad

• Kontot måste ha Sign Pro och tillvalet BankID aktiverat — samma krav som bankid_required.
• Identifieringar räknas inte mot BankID-kvoten på 100 signeringar/mån. Endast faktiska BankID-signeringar (bankid_required: true) debiteras 5 kr/styck efter inkluderade.
• Saknar kontot tillvalet returnerar POST /agreements/:id/lifecycle med action: "send" felet 402 bankid_disabled.

Webhook-payload

En extra händelse agreement.identified sänds när en mottagare legitimerat sig. Personnummer, certifikat och OCSP-svar exponeras aldrig via API:t.

{
  "event": "agreement.identified",
  "delivery_id": "whd_...",
  "created_at": "2026-06-12T10:21:04.000Z",
  "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"
  }
}

Krav & pris

• Avtalsmodulen måste vara aktiv på kontot (99 kr/användare/månad). Annars returneras 402 plan_required.
• Vid MCP/agent-anrop tillkommer 3 kr per generering ovanpå modulpriset.
• Källdokument max 20 MB per fil, 2–10 filer per mall (PDF eller DOCX).

Scopes

• templates:read — lista och hämta mallar
• templates:manage — skapa och radera mallar
• generations:create — generera nya avtal från mall
• generations:read — lista, hämta och ladda ner genererade avtal
• Om signature_method: "bankid" används i generate krävs även agreements:send.

Scopes

• sub_accounts:read — läs lista och detaljer
• sub_accounts:manage — skapa, uppdatera, arkivera, ändra parent-access
• sub_accounts:members — hantera medlemmar och roller

Scopes är opt-in per token — gå till Inställningar → API för att tilldela dem.

Felkoder (specifika för underkonton)

• 403 license_required — ingen aktiv årslicens på huvudkontot
• 403 license_seat_limit — alla seats på licensen är upptagna
• 403 plan_limit — planen tillåter inte fler underkonton
• 403 parent_only — token tillhör ett underkonto; använd huvudkontots token
• 404 not_found — underkontot finns inte eller tillhör annat huvudkonto
• 409 conflict — underkontot är arkiverat

GDPR / retention

Arkiverade underkonton raderas permanent efter 30 dagar via ett dagligt jobb (purge_archived_sub_accounts()) som tar bort kontot, medlemmar, inbjudningar samt tillhörande dokument i storage. Alla skrivningar via API:t loggas i sign_account_hierarchy_audit med actor_api_client_id så ni kan spåra exakt vilken token som utförde åtgärden.

CRM (read-only)

Underkonton exponeras inte via CRM-API:t som skrivbara entiteter — CRM:t är read-only enligt befintlig spec. Använd /v1/sub-accounts för all hantering.