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.
De gebruiker
Deze omgeving is gekoppeld aan een gebruiker (met wachtwoord) en een externe applicatie.
Gekoppeld aan de omgeving
De omgeving is gekoppeld met de gegevens van de gebruiker
Gegevens ophalen
De bestanden kunnen worden opgehaald van de computer
Na het kiezen voor verwerken zullen de facturen worden geïmporteerd Tijdens het laden kan je de voortang zien recht onderin
De inkoopfactuur
Na verwerken zijn de producten aangemaakt
Hier word een voorbeeld van een artikel getoond
De inkoopfactuur is nu toegevoegd in Hybrid SaaS met de volgende eigenschappen:
Indien er een verschil in berekening van de btw op zit, zal deze automatisch worden gecorrigeerd.
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
Door te dubbelklikken op de regel komt de meldingen in beeld:
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.
De gebruiker
Deze omgeving is gekoppeld aan een gebruiker (met wachtwoord) en een externe applicatie.
Gekoppeld aan de omgeving
De omgeving is gekoppeld met de gegevens van de gebruiker
Gegevens ophalen
De bestanden kunnen worden opgehaald van de computer
Na het kiezen voor verwerken zullen de producten worden geïmporteerd Tijdens het laden kan je de voortang zien recht onderin
Producten
Na verwerken zijn de producten aangemaakt
Hier word een voorbeeld van een artikel getoond
Het product is nu toegevoegd in Hybrid SaaS met de volgende eigenschappen:
Indien er een verschil in berekening van de btw op zit, zal deze automatisch worden gecorrigeerd.
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
Selecteer het type koppeling welke u wilt aanmaken Vul de verkregen ftp-gegevens in bestaande uit een gebruikersnaam en wachtwoord.
Selecteer website
Selecteer bij Alleen voor website de website waar de productkoppeling betrekking op heeft.
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.
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.
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
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.
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
Een aantal gegevens zijn in de order weer terug te zien
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
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)
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
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"
},
- 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
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
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:
Verschillende voorraad weergave
Er kunnen op 2 manieren voorraden worden meegegeven.
- Voorraad weergeven huidige waarde
- Alleen voorraad weergeven boven bepaalde aantal
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
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
- 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
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}
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}
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
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
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
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.