INHOUDSOPGAVE

• Introductie
• Voorwaarden
• Globaal stappenplan
• Technische details
  • Connectie
  • Authenticatie
  • Aanroep
  • Response
  • Payload
• Troubleshooting

Introductie

Met Connect XS kan op verschillende manieren verbinding gemaakt worden om gegevens uit te wisselen: onder andere op basis van SFTP (als server of client), via een Application Programming Interface (API) met een extern systeem of door middel van Web Services. Hierbij lijken SFTP en Web Services veel op elkaar in dat ze beiden gebruikt worden om (verschillende typen) bestanden als geheel uit te wisselen, waar bij een API de structuur van de data vaststaat.

LET OP:
Het is in verregaande mate mogelijk om alle voorbereidingen te treffen om een verbinding op basis van Web Servies te realiseren. Het daadwerkelijk uitgeven van de credentials kan echter enkel worden uitgevoerd door Otherside at Work.

De Web Services van Otherside at Work ondersteunen de volgende functies op basis van SOAP-instructies:

Voorwaarden

Web Services zijn een methode van bestandsoverdracht. Hoe deze bestanden gegenereerd (in geval van een export uit XS) of verwerkt (in geval van een import in XS) worden staat er volledig van en kan derhalve naar believen voorbereid worden in Connect XS. Omdat elke Web Service zich anders gedraagt, zal de aansluitende partij programmeerwerk moeten verrichten om specifiek met de Web Services van Otherside at Work te kunnen verbinden.

Globaal stappenplan

1. Creëer in Connect XS een klantaccount van het type Otherside SFTP
2. Creëer daarbinnen de gewenste import(s) en export(s)
3. Creëer in FreshDesk een ticket voor Technical Support met daarin de volgende parameters:
   1. het externe systeem van waaruit de verbinding zal worden gelegd. Indien dit een SaaS-oplossing is ('in the cloud'), graag de leverancier erbij vermelden
   2. het IP-adres - of de IP-adressen - van het externe systeem van waaruit verbinding zal worden gemaakt
   3. de XS-omgeving waarmee de verbinding moet worden gelegd. U mag ook uw eigen XS gebruikersnaam opgeven, dan kan Support op basis daarvan de juiste XS-omgeving bepalen
   4. de naam van het klantaccount in Connect XS zoals gecreëerd bij 1
   5. optioneel: een gewenste gebruikersnaam (hierna te noemen 'klantcode') die wordt aangemaakt voor deze Web Services
4. Verstrek de door Support gegenereerde klantcode en token aan de leverancier of persoon die de koppeling vanuit het externe systeem realiseert 

Tip:
Voeg aan de lijst van IP-adressen ook een IP-adres toe van (de laptop van) een kennishoudend persoon zodat deze eventueel handmatig de Web Services kan aanroepen om te troubleshooten. Dit IP-adres kan na het testen door Technical Support verwijderd worden.

Technische details

Connectie

De Web Services van Otherside at Work zijn te benaderen via de volgende URLs:

Op de home page kan een externe partij de WSDL (Web Services Description Language) vinden waarin alle mogelijke functies zijn opgenomen. Hiermee hebben ze een eerste vliegende start bij het programmeren.

Authenticatie

Voor een succesvolle aanroep van de Web Services dient een drietal zaken te worden gecombineerd:

• de datum/tijd van berekening (in format 2025-01-01T12:34:56)
• de klantcode zoals door TSC uitgegeven
• een application token uitgegeven in lower case

Deze drie gegevens dienen door middel van SHA512 in deze combinatie te worden versleuteld:

Token_DatumTijd_Klantcode

Als voorbeeld:

Aanroep

De meest eenvoudige functie om mee te testen is de GetMetaData. Daarmee kan het succesvol authenticeren getest worden zonder dat ook rekening gehouden dient te worden met het succesvol samenstellen van een 'payload' - een te versturen bestand.

Een voorbeeld van een dergelijke aanroep is als volgt:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.verzuimexpert.nl/" xmlns:emp="http://schemas.datacontract.org/2004/07/Empirion.ImportWebService.Models">

   <soapenv:Header/>

   <soapenv:Body>

      <web:GetMetaData>

         <web:header>

            <emp:DatumTijd>2025-01-01T12:34:56</emp:DatumTijd>

            <emp:Hash>

3fb8691c806a6242513270dc662e839a88ef29ad390029d75290b9fda67998af6aff0b8092ac629ed53aec2a0c35bb6b0ca69ae3bedc22dba5fb8897a0b1d802

            </emp:Hash>

            <emp:KlantCode>Hashvoorbeeld</emp:KlantCode>

         </web:header>

     </web:GetMetaData>

   </soapenv:Body>

</soapenv:Envelope>

Response

In dat geval kan men vanuit de Web Services het antwoord krijgen dat de authenticatie correct was (Status: OK), maar dat er geen bestanden klaarstaan om vanuit Connect XS op te halen (Bestanden: 'leeg')

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

   <s:Body>

      <GetMetaDataResponse xmlns="http://webservices.verzuimexpert.nl/">

        <GetMetaDataResult

xmlns:a="http://schemas.datacontract.org/2004/07/Empirion.ImportWebService.Models" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

            <a:Bestanden i:nil="true"/>

            <a:Status>OK</a:Status>

         </GetMetaDataResult>

      </GetMetaDataResponse>

   </s:Body>

</s:Envelope>

Payload

Als men een bestand wil uploaden naar Connect XS, dient men deze aan te leveren als 'payload' binnen het SOAP Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.verzuimexpert.nl/" xmlns:emp="http://schemas.datacontract.org/2004/07/Empirion.ImportWebService.Models">

   <soapenv:Header/>

   <soapenv:Body>

      <web:Upload>

         <web:header>

            <emp:DatumTijd>2025-01-01T12:34:56</emp:DatumTijd>

            <emp:Hash>

3fb8691c806a6242513270dc662e839a88ef29ad390029d75290b9fda67998af6aff0b8092ac629ed53aec2a0c35bb6b0ca69ae3bedc22dba5fb8897a0b1d802

            </emp:Hash>

            <emp:KlantCode>Hashvoorbeeld</emp:KlantCode>

         </web:header>

         <web:metadata>

            <emp:Bestandsnaam>VZ20250101_123456_01.xml</emp:Bestandsnaam>

            <emp:ImportType>VZ</emp:ImportType>

         </web:metadata>

         <web:data>

             Hier volgt het daadwerkelijke bestand met behulp van Base64 Encode

         </web:data>

      </web:Upload>

   </soapenv:Body>

</soapenv:Envelope>

Te vullen velden in de aanroep:

Troubleshooting

De Connect XS Web Services kunnen de volgende SOAP responses geven:

OK

De aanroep was succesvol en de betreffende functie is succesvol uitgevoerd:

• Upload: het bestand is in Connect XS afgeleverd aan de ontvangende partij
• GetMetaData: in de respons staan de op dat moment klaarstaande bestanden met hun bijbehorende ImportType. Als er geen bestanden klaarstaan, is de respons leeg
• GetFile: in de respons staat in <Bestandsnaam> de fysieke bestandsnaam en in het <Data>-veld de Base64-representatie van het opgehaalde bestand
• Delete: de verwijdering van het in de request aangegeven bestand is voltooid

NotAuthorized

De authenticatie van de Web Services is als volgt:

1. Bestaat er een configuratie van de Web Services met die Klantcode?
   Zo ja, ga naar 2
   Zo nee: uitvalmelding 'NotAuthorized': klantcode onbekend
2. Komt deze connectie vanuit een IP-adres dat hoort bij het externe systeem dat is vastgesteld voor deze klantcode?
   Zo ja, ga naar 3
   Zo nee: uitvalmelding 'NotAuthorized': het gebruikte IP-adres is niet geautoriseerd om deze klantcode aan te roepen
3. klopt de hashberekening bij de klantcode?
   Zo ja, ga naar 4
   Zo nee: uitvalmelding 'NotAuthorized': de hashberekening is incorrect
4. de externe partij is nu volledig geauthenticeerd. Nu komt nog de check met Connect XS van de betreffende XS-omgeving: komt de <ImportType> in het SOAP Request voor als beschikbare map in het klantaccount behorende bij deze configuratie van de Web Services?
   Zo ja: succes!!!!
   Zo nee: uitvalmelding 'NotAuthorized': men probeert een bestand uit te wisselen op een niet-bestaande map

MessageExpired

De hashberekening (en dus de in de aanroep gehanteerde <DatumTijd>) moet binnen een bepaalde 'time window' te vallen: -5 min > OaW-servertijd > 55 min. Op die manier kan een door een andere partij onderschepte aanroep niet nogmaals gebruikt worden.

Error

Er is een probleem met de door OaW geïmplementeerde configuratie van de Web Services. Dit dient door Otherside geanalyseerd en gecorrigeerd te worden. Maak hiertoe een ticket aan in FreshDesk en geef hierbij zo goed als mogelijk aan op welke datum en tijd je de aanroep deed.