Overslaan naar inhoud
Nederlands
Meer over cash
  • Er zijn geen suggesties want het zoekveld is leeg.

Hoe stel ik een API-gebruiker en koppeling in?

Stappenplan voor het leggen van een API-koppeling (inclusief technische documentatie)

Een API-applicatie is een softwaretoepassing die is ontwikkeld om te communiceren met een API (Application Programming Interface). Met een API kunnen verschillende softwaretoepassingen veilig en direct met elkaar praten en gegevens uitwisselen. Dit bespaart veel tijd, omdat je hiermee realtime gegevens kunt ophalen, verzenden of bijwerken, zonder dit handmatig in het pakket te hoeven doen.

Binnen het pakket ondersteunen we twee soorten koppelingen:

  • Versie drie (SOAP API): Maakt gebruik van XML en wordt veel gebruikt voor de compatibiliteit tussen oudere en complexe systemen.
  • Versie vier (REST API): Een modernere benadering die zorgt voor efficiënter dataverbruik en een snellere uitwisseling van gegevens.
1. Wat is een API-gebruiker?

Om een externe partij of applicatie toegang te geven tot jouw administratie, moet je een specifieke API-gebruiker instellen. Dit is een apart account dat uitsluitend is bedoeld voor de technische koppeling. Gebruik dit account dus bewust niet voor je eigen, dagelijkse handelingen in het pakket!

2. Een nieuwe API-gebruiker aanmaken

Volg de onderstaande stappen om een gebruiker voor de koppeling in te stellen:

  • Inloggen: Log in met je relatienummer, e-mailadres en wachtwoord en open de gewenste administratie.
  • Gebruikersoverzicht: Klik rechtsboven op het tandwiel-icoontje (Instellingen) en kies in het menu voor Gebruikersoverzicht.
  • Gebruiker toevoegen: Gebruik je een bestaande gebruiker? Ga dan door naar stap drie. Wil je een nieuwe gebruiker aanmaken? Klik dan op de knop Maak aan. Vul hier een herkenbare naam en een uniek e-mailadres in voor deze koppeling. Sla dit op via de groene knop Maak aan.
3. De API-gebruiker activeren (Belangrijk!)

Heb je zojuist een volledig nieuw account aangemaakt voor de koppeling? Dan moet je deze eerst eenmalig activeren. Dit doe je simpelweg door één keer met dat nieuwe e-mailadres in te loggen in het pakket. Zodra je succesvol bent ingelogd, is het account actief.

4. De API-sleutel (API-key) genereren

Nu de gebruiker klaarstaat, kun je de unieke sleutel genereren waarmee de externe applicatie toegang krijgt.

  • Gebruiker wijzigen: Ga terug naar het Gebruikersoverzicht (via het tandwiel-icoontje) en klik op Wijzig bij de zojuist gekozen API-gebruiker.
  • Tabblad API: Klik bovenaan op het tabblad API. De overige tabbladen en instellingen mag je leeglaten, deze zijn voor de koppeling niet belangrijk.
  • Sleutel genereren: Vink de optie API gebruiker aan en klik op de knop Genereer. Er verschijnt nu een lange, unieke code. Dit is de API-key.
  • Kopiëren: Selecteer de volledige code (bijvoorbeeld met de sneltoets Ctrl + A) en kopieer deze. Je moet deze code straks invullen in de externe applicatie.
  • Opslaan: Klik ten slotte op de groene knop Wijzig om de instellingen definitief op te slaan (dit is essentieel bij versie vier).
     

Belangrijke tips van de Helpdesk:

  • Geen administratiecode: Koppel nooit een standaard administratiecode aan de API-gebruiker! Doe je dit wel, dan beperk je de koppeling tot uitsluitend die ene administratie en kunnen er geen gegevens uit andere administraties worden opgehaald.
  • Rechten: Via de meewerkfunctie (voor bijvoorbeeld accountants) is het niet mogelijk om een API-key te genereren. Dit kan alleen worden gedaan door de systeembeheerder die de licentie beheert. Mocht de bouwer van de API-applicatie ook zelf mee willen kijken in het pakket, maak daar dan een apart (normaal) gebruikersaccount voor aan.
5. Technische specificaties en voorbeelden

Onderstaande onderwerpen gaan over uitgebreide technische informatie over indexen, REST-API requests en de webshopkoppeling.

 1: Index referentie

In dit onderdeel vind je per index een korte toelichting en de bijbehorende 'request URL'.

  • 101 Relatie: Voor het opvragen van relatie stamgegevens en debiteurenposten per relatie.
    • 101: Alle relatie stamgegevens.
    • 101P: Relatie stamgegevens plus de individuele openstaande debiteurenposten.
    • 101D: Relatie stamgegevens plus het saldo openstaande debiteurenposten.
    • 101V: Relatie stamgegevens plus het saldo vervallen debiteurenposten.
    • 101T: Relatie stamgegevens gefilterd op trefwoord.
    • 101W: Recent gemuteerde relatie stamgegevens.
  • 201 Grootboeksaldi: Voor het opvragen van de grootboeksaldi (bijvoorbeeld per jaar of periode). Inclusief indexen zoals 211T (resultaat vorige jaren) en 211R (met RGS codes).
  • 301 Grootboekmutatie: Voor het opvragen van grootboekmutaties en boekstukken. Handige indexen zijn 301T (van/tot periode) en 301P (opvragen pdf bij een boekstuk in BASE64).
  • 311 Subadministratie: Opvragen van de debiteuren en crediteuren subadministratie. Beschikbaar als 311T (inclusief vervaldatum en bedrag) en 311H (historisch).
  • 450 Artikelcodes (Factureren): Voor het opvragen van de financiële artikelcodes.
  • 2050 Opvragen nieuw relatienummer: Voor het opvragen (2050N) en reserveren (2050R) van het eerstvolgende nieuwe relatienummer.
  • 2260 Artikel (Handel): Voor het opvragen van handelsartikelen. Inclusief varianten zoals 2260I (met inkoopprijzen), 2260K (met voorraad) en 2260W (recent gemuteerd).
  • 2400 / 2410 Verkooporder: Voor het opvragen van orderkoppen (2400) en orderregels (2410).
  • 8500 / 8504 Laatste stuknummer: Voor het opvragen van het laatste stuknummer per dagboek.
  • 8502 / 8503 Recent gemuteerd: Voor respectievelijk relaties (8502) en artikelen (8503).
 2: REST-API requests en voorbeelden

Alle genoemde API-requests kunnen veilig worden uitgeprobeerd in de REST API Swagger UI.

Export cURL GET voorbeeld

Toelichting op de query parameters:

  • admin: De vier tekens van de administratiecode (bijv. demo).
  • format: Niet van toepassing of gereserveerd.
  • params: Voor het meegeven van extra parameters bij de opgevraagde index (gescheiden door een pipe-teken |).
  • admdir: Het opgeven van een submap indien de administratie niet in de hoofdmap staat.
  • index: Geeft aan welke gegevens opgevraagd moeten worden.
curl -X 'GET'   'https://www.cashweb.nl/api/4.0/get/index/301T?admin=demo&params=2201%7C2202'   -H 'accept: application/json'   -H 'Authorization: MTIzNDU2X2V4YW1wbGVrZXlleGFtcGxla2V5ZXhhbXBsZWtleV85OTk5OQ=='

Import cURL POST voorbeeld

Met een POST-verzoek kun je gegevens wegschrijven, zoals het importeren van nieuwe relaties.

curl -X 'POST'   'https://www.cashweb.nl/api/4.0/import'   -H 'Content-Type: application/json'   -d '{
  "admin": "demo",
  "format": 0,
  "content": {
    "cash": [
      { "R101": [ { "F0101": "001101", "F0103": "Naam 1" } ] }
    ]
  }
}'

Administrations cURL GET voorbeeld

Met dit verzoek vraag je een overzicht op van de via API beschikbare administraties voor een specifieke gebruiker.

Subartikel 3: Webshopkoppeling REST-API (versie vier)

Als een externe webshop wordt gebruikt in combinatie met de handelsmodule, dan kan de specifieke webshopkoppeling geactiveerd worden.

Om de laatste wijzigingen in relaties en artikelen op te kunnen vragen én aan te geven welke artikelgroepen beschikbaar moeten zijn via de API, dient de webshopkoppeling handmatig geactiveerd te worden. Dit doe je als volgt:

  1. Log in met je relatienummer, e-mailadres en wachtwoord in het pakket.
  2. Selecteer de gewenste administratie.
  3. Navigeer in het menu naar Handel > Instellingen > Systeemswitches.
  4. Klik op de knop Verk-I.
  5. Vink de optie Webshoplink aan en klik op Opslaan om je keuze te bevestigen.

Na het uitvoeren van deze stappen moet je de artikelgroepen activeren die via de API opgevraagd mogen worden. Hiermee activeer je direct ook de onderliggende artikelen:

  • Navigeer in het menu naar Handel > Tabellen > Artikelen > Artikelgroep.
  • Blader door de artikelgroepen, open ze en kies bij de optie Synchroniseren web voor de waarde Gekoppeld.