Bygg integrationer med tydlig åtkomst
Anslut era arbetsflöden till Clarent med dokumenterade API:er och behörighet per byrå och bolag.
Börja med vad integrationen ska göra
- Beskriv vilka uppgifter integrationen ska läsa eller skapa och för vilka bolag.
- Kontakta Clarent om en avgränsad tjänsteidentitet och rätt behörigheter.
- Prova med syntetiska uppgifter i en separat testmiljö.
- Kontrollera felhantering, omförsök och återkallelse innan integrationen används med verksamhetsdata.
API:t använder versionerade adresser under /api/v1. Läs den aktuella OpenAPI-beskrivningen för varje operation; tillgänglig funktion beror även på tilldelad behörighet.
Autentisering och bolagskontext
En integration använder en särskilt tilldelad tjänsteidentitet med en tidsbegränsad åtkomstnyckel. Förvara nyckeln på serversidan, utanför källkod, webbläsarkod och loggar. Dela inte en medarbetares inloggning.
Bolagsoperationer anger både byrå-ID och bolags-ID. Servern kontrollerar identitet, behörighet och giltighet vid varje anrop. En lista visar bara de bolag identiteten får se.
GET /api/v1/companies
Authorization: Bearer <din tjänstenyckel>
Accept: application/jsonOmförsök och samtidiga ändringar
För affärsoperationer som kräver Idempotency-Key skapar du en unik nyckel per avsedd åtgärd. Om svaret uteblir återanvänder du samma nyckel och exakt samma uppgifter. Skapa inte en ny nyckel enbart för att anslutningen bröts.
Ändringar av befintliga poster kan kräva aktuellt versionsnummer. Vid en versionskonflikt läser du om posten och granskar skillnaden innan du försöker igen. Belopp representeras som decimalsträngar enligt operationens schema.
Hantera fel begripligt
API:t använder HTTP-status och strukturerade fel med kod och meddelande. Valideringsfel kan ange berörda fält. Kontrollera svaret även när anslutningen fungerar och spara ett tekniskt fel-ID om ett sådant finns.
| Status | Hantering |
|---|---|
| 401 | Kontrollera om inloggningen eller nyckeln har gått ut. |
| 403 | Kontrollera åtkomst och eventuella krav för kontot. |
| 409 | Granska versions- eller omförsökskonflikten. |
| 422 | Rätta de uppgifter som inte kan godtas. |
| 429 | Minska anropsfrekvensen och vänta före nästa försök. |
MCP och avgränsad automatisering
MCP-gränssnittet finns på /api/mcp. Verktyg använder Clarents gemensamma domäntjänster och ger inte större åtkomst än motsvarande tillåtna operation. En tjänsteidentitet får bara använda tilldelade bolag och behörigheter.
Individuella löneuppgifter och skyddade personuppgifter omfattas av särskilda spärrar. Utgå inte från att en integration kan utföra allt som en mänsklig administratör kan göra.
Samlade arbetsmejl
Arbetsmejl är avstängda från början. Ett eget val gäller framför byråns standard. Användaren väljer dagligen eller veckovis, svensk tid och vilka aktuella uppgifter som ska ingå. Tidigare direktmejl per händelse är pausade.
Förhandsvisningen visar högst 20 uppgifter och rätt total från samma arbetsmodell som sändningen. Den går att använda utan mejlanslutning och skapar ingen kö eller något mejl. Historiken visar bara rader som användaren fortfarande får läsa.
Dessa val, förhandsvisningar och historik kräver en mänsklig identitet. API och MCP använder samma kontroller som Clarents vyer. En tjänsteidentitet eller AI får inte aktivera arbetsmejl åt någon annan. Se de aktuella operationerna i OpenAPI-beskrivningen.
Externa anslutningar
Bank-, mejl- och e-fakturatjänster kräver rätt anslutning, behörigheter och leverantörsvillkor. Kontrollera vilket flöde som är tillgängligt för den aktuella byrån och skilj en förberedd leverans från en mottagen kvittens.