App Keys aanmaken, een SecurityToken ophalen en geauthenticeerde SOAP-requests doen op de legacy eConnect API.
Voordat je de legacy SOAP API kunt gebruiken, heb je App Keys nodig en moet je een SecurityToken ophalen via het Login-endpoint. Dit artikel legt stap voor stap uit hoe dat werkt.
Let op: Dit is de legacy SOAP API. Voor nieuwe integraties raden we de REST API aan, die OAuth 2.0 gebruikt.
App Keys bestaan uit een Consumer Key en een Consumer Secret. Je maakt ze aan in het eConnect-platform onder het menu Verbindingen. Hiervoor heb je een beheerdersrol nodig.
Er zijn twee typen apps beschikbaar:
Voor de accountant-variant gebruik je App Integration Requests: de klant geeft via het platform toestemming voor toegang tot zijn administratie. Dit is relevant als je als softwareleverancier namens meerdere klanten werkt.
De authenticatie verloopt in twee stappen:
Stap 1: Login
Roep het Login-endpoint aan met je Consumer Key en Consumer Secret. Je krijgt een SecurityToken terug.
<Login>
<ConsumerKey>jouw-consumer-key</ConsumerKey>
<ConsumerSecret>jouw-consumer-secret</ConsumerSecret>
</Login>
Stap 2: SecurityToken meegeven
Geef het SecurityToken mee in de SOAP-header bij alle vervolgaanroepen. Het token is 4 uur geldig. Je kunt ook per sessie een nieuw token aanvragen.
<soap:Header>
<SecurityToken>ontvangen-security-token</SecurityToken>
</soap:Header>
Stap 3: Account-informatie ophalen
Na een succesvolle login roep je GetAccountParties aan om je EConnectPartyId (XCNL-nummer) op te halen. Dit ID heb je nodig bij het verzenden en ontvangen van documenten.
https://api.everbinding.nl/soap/v3.1?subscriptionKey={subscriptionKey}De WSDL bevat de volledige specificatie van alle beschikbare endpoints, datatypes en foutcodes. Je kunt de WSDL importeren in tools als SoapUI of Visual Studio om automatisch client-code te genereren.
Transfer-Encoding=chunked: de SOAP API ondersteunt geen chunked transfer encoding. Zorg dat je HTTP-client de content-length header meestuurt in plaats van chunked encoding te gebruiken. Dit is een van de meest voorkomende implementatiefouten.
Token verlopen: als je SecurityToken ouder is dan 4 uur, krijg je een authenticatiefout (foutcodeserie 600). Vraag dan een nieuw token aan via Login.
Geen subscriptionKey: zonder geldige subscriptionKey in de endpoint-URL worden alle requests afgewezen. Controleer of de key correct is en nog actief.
De SOAP API retourneert gestructureerde foutcodes in het formaat ERR + opcode + serie + ID. De foutcodeseries geven het type fout aan:
Een SecurityToken is 4 uur geldig na het aanvragen via het Login-endpoint. Na afloop ontvang je een authenticatiefout (foutcodeserie 600) bij vervolgaanroepen. Vraag dan een nieuw token aan. Je kunt er ook voor kiezen om per sessie een nieuw token op te halen.
Een Generic App heeft een publieke naam die vooraf is ingevuld door eConnect en is geschikt voor standaardintegraties. Een Own App is privé: je kiest zelf een naam en optioneel een logo, wat handig is voor maatwerkkoppelingen. Beide typen leveren een Consumer Key en Consumer Secret op.
De SOAP API ondersteunt geen chunked transfer encoding. Dit is een van de meest voorkomende implementatiefouten. Zorg dat je HTTP-client de Content-Length header meestuurt in plaats van chunked encoding te gebruiken. Pas dit aan in de configuratie van je HTTP-client of SOAP-library.
Overweeg je de overstap naar OAuth2 en de REST API? Bekijk de PSB-documentatie op psb.econnect.eu voor de moderne authenticatieflow.
Stap over naar de REST API