FAQ API

Zie Nmbrs® API voor inhoudelijke informatie over onze API!

Dit artikel bevat de meest gestelde vragen over de API en bijbehorende antwoorden of oplossingen. Staat je vraag er niet tussen? Neem dan contact op met onze support.

  1. Ik krijg een error. Wat nu?
  2. Kan ik de API gebruiken met mijn gewone gebruikersnaam en wachtwoord?
  3. De oorzaak van mijn error is volgens het artikel dat ik geen toegang heb tot het betreffende bedrijf of medewerker, maar dat heb ik wel. Hoe kan dat?
  4. Wat betekent het als ik de 1002 error krijg en geen toegang heb tot de debtor, company of employee services?
  5. Wat is het verschil tussen het API user template en het gewone template van een gebruiker?
  6. Welke calls moet ik voor een koppeling met partij X activeren in het API user template?
  7. Hoe weet ik op welk niveau ik een gebruiker met een API token voor een koppeling moet aanmaken?
  8. Ik krijg een error in een koppeling met een externe partij. Wat moet ik doen?
  9. Ik wil graag weten of er een API call bestaat voor wat ik zoek. Waar kan ik dit vinden?
  10. Ik zie geen call voor het dashlet dat ik zoek staan op api.nmbrs.nl of op de kennisbank. Wat moet ik doen?
  11. Ik maak gebruik van een ander pakket en zou het fijn vinden als er een koppeling te realiseren was, maar ik zie de partij nog niet tussen de koppelingen staan. Hoe nu verder?
  12. Wat wordt de Run ID, wanneer twee of meerdere runs worden samengevoegd?

1. Ik krijg een error. Wat nu?

We hebben een artikel beschikbaar, waar de verschillende error codes die er zijn worden doorgenomen. Ook wordt er een oplossing voor elke error gegeven. 

2.  Kan ik de API gebruiken met mijn gewone gebruikersnaam en wachtwoord?

Via de API wordt geen verbinding gemaakt met een gebruikersnaam en wachtwoord, zoals in de omgeving zelf, maar er wordt gebruik gemaakt van een gebruikersnaam en API token. De gebruikersnaam is altijd het e-mailadres waarmee ook wordt ingelogd in de omgeving, de API token kun je toevoegen aan die gebruiker.
Over het toevoegen van een API token aan een gebruiker hebben wij ook artikelen beschikbaar, meer informatie daarover kun je hier lezen:

3. De oorzaak van mijn error is volgens het artikel dat ik geen toegang heb tot het betreffende bedrij of medewerker, maar dat heb ik wel. Hoe kan dat?

Wanneer dit het geval is, is er meestal sprake van verwarring tussen het ID en het nummer van een bedrijf, medewerker of debiteur in Nmbrs.

De API maakt gebruik van ID's, waar in de omgeving zelf gebruik wordt gemaakt van nummers. Dit geldt voor alles, maar in dit stukje zoomen we even in op bedrijf, medewerker en debiteur ID's, omdat dit in de praktijk het vaaks fout blijkt te gaan.

Veel voorkomende errors zijn de:

  • 1003: unauthorized access
  • 2003: unauthorized access
  • 2004: unauthorized access

Te lezen is in het artikel met API error codes, is de oorzaak hiervoor dat er geen rechten zijn voor het bedrijf, de medewerker of de debiteur waarvoor je de call doet. Vaak ligt dit aan een verwarring tussen het ID en het nummer van (bijvoorbeeld) het bedoelde bedrijf. Wordt het ID verward met het nummer, zal de database dit "ID" niet herkennen in combinatie met de gebruikersnaam en token en er automatisch vanuit gaan dat er geen rechten zijn voor het bedoelde bedrijf.

Let op! Ook als er informatie over een medewerker wordt opgevraagd, kan één van de bovenstaande errors optreden. Een medewerker is tenslotte altijd onderdeel van een bedrijf en als er geen toegang is tot de medewerker, betekent dit dat er geen toegang is tot het bedrijf.

Een andere manier waarop het companyID of employeeID gemakkelijk te vinden is, is als je de volgende stappen doorloopt:

  1. Ga naar de omgeving waar het bedrijf / de medewerker zich bevindt waarvan / van wie je het ID nodig hebt.
  2. Wanneer je in de omgeving bij het specifieke bedrijf bent, klik rechter muisknop - inspecteren. Het volgende scherm verschijnt:


    Sidenote: dit kan er iets anders uitzien dan op bovenstaand voorbeeld. Dit scherm kan bijvoorbeeld ook links of onderaan verschijnen.
  3. Vervolgens klik je op het tekentje links boven in dat scherm:
  4. Er verschijnt nu een mogelijkheid verschillende delen van de pagina te selecteren. Je selecteert met je muis het gewenste bedrijf, of de gewenste medewerker, en klikt daarop:
  5. Wanneer je geklikt hebt, verschijnt in het scherm een nummer. Dat nummer is het gezochte ID:

4. Wat betekent het als ik de 1002 error krijg en geen toegang heb tot de debtor, company of employee services?

Voor de API geldt dat gebruik wordt gemaakt van de rechten, die geregeld worden in het API user template. Dit template vind je in het reguliere "template users" dashlet, op debiteur- of masterniveau.

In het API user template staan alle beschikbare calls. Per call kun je aanvinken of je will dat deze actief (active) of niet actief (inactive) is. Op deze manier bepaal je welke calls succesvol (dus zonder error) kunnen worden gedaan door gebruikers met het betreffende template.  Wanneer je de 1002 error krijgt, die als oorzaak heeft dat er geen rechten zijn voor de betreffende service, betekent dit dat de rechten in het API user template van de specifieke gebruiker voor de call op inactive staan.

Meer informatie over het API user template, vind je in dit artikel: API user template.

5. Wat is het verschil tussen het API user template en het gewone template van een gebruiker?

Het API user template en het gewone template van een gebruiker staan helemaal los van elkaar. Wanneer een gebruiker geen toegang heeft tot een bepaald dashlet in Nmbrs, omdat de rechten hiervan op "geen" staan, kan de gebruiker mogelijk nog wel via de API de gegevens uit dat dashlet opvragen, als de calls hiervoor aan staan.

Dit is handig in bijvoorbeeld de situatie waarin je een speciale login aanmaakt voor een koppeling met (bijvoorbeeld) een planningspakket, maar niet wil dat zij ook daadwerkelijk iets kunnen zien in de omgeving zelf. Je kunt dan alle rechten met betrekking tot dashlets op "geen" zetten in de omgeving, zodat bij inloggen niets te zien is. Vervolgens kun je in het API user template alle calls die nodig zijn voor het optimaal functioneren van de koppeling activeren. De gebruiker kan dan wel de benodigde informatie via de API opvragen.

Let op! De API zal de basisrechten van het template volgen. Een klantlogin bijvoorbeeld heeft nooit toegang tot debiteurniveau. Om deze reden zullen DebtorService calls van de API voor een gebruiker met een klantlogin ook een lege respons hebben, ook al staan de rechten in het API user template op "active".

6. Welke calls moet ik, voor een koppeling met partij X, activeren in het API user template?

Dit is afhankelijk van de koppeling. Wij stellen onze open API gratis beschikbaar voor het bouwen van koppelingen door andere partijen, die op deze manier onze partners kunnen worden. De koppelingen zijn dus echter altijd door deze andere partij gebouwd. Zij kunnen je daarom ook het beste informeren over welke calls voor hun koppeling belangrijk zijn om geactiveerd te hebben - zij weten namelijk welke calls er bij het bouwen zijn gebruikt. Neem voor dit soort vragen dus altijd contact op met onze partner.

7. Hoe weet ik op welk niveau ik een gebruiker met een API token moet aanmaken?

Eigenlijk geldt voor deze vraag hetzelfde als voor vraag 6, de partner kan je hier het beste over informeren. Wel kun je je van tevoren afvragen welk niveau je zelf logisch lijkt. Is het bijvoorbeeld een koppeling die, met één API token, moet werken voor meerdere bedrijven onder verschillende debiteuren? In dat geval zal sowieso alleen een gebruiker op masterniveau volstaan.

8. Ik krijg een error in een koppeling met een externe partij. Wat moet ik doen?

Waarschijnlijk gaat er iets niet goed in de koppeling. Neem contact op met de support van onze partner in kwestie, zij kunnen je waarschijnlijk verder helpen. Mochten zij er niet uit komen, nemen zij met ons contact op.

9. Ik wil graag weten of er een API call bestaat voor wat ik zoek. Waar kan ik dat vinden?

Op api.nmbrs.nl staat een overzicht van alle calls die we hebben, per service. Je kunt doorklikken naar een van de API services welke wordt aangeboden. Vervolgens kun je zoeken op trefwoorden om na te gaan of de call waar je naar op zoek bent bestaat.

10. Ik zie geen call voor het dashlet dat ik zoek staan op api.nmbrs.nl of op de kennisbank. Wat moet ik doen?

Als je echt geen call ziet die betrekking heeft op de betreffende functionaliteit of het betreffende dashlet, kun je een wens indienen op onze feature request pagina. Deze pagina vind je hier:

11. Ik maak gebruik van een ander pakket en zou het fijn vinden als er een koppeling te realiseren was, maar ik zie de partij nog niet tussen de koppelingen staan. Hoe nu verder?

Omdat wij nooit, zoals uitgelegd onder punt 6, zelf actief koppelen met een externe partij is dit iets dat wij bij de andere partij neerleggen. Je zou dus kunnen informeren of er aan die kant interesse is te koppelen met onze software.

Daarnaast kun je altijd kijken in onze lijst met koppelingen met maatwerkpartners. Deze partners zijn in staat een maatwerkoplossing te bouwen naar jouw wensen.

12. Wat wordt de Run ID, wanneer twee of meerdere runs worden samengevoegd?

Na het samenvoegen blijft de run-ID van de normale run altijd behouden.

Bijvoorbeeld: de run van periode 1 ID 101. Een correctie wordt uitgevoerd voor periode 1; deze run heeft ID 202. Wanneer de runs worden samengevoegd, heeft de run ID 101.

Zie Run samenvoegen voor meer informatie over het samenvoegen van runs.

Opmerkingen