API-documentatie

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:

  1. Inkomende webservices via Client settings → Authentication → Access rules.
image-20230808-091818.png
  1. Alleen OAuth: API Connector met AES shared key-trustrelation, bevoegde gebruiker ook gekoppeld onder System users. Niveau 3 kan dit maken.
image-20230808-091924.png
  1. Allowed origins for REST web services voor externe CORS-domeinen.
image-20230913-084814.png

2.1 Parameters

Benodigde oproepparameters:

Parameter

Beschrijving

Voorbeeld

server

Tenant- of algemene server-URL.

https://demotenant.axxerion.com
OF
https://axpr13.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:

oauth WPM.drawio (2).png

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:

jsonwide760note92b97441dc10

Alias 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:

wide760

Verstuur als encrypted-params.

HTTP-tokenaanvraag

Maak een POST aanvraag naar onderstaande endpoint; server vervangen.

wide760

Vereiste headers met echte waarden:

wide760

Form URL-encoded body volgens tabel:

sleutel

waarde

encrypted-params

[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

object_name

Objectklassenaam; zie Objects op klantniveau.

Request

category_folder_id

Categorieobjecten worden binnen categorie gemaakt. Zonder categorie eerste beschikbare; specificeer altijd de categorie om onverwachte wijzigingen te vermijden.

Zie: Categorieën

720000000000296

object_id

Bestaande instantie vereist ID.
Gebruik uniqueReference indien beschikbaar, anders DatabaseId, te vinden via Inspect Element.

Aanmaak retourneert beide identifiers indien van toepassing.

5005958a-7a14-45bf-a3da-5e2aaecff011::g1

OF:

720000000000296

context_object_name

Contextobjecttype bij aanmaak in context.

Zie object_name

context_object_id

Context-ID als uniqueReference/DatabaseId; zie ‘object_id' hierboven.

Zie object_id

workflow_function_name

Workflowfunctienaam zoals submit; vind via workflowpagina-definitie.

submit

field_name

Technische veldnaam bij aanmaak/wijziging. Zie createupdate ‘Velden bijwerken’.

email

field_value

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 object_id vorige tabel.

“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_id moet DatabaseId zijn; uniqueReference nog niet ondersteund.
  • Als object_name Document 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:

wide760

Met object via ‘objectName’ en ‘instanceId’.

wide760wide760

Met object via ‘objectName’ en ‘instanceId’ uniqueReference en info/warning/error-type.

wide760

Succesantwoord:

wide760

Foutantwoord:

wide760

Datum 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:

image-20230808-112324.png

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:

image-20230808-112711.png

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:

image-20230808-112858.png

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:

image-20230808-113229.png

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:

image-20230901-092246.png

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:

image-20230808-120127.png

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:

image-20230904-071219.png

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:

image-20230904-064139.png

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:

image-20230904-064610.png

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:

image-20230808-121341.png

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:

image-20230904-070401.png

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.

image-20230808-124938.png

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.