Teknisk dokumentation

Dokumentation för VisitSign API

VisitSign API använder en statisk bearer-token för skyddade endpoints. Varje integration tilldelas en unik token som skickas i HTTP-headern Authorization. En kund kan ha flera sidor, vilket innebär att rätt page_id först bör hämtas via GET /pages och därefter skickas med vid validering via POST /status. Dokumentationen nedan beskriver autentisering, endpoint-specifikationer, svarsformat, felkoder, säkerhet, drift och färdiga exempel för produktion.

Bas-URL
https://api.visitsign.se/v1
Autentisering
Statisk bearer-token
Content-Type
application/json; charset=utf-8
Senast uppdaterad
2026-04-15

Översikt

VisitSign API är avsett för server-till-server-integrationer där skyddade resurser nås med en statisk bearer-token via HTTP-headern Authorization.

Varje integration tilldelas en unik bearer-token. Den tokenen lagras av kunden på serversidan och skickas med varje anrop till skyddade endpoints.

Eftersom en kund kan ha flera sidor finns en skyddad endpoint för att lista tillgängliga sidor och deras page_id innan valideringsanrop görs.

API:et innehåller publika endpoints för hälsokontroll och versionsinformation samt skyddade endpoints för sidlistning och registreringsvalidering.

Funktioner

  • Lista alla tillgängliga sidor för den autentiserade kunden via GET /pages.
  • Returnera page_id, page_hid, page_name, BankID-stöd och kopplade domäner per sida.
  • Validera en registrering med page_id, customer_id och verification_id.
  • Returnera identitetsuppgifter endast när registreringen är giltig.
  • Exponera hälsoinformation för övervakning och driftkontroller.
  • Exponera versions- och buildinformation för diagnostik och releaseverifiering.
  • Returnera konsekventa, maskinläsbara felkoder för misslyckade anrop.

Snabbstart

  1. Spara den tilldelade bearer-tokenen på serversidan i integrationsmiljön.
  2. Skicka tokenen i headern Authorization: Bearer <token> vid anrop till skyddade endpoints.
  3. Anropa GET /pages för att hämta kundens tillgängliga sidor och rätt page_id.
  4. Anropa POST /status med page_id, customer_id och verification_id för att validera en registrering.
  5. Använd GET /health för övervakning och GET /version för diagnostik och releaseverifiering.
  6. Vid misstänkt tokenläcka eller behov av rotation ska en ny token utfärdas administrativt och den tidigare tokenen sluta användas omedelbart.

Autentisering

Skyddade endpoints accepterar endast bearer-token.

Formatet är Authorization: Bearer <token>.

Varje integration tilldelas en unik statisk bearer-token som används direkt mot skyddade endpoints.

Tokenen ska hanteras som en hemlighet, endast på serversidan och aldrig exponeras i frontendkod, mobila appar eller publika klientapplikationer.

Följande endpoints kräver bearer-token: GET /pages och POST /status.

Följande endpoints är publika: GET /health och GET /version.

Tokenutgivning, återkallelse och rotation hanteras utanför detta publika API.

Authorization header
Authorization: Bearer vs_live_4f9348d31cf54b3ea8c12d1cfab0ce42

Headers

Standardheaders som används i API:et.

Header Krav Beskrivning
Authorization För skyddade endpoints Bearer-token för skyddade endpoints. Format: Bearer <token>.
Content-Type: application/json För JSON-body Måste skickas när request body innehåller JSON.
Accept: application/json Nej Rekommenderas för att uttryckligen begära JSON-svar.

Endpoints

Metod Endpoint Autentisering Syfte
GET /pages Bearer Listar kundens tillgängliga sidor och deras page_id.
POST /status Bearer Validerar registrering för en specifik sida.
GET /health Publik Returnerar tjänstens hälsostatus.
GET /version Publik Returnerar API-version och buildinformation.
GET

GET /pages

Listar alla sidor som tillhör den autentiserade kund som bearer-tokenen är kopplad till.

  • Endpointen kräver bearer-token.
  • Används för att hämta rätt page_id innan valideringsanrop görs.
  • Varje sida kan ha en eller flera kopplade domäner.
Respons
{
	"status": "ok",
	"pages": [
		{
			"page_id": 101,
			"page_hid": "c0a4d62f9ddf4a5f8c2c3e7d1f9a0b11c2d3e4f5",
			"page_name": "Exempelbolaget Downhill AB",
			"use_bankid": true,
			"domains": [
				"exempelbolaget-downhill.visitsign.se"
			]
		},
		{
			"page_id": 102,
			"page_hid": "f7b2a1c4836d4b0c8f31d9e8a4c2b6d7e9f0a1b2",
			"page_name": "Exempelbolaget Event AB",
			"use_bankid": true,
			"domains": [
				"exempelbolaget-event.visitsign.se"
			]
		}
	]
}

Fält

Fält Typ Beskrivning
page_id integer Internt sid-ID som används i sidspecifika anrop.
page_hid string Publikt eller externt sid-ID.
page_name string Sidans namn.
use_bankid boolean Anger om sidan använder BankID.
domains array Lista över domäner kopplade till sidan.
POST

POST /status

Validerar en registrering med page_id, customer_id och verification_id.

  • Endpointen kräver bearer-token.
  • page_id måste tillhöra den kund som tokenen är kopplad till.
  • Returnerar status: "valid" eller status: "invalid".
  • Identitetsfält returneras endast när registreringen är giltig.
Förfrågan
{
	"page_id": 101,
	"customer_id": "EXEMPEL-1",
	"verification_id": "VERIFY-1001"
}
Respons · valid
{
	"status": "valid",
	"givenname": "Anna",
	"surname": "Exempelsson",
	"ssn": "19980512-1234",
	"valid_until": "2026-11-02"
}
Respons · invalid
{
	"status": "invalid"
}
Respons · expired
{
	"status": "invalid",
	"reason": "expired"
}

Fält

Fält Typ Beskrivning
page_id integer Obligatoriskt sid-ID för den sida som valideringen avser.
customer_id string Unikt kund-ID.
verification_id string Verifikations-ID för registreringen.
GET

GET /health

Returnerar hälsostatus för tjänsten.

  • Endpointen är publik.
  • Kan användas för övervakning och driftkontroller.
Respons
{
	"status": "ok",
	"service": "visitsign-api",
	"timestamp": "2026-04-15T12:00:00Z"
}
GET

GET /version

Returnerar versions- och buildinformation för den aktuella deploymenten.

  • Endpointen är publik.
  • Kan användas för diagnostik, drift och releaseverifiering.
Respons
{
	"status": "ok",
	"version": "v1",
	"build": "2026-04-15"
}

Svar & semantik

Alla lyckade svar returneras som JSON med Content-Type: application/json; charset=utf-8.

  • valid: registreringen finns och är giltig för aktuell användning.
  • invalid: registreringen finns, men är inte giltig för aktuell användning.
  • invalid + reason: "expired": registreringen finns men har gått ut.
  • ok: endpointen genomfördes utan fel.
  • pages: lista med sidor som tillhör kunden.
  • not_found: ingen registrering matchade angivna identifierare.
Error response
{
	"status": "error",
	"error_code": "missing_page_id",
	"message": "No page_id supplied."
}

Felkoder

Felsvar returneras som JSON med maskinläsbar felkod och meddelande.

Felkod HTTP-status Beskrivning
invalid_endpoint 404 Den begärda endpointen finns inte.
invalid_method 405 HTTP-metoden är inte tillåten för endpointen.
invalid_payload 400 Request body innehåller ogiltig JSON.
missing_token 401 Ingen bearer-token skickades med.
invalid_token 401 Den angivna bearer-tokenen är ogiltig.
expired_token 401 Den angivna bearer-tokenen har löpt ut.
revoked_token 401 Den angivna bearer-tokenen har återkallats.
missing_page_id 400 Fältet page_id saknas.
invalid_page_id 404 Angivet page_id finns inte.
forbidden_page 403 Angivet page_id tillhör inte den autentiserade kunden.
missing_customer_id 400 Fältet customer_id saknas.
missing_verification_id 400 Fältet verification_id saknas.
not_found 404 Ingen registrering matchade de angivna identifierarna.
internal_error 500 Ett oväntat internt fel uppstod.

Exempel

Produktionsnära exempel för cURL och PHP.

cURL · GET /pages
curl -X GET https://api.visitsign.se/v1/pages \
	-H "Authorization: Bearer vs_live_4f9348d31cf54b3ea8c12d1cfab0ce42" \
	-H "Accept: application/json"
cURL · POST /status
curl -X POST https://api.visitsign.se/v1/status \
	-H "Authorization: Bearer vs_live_4f9348d31cf54b3ea8c12d1cfab0ce42" \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{
		"page_id": 101,
		"customer_id": "EXEMPEL-1",
		"verification_id": "VERIFY-1001"
	}'
cURL · GET /health
curl -X GET https://api.visitsign.se/v1/health \
	-H "Accept: application/json"
cURL · GET /version
curl -X GET https://api.visitsign.se/v1/version \
	-H "Accept: application/json"
PHP
<?php

$baseUrl = 'https://api.visitsign.se/v1';
$bearerToken = 'vs_live_4f9348d31cf54b3ea8c12d1cfab0ce42';

function apiRequest(string $method, string $url, ?array $payload = null, ?string $bearerToken = null): array
{
	$headers = [
		'Accept: application/json'
	];

	if($payload !== null) {
		$headers[] = 'Content-Type: application/json';
	}

	if($bearerToken !== null) {
		$headers[] = 'Authorization: Bearer ' . $bearerToken;
	}

	$ch = curl_init($url);

	curl_setopt_array($ch, [
		CURLOPT_RETURNTRANSFER => true,
		CURLOPT_CUSTOMREQUEST => $method,
		CURLOPT_HTTPHEADER => $headers,
		CURLOPT_TIMEOUT => 15
	]);

	if($payload !== null) {
		curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
	}

	$response = curl_exec($ch);
	$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

	if($response === false) {
		throw new RuntimeException(curl_error($ch));
	}

	curl_close($ch);

	return [
		'http_code' => $httpCode,
		'body' => $response,
		'json' => json_decode($response, true)
	];
}

$pagesResponse = apiRequest('GET', $baseUrl . '/pages', null, $bearerToken);

if(($pagesResponse['json']['status'] ?? null) !== 'ok' || empty($pagesResponse['json']['pages'])) {
	throw new RuntimeException('No pages returned from API.');
}

$pageId = $pagesResponse['json']['pages'][0]['page_id'];

$statusResponse = apiRequest('POST', $baseUrl . '/status', [
	'page_id' => $pageId,
	'customer_id' => 'EXEMPEL-1',
	'verification_id' => 'VERIFY-1001'
], $bearerToken);

echo 'HTTP ' . $statusResponse['http_code'] . PHP_EOL;
echo $statusResponse['body'] . PHP_EOL;

Säkerhet

  • Använd alltid HTTPS.
  • Lagra bearer-token säkert på serversidan.
  • Exponera aldrig token i frontendkod, appar eller delade klientmiljöer.
  • Implementera rimliga timeouts, loggning och felhantering.
  • Vid rotation eller återkallelse ska den tidigare tokenen omedelbart sluta användas.

Drift

  • Övervaka GET /health kontinuerligt.
  • Verifiera distribution via GET /version efter release.
  • Kontrollera både HTTP-statuskod och JSON-body i integrationen.
  • Hämta alltid giltiga page_id via GET /pages innan validering görs.
  • Utgå inte från att en kund bara har en sida.

Kontakt

För onboarding, API-frågor eller teknisk support, kontakta Sweden Sites AB.

Sweden Sites AB
support@swedensites.com
+46 651 13070