- 1. Inleiding
- 2. Vereisten
- 3. Basis-URL
- 4. Authenticatie
- 5. Fouten
- 6. Generieke API’s
- 7. Andere API’s
- 8. Objectvoorbeelden
- 8.2 Postman-project
1. Inleiding
Webservices lezen, maken en wijzigen Asset-gegevens.
REST-framework met Bearer-tokens en vooraf gedeelde sleutel.
Inkomende Generic Functions API; uitgaande klantwebservices mogelijk via scripts/integraties.
2. Vereisten
Een technisch consultant richt de vereisten in.
Asset-omgeving met:
- Inkomende webservices via Client settings → Authentication → Access rules.
- Alleen OAuth: API Connector met AES shared key-trustrelation, bevoegde gebruiker ook gekoppeld onder System users. Niveau 3 kan dit maken.
- Allowed origins for REST web services voor externe CORS-domeinen.
2.1 Parameters
Benodigde oproepparameters:
Parameter |
Beschrijving |
Voorbeeld |
|---|---|---|
server |
Tenant- of algemene server-URL. |
https://demotenant.axxerion.com |
client_reference |
Omgevingsreferentie |
demotenant |
username |
Gebruikersnaam voor tokenauthenticatie. Koppel gebruiker onder System users aan connector. Alleen relevant voor OAuth, niet Basic Auth. |
demo_api |
app_id |
Connectorreferentie voor tokenauthenticatie. Alleen relevant voor OAuth, niet Basic Auth. |
DTW-EA-001 |
x_access_id_value |
Trustrelation Access ID. Alleen relevant voor OAuth, niet Basic Auth. |
demo_api_id |
secret_key |
Geheime trustrelationsleutel. Alleen relevant voor OAuth, niet Basic Auth. |
DB2E51543E463290B946602B8047CC9E16048E2C99728DB2E51543E463290B946602B8047CC9E16048E2C99728 |
authentication_mode |
Vaste waarde GENERIC. Voor OAuth-tokenauthenticatie. Alleen voor automatische Postman-tokenaanvragen bij OAuth. |
GENERIC |
3. Basis-URL
Iedere endpoint heeft een basis-URL: https://{server}/webservices/{{client_reference}}/rest/functions
Beide ‘server’ en ‘client_reference’ volgens omgevingsparameters invullen.
4. Authenticatie
Twee methoden:
- basic Auth
- OAuth 2.0
4.1 Basic Auth
Basic Auth met bevoegde gebruiker/wachtwoord ondersteund, maar minder veilig en uiteindelijk vervangen. De bron adviseert OAuth/Bearer.
4.2 API OAuth 2.0
Algemeen
Vraag eerst een Bearer-token:
Grant type
Resource Owner Password Credentials-grant gebruikt hier geen wachtwoord maar een met AES versleuteld tokenbericht. Bij succes token; gegevens volgens gebruikersrechten.
Tokenaanvraagbericht
JSON-tokenbericht met onderstaande letterlijke waarden:
jsonwide760note92b97441dc10Alias axx::access::admin gebruikt de standaard bevoegde gebruiker van de AES-trustrelation in plaats van de individuele gebruiker.
Alias axx::access::admin gebruikt de standaard bevoegde gebruiker van de AES-trustrelation in plaats van de individuele gebruiker.
Tokenbericht versleutelen
AES-CBC met gedeelde sleutel levert ciphertext en IV. Vorm onderstaande tekst:
wide760Verstuur als encrypted-params.
HTTP-tokenaanvraag
Maak een POST aanvraag naar onderstaande endpoint; server vervangen.
Vereiste headers met echte waarden:
wide760Form URL-encoded body volgens tabel:
sleutel |
waarde |
|---|---|
|
[encrypted-params] |
Bij geaccepteerde autorisatie 200 OK ontvang je een geldig Bearer-token voor resources.
Zie Pre-request script in Postman-download onderaan.
5. Fouten
Mogelijke foutcodes:
Foutcode |
Betekenis |
Beschrijving |
|---|---|---|
400 |
Bad Request |
Ongeldig verzoek |
401 |
Unauthorized |
Ongeldige credentials of onvoldoende toegang |
403 |
Forbidden |
Resource niet toegestaan |
404 |
Not Found |
Resource/endpoint/object niet gevonden |
405 |
Method Not Allowed |
HTTP-methode niet toegestaan, zoals POST waar alleen GET mag |
412 |
Precondition Failed |
Voorwaarde niet voldaan |
500 |
Internal Server Error |
Onverwachte serverfout |
503 |
Service Unavailable |
Tijdelijk niet beschikbaar; later proberen |
6. Generieke API’s
Objectspecifieke parameters maken dezelfde endpoints bruikbaar voor veel objecttypen.
Aanvullende parameters:
parameter |
beschrijving |
voorbeeld |
|---|---|---|
|
Objectklassenaam; zie Objects op klantniveau. |
Request |
|
Categorieobjecten worden binnen categorie gemaakt. Zonder categorie eerste beschikbare; specificeer altijd de categorie om onverwachte wijzigingen te vermijden. Zie: Categorieën |
720000000000296 |
|
Bestaande instantie vereist ID. Aanmaak retourneert beide identifiers indien van toepassing. |
5005958a-7a14-45bf-a3da-5e2aaecff011::g1 OF: 720000000000296 |
|
Contextobjecttype bij aanmaak in context. |
Zie object_name |
|
Context-ID als uniqueReference/DatabaseId; zie ‘ |
Zie object_id |
|
Workflowfunctienaam zoals submit; vind via workflowpagina-definitie. |
submit |
|
Technische veldnaam bij aanmaak/wijziging. Zie createupdate ‘Velden bijwerken’. |
|
|
Gewenste waarde samen met field_name. Zie createupdate ‘Velden bijwerken’. |
“john.doe@spacewell.com“ |
Ondersteunde functies:
6.1 createupdate
POST maakt object en vult velden; objectnaam zoals Area/Asset/Contact/Request in endpoint.
POST https://{server}/webservices/{client_reference}/rest/functions/createupdate/{object_name}
Bij object- Categorieëncategorieën ook categoryId in endpoint.
POST https://{server}/webservices/{client_reference}/rest/functions/createupdate/{object_name}/{category_folder_id}
Categorie-ID ophalen via rapport en completeReportResult; resultaten bevatten ID’s.
Velden bijwerken:
Veldnamen en waarden in body.
Technische namen via Object → Fields.
Invoer verschilt per veldtype:
Veldtype |
invoer |
voorbeeld |
|---|---|---|
Tekst |
tekst |
“My example text“ |
Datum/tijd |
Datum/tijd volgens ISO 8610 Combined date and time representations, zoals in de bron (zie https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) |
“2024-11-30T10:00:00Z“ |
Integer |
getal |
10 |
Objectselectie, zoals verzoekaanvrager |
DatabaseId of uniqueReference; zie |
“720000000000002” of “076bc687-d25f-4555-acda-ea74864fefe0::g1” |
Bolean |
True of False |
True |
Enumeratiewaarde |
Integercode via Enumerations. |
2000 |
Info
Velden kunnen aanvullende invoer-/lengtebeperkingen hebben.
Voorbeeldbody:
{
"exampleTextField" : "My example text",
"exampleDateTimeField" : “2024-11-30T10:00:00Z“,
"exampleIntegerField" : 10,
“exampleObjectField” : “076bc687-d25f-4555-acda-ea74864fefe0::g1”,
“exampleBoleanField“ : True,
“exampleEnumerationField“ : 2000 ;
}
6.1.1 Aanmaak in context
Context ondersteunt bijvoorbeeld Area binnen Property met type en context-ID.
POST https://{server}/webservices/{client_reference}/rest/functions/createupdate/{object_name}/{context_object_name}/{context_object_id}
propertyId in createUpdate kan ook, maar omzeilt mogelijk contextbedrijfslogica.
6.2 update
PUT wijzigt objectvelden met naam en DatabaseId/uniqueReference.
PUThttps://{server}/webservices/{client_reference}/rest/functions/update/{object_name}/{object_id}
Velden/waarden zoals createUpdate in body.
Rechten, workflowstatus en bedrijfslogica bepalen wijzigbaarheid.
6.3 delete
DELETE verwijdert object met naam en ID.
DELETE https://{server}/webservices/{client_reference}/rest/functions/delete/{object_name}/{object_id}
Rechten en objectmogelijkheden bepalen verwijdering; soms alleen archief. Zie: Verwijderen en archiveren – Knowledge Base
6.4 archive
DELETE archiveert object met naam en ID.
DELETE https://{server}/webservices/{client_reference}/rest/functions/archive/{object_name}/{object_id}
Velden/waarden in body zoals createUpdate.
Archivering hangt van rechten af.
6.5 restore
PUT herstelt uit prullenbak of archief met objectnaam en ID.
PUThttps://{server}/webservices/{client_reference}/rest/functions/restore/{object_name}/{object_id}
6.6 executefunction
PUT voert workflowfunctie uit op actief object met naam, ID en functie. Functies via statusenumeratie, bijvoorbeeld RequestStatusCode/RequestStatus.
PUT https://{server}/webservices/{client_reference}/rest/functions/executefunction/{object_name}/{object_id}/{workflow_function_name}
Juiste status, taakrechten en connectorvoorwaarden vereist, zoals verplichte velden.
6.7 findall
GET haalt alle instanties van objecttype op.
GET https://{server}/webservices/{client_reference}/rest/functions/findall/{object_name}
Alle velden komen terug; slechts een deel kan relevant zijn.
Geen filters, kolombeperking of alternatieve veldweergave.
Voor fijnmazig ophalen zie CompleteReportResult ; aanbevolen voor specifieke behoeften.
6.8 findbyfield
GET filtert objecttype op één veldwaarde.
GET https://{server}/webservices/{client_reference}/rest/functions/findbyfield/{object_name}/{field_name}/{field_value}
Alle velden terug, niet allemaal relevant.
Geen meerdere filters of veldopmaak; gebruik CompleteReportResult voor specifieke behoeften.
6.9 CompleteReportResult
POST voert rapport uit met referentie en optionele filtervelden/waarden.
POST https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Minimale body:
{
"reference":"{report_reference}"
}
Body met filters:
{
"reference":"{reportReference}",
"filterFields":["{filterfield1}","{filterfield2}"],
"filterValues":["{filterFieldvalue1}","{filterFieldvalue2}"]
}
Flexibel voor standaard-/maatwerkrapporten, vaste filters en resultaatskolommen.
Niveau 3 beheert Reports en filtervelden.
7. Andere API’s
Specifieke API’s:
7.1 Importconnectoren
7.1.1 Bestanden uploaden
POST uploadt CSV-bestanden naar connectorreferentie, Content-Type multipart/form-datavoor meerdere bestanden; publieke specificatie beschikbaar.
POST https://{server}/webservices/{client_reference}/rest/functions/v2/connectors/{ftpconnector_reference/document
Import is asynchroon, met antwoord:
{"status":status,"uuid":uuid,"type":"ConnectorDocumentResponse","infoMessage":"The FTP connector will be started in the background.""response":{"submitted":date-time-submitted,"status":status}}
waar:
- status REST-status
- date-time-submitted Uploadindieningsdatum/tijd
Zie algemeen: Standaardimports.
7.1.2 Importstatus
GET laatste importstatus na asynchrone upload.
GET https://{server}/webservices/{client_reference}/rest/functions/v2/connectors/{ftpconnector_reference}/status
Antwoord:
{"status":status,"uuid":uuid,"type":"ConnectorStatusResponse","response": {
"message":message, "filesProcessed":number-of-files-processed, "startTime":start-date-time, "endTime":end-date-time, "warnings":number-of-warnings, "errors":number-of-errors, "created":number-of-objects-created, "updated":number-of-objects-updated, "deleted":number-of-objects-deleted, "interrupted":boolean-value, "status":status }}
waar:
- status REST-status
- message Connectormelding
- number-of-files-processed Verwerkte bestanden
- start-date-time Laatste starttijd; ontbrekend = nooit gestart
- end-date-time Laatste eindtijd; ontbrekend = nooit gestart of nog bezig
- number-of-warnings Aantal waarschuwingen
- number-of-errors Aantal fouten
- number-of-objects-created Aangemaakte objecten
- number-of-objects-updated Bijgewerkte objecten
- number-of-objects-deleted Verwijderde objecten
-
boolean-value is
"true"of"false"en geeft onderbreking aan.
Gebruik start-date-time en end-date/time om voltooiing te controleren: latere start dan vorige oproep en niet-lege eindtijd.
Maximaal één oproep per minuut om overbelasting te voorkomen.
7.1.3 Importlog
GET logbestand van type log-type voor laatste import. Save documents = Yes geeft info- en foutlog. Type infoen error. Info altijd; error alleen bij fouten.
GET https://{server}/webservices/{client_reference}/rest/functions/v2/connectors/{ftpconnector_reference}/document?type=info
Antwoordtype application/octet-streamis het logbestand.
Maximaal één oproep per minuut.
7.2 Documenten
7.2.1 Downloaden
GET document via referentie.
https://{server}/webservices/{client_reference}/rest/functions/v2/documents/{document_reference}
Voor preview: format=preview.
uniqueReference in plaats van referentie:
Gewone referentie D-XXXXXX hoeft niet uniek; uniqueReference met idForRef=true.
7.2.2 Uploaden
POST uploadt en koppelt aan {instanceId}/{ObjectName}; bestandsnaam in endpoint.
https://{server}/webservices/{client_reference}/rest/functions/upload/{object_name}/{object_id}?name=file-name
Vereiste toegestane Content-Types:
- binary/octet-stream
- application/pdf
- application/msword
- application/vnd.ms-excel
- image/png
- image/gif
- image/jpeg
Let op:
- De
object_idmoet DatabaseId zijn; uniqueReference nog niet ondersteund. - Als
object_nameDocument is, maak geen nieuw Document maar gekoppelde DocumentVersion bij instance-idmet het bestand. - Te groot bestand geeft fout.
7.3 Eventlog
POST maakt eventlog.
Queryparameters
Parameter |
Type |
Verplicht |
Standaard |
Beschrijving |
|---|---|---|---|---|
type |
String |
NO | info |
Logtype: info, warning, error, debug |
Padparameters
Parameter |
Type |
Beschrijving |
|---|---|---|
objectName |
String |
Objectnaam zoals Asset/Request of numerieke objectNameId |
instanceId |
String |
Numeriek ID of uniqueReference, bijvoorbeeld f3ea04a9-6153-430e-a96d-80fdf378c806::g1 |
Verzoekbody
Logbericht als gewone tekst.
Content-Type |
Beschrijving |
|---|---|
text/plain |
Opgeslagen in EventLog.detailsClob |
Automatische velden
- clientId - Uit geauthenticeerde sessie
- externalAppId - Uit sessiecontext indien beschikbaar
- logId - Via RestApi LogName
Zonder objectkoppeling:
wide760Met object via ‘objectName’ en ‘instanceId’.
wide760wide760Met object via ‘objectName’ en ‘instanceId’ uniqueReference en info/warning/error-type.
wide760Succesantwoord:
wide760Foutantwoord:
wide760Datum en connectorcontext automatisch ingevuld.
8. Objectvoorbeelden
Voorbeelden voor aanmaak/ophalen/wijzigen; reportfilters hieronder.
8.1.1 Organisaties
POST haalt eigen organisaties en leveranciers op.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Organizations_01", "filterFields":["Email"], "filterValues":["example@email.com"]}
Verplicht rapport: API_Report_Organizations_01
Filters optioneel.
Beschikbare filters:
Email op organisatie-e-mail.
Voorbeeldresultaat:
8.1.2 Personen
POST haalt personen op.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Contacts_01", "filterFields":["Email"], "filterValues":["noreply@spacewell.com"]}
Verplicht rapport: API_Report_Contacts_01
Filters optioneel.
Beschikbare filters:
Email op persoons-e-mail.
Voorbeeldresultaat:
8.1.3 Gebouwen
POST haalt gebouwen op.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Properties_01"}
Verplicht rapport: API_Report_Properties_01
Geen extra filters.
Voorbeeldresultaat:
8.1.4 Ruimtes
POST haalt ruimtes op.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Areas_01", "filterFields":["Property"], "filterValues":[[1210000000000849]]}
Verplicht rapport: API_Report_Areas_01
Filters optioneel.
Beschikbare filters:
Property voor gebouw.
Gebruik gebouw-ID uit gebouwoproep.
Voorbeeldresultaat:
8.1.5 Assets
POST haalt assets op.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Asset_01", "filterFields":["Property","Area"], "filterValues":[[1000066632],[1000212917]]}
Verplicht rapport: API_Report_Asset_01
Filters optioneel.
Beschikbare filters:
Property voor gebouw.
Area voor ruimte.
Gebouw-/ruimte-ID uit bijbehorende oproep.
Voorbeeldresultaat:
8.1.6 Assetcategorieën
POST haalt assetcategorieën op; ID voor nieuwe asset (zie Asset maken). Bijvoorbeeld Car, Bike, Coffee machine.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Asset_Categories_01"}
Verplicht rapport: API_Report_Asset_Categories_01
Geen extra filters.
Voorbeeldresultaat:
8.1.7 Verzoeken
POST haalt verzoeken op.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Requests_01", "filterFields":["CreatedSince","CreatedUntil"], "filterValues":["2023-01-01T00:00:00Z","2023-08-01T00:00:00Z"]}
Verplicht rapport: API_Report_Requests_01
Filters optioneel.
Beschikbare filters:
CreatedSince/CreatedUntil voor aanmaakdatum.
Datum/tijd volgens bron ISO 8610 (zie https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
Ook beschikbaar:
- Asset-ID voor gekoppelde verzoeken
- Area-ID voor gekoppelde verzoeken
- Property-ID voor gekoppelde verzoeken
Voorbeeldresultaat:
8.1.8 Servicetypen
POST haalt servicetypen op voor verzoektype en servicegroeptoewijzing.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_ProblemTypes_01"}
Verplicht rapport: API_Report_ProblemTypes_01
Geen extra filters.
Voorbeeldresultaat:
8.1.9 Servicegroepleden
POST haalt servicegroepscontacten op; groep volgt servicetype.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_ServiceGroupMembers_01"}
Verplicht rapport: API_Report_ServiceGroupMembers_01
Geen extra filters.
Voorbeeldresultaat:
8.1.10 Correctieve werkorders
POST haalt correctieve orders uit verzoeken op.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Corrective_WorkOrders_01", "filterFields":["CreatedSince","CreatedUntil"], "filterValues":["2023-01-01T00:00:00Z","2023-09-01T00:00:00Z"]}
Verplicht rapport: API_Report_Corrective_WorkOrders_01
Filters optioneel.
Beschikbare filters:
CreatedSince/CreatedUntil voor aanmaakdatum.
Datum/tijd volgens bron ISO 8610 (zie https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
Ook beschikbaar:
- Asset-ID voor gekoppelde orders
- Area-ID voor gekoppelde orders
- Property-ID voor gekoppelde orders
- Request-ID voor bronverzoek
Voorbeeldresultaat:
8.1.11 Preventieve werkorders
POST haalt preventieve orders uit schema’s op.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/completereportresult
Body:
{ "reference":"API_Report_Preventive_WorkOrders_01", "filterFields":["CreatedSince","CreatedUntil"], "filterValues":["2023-01-01T00:00:00Z","2024-01-01T00:00:00Z"]}
Verplicht rapport volgens brontekst: API_Report_Corrective_WorkOrders_01
Filters optioneel.
Beschikbare filters:
CreatedSince/CreatedUntil voor aanmaakdatum.
Datum/tijd volgens bron ISO 8610 (zie https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
Ook beschikbaar:
Meerdere objectkoppelingen kunnen dezelfde order meermaals teruggeven. Filter op specifiek gekoppeld object, niet slechts gebouw van het asset.
- Object-ID van asset/ruimte/gebouw
Voorbeeldresultaat:
8.1.12 Asset maken
POST maakt asset.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/createupdate/Asset/{{assetCategory}}
{{assetCategory} moet categorie-ID uit de Assetcategorieënlijst zijn.
Body met voorbeeldwaarden:
{ "name": "Example laptop 2", "externalReference": "987654321", "serialNumber": "123456789", "tradeName": "DTwin turbo", "modelName": "model X1", "quantity": "1", "manufacturerContactId": "1210000000005286", "supplierContactId": "", "purchaseDate": "2023-01-01T00:00:00Z", "propertyId": "1210000000000849", "areaId": "1210000000048836", "parentAssetId": "1210000000008548"}
Alle volgende velden optioneel:
Parameter |
Beschrijving |
|---|---|
Name |
Vrije tekst, maximaal 255 tekens |
ExternalReference |
Vrije tekst, maximaal 255 tekens |
serialNumber |
Vrije tekst, maximaal 255 tekens |
modelName |
Vrije tekst, maximaal 255 tekens |
quantity |
Integer |
manufacturerContactId |
Organisatie-/persoon-ID uit lijst van organisaties of personen-API . |
supplierContactId |
Organisatie-/persoon-ID uit lijst van organisaties of personen-API . |
purchaseDate |
Datum/tijd volgens bron ISO 8610 (zie https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) |
propertyId |
Gebouw-ID uit gebouwenlijst API) |
areaId |
Ruimte-ID uit lijst van de ruimtes API) |
parentAssetId |
Asset-ID uit lijst van de assets API) |
Antwoord bevat nieuw ID en uniqueReference.
8.1.13 Verzoek maken
POST maakt verzoek.
Endpoint: https://{server}/webservices/{client_reference}/rest/functions/createupdate/Request/1000000786
Body met voorbeeldwaarden:
{ "fromContactId": "1210000000004567", "name": "Test request", "description": "Test request", "problemTypeId": "1210000000005757", "propertyId": "12100000000057634", "areaId": "1210000000005764", "assetId": "1210000000005734"}
Alle volgende velden optioneel:
Parameter |
Beschrijving |
|---|---|
fromContactId |
Organisatie-/persoon-ID uit lijst van organisaties of personen-API |
name |
Vrije tekst, maximaal 255 tekens |
beschrijving |
Vrije tekst, maximaal 255 tekens |
problemTypeId |
Servicetype-ID uit lijst van servicetypen API) |
propertyId |
Gebouw-ID uit lijst van gebouwen API) |
areaId |
Ruimte-ID uit lijst van ruimtes API) |
assetId |
Asset-ID uit lijst van assets API) |
Antwoord bevat nieuw ID en uniqueReference.
8.2 Postman-project
Voorbeeld- Postman project en dummy-omgeving. Vul echte omgevingsparameters in vóór gebruik.