Heeft BOXwise een API?

Volgen

BOXwise heeft geen open gedocumenteerde API voor alle onderdelen in de applicatie. Wel zijn er bepaalde onderdelen die speciaal zijn gemaakt om met BOXwise gegevens uit te kunnen wisselen. Daarnaast is de database van BOXwise een open database (Microsoft SQL Server) waarover u meer kunt lezen onder Remote Publishing.

Remote Publishing

BOXwise beschikt over een (RESTful) API welke is bedoeld om derde partijen data te laten versturen via HTTP naar BOXwise, dit noemen we Remote Publishing. De data wordt via een specifieke URL naar BOXwise gestuurd. In BOXwise komt dit vervolgens terecht in de wachtrij (message queue) van waaruit er een actie op het bericht volgt. Dit kan bijvoorbeeld een verwerking van een zending of het aanmaken van een voorontvangst zijn. 

Schematische weergave

schematische_weergave_remote_publishing.png

De API Specificatie

De specificatie van de API kan via de volgende link geraadpleegd worden:

Meer technische documentatie kan gevonden worden op:

Met name de route /api/files is belangrijk voor een remote publisher. Hier kunnen ook code samples gevonden worden in de diverse programmeertalen.

Omdat de API in Swagger is gedefinieerd, kan indien gewenst de volgende link gebruikt worden om libraries in diverse programmeertalen te genereren:

Hiervoor is de volgende definitie nodig:

 

Een bestand insturen?

Het ingestuurde bestand moet voldoen aan de overeengekomen bestandsindeling. Ook de filenaam zal hierbij bepaald worden. Bestanden die hier niet aan voldoen, zullen niet verwerkt kunnen worden en met een foutstatus in de wachtrij blijven staan. Hieronder een voorbeeld met cURL.

curl -X POST \
  https://rp-httprest.app.boxwise.nl/api/files \
  -H 'accept: application/json' \
  -H 'authorization: Publisher ' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "filename": "package-slip-201722100032888444.json",
  "file": "{\"packingslip\":{\"number\":\"180267834_IDOC2360235_J521911\",\"ordernumber\":\"1234567\",\"lines\":[{\"itemcode\":\"77400\",\"quantity\":25,\"itemids\":[{\"batchnumber\":\"123456789AAB\",\"quantity\":25,\"expirationdate\":\"2021-08-23\"}]}]}}",
  "overwrite": false,
  "prefix": "/ex"
}'

 

Uitleg Authenticatie API

Remote publishers krijgen, nadat ze zijn toegevoegd aan BOXwise, ter beveiliging een key en secret waarmee ze een publisher token kunnen maken. Deze kan worden gebruikt in de Authorization header.

Het maken van de publisher token moet worden gedaan door deze achter elkaar te plakken, gescheiden door een ‘:’, en dit tezamen in base64 te encoderen. Hieronder een voorbeeld in C#. 

var key = "your key";
var secret = "your secret";
var token = Base64Encode($"{key}:{secret}"));
var authHeader = $"Authorization: Publisher {token}"

public static string Base64Encode(string plainText) {
  var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText);
  return System.Convert.ToBase64String(plainTextBytes);
}

 

Gegevens uit BOXwise halen

Op dit moment is de Remote Publishing API alleen beschikbaar om gegevens bij BOXwise aan te leveren en niet om gegevens uit BOXwise te halen.

Echter zijn er wel andere mogelijkheden om informatie (met name historische gegevens) uit het systeem te halen.  BOXwise Pro gebruikt Microsoft SQL Server (versie 2008 of hoger) als database systeem. Dit is een open database systeem waarbij (mits je de juiste rechten hebt) alle gegevens door meerdere verbindingen te raadplegen zijn. 

Verbinding maken

Microsoft SQL Server is standaard bereikbaar voor de meeste platformen via Native connectoren of ODBC koppelingen. Hieronder een aantal links met voorbeelden:

ODBC https://docs.microsoft.com/en-us/sql/integration-services/import-export-data/connect-to-an-odbc-data-source-sql-server-import-and-export-wizard
MS Excel https://support.office.com/nl-nl/article/Een-SQL-Server-database-aan-de-werkmap-koppelen-Power-Query-22c39d8d-5b60-4d7e-9d4b-ce6680d43bad
ASP.NET  https://msdn.microsoft.com/en-us/library/ms178371(v=vs.100).aspx
PHP http://php.net/manual/en/function.mssql-connect.php
POWER BI

https://powerbi.microsoft.com/en-us/documentation/powerbi-gateway-enterprise-manage-sql/

 

 

 

 

 

 

 

 

 

 

 

Naam van de BOXwise Pro database

Standaard is de naam van de database BOXwisePro. Dit kan echter verschillen per omgeving aangezien klanten zelf het beheer over databases voeren.

Met welk doel?

Heeft u als doel rapportages o.i.d. te maken op de BOXwise Pro database dan doet u dit vermoedelijk met gespecialiseerd software zoals Power BI of Excel. Deze producten hebben allemaal de mogelijkheid om standaard een verbinding met SQL Server te maken.

Externe partij "Alleen-lezen" toegang geven?

In de regel is het zeer verstandig externe partijen alleen lezen toegang te geven tot de database (let hierbij op welke databases u selecteert). Dit kan zeer gemakkelijk door deze handleiding te volgen: 

https://www.itsupportguides.com/knowledge-base/server-side-tips/sql-management-studio-how-to-create-read-only-users/

 

Ik heb verbinding. En nu?

Als u eenmaal verbinding heeft met de database van BOXwise is het praktisch om te weten welke tabellen welke informatie bevatten. Zie onderstaande bijlage voor een beschrijving van de tabellen in de BOXwise Pro database.

Hebben de voorgestelde antwoorden uit de Knowledge Base u niet geholpen? Stuur dan een incident in.

Stuur een incident in
Was dit artikel nuttig?
Aantal gebruikers dat dit nuttig vond: 0 van 0
Hebt u meer vragen? Een aanvraag indienen

Opmerkingen

  • Avatar
    Gertjan Wobbes

    Dank voor de database documentatie