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 je 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
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 PowerShell.
$token = " *** SEE BELOW *** "
$token_encoded = [Convert]::ToBase64String([System.Text.Encoding]::Unicode.GetBytes($token)
$file_content = @{
"Hello" = "World"
"Foo" = @{
"Bar" = "Baz"
}
} | ConvertTo-Json
$file_content_encoded = [Convert]::ToBase64String([System.Text.Encoding]::Unicode.GetBytes($file_content))
$body = @{
filename = "example.json"
file = "$file_content_encoded"
overwrite = $true
prefix = "/example"
} | ConvertTo-Json
$headers = @{
"Authorization" = "Publisher $token_encoded"
"Accept" = "application/json"
"Cache-Control" = "no-cache"
"Content-Type" = "application/json"
}
Invoke-RestMethod -Uri "https://rp-httprest.app.boxwise.nl/v2/api/files" `
-Body $body `
-Headers $headers `
-Method Post
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 PowerShell.
$key = "your key"
$secret = "your secret"
$token = "$key:$secret"
$token_encoded = [Convert]::ToBase64String([System.Text.Encoding]::Unicode.GetBytes($token)
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 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:
Naam van de Boxwise 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?
Heb je als doel rapportages o.i.d. te maken op de boxwise dan doe je 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 je selecteert). Dit kan zeer gemakkelijk door deze handleiding te volgen:
Ik heb verbinding. En nu?
Als je eenmaal verbinding hebt 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 databases.