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.
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.