REST API

Met de REST API praten je eigen systemen rechtstreeks met SalesDash. Je leest de cijfers die SalesDash heeft berekend — welke metrics er zijn, en wat elke agent op één daarvan scoorde over een periode — en je schrijft doelstellingen weg vanuit de plek waar je ze toch al plant.

Hij staat naast de twee andere manieren waarop data in en uit SalesDash beweegt:

Wat je wilt	Wat je gebruikt
Activiteit naar SalesDash sturen — sales, gesprekken, deals	Een provider, of de webhooks-provider
Resultaten uit SalesDash lezen, of doelstellingen vanuit een ander systeem zetten	De REST API, deze sectie
Vragen stellen en meteen handelen naar het antwoord	De AI-verbinding

Vaak lopen alle drie tegelijk: een provider voert activiteit aan, SalesDash maakt er metrics van, en de REST API geeft die cijfers door aan je intranet, je salarisrun of je weekrapportage.

Basis-URL

Elk endpoint hangt onder je eigen SalesDash-adres:

https://jouwbedrijf.salesdash-app.com/integrations/api/v1

Vervang de host door het adres waarmee je inlogt. De v1 in het pad is de versie — een volgende versie komt ernaast te staan en verandert niets aan wat v1 teruggeeft.

Een sleutel aanmaken

Ga naar Organisatie > API sleutels in de admin, klik op API sleutel aanmaken en geef hem een naam die zegt welk systeem hem gebruikt — Salarisexport, Intranet-dashboard.

SalesDash toont de sleutel meteen na het aanmaken, en je kunt hem later opnieuw openen met Bekijken in de lijst.

Maak per systeem een eigen sleutel in plaats van één sleutel rond te delen. Als je een koppeling uitzet, verwijder je die ene sleutel en blijft de rest gewoon werken.

Een sleutel draagt de toegang van degene die hem maakte

Een sleutel hoort bij de admin die hem heeft aangemaakt en handelt volledig namens die persoon. Verliest die persoon zijn adminrol, of zijn toegang tot SalesDash, dan stoppen al zijn sleutels op datzelfde moment. Loopt er een koppeling op de sleutel van iemand die vertrekt, dan merk je dat anders pas als het misgaat.

Authenticeren

Stuur de sleutel bij elk verzoek mee als bearer token:

Authorization: Bearer JOUW_API_SLEUTEL

Om te controleren of een sleutel werkt, vraag je op bij wie hij hoort:

GET /integrations/api/v1/me

{
  "id": 1,
  "name": "Fixture Admin",
  "email": "admin@jouwbedrijf.example"
}

Dat is ook de snelste manier om te zien namens welke admin een overgenomen sleutel draait.

Als er iets misgaat

401 Unauthorized — de sleutel ontbreekt, klopt niet, is onbekend, of hoort bij iemand die geen actieve admin meer is. De reden komt terug in de WWW-Authenticate-header en niet in de body, dus lees die header als je wilt weten welke van de vier het was.

422 Unprocessable Content — het verzoek kwam aan, maar er klopt iets niet: een datum in het verkeerde formaat, een metric die niet per agent te scoren is, een team dat niet bestaat. De body noemt het veld:

{
  "message": "Geselecteerde metric id is ongeldig.",
  "errors": {
    "metric_id": [
      "Geselecteerde metric id is ongeldig."
    ]
  }
}

Een 422 is er om te lezen, niet om opnieuw te proberen — hetzelfde verzoek faalt op dezelfde manier tot je het aanpast, of tot iemand de metric in de admin aanpast.

Meldingen komen in de taal van je omgeving

Foutmeldingen worden net als de rest van SalesDash vertaald, dus een Engelstalige omgeving antwoordt in het Engels. Kijk naar de sleutel in errors (metric_id, team_goals.0.team_id) in plaats van naar de tekst van de melding.

5xx — er ging iets mis aan de kant van SalesDash, bijvoorbeeld een query die te lang duurde. Die zijn het opnieuw proberen waard; een 422 niet.

Wat je hier vindt

• Metricscores — de metrics in je omgeving opvragen, en daarna lezen wat elke actieve agent op één ervan scoorde over een periode.
• Doelstellingen — een doelstelling voor één of meer teams aanmaken of bijwerken, en een persoonlijke doelstelling voor een agent zetten.