Tilslutning af dit fakturerings- eller CRM-system til Uniqkey Partner API

Uniqkey-partnere kan læse månedligt licensforbrug for alle deres kundeorganisationer via en REST API, så et fakturerings-, CRM- eller rapporteringssystem kan hente tallene direkte i stedet for at nogen eksporterer dem fra Partnerportalen. Denne artikel forklarer, hvordan du opretter en API-nøgle i Partnerportalen, hvordan API'en fungerer, og hvad du kan forvente af dataene.

Hvem kan bruge dette

• API'en er til Uniqkey-partnere. API-nøgler oprettes i Partnerportalen af en partnerbruger med rollen Admin. Andre roller kan ikke se siden API keys.
• En nøgle tilhører din partnerkonto, ikke den bruger, der oprettede den. Den fortsætter med at fungere, hvis brugeren stopper eller fjernes.
• En nøgle kan se din egen partnerkonto og partnerne under den i dit hierarki, så en distributør også kan se sine forhandleres kunder. Den kan aldrig se partnere over eller ved siden af din.
• Dit system skal have udgående HTTPS-adgang til https://partner-api-public.production.uniqkey.eu.
• API'en er skrivebeskyttet og returnerer licenstal og organisationsnavne. Vault-data, adgangskoder, nøgler eller medarbejderoplysninger inkluderes aldrig.

Trin 1: Opret en API-nøgle

1. Log ind på Partnerportalen som Admin.
2. Åbn API keys i menuen.
3. Klik på Create API key.
4. Angiv et Name for den integration, der skal bruge nøglen, f.eks. Billing sync. Navnet vises i revisionsloggen for alt, hvad nøglen gør, så gør det genkendeligt.
5. Vælg eventuelt en Expiry date. Den tidligste dato, du kan vælge, er i morgen. Nøglen fungerer indtil slutningen af den dag i din browsers tidszone. Lad feltet stå tomt for en nøgle, der ikke udløber.
6. Klik på Create. Dialogboksen Copy your API key now viser den nye nøgle, som begynder med uk_p_.
7. Kopiér nøglen, og gem den i dit systems lager til hemmeligheder. Nøglen vises kun én gang. Markér I have stored this API key in a safe place for at lukke dialogboksen. Derefter kan nøglen ikke vises igen. Hvis du mister den, skal du oprette en ny nøgle.

Håndtering af nøgler senere:

• Siden API keys viser alle nøgler med deres navn, de første tegn i nøglen (så du kan skelne nøglerne fra hinanden), hvornår de blev oprettet, hvornår de udløber, hvornår de sidst blev brugt, samt deres status: Active, Expired eller Revoked.
• Hvis du vil tilbagekalde en nøgle, skal du åbne menuen på dens række, vælge Revoke og bekræfte. Tilbagekaldelse er permanent og kan ikke fortrydes. Nøglen holder straks op med at fungere; i sjældne tilfælde kan det tage op til 1 minut. Tilbagekaldte nøgler bliver på listen med status Revoked.
• Last used opdateres højst hvert 5. minut, så en nøgle, der bruges aktivt, kan vise et tidspunkt, der er op til 5 minutter gammelt.
• En udløbsdato kan ikke ændres, efter nøglen er oprettet. Når en nøgle er ved at udløbe, skal du oprette en ny.
• Du kan oprette flere nøgler, f.eks. én pr. integration, så du kan tilbagekalde én uden at påvirke de andre. Alle en partners nøgler deler én hastighedsgrænse (se "Rate limits").
• Sådan roterer du en nøgle: Opret en ny nøgle, opdater dit system, kontrollér, at Last used viser, at den nye nøgle er i brug, og tilbagekald derefter den gamle.
• Oprettelse og tilbagekaldelse af en nøgle registreres under Audit logs i Partnerportalen sammen med nøglens navn. Alle vellykkede forespørgsler efter licensdata, der foretages med en nøgle, registreres også med nøglens navn som aktør. Posterne vises i revisionsloggen for den partner, der ejer nøglen. Afviste forespørgsler og forespørgsler til /v1/me registreres ikke.

Trin 2: Konfigurer dit system

Alle integrationer kræver de samme ting:

Det er en god standard at hente dataene én gang om dagen. Tallene opdateres af et dagligt job (se "Hvad du kan forvente" nedenfor), så hyppigere forespørgsler giver ingen fordel.

Interaktiv API-dokumentation findes på https://partner-api-public.production.uniqkey.eu/docs. OpenAPI-specifikationen, som de fleste værktøjer kan bruge til at generere en klient, findes på https://partner-api-public.production.uniqkey.eu/openapi/v1.json.

Hurtig test med curl

Kontrollér, at nøglen fungerer, og hvilken partner den tilhører:

curl -s "https://partner-api-public.production.uniqkey.eu/v1/me" \
  -H "Authorization: Bearer <your key>"

Hent derefter de første licensrækker:

curl -s "https://partner-api-public.production.uniqkey.eu/v1/licenses?limit=5" \
  -H "Authorization: Bearer <your key>"

En fungerende opsætning returnerer HTTP 200 med et JSON-body som dem i afsnittet "Svar". 401 betyder, at Authorization-headeren mangler, ikke er et Bearer-token, eller at nøglen er forkert, tilbagekaldt eller udløbet.

API-reference

Forespørgsel

GET /v1/licenses

En forespørgsel uden parametre er gyldig og returnerer hver måned for alle organisationer, som nøglen kan se, med de nyeste først og én side ad gangen.

Cursoren er uigennemsigtig. Du må ikke oprette, fortolke eller ændre den. Formatet kan ændres uden varsel.

GET /v1/me

Tager ingen parametre. Returnerer den partner, som nøglen tilhører, samt nøglens eget navn, præfiks og udløb. Brug den til at teste en nøgle. Den tæller med i hastighedsgrænsen som enhver anden forespørgsel.

Svar

GET /v1/licenses:

{
  "items": [
    {
      "organizationId": "d5ecd732-4a67-418c-9dea-38a097fba1f6",
      "organizationName": "Example Customer ApS",
      "organizationExternalId": "CRM-10442",
      "partnerId": "3f2a9c1e-7b44-4d0a-9e51-2a6c8f0d1b77",
      "partnerName": "Example Reseller A/S",
      "month": "2026-09",
      "usageLicenseCount": 48,
      "committedLicenseCount": 50,
      "discoveryInstallationCount": 12,
      "discoveryActivatedNow": true
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJEIjoiMjAyNi0wOS0wMSIsIk8iOiJkNWVj..."
}

• Rækker sorteres med den nyeste måned først og derefter efter organizationId.
• hasMore fortæller, om du skal anmode om den næste side. Fortsæt, så længe hasMore er sand.
• nextCursor er null på den sidste side.

GET /v1/me:

{
  "partnerId": "3f2a9c1e-7b44-4d0a-9e51-2a6c8f0d1b77",
  "partnerName": "Example Reseller A/S",
  "keyName": "Billing sync",
  "keyPrefix": "uk_p_Xa81kQ2z",
  "expiresAt": "2027-03-31T21:59:59.999Z"
}

expiresAt er i UTC og er null for en nøgle, der ikke udløber.

Fejl bruger standardformatet for problemdetaljer (Content-Type: application/problem+json) med en stabil, maskinlæsbar code:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request could not be processed.",
  "code": "bad_request",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Basér din fejlhåndtering på code og HTTP-statusen. title og detail er til mennesker og kan ændres.

Rækkeformat

Hastighedsgrænser

• Hver partner kan foretage mindst 120 forespørgsler pr. minut. Grænsen deles af alle partnerens nøgler, så oprettelse af flere nøgler giver ikke mere kapacitet.
• Når grænsen overskrides, returnerer API'en 429 med koden too_many_requests og en Retry-After-header med det antal sekunder, der skal ventes. Vent mindst så længe, før du prøver igen.
• Der anvendes en separat, højere grænse pr. kilde-IP-adresse ved netværkskanten. Normale svar indeholder X-RateLimit-*-headere for denne grænse. Når den overskrides, får du også 429, men uden JSON-body, så håndtér en 429 ud fra status og Retry-After, ikke ved at fortolke bodyen.

En daglig synkronisering med limit=1000 kræver kun en håndfuld forespørgsler og holder sig langt inden for grænserne.

Hvad du kan forvente af dataene

• Antallene er månedlige maksimumtal. usageLicenseCount og discoveryInstallationCount er de højeste daglige antal, der blev registreret i løbet af måneden, ikke et gennemsnit eller værdien ved månedens udgang. En bruger, der tilføjes og fjernes igen mellem to daglige optællinger, registreres ikke.
• Data er op til en dag forsinkede. Tallene registreres af et dagligt job, der kører kort efter midnat UTC og tæller med for den foregående dag. En ændring, der foretages i dag, vises efter næste kørsel.
• Den aktuelle måned kan stadig ændre sig. Indtil måneden er slut, øger en ny top den aktuelle måneds række. Den sidste optælling for en måned foretages i den første time den 1. i den følgende måned (UTC), så betragt en måned som endelig fra kl. 02.00 UTC den 1.
• Alle organisationer får en række hver måned, også måneder med et forbrug på nul. Rækker begynder i den måned, organisationen blev oprettet. I sjældne tilfælde, f.eks. ved en mislykket daglig kørsel, kan en måned mangle for en organisation. Betragt en manglende måned som ukendt, ikke som nul.
• Prøveorganisationer er inkluderet. Der returneres rækker for alle organisationer under din partnerkonto, uanset om de er betalende kunder.
• Ingen forpligtelse og en forpligtelse på 0 ser ens ud. Begge returneres som committedLicenseCount: null.
• discoveryInstallationCount er installationer, ikke identiteter. Det tæller passive udvidelsesinstallationer, som er det, Discovery licenseres efter. Tallet "Corporate identities" på Discovery-dashboardet tæller noget andet og vil ikke stemme overens.
• discoveryActivatedNow er ikke historisk. Det afspejler indstillingen i dag og gentages for hver måned. Brug discoveryInstallationCount til fakturering.
• Navne er aktuelle navne. Hvis en organisation eller partner omdøbes, viser alle dens måneder det nye navn. Match på organizationId, ikke på navne.
• Slettede organisationer beholder deres historik. Måneder, der er registreret, før en organisation blev slettet, returneres stadig. Rækkerne viser ikke, at organisationen er blevet slettet.
• Flytning af en organisation flytter dens historik. Kun Uniqkey kan flytte en organisation til en anden partner. Hvis det sker, følger alle dens måneder, inklusive allerede fakturerede måneder, med til den nye partner. De forsvinder fra den gamle partners resultater, medmindre den nye partner er under den gamle.

Bemærkninger til fakturerings- og CRM-integrationer

• Gem din egen kopi af fakturerede måneder. Gem hver måneds rækker i dit system, når du fakturerer. På grund af de flytninger og omdøbninger, der er beskrevet ovenfor, kan en måned, du forespørger på igen senere, afvige fra det, du fakturerede.
• Brug organizationId og month som nøgle. Hver organisation har højst én række pr. måned. Opdatér rækken ved gentagne synkroniseringer i stedet for at indsætte dubletter.
• Læs de seneste måneder igen. En enkel og robust synkronisering er at anmode om from sat til den foregående måned ved hver kørsel og overskrive disse rækker, og derefter låse en måned i dit system, når den er blevet faktureret.
• Knyt kunder sammen med organizationExternalId. Åbn organisationen i Partnerportalen, redigér dens oplysninger, og angiv dit CRM's kundenummer i External ID. Du kan også angive det, når du opretter en organisation. Det returneres derefter på hver række. Uniqkey kontrollerer ikke, om værdien er unik.
• Brug én nøgle pr. system. En separat nøgle til fakturering og CRM gør revisionsloggen lettere at læse og giver dig mulighed for at tilbagekalde den ene uden at afbryde den anden.

Fejlfinding

Når du kontakter support, skal du inkludere dit partner-id (fra /v1/me), nøglens navn, den nøjagtige forespørgsels-URL uden nøglen, HTTP-statusen og svar-bodyen inklusive traceId.