API

Alle beschrijvingen over de module: API kunt u hier vinden

Inkoop facturen Importeren

Doormiddel van een externe applicatie kunnen er inkoopfacturen worden ingelezen in Hybrid SaaS van een bepaalde leverancier

De Applicatie

In de applicatie kan de instelling van de omgeving worden ingesteld. In het hoofdscherm is er zichtbaar welke omgeving actief is.

Image Source: Hybrid SaaS

De gebruiker

Deze omgeving is gekoppeld aan een gebruiker (met wachtwoord) en een externe applicatie.

Image Source: Hybrid SaaS

Gekoppeld aan de omgeving

De omgeving is gekoppeld met de gegevens van de gebruiker

Image Source: Hybrid SaaS
Image Source: Hybrid SaaS

Gegevens ophalen

De bestanden kunnen worden opgehaald van de computer

Image Source: Hybrid SaaS

Na het kiezen voor verwerken zullen de facturen worden geïmporteerd Tijdens het laden kan je de voortang zien recht onderin

Image Source: Hybrid SaaS

De inkoopfactuur

Na verwerken zijn de producten aangemaakt

Hier word een voorbeeld van een artikel getoond

Image Source: Hybrid SaaS

De inkoopfactuur is nu toegevoegd in Hybrid SaaS met de volgende eigenschappen:

Image Source: Hybrid SaaS

Indien er een verschil in berekening van de btw op zit, zal deze automatisch worden gecorrigeerd.

Image Source: Hybrid SaaS

De inkoopfacturen worden gekoppeld aan de standaard entiteit en standaard inkoop werkcode, daarnaast zoekt het systeem op de letterlijke naam van de leverancier die in de import staat, indien er ook producten zijn gevonden worden deze automatisch gelinkt

De foutmelding

Indien er fouten optreden tijdens het verwerken is dat terug te zien

Image Source: Hybrid SaaS

Door te dubbelklikken op de regel komt de meldingen in beeld:

Image Source: Hybrid SaaS

Producten importeren

Doormiddel van een externe applicatie kunnen er producten worden ingelezen in Hybrid SaaS van een bepaalde leverancier

De Applicatie

In de applicatie kan de instelling van de omgeving worden ingesteld. In het hoofdscherm is er zichtbaar welke omgeving actief is.

Image Source: Hybrid SaaS

De gebruiker

Deze omgeving is gekoppeld aan een gebruiker (met wachtwoord) en een externe applicatie.

Image Source: Hybrid SaaS

Gekoppeld aan de omgeving

De omgeving is gekoppeld met de gegevens van de gebruiker

Image Source: Hybrid SaaS
Image Source: Hybrid SaaS

Gegevens ophalen

De bestanden kunnen worden opgehaald van de computer

Image Source: Hybrid SaaS

Na het kiezen voor verwerken zullen de producten worden geïmporteerd Tijdens het laden kan je de voortang zien recht onderin

Image Source: Hybrid SaaS

Producten

Na verwerken zijn de producten aangemaakt

Hier word een voorbeeld van een artikel getoond

Image Source: Hybrid SaaS

Het product is nu toegevoegd in Hybrid SaaS met de volgende eigenschappen:

Image Source: Hybrid SaaS

Indien er een verschil in berekening van de btw op zit, zal deze automatisch worden gecorrigeerd.

Image Source: Hybrid SaaS

Externe productkoppeling

Met externe productkoppeling van Hybrid SaaS is het mogelijk uw productcatalogus en voorraadinformatie te delen met externe partijen. Momenteel bieden wij ondersteunen wij de volgende partijen:
• Bol.com
• Beslist.nl
• Google

Tevens is het mogelijk om ruwe productsheets aan te leveren aan andere externe partijen. Voordat u aan de slag gaat dient u eerst e.e.a. af te stemmen met de partij waar u een koppeling mee wilt realiseren. Denk hierbij bijvoorbeeld aan het afstemmen van eventuele product- of productgroep benamingen. Tevens dient u zogenoemde ftp-inloggegevens te verkrijgen.

Toevoegen externe productkoppeling

Klik op start en zoek naar externe productkoppeling Klik op toevoegen om een nieuwe externe productkoppeling toe te voegen

Image Source: Hybrid SaaS

Selecteer het type koppeling welke u wilt aanmaken Vul de verkregen ftp-gegevens in bestaande uit een gebruikersnaam en wachtwoord.

Image Source: Hybrid SaaS

Selecteer website

Selecteer bij Alleen voor website de website waar de productkoppeling betrekking op heeft.

Image Source: Hybrid SaaS

Indien er nog geen website te selecteren is dient deze aangemaakt te worden. Zoek in het menu voor websites waar u in een paar stappen een nieuwe website aan kunt maken.

Prijsafspraken vastleggen

Selecteer bij prijzen van organisatie de organisatie waarmee u de koppeling wilt realiseren.

Image Source: Hybrid SaaS

Indien er geen prijsafspraken zijn vastgelegd dienen deze eerst aangemaakt te worden. Op de relatiekaart van de betreffende organisatie kunnen deze worden vastgelegd op het tabblad prijsafspraken

Productkenmerken vastleggen

Selecteer bij welke productkenmerken worden meegenomen de productkenmerken welke meegenomen dienen te worden in de product feed.

Image Source: Hybrid SaaS

Er kunnen meerdere productkenmerken worden geselecteerd. Afhankelijk met de afspraken welke zijn gemaakt met de ontvangende partijen kunnen kenmerken worden toegevoegd.

Productkenmerken aanmaken

Om niet alle producten mee te nemen in de product feed kan er een kenmerk worden aangemaakt. Alle producten welke in gedeeld dienen te worden vervolgens gekoppeld dat het betreffende kenmerk. Klik op start en zoek Productkenmerken Klik op toevoegen om een nieuw kenmerk toe te voegen

Image Source: Hybrid SaaS

Koppel de producten welke in de feed naar voren dienen te komen aan het betreffende kenmerken. Het is mogelijk om meerdere producten tegelijk aan een kenmerk te koppelen. Uiteraard is het ook mogelijk om de kenmerken per stuk aan een product te koppelen.

Image Source: Hybrid SaaS

Externe orderkoppeling op basis van een Json file

Deze handleiding is voor de developer die gebruik gaat maken van deze functie. Deze functie is alleen op basis van orders van de tegenpartij (Developer) naar Hybrid SaaS.

De URL

Er wordt vanuit de beheerder van Hybrid SaaS een URL aangemaakt deze is als met de volgende gegevens opgebouwd: Deze URL laat een lege pagina zien maar is de URL op tegen aan te programmeren

https://{domein}.hybridsaas.com/import/order/{koppelingId}?secret={secretId}

- {domein}
- De domeinnaam van de klant van Hybrid SaaS
- {koppelingId}
- Dit is de gecreëerde koppeling ’s ID van deze koppeling (deze is aangemaakt door het systeem)
- {secretId}
- Dit is de geheime sleutel van de koppeling

Aanvullende delen voor de URL:
- &example=1
- Hiermee is een voorbeeld pagina op te vragen
- Hier staat in aangegeven wat de gewenste bestandformaat is voor het inlezen van de order

De Instellingen in Hybrid SaaS

Er zijn een aantal instelling welke ingevuld moeten worden in Hybrid SaaS om de koppeling te kunnen laten werken

Koppeling

- Entiteit
- Vul hier de entiteit in waar de orders op moeten komen
- Organisatie
- Over het algemeen zal hier de relatie worden ingevuld van de tegenpartij (Developer)
- Bron
- Hier kan er aangegeven worden vanaf welke bron deze order is gekomen
- Referentie
- Deze is terug te vinden bij de orders (hierop kan er gefilterd worden)
- Document schema
- Hier dient een schema te worden gekozen welke bij de orders word vastgezet

Image Source: Hybrid SaaS

Een aantal gegevens zijn in de order weer terug te zien

Image Source: Hybrid SaaS

Historie

Na elke order wordt er een historie bijgehouden, in de historie wordt aangetoond of het correct is aangemaakt of dat er fouten zijn geconstateerd

Goed

Image Source: Hybrid SaaS

Beveiliging

De {secretId} is hier te maken, doormiddel van de knop nieuwe sleutel zal er een code worden gegenereerd, deze code dient doorgegeven te worden naar de tegenpartij (developer)

Image Source: Hybrid SaaS

De voorbeeldpagina

Door de volgende URL is er een voorbeeld pagina op te vragen, Op deze pagina wordt er getoond welke waarde het bestand moet hebben om ingelezen te kunnen worden.

https://{domein}.hybridsaas.com/import/order/{koppelingId}?secret={secretId}&example=1

Image Source: Hybrid SaaS

Het adres

Het afleveradres is het adres wat van de klant is deze word in de order weergegeven onder afleveradres

{
"deliveryAddress": {
"streetname": "Test straat",
"streetNumber": "123",
"postalCode": "1234AB",
"email": "test@test.com",
"phone": "+31123456789",
"country": "NL",
"city": "Stad"
},

Image Source: Hybrid SaaS

- Het factuuradres is het adres van de tegenpartij welke is ingevuld in de koppeling (rood)
- Het aflever adres van de klant word rechts getoond(zwart)

De order regels

Daarna begint het bestand met de order regels, deze is al volgt opgebouwd

1 orderregel:

"orderLines": [

{
"productcode": "12345",
"amount": 2,
"description": "test omschrijving"
}]}

2 of meerdere order regels:

Als je 2 of meerdere regels wilt toevoegen dien je na elke eerste regel achter de } een , te plaatsen

"orderLines": [

{
"productcode": "1001",
"amount": 2,
"description": "test omschrijving"
},
{

"productcode": "Voorbeeld artikel",
"amount": 1,
"description": ""
}
]}

Bij description kan er een eigen benaming worden gegeven, indien deze gevuld is zal deze omschrijving worden getoond in de order regel, indien deze niet is gevuld zal de beschrijving welke het product heeft in Hybrid SaaS worden getoond

Image Source: Hybrid SaaS

De aangemaakte order

Na het indienen van de order dien je een melding terug te krijgen

- ok=True
- Na het zien van deze melding zal de order zijn aangemaakt in Hybrid SaaS
- ok=False
- Na het zien van deze melding zal er geen order zijn aangemaakt
- Er zal een fout zitten in de gegevens van de koppeling (Dit dient door Hybrid SaaS te worden nagekeken)
- runtime error 500
- Na het zien van deze melding zal er geen order zijn aangemaakt
- Er een fout zitten in de bestandopbouw
- geen melding
- Indien er geen melding naar voren komt zal er geen order zijn aangemaakt
- De geheime sleutel zal niet correct zijn

Het kan ook zijn dat de melding OK is bevonden maar dat de order toch niet volledig is aangemaakt. Deze meldingen zijn in de historie van de koppeling terug te vinden
In het voorbeeld hieronder is te zien dat de productcode's niet herkend zijn, deze zijn ook niet aan de order toegevoegd

Foutmelding

Image Source: Hybrid SaaS

Externe Productkoppeling op basis van een Json file

Deze handleiding is voor de developer die gebruik gaat maken van deze functie. Er worden op basis van URL-gegevens getoond, sommige gegevens worden door de gebruiker in Hybrid SaaS gezet, andere gegevens worden hard uit het systeem gehaald. Hieronder volgt de beschrijven welke URL welke informatie laat zien

De URL

Er wordt vanuit de beheerder van Hybrid SaaS een URL aangemaakt deze is als met de volgende gegevens opgebouwd:

https://{domein}.hybridsaas.com/export/customer-stock-feed/{koppelingId}?output=json&secret={secretId}

- {domein}
- De domeinnaam van de klant van Hybrid SaaS
- {koppelingId}
- Dit is de gecreëerde koppeling ’s ID van deze koppeling (deze is aangemaakt door het systeem)
- {secretId}
- Dit is de geheime sleutel van het bestand

Aanvullende delen voor de url:

- {Productcode}
- Dit is de productcode uit Hybrid SaaS
- &detail=1 of &detail=true
- Uitgebreide informatie over het product
- &page=1
- Meerdere pagina's opvragen (max per pagina is 100)

De standaard URL geeft de volgende output:

Image Source: Hybrid SaaS

Verschillende voorraad weergave

Er kunnen op 2 manieren voorraden worden meegegeven.

- Voorraad weergeven huidige waarde
- Alleen voorraad weergeven boven bepaalde aantal

Image Source: Hybrid SaaS

Voorraad exacte voorraad waarde

De gebruiker heeft in Hybrid SaaS de keuze om de exacte waarde te laten zien, als hiervan het vinkje aanstaat word de exacte voorraad waarde meegegeven in de koppeling

Image Source: Hybrid SaaS

Alleen voorraad weergeven boven bepaalde aantal

De gebruiker heeft in Hybrid SaaS de keuze om de voorraad als een vaste waarde te laten zien, De waarde welke ingevuld wordt bij minimale aantal zal dan worden gehanteerd

Als de voorraad
- Lager is dan de Minimale aantal Word getoond als: 0

Image Source: Hybrid SaaS

- Hoger is dan de Minimale aantal Word getoond als: het aantal ingegeven bij minimale aantal

Let op! indien de voorraad hoger is dan het aangegeven minimale aantal zal er alleen het minimale aantal worden weergegeven

Image Source: Hybrid SaaS

1 of meerdere producten opvragen

1 product opvragen

Doormiddel van &sku={Productcode} achter de URL te zetten kan er gefilterd worden op een bepaald product

https://{domein}.hybridsaas.com/export/customer-stock-feed/{koppelingId}?output=json&secret={secretId}&sku={Productcode}

Image Source: Hybrid SaaS

Meerdere producten opvragen

Doormiddel van een, na de eerste productcode te zetten &sku={Productcode},{Productcode} kan er gefilterd worden op meerdere producten

https://{domein}.hybridsaas.com/export/customer-stock-feed/{koppelingId}?output=json&secret={secretId}&sku={Productcode},{Productcode}

Image Source: Hybrid SaaS

De details van een product

1 product opvragen

Doormiddel van &detail=1 achter de URL te zetten kunnen er details worden getoond van het product

https://{domein}.hybridsaas.com/export/customer-stock-feed/{koppelingId}?output=json&secret={secretId}&sku={Productcode}&detail=1

Image Source: Hybrid SaaS

Meerdere producten opvragen

Doormiddel van een, na de eerste productcode te zetten &sku={Productcode},{Productcode}&detail=1 kan er gefilterd worden op meerdere producten met de details die daar bij horen

https://{domein}.hybridsaas.com/export/customer-stock-feed/{koppelingId}?output=json&secret={secretId}&sku={Productcode},{Productcode}&detail=1

Image Source: Hybrid SaaS

De gegevens van de details

De gegevens welke worden getoond bij de details zijn gegevens welke door de gebruiker ingevuld kunnen worden in Hybrid SaaS. Dit kan in het product worden vast gelegd onder het tabblad CMS - Extra info. Dit is naar eigen wens te veranderen

Image Source: Hybrid SaaS

Meerdere pagina's opvragen

Doormiddel van &page=1 achter de URL te zetten kunnen meerdere pagina's worden opgevraagd. (De max. per aantal producten per pagina is 100)

De telling van de pagina's kan net zo lang doorgaan totdat er geen producten meer worden opgehaald

https://{domein}.hybridsaas.com/export/customer-stock-feed/{koppelingId}?output=json&secret={secretId}&page=1

Rest API authentication

All Hybrid SaaS Rest API-interaction is signed with a Hash-based Message Authentication Code (HMAC) by using the

Sample

The given sample is using a HTML-page with jQuery and CryptoJS. jQuery is a JavaScript framework. For more information Click here. CryptoJS is a collection of standard and secure cryptographic algorithms implemented in JavaScript using best practices and patterns. For more information Click here.

How to access the Rest Api (in this code example)

In order to communicate with the Rest API you will need a application id and a secret. These can be obtained by request on the /rest/api/login-endpoint. With those variables you can sign the requests and(in the header of the request). All steps will be explained with code samples.

Pre requirements

Firstly, we need to include jQuery and CryptoJs in the HTML-page..To load the jQuery script you need to add this:
<script src="//code.jquery.com/jquery-2.1.4.min.js"></script>
To load the CryptoJS script you need to add this:
<script src="//crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/hmac-sha256.js"></script>

Needed variables

You will need your application id and secret key from the login function in order to continue. You are able to get this information at the page: "/rest/api/login". To receive your crendentials you need to post a JSON to the login page:

//Attention! This example uses jQuery.
//First import the jQuery script in your html page.

$.ajax({
method: 'POST',
url: '/rest/api/login',
data : '{ "username": "testUsername", "password": "testPassword", "application": "rest" }'
}).done(function (data) {
//In data is your response.
//To get your application id and secret key you can use this code:
var applicationId = data.applicationId;
var secretId = data.secret;
});

You have now received the application id and the secret id from the Rest API. In the variable "data" are the values stored. You can access the values by using data.variableName;

Creating the hash for the request

Each Rest API-request has to be signed. To sign the request you need the Application Id, the HTTP-method, the url you are calling (example: /rest/api/organization) and a Timestamp () and the Secret. The following values have to be concatenated in a single string in the following fixed order:
-1. Application id
-2. HTTP-method in lowercase
-3. (Relative) url you are calling
-4. Unix timestamp

Creating string to hash

In this example we are going to request the organizations-endpoint, for this request we have a the following parameters:

-1. Application id: a9a0d2640fa940af8011596e3686e397
-2. Http-Method: GET
-3. Url: /rest/api/organizations?envelope=1
-4. Timestamp: 1435235082725
-5. Secret: 5ff72d0084c831a918a52b2d5c2008e53ec0d29b2c49f84ec1abd582680dcd9a

When we concatenate these values into the following format:

<Application Id> <Http-Method> <Url> <Timestamp>

we obtain the following result:

*a9a0d2640fa940af8011596e3686e397get/rest/api/organizations?envelope=11435235082725*

- The Http-method has to be in lowercase
- The url has to include the trailing forward slash

Concatenate the values without spaces

Signing the string

The result can be hashed with the HmacSHA256 using the secret:

After you put them in a string you can hash them with this function:

var hash = CryptoJS.HmacSHA256(string_to_hash, secret);

CryptoJS.HmacSHA256 returns the hash value into the variable hash. This hash is a part that is required to sign the request.

Creating the Authentication header

Now you need to create the final string that is going to be used as a authenthication key.

The authenthication key looks like this:

<Hashing protocol> <Application Id> <Timestamp> <Resulting Hash>
Concatenate the values WITH spaces
Now you are able to put this authenthication string into the header of the request.

Example: var headers = { Authentication: "hmac256 applicationId timeStamp hash" }; $.ajax({ method: 'GET', url: '/rest/api/endpoint', headers: headers } ).done(function (data) { //In variable data is your response. //To get your application id and secret key you can use this code: var applicationId = data.applicationId; var secretId = data.secret; });

Working example

This is the full script to access the Rest API <script src="//code.jquery.com/jquery-2.1.4.min.js"></script> <!--Imports the hasing algorithm (hmac256)--> <script src="//crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/hmac-sha256.js"></script> <script> //the applicationid and secret have already been obtained and stored in there variables: var applicationId = "a9a0d2640fa940af8011596e3686e397 "; var secret = "5ff72d0084c831a918a52b2d5c2008e53ec0d29b2c49f84ec1abd582680dcd9a"; //Get the epoch timestamp (Epoch timestamp is the number of seconds since January 1, 1970) var timeStamp = new Date().getTime(); // = 1435235082725 //the relative path (with query) of the request.. eg: /test var url = '/rest/api/organizations?envelope=1'; var type = 'GET'; // Create an array with the following values. var hashArray = []; hashArray.push( applicationId ); // a9a0d2640fa940af8011596e3686e397 hashArray.push( type.toLowerCase() ); // 'get', make sure this is lowercase hashArray.push( url.substring( url ) ); // '/rest/api/organizations?envelope=1' hashArray.push( timeStamp ); // 1435235082725 // Join the array to the string to hash var stringToHash = hashArray.join(''); // 'a9a0d2640fa940af8011596e3686e397get/rest/api/organizations?envelope=11435235082725' // Create hash with the Hmac algorithm. var hash = CryptoJS.HmacSHA256(stringToHash, secret); // Sign the string the secret. The result will be: '5ff72d0084c831a918a52b2d5c2008e53ec0d29b2c49f84ec1abd582680dcd9a' // Create authentication header: var headerValue = []; // The hashing method in lowercase headerValue.push( 'hmac256' ); // Application id headerValue.push( applicationId ); // 'a9a0d2640fa940af8011596e3686e397' // The epoch headerValue.push( timeStamp ); // 1435235082725 //The hash headerValue.push( hash ); // '5ff72d0084c831a918a52b2d5c2008e53ec0d29b2c49f84ec1abd582680dcd9a' //Join the values with a space var authenticationValue = headerValue.join(' '); // 'hmac256 a9a0d2640fa940af8011596e3686e397 1435235082725 5ff72d0084c831a918a52b2d5c2008e53ec0d29b2c49f84ec1abd582680dcd9a' //Set the request parameters var requestInfo = { headers: { Authentication: authenticationValue }, url: url, dataType: 'json', processData: false, contentType: 'application/json; charset=utf-8', type: type // GET }; $.ajax( requestInfo ) .done( function (data) { // alert the result alert( JSON.stringify(data) ); }) .fail( function (data) { // something went wrong alert('Something went wrong'); }); </script>

Good to know

- A single hash for a request is valid for a maximum period of 15 minutes. This wil protect the application against replay-attacks.
- The **Application Id** and **Application secret** can be cached locally by your implementation.
- If the user changes his password or looses rights to login, all linked **Application secrets** will automatically become invalid.

Please do not authenticate on the **/login** endpoint on every single request, this will trigger brute-force detection.

Heeft u een vraag?

Nog geen account? Vraag hem vandaag nog aan