API-dokumentation — Certiflow

Introduktion

Certiflow REST API låter dig integrera elektronisk signering direkt i dina egna system. Skicka dokument, övervaka signeringsstatus, hantera signatärer och ta emot realtidshändelser via webhooks.

Base URL https://certiflow.se/api/v1

💡

Alla svar returneras som JSON. Alla anrop kräver headern Content-Type: application/json och Authorization: Bearer {din-api-nyckel}.

🌍

API:et är GDPR-kompatibelt. All data lagras inom EU. Känslig data krypteras i vila med AES-256.

Autentisering

Alla API-anrop måste inkludera din API-nyckel i Authorization-headern som en Bearer-token. Hämta din nyckel från API-nycklar i dashboarden.

⚠️

Håll aldrig din live-nyckel (sw_live_…) i frontend-kod eller publika repositorier. Använd sw_test_… under utveckling.

HTTP Headers

Authorization: Bearer sw_live_a1b2c3d4e5f6g7h8i9j0…
Content-Type:  application/json
Accept:        application/json

JavaScript (fetch)

const SW_KEY = 'sw_live_a1b2c3…';

const res = await fetch('https://certiflow.se/api/v1/documents', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${SW_KEY}`,
    'Content-Type':  'application/json'
  }
});
const data = await res.json();

PHP (cURL)

$ch = curl_init('https://certiflow.se/api/v1/documents');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer sw_live_a1b2c3…',
    'Content-Type: application/json'
  ]
]);
$response = json_decode(curl_exec($ch), true);

Dokument

GET /documents Lista alla dokument ▼

Parameter	Typ	Beskrivning
pagevalfri	integer	Sida (standard: 1)
per_pagevalfri	integer	Resultat per sida, max 100 (standard: 20)
statusvalfri	string	Filtrera: `pending`, `signed`, `draft`, `expired`
searchvalfri	string	Fritextsök på dokumenttitel

cURL

curl -G https://certiflow.se/api/v1/documents \
  -H "Authorization: Bearer sw_live_…" \
  --data-urlencode "status=pending" \
  --data-urlencode "per_page=10"

200 OK

JSON

{
  "data": [{
    "id":         "doc_a1b2c3d4",
    "title":      "Anställningsavtal",
    "status":     "pending",
    "created_at": "2025-11-22T09:14:00Z",
    "expires_at": "2025-12-22T09:14:00Z",
    "signers":    2,
    "signed":     1
  }],
  "meta": {
    "total":    47,
    "page":     1,
    "per_page": 20
  }
}

POST /documents Skapa & ladda upp dokument ▼

Fält	Typ	Beskrivning
titlekrav	string	Dokumenttitel (max 255 tecken)
file_base64krav	string	PDF-fil kodad i Base64 (max 25 MB)
signerskrav	array	Lista av signatärsobjekt (se nedan)
signers[].namekrav	string	Signatärens fullständiga namn
signers[].emailkrav	string	E-postadress dit inbjudan skickas
signers[].bankidvalfri	boolean	Kräv BankID-verifiering (standard: false)
signers[].ordervalfri	integer	Signeringsordning (1 = signerar först)
expires_daysvalfri	integer	Giltighetstid i dagar (standard: 30)
messagevalfri	string	Personligt meddelande i inbjudans-e-post
send_immediatelyvalfri	boolean	Skicka inbjudan direkt (standard: true)

JavaScript

const res = await fetch('/api/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type':  'application/json'
  },
  body: JSON.stringify({
    title:            'Anställningsavtal',
    file_base64:     'JVBERi0xLjQ…', // Base64-kodad PDF
    expires_days:    30,
    message:         'Vänligen signera bifogat avtal.',
    signers: [{
      name:   'Anna Lindström',
      email:  '[email protected]',
      bankid: true,
      order:  1
    }]
  })
});
const { id, signing_url } = await res.json();

201 Created

JSON

{
  "id":           "doc_a1b2c3d4",
  "title":        "Anställningsavtal",
  "status":       "pending",
  "signing_url":  "https://certiflow.se/sign/tok_xyz123",
  "created_at":  "2025-11-22T09:14:00Z",
  "expires_at":   "2025-12-22T09:14:00Z",
  "signers": [{
    "id":        "sig_111aaa",
    "name":     "Anna Lindström",
    "email":    "[email protected]",
    "status":   "pending",
    "bankid":   true
  }]
}

POST /documents/{id}/send Skicka inbjudan till signatärer ▼

cURL

curl -X POST https://certiflow.se/api/v1/documents/doc_a1b2c3d4/send \
  -H "Authorization: Bearer sw_live_…"

200 OK

JSON

{ "success": true, "sent_to": 2 }

GET /documents/{id}/download Ladda ned signerad PDF ▼

💡

Returnerar binär PDF-data med Content-Type: application/pdf. Spara med korrekt MIME-typ.

cURL

curl https://certiflow.se/api/v1/documents/doc_a1b2/download \
  -H "Authorization: Bearer sw_live_…" \
  --output signerat_avtal.pdf

Signatärer

POST /documents/{id}/remind Skicka manuell påminnelse ▼

Fält	Typ	Beskrivning
signer_idvalfri	string	Skicka bara till en specifik signatär. Utelämna för att påminna alla.
messagevalfri	string	Anpassat påminnelsemeddelande

200 OK

JSON

{ "success": true, "reminded": 1 }

Webhooks

Certiflow skickar HTTP POST-anrop till din endpoint när händelser inträffar. Alla webhook-anrop inkluderar headern X-Certiflow-Signature för verifiering.

🔐

Verifiera alltid signaturen: hash_hmac('sha256', $payload, $webhookSecret) === $header

Tillgängliga händelser

document.createdDokument skapat (ej skickat)

document.sentInbjudan skickad till alla signatärer

document.viewedSignatär öppnade dokumentet

document.signedEn signatär signerade

document.completedAlla signatärer har signerat — slutgiltig PDF redo

document.expiredDokumentet har utgått utan komplett signering

document.declinedEn signatär nekade att signera

signer.bouncedInbjudans-e-post studsar

Webhook payload — document.completed

{
  "event":      "document.completed",
  "timestamp": "2025-11-22T14:42:00Z",
  "data": {
    "id":           "doc_a1b2c3d4",
    "title":        "Anställningsavtal",
    "status":       "signed",
    "completed_at": "2025-11-22T14:42:00Z",
    "pdf_url":      "https://certiflow.se/api/v1/documents/doc_a1b2/download"
  }
}

Felhantering

API:et returnerar alltid JSON vid fel. Kontrollera HTTP-statuskoden och fältet error.code för maskinsläsbara felkoder.

Felsvar

{
  "error": {
    "code":    "VALIDATION_ERROR",
    "message": "Fältet 'signers' saknas eller är tomt.",
    "field":   "signers"
  }
}

HTTP-status	Kod	Beskrivning
400	`BAD_REQUEST`	Felaktigt formaterad JSON eller ogiltig parameter
401	`UNAUTHORIZED`	Saknad eller ogiltig API-nyckel
403	`FORBIDDEN`	Nyckeln saknar behörighet för denna åtgärd
404	`NOT_FOUND`	Resursen hittades inte
422	`VALIDATION_ERROR`	Valideringsfel — se fältet `field`
429	`RATE_LIMITED`	För många anrop — se Rate limiting
500	`SERVER_ERROR`	Internt serverfel — kontakta support

Rate limiting

API-anrop begränsas per nyckel. Vid överskridning returneras statuskod 429. Headrarna X-RateLimit-Remaining och X-RateLimit-Reset finns i varje svar.

Plan	Anrop / månad	Burst (anrop / minut)
Starter	1 000	30
Business	10 000	120
Enterprise	Obegränsat	Obegränsat

Konto

GET /account Hämta kontoinformation och kvoter ▼

200 OK

JSON

{
  "name":   "Anna Lindström",
  "email":  "[email protected]",
  "plan":   "business",
  "usage": {
    "documents":   { "used": 47, "limit": 100 },
    "api_calls":   { "used": 1240, "limit": 10000 },
    "storage_mb":  { "used": 2355, "limit": 10240 }
  }
}