Je facturatie- of CRM-systeem verbinden met de Uniqkey Partner API

Uniqkey-partners kunnen het maandelijkse licentiegebruik voor al hun klantorganisaties lezen via een REST API. Zo kan een facturatie-, CRM- of rapportagesysteem de aantallen rechtstreeks ophalen, in plaats van dat iemand ze uit het Partner Portal exporteert. In dit artikel wordt uitgelegd hoe je een API-sleutel maakt in het Partner Portal, hoe de API werkt en wat je van de gegevens kunt verwachten.

Wie dit kan gebruiken

• De API is bedoeld voor Uniqkey-partners. API-sleutels worden in het Partner Portal gemaakt door een partnergebruiker met de rol Admin. Andere rollen zien de pagina API keys niet.
• Een sleutel hoort bij je partneraccount, niet bij de gebruiker die deze heeft gemaakt. De sleutel blijft werken als die gebruiker vertrekt of wordt verwijderd.
• Een sleutel heeft toegang tot je eigen partneraccount en de partners daaronder in je hiërarchie. Een distributeur ziet dus ook de klanten van zijn resellers. De sleutel heeft nooit toegang tot partners boven of naast je account.
• Je systeem heeft uitgaande HTTPS-toegang nodig tot https://partner-api-public.production.uniqkey.eu.
• De API is alleen-lezen en retourneert licentiegegevens en organisatienamen. Er worden nooit kluisgegevens, wachtwoorden, sleutels of werknemersgegevens opgenomen.

Stap 1: Een API-sleutel maken

1. Log in op het Partner Portal als Admin.
2. Open API keys in het menu.
3. Klik op Create API key.
4. Voer een Name in voor de integratie die de sleutel gaat gebruiken, bijvoorbeeld Billing sync. De naam wordt in het auditlog weergegeven voor alles wat de sleutel doet, dus zorg dat deze herkenbaar is.
5. Kies desgewenst een Expiry date. De vroegste datum die je kunt kiezen is morgen. De sleutel werkt tot het einde van die dag in de tijdzone van je browser. Laat het veld leeg voor een sleutel die niet verloopt.
6. Klik op Create. In het dialoogvenster Copy your API key now wordt de nieuwe sleutel weergegeven. Deze begint met uk_p_.
7. Kopieer de sleutel en sla deze op in de geheimenopslag van je systeem. De sleutel wordt maar één keer weergegeven. Schakel I have stored this API key in a safe place in om het dialoogvenster te sluiten. Daarna kan de sleutel niet opnieuw worden weergegeven. Als je de sleutel kwijtraakt, maak je een nieuwe.

Sleutels later beheren:

• Op de pagina API keys staat elke sleutel met de naam, de eerste tekens van de sleutel (zodat je sleutels uit elkaar kunt houden), de aanmaakdatum, de vervaldatum, het laatste gebruik en de status: Active, Expired of Revoked.
• Als je een sleutel wilt intrekken, open je het menu op de bijbehorende rij, kies je Revoke en bevestig je dit. Intrekken is permanent en kan niet ongedaan worden gemaakt. De sleutel werkt onmiddellijk niet meer; in zeldzame gevallen kan dit maximaal 1 minuut duren. Ingetrokken sleutels blijven in de lijst staan met de status Revoked.
• Last used wordt maximaal elke 5 minuten bijgewerkt. Een sleutel die actief wordt gebruikt, kan daarom een tijd tonen die maximaal 5 minuten oud is.
• Een vervaldatum kan niet worden gewijzigd nadat de sleutel is gemaakt. Maak een nieuwe sleutel wanneer een sleutel bijna verloopt.
• Je kunt meerdere sleutels maken, bijvoorbeeld één per integratie, zodat je één sleutel kunt intrekken zonder de andere te beïnvloeden. Voor alle sleutels van een partner geldt één gezamenlijke snelheidslimiet (zie "Rate limits").
• Een sleutel roteren: maak een nieuwe sleutel, werk je systeem bij, controleer of Last used aangeeft dat de nieuwe sleutel wordt gebruikt en trek daarna de oude sleutel in.
• Het maken en intrekken van een sleutel wordt vastgelegd onder Audit logs in het Partner Portal, inclusief de sleutelnaam. Elk geslaagd verzoek om licentiegegevens dat met een sleutel wordt gedaan, wordt daar ook vastgelegd, waarbij de sleutelnaam als actor wordt weergegeven. De vermeldingen verschijnen in het auditlog van de partner waartoe de sleutel behoort. Afgewezen verzoeken en verzoeken naar /v1/me worden niet vastgelegd.

Stap 2: Je systeem configureren

Elke integratie heeft dezelfde zaken nodig:

De gegevens één keer per dag ophalen is een goede standaard. De aantallen worden bijgewerkt door een dagelijkse taak (zie "Wat je van de gegevens kunt verwachten" hieronder), dus vaker pollen levert niets op.

Interactieve API-documentatie is beschikbaar op https://partner-api-public.production.uniqkey.eu/docs. De OpenAPI-specificatie, die de meeste tools kunnen gebruiken om een client te genereren, staat op https://partner-api-public.production.uniqkey.eu/openapi/v1.json.

Snel testen met curl

Controleer of de sleutel werkt en bij welke partner deze hoort:

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

Haal vervolgens de eerste paar licentierijen op:

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

Een werkende configuratie retourneert HTTP 200 met een JSON-body zoals die in de sectie "Response" staan. 401 betekent dat de Authorization-header ontbreekt, geen Bearer-token bevat of dat de sleutel onjuist, ingetrokken of verlopen is.

API-referentie

Verzoek

GET /v1/licenses

Een verzoek zonder parameters is geldig en retourneert elke maand van elke organisatie waartoe de sleutel toegang heeft, met de nieuwste maand eerst, één pagina per keer.

De cursor is ondoorzichtig. Maak, parseer of wijzig deze niet. De indeling kan zonder voorafgaande kennisgeving veranderen.

GET /v1/me

Accepteert geen parameters. Retourneert de partner waartoe de sleutel behoort en de eigen naam, prefix en vervaldatum van de sleutel. Gebruik dit om een sleutel te testen. Dit telt, net als elk ander verzoek, mee voor de snelheidslimiet.

Antwoord

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

• Rijen worden gesorteerd op nieuwste maand eerst en daarna op organizationId.
• hasMore geeft aan of je de volgende pagina moet opvragen. Herhaal zolang hasMore waar is.
• nextCursor is null op de laatste pagina.

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 staat in UTC en is null voor een sleutel die niet verloopt.

Fouten gebruiken de standaardindeling voor probleembeschrijvingen (Content-Type: application/problem+json) met een stabiele, machineleesbare 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"
}

Baseer je foutafhandeling op code en de HTTP-status. title en detail zijn bedoeld voor mensen en kunnen veranderen.

Indeling van rijen

Snelheidslimieten

• Elke partner kan minstens 120 verzoeken per minuut doen. De limiet wordt gedeeld door alle sleutels van de partner, dus meer sleutels maken voegt geen capaciteit toe.
• Wanneer de limiet wordt overschreden, retourneert de API 429 met de code too_many_requests en een Retry-After-header met het aantal seconden dat je moet wachten. Wacht minstens zo lang voordat je het opnieuw probeert.
• Aan de netwerkrand geldt een afzonderlijke, hogere limiet per bron-IP-adres. Normale antwoorden bevatten voor die limiet X-RateLimit-*-headers. Wanneer deze wordt overschreden, krijg je ook 429, maar zonder JSON-body. Handel een 429 daarom af op basis van de status en Retry-After, en niet door de body te parseren.

Een dagelijkse synchronisatie met limit=1000 heeft maar een handvol verzoeken nodig en blijft ruim binnen de limieten.

Wat je van de gegevens kunt verwachten

• Aantallen zijn maandelijkse pieken. usageLicenseCount en discoveryInstallationCount zijn de hoogste dagelijkse aantallen die in de maand zijn geregistreerd, niet een gemiddelde of het aantal aan het einde van de maand. Een gebruiker die tussen twee dagelijkse tellingen wordt toegevoegd en weer verwijderd, wordt niet gezien.
• Gegevens kunnen maximaal één dag achterlopen. De aantallen worden geregistreerd door een dagelijkse taak die kort na middernacht UTC wordt uitgevoerd en voor de vorige dag telt. Een wijziging die vandaag wordt aangebracht, verschijnt na de volgende uitvoering.
• De huidige maand kan nog veranderen. Tot de maand voorbij is, verhoogt een nieuwe piek de rij van de huidige maand. De laatste telling voor een maand wordt uitgevoerd in het eerste uur van de 1e van de volgende maand (UTC). Beschouw een maand daarom vanaf 02:00 UTC op de 1e als definitief.
• Elke organisatie krijgt elke maand een rij, ook in maanden met nul gebruik. Rijen beginnen in de maand waarin de organisatie is gemaakt. In zeldzame gevallen, bijvoorbeeld wanneer een dagelijkse uitvoering mislukt, kan een maand voor een organisatie ontbreken. Behandel een ontbrekende maand als onbekend, niet als nul.
• Proeforganisaties zijn inbegrepen. Er worden rijen geretourneerd voor elke organisatie onder je partneraccount, ongeacht of deze een betalende klant is.
• Geen afspraak en een afspraak van 0 zien er hetzelfde uit. Beide worden geretourneerd als committedLicenseCount: null.
• discoveryInstallationCount betreft installaties, niet identiteiten. Het telt passieve extensie-installaties, waarop Discovery wordt gelicenseerd. Het aantal "Corporate identities" op het Discovery-dashboard telt iets anders en komt niet overeen.
• discoveryActivatedNow is niet historisch. Het weerspiegelt de instelling van vandaag en wordt voor elke maand herhaald. Gebruik discoveryInstallationCount voor facturatie.
• Namen zijn huidige namen. Als een organisatie of partner wordt hernoemd, tonen al zijn maanden de nieuwe naam. Koppel op organizationId, niet op namen.
• Verwijderde organisaties behouden hun geschiedenis. Maanden die vóór het verwijderen van een organisatie zijn geregistreerd, worden nog steeds geretourneerd. De rijen tonen niet dat de organisatie is verwijderd.
• Het verplaatsen van een organisatie verplaatst ook de geschiedenis. Alleen Uniqkey kan een organisatie naar een andere partner verplaatsen. Als dat gebeurt, volgen alle maanden, inclusief reeds gefactureerde maanden, de organisatie naar de nieuwe partner. Ze verdwijnen uit de resultaten van de oude partner, tenzij de nieuwe partner onder de oude partner valt.

Opmerkingen voor facturatie- en CRM-integraties

• Bewaar je eigen kopie van gefactureerde maanden. Sla de rijen van elke maand in je systeem op wanneer je factureert. Door de hierboven beschreven verplaatsingen en naamswijzigingen kan een maand die je later opnieuw opvraagt verschillen van wat je hebt gefactureerd.
• Gebruik organizationId en month als sleutel. Elke organisatie heeft maximaal één rij per maand. Werk de rij bij bij volgende synchronisaties in plaats van duplicaten in te voegen.
• Lees recente maanden opnieuw. Een eenvoudige, robuuste synchronisatie vraagt bij elke uitvoering from op vanaf de vorige maand en overschrijft die rijen. Vergrendel vervolgens een maand in je systeem zodra deze is gefactureerd.
• Koppel klanten met organizationExternalId. Open in het Partner Portal de organisatie, bewerk de gegevens en voer het klantnummer uit je CRM in bij External ID. Je kunt dit ook instellen wanneer je een organisatie maakt. Het wordt vervolgens op elke rij teruggegeven. Uniqkey controleert niet of de waarde uniek is.
• Gebruik één sleutel per systeem. Een afzonderlijke sleutel voor facturatie en CRM maakt het auditlog overzichtelijker en stelt je in staat één sleutel in te trekken zonder de andere te verbreken.

Problemen oplossen

Vermeld bij contact met support je partner-id (uit /v1/me), de sleutelnaam, de exacte verzoek-URL zonder de sleutel, de HTTP-status en de antwoordbody inclusief de traceId.