# Externe API-toegang

# Inleiding

Voor externe toegang tot uw TrackOnline-gegevens kunt u de externe REST Api gebruiken. Toegang / authenticatie gebeurt met een API-sleutel. De REST API is toegankelijk via de volgende website.

Deze productiesite slaat de gegevens op die het ontvangt.

# Genereer een API-sleutel

Voordat u toegang kunt krijgen tot de externe api, moet u een API-sleutel genereren in uw TrackOnline-omgeving.

1. Open het tandwielmenu en navigeer naar de beheerinstellingen.
2. Navigeer naar de optie API-instellingen.
3. Geef uw API-sleutel een naam en druk op maken.

Deze gegenereerde API-sleutel kan worden gebruikt in de koptekst van het verzoek of in de querytekenreeks.

# Voorbeeld met curl en een querytekenreeks:

curl -X GET "https://api.trackonline.com/api/v1/iot/item?includeDeleted=false&page=1&apikey=xxx.xxxx.xxx" -H "accept: application/json"

# Voorbeeld met krul en een koptekst:

curl -X GET "https://api.trackonline.com/api/v1/iot/item?includeDeleted=false&page=1" -H "accept: application/json" -H "X-ApiKey: xxxx.xxxx.xxx"

# API-tijdslimieten

De onderstaande tijdslimieten beperken het aantal verzoeken dat uw app gedurende een bepaalde periode mag verzenden. Deze limieten zijn afhankelijk van uw licentietype.

1. START en PRO
   • Minuutlimiet: uw app kan 60 API-aanroepen doen, per administratie, per minuut.
   • Daglimiet: uw app kan 1000 API-aanroepen doen, per administratie, per dag.
2. PRO PLUS
   • Minuutlimiet: uw app kan 60 API-aanroepen doen, per administratie, per minuut.
   • Daglimiet: uw app kan 5000 API-aanroepen doen, per administratie, per dag.
3. ENTERPRISE
   • Minuutlimiet: uw app kan 1000 API-aanroepen doen, per administratie, per minuut.
   • Daglimiet: uw app kan 10000 API-aanroepen doen, per administratie, per dag.

Als uw app deze limiet overschrijdt, ontvangt u bij elke aanvraag een reactie met HTTP-statuscode 429. Dit antwoord bevat ook de Retry-After-header, die aangeeft hoe lang je app moet wachten voordat hij een vervolgverzoek doet.

# Beschikbare API-aanroepen

Voor GET zijn onder andere de volgende aanroepen per categorie beschikbaar in de API:

1. Status
   • GET API-status
2. IoT
   • GET IoT-item(s)
   • GET IoT-itemmeting(en)
3. Item definitie
   • GET item definitie(s)
   • GET resultaat van opgeslagen item definitie(s)
4. Uniek item
   • GET uniek(e) item(s)
   • GET resultaat van opgeslagen uniek(e) item(s)
5. Locatie
   • GET locatie (s)
   • GET resultaat van opgeslagen locatie(s)
6. Transactie
   • GET transactie(s)
   • GET resultaat van opgeslagen transactie(s)
7. Saldo
   • GET saldo (en)
   • GET tegenpartij saldo (s)
8. Batch berekening
   • GET batch berekening(en)
   • GET een downloadbestand van het batch berekeningsresultaat
   • GET Document(en) voor batch berekening(en)
   • GET een downloadbestand van een batch berekeningsresultaat document

Voor POST zijn onder andere de volgende aanroepen per categorie beschikbaar in de API:

1. Item definitie
   • POST item definitie(s)
2. Uniek item
   • POST uniek(e) item(s)
3. Locatie
   • POST locatie(s)
4. Transactie
   • POST transactie(s)

# Item definitie

Het gegevensmodel voor de item definitie GET- of POST-oproepen bestaat uit het volgende (gemarkeerd met * zijn verplichte velden):

# GET-parameters

De GET-parameters zijn de parameters die u kunt doorgeven om de item definities te filteren bij het ophalen van item definities. Een voorbeeld is beschikbaar in de volgende sectie.

# Voorbeeldoproepen

In dit voorbeeld gaan we een POST maken van een item definitie voor de CC TAG5-lastdrager met alleen de verplichte info.

[
  {
    "number": "CC TAG5",
    "name": "CC TAG 5",
    "code": "TAG5",
    "type": "LoadCarrier"
  }
]

In dit voorbeeld gaan we een POST maken van een item definitie voor de CC TAG5 lastdrager inclusief afmetingen en het gewicht.

[
  {
    "number": "CC TAG5",
    "name": "CC TAG 5",
    "code": "TAG5",
    "type": "LoadCarrier",
    "basePrice": 250,
    "length": 1.4,
    "width": 0.6,
    "height": 2.0,
    "weight": 50
  }
]

Bij het ophalen van uw item definities kunt u ook de parameters gebruiken die worden uitgelegd in de sectie GET-parametersom te filteren. Dit is bijvoorbeeld de URL voor het ophalen van de eerste pagina met resultaten die overeenkomt met de item definities met "box" in hun naam:

https://api.trackonline.com/api/v1/itemdefinition?Name=box&page=1&apikey=xxx

U kunt natuurlijk zoveel parameters toevoegen als u wilt in de URL. Voeg daarom &filter=waarde toe aan de URL waar filter de naam van het filter is en waarde de waarde is waarop je wilt filteren. Als u nu item definities wilt filteren met "box" in hun naam EN met het nummer 10, dan ziet de URL er als volgt uit:

https://api.trackonline.com/api/v1/itemdefinition?Number=10&Name=box&page=1&apikey=xxx

# Uniek item

Het gegevensmodel voor de unieke item GET- of POST-oproepen bestaat uit het volgende (gemarkeerd met * zijn verplichte velden):

# GET-parameters

De GET-parameters zijn de parameters die u kunt doorgeven om de unieke items te filteren bij het ophalen van unieke items. Een voorbeeld is beschikbaar in de volgende sectie.

# Voorbeeldoproepen

In dit voorbeeld gaan we een POST maken van een uniek item voor item defintie CC TAG5.

[
  {
    "number": "123",
    "barcode": "bc123",
    "itemDefinition": {
      "number": "CC TAG5"
    },
    "deviceIds": {
      "deviceId": "d123"
    }
  }
]

Bij het ophalen van uw unieke items kunt u ook de parameters gebruiken die worden uitgelegd in de sectie GET-parametersom te filteren. Dit is bijvoorbeeld de URL voor het ophalen van de eerste pagina met resultaten die overeenkomt met het unieke item met nummer "123":

https://api.trackonline.com/api/v1/uniqueitem?ItemNumber=123&page=1&apikey=xxx

U kunt natuurlijk zoveel parameters toevoegen als u wilt in de URL. Voeg daarom &filter=waarde toe aan de URL waar filter de naam van het filter is en waarde de waarde is waarop je wilt filteren.

# Locatie

Het gegevensmodel voor de GET- of POST-oproepen voor de locatie bestaat uit het volgende (gemarkeerd met * zijn verplichte velden):

# GET-parameters

De GET-parameters zijn de parameters die u kunt doorgeven om de locaties te filteren wanneer u ze ophaalt. Een voorbeeld is beschikbaar in de volgende sectie.

# Voorbeeldoproepen

In dit voorbeeld gaan we een POST maken van een nieuwe locatie genaamd 'Van locatie' met alleen de verplichte info.

[
  {
    "number": "123",
    "name": "Van locatie",
    "type": "Bedrijfslocatie"
  }
]

In dit voorbeeld gaan we een POST maken van een nieuwe locatie genaamd 'Van locatie' met wat aanvullende informatie.

[
  {
    "number": "456",
    "name": "Naar locatie",
    "nameShort": "ToLoc",
    "type": "Klant",
    "addressLine": "123 Klantstraat",
    "postalCode": "12345",
    "city": "Customerville",
    "stateOrProvince": "CUS",
    "country": "Customerland",
    "emailAddress": "info@customer.com",
    "languageId": "Engels",
    "balanceOperationMode": "NoRestriction",
    "tags": ["Klant", "CUS", "Customerville"]
  }
]

Bij het ophalen van uw locaties kunt u ook de parameters gebruiken die worden uitgelegd in de sectie GET-parameters om te filteren. Dit is bijvoorbeeld de URL voor het ophalen van de eerste pagina met resultaten die overeenkomt met de locaties met hiërarchieniveau 1 EN een naam of korte naam met "klant" 0:

https://api.trackonline.com/api/v1/location?HierarchyLevels=1&Naam=klant&pagina=1&apikey=xxx

U kunt natuurlijk zoveel parameters toevoegen als u wilt in de URL. Voeg daarom &filter=waarde toe aan de URL waar filter de naam van het filter is en waarde de waarde is waarop je wilt filteren.

# Verpakkingslabel

Het gegevensmodel voor de GET- of POST-oproepen voor de verpakkingslabel bestaat uit het volgende (gemarkeerd met * zijn verplichte velden):

# GET parameters

De GET-parameters zijn de parameters die u kunt doorgeven om de verpakkingslabels te filteren wanneer u ze ophaalt. Een voorbeeld is beschikbaar in de volgende sectie.

# Voorbeeldoproepen

In dit voorbeeld gaan we een POST maken van een nieuwe verpakkingslabel met nummer PL0123456789 van het type Sscc en verloopdatum op 25-01-2028 met alleen de verplichte info. Dit verpakkingslabel heeft GEEN niet-geserialiseerde en geserialiseerde items.

[
  {
    "number": "PL0123456789",
    "expirationOn": "2028-01-25T00:00:00.000Z",
    "type": "Sscc"
  }
]

In dit voorbeeld gaan we een POST maken van een nieuwe verpakkingslabel met nummer PL9876543210 van het type Sscc en verloopdatum op 26-03-2028 met wat aanvullende informatie. Dit verpakkingslabel bevat 25 items van item definitie 'CC Tag5' (niet-geserialiseerde items) EN 2 unieke items 'UI01' en 'UI02' (geserialiseerde items).

[
  {
    "number": "PL9876543210",
    "expirationOn": "2028-03-26T00:00:00.000Z",
    "type": "Sscc",
    "packagingNonSerializedItems": [
      {
        "itemDefinition": {
          "number": "CC TAG5",
          "name": "CC TAG5",
          "code": "TAG5",
          "type": "LoadCarrier"
        },
        "quantity": "25"
      }
    ],
    "packagingSerializedItems": [
      {
        "item": {
          "number": "UI01",
          "barcode": "123456",
          "itemDefinition": {
            "number": "CC TAG5",
            "name": "CC TAG5",
            "code": "TAG5",
            "type": "LoadCarrier"
          }
        },
        "item": {
          "number": "UI02",
          "barcode": "789012",
          "itemDefinition": {
            "number": "CC TAG5",
            "name": "CC TAG5",
            "code": "TAG5",
            "type": "LoadCarrier"
          }
        }
      }
    ]
  }
]

Bij het ophalen van uw verpakkingslabels kunt u ook de parameters gebruiken die worden uitgelegd in de sectie GET-parameters om te filteren. Dit is bijvoorbeeld de URL voor het ophalen van de eerste pagina met resultaten die overeenkomt met de verpakkingslabels met de letters "PL" in het nummer:

https://api.trackonline.com/api/v1/packaginglabel?Number=PL&page=1&apikey=xxx

U kunt natuurlijk zoveel parameters toevoegen als u wilt in de URL. Voeg daarvoor &filter=waarde toe aan de URL waar filter de naam van het filter is en waarde de waarde is waarop je wilt filteren. Als u nu verpakkingslabels wilt filteren met de letters "PL" in het nummer EN van het type Sscc (typecode = 1) EN zowel actieve als inactieve verpakkingslabels mee wilt nemen, dan ziet de URL er als volgt uit:

https://api.trackonline.com/api/v1/packaginglabel?Number=PL&TypeCodes=1&IncludeInactive=true&page=1&apikey=xxx

# Transactie

Het datamodel voor de transactie GET- of POST-oproepen bestaat uit het volgende:

# GET-parameters

De GET-parameters zijn de parameters die u kunt doorgeven om de transacties te filteren wanneer u ze ophaalt. Een voorbeeld is beschikbaar in de volgende sectie.

# Voorbeeldoproepen

In dit voorbeeld gaan we een POST maken van een transactie van “Van Locatie” naar “Naar Locatie” met daarin 25 stuks van de CC TAG5-ladingdrager. Dit is een voorbeeld zonder unieke items.

[
  {
    "statusCode": 0,
    "typeCode": 60,
    "transactionNumber": "1234567890",
    "fromLocation": {
      "number": "123",
      "name": "From Location",
      "type": "Customer"
    },
    "toLocation": {
      "number": "456",
      "name": "To Location",
      "type": "Customer",
      "tags": []
    },
    "dateTransaction": "2020-01-01T00:00:00.000Z",
    "dateTransactionCounterpart": "2020-01-01T00:00:00.000Z",
    "transactionItems": [
      {
        "itemDefinition": {
          "number": "CC TAG5",
          "name": "CC TAG5",
          "code": "TAG5",
          "type": "LoadCarrier"
        },
        "quantity": "25"
      }
    ]
  }
]

In dit voorbeeld gaan we een POST maken van een transactie van “Van Locatie” naar “Naar Locatie” met 3 unieke items die een streepjescode bevatten.

[
  {
    "statusCode": 35,
    "typeCode": 15,
    "transactionNumber": "1234567890",
    "fromLocation": {
      "number": "123",
      "name": "Van locatie"
    },
    "toLocation": {
      "number": "456",
      "name": "Naar locatie"
    },
    "dateTransaction": "2021-01-01T00:00:00.0000000+00:00",
    "scannedItems": [
      {
        "type": "BarCode",
        "code": "0000001"
      },
      {
        "type": "BarCode",
        "code": "0000002"
      },
      {
        "type": "BarCode",
        "code": "0000003"
      }
    ]
  }
]

Bij het ophalen van uw transacties kunt u ook de parameters gebruiken die worden uitgelegd in de sectie GET-parameters om te filteren. Dit is bijvoorbeeld de URL voor het ophalen van de eerste pagina met resultaten die overeenkomt met de transacties die tussen 1 en 31 mei zijn gemaakt met de vervoerders 001 of 002:

https://api.trackonline.com/api/v1/transaction?CreatedDateFrom=2020-05-01T00%3A00%3A00.000Z&CreatedDateTo=2020-05-31T23%3A59%3A59.000Z&Carriers=001&Carriers=002&page=1&apikey=xxx

U kunt natuurlijk zoveel parameters toevoegen als u wilt in de URL. Voeg daarom &filter=waarde toe aan de URL waar filter de naam van het filter is en waarde de waarde is waarop je wilt filteren.

# Transactie Rit

U kunt de status van een rit naar de volgende status zetten. Hiervoor diendt een entityguid van de rit opgestuurd te worden. Een rit in de status nieuw zal naar de status in behandeling worden gezet. Een rit in de status in behandeling zal naar de status verwerkt worden gezet.

Hieronder is een voorbeeldoproep te zien.

# Voorbeeldoproep

In dit voorbeeld wordt de status van de rit met guid (id) A7B8AF3F-4C16-492E-A3B7-451E8E096D30 naar de volgende status gezet.

[
  {
    "id": "A7B8AF3F-4C16-492E-A3B7-451E8E096D30"
  }
]

# IoT-apparaten

# GET IoT-apparaat

Het datamodel voor de IoT GET-oproep bestaat uit het volgende:

# GET IoT-apparaatgeschiedenis

Bovendien is het mogelijk om de geschiedenis van locaties voor een IoT-apparaat op te halen, zoals hieronder wordt uitgelegd. De GET-parameters zijn de parameters die u kunt doorgeven om de transacties te filteren wanneer u ze ophaalt. Een voorbeeld is beschikbaar in de volgende sectie.

# Voorbeeldoproepen

Stel dat u de IoT-apparaten moet vinden die zijn gekoppeld aan items met item definitie ID b2ccd1e4-e30f-4473-862f-28eb69238f65. Dit is hoe de URL eruit ziet.

https://api.trackonline.com/api/v1/iot/item?itemDefinitionId=b2ccd1e4-e30f-4473-862f-28eb69238f65&page=1&apikey=xxx

Als u nu de geschiedenis van een specifiek IoT-apparaat wilt bekijken, laten we zeggen 00EDBED7, kunt u het volgende doen:

https://api.trackonline.com/api/v1/iot/item/measurement?deviceId=00EDBED7&apikey=xxx

U kunt natuurlijk zoveel parameters toevoegen als u wilt in de URL. Voeg daarom &filter=waarde toe aan de URL waar filter de naam van het filter is en waarde de waarde is waarop je wilt filteren.

# Saldo

U kunt het reguliere saldo van een locatie of het saldo per tegenpartij krijgen, ongeacht of u een tegenpartij opgeeft of niet. Het datamodel voor de saldo-GET-oproepen bestaat uit het volgende:

|Parameter|Type|Informatie| ​ |date|string|De datum en tijd waarop het saldo moet worden gefilterd.| |locations|[string]|Array met locatienummers.| |onlyProcessed|boolean|Bereken het saldo alleen voor verwerkte transacties.| |excludeZeroBalance|boolean|0 saldi uitsluiten van de gegevens.| |counterparts|[string]|Array met locatienummers. Alleen voor / api / v1 / balance / counterpart|

# Voorbeeldoproepen

Dit eerste voorbeeld is voor het ophalen van het saldo voor locaties A en B, exclusief lopende transacties en lege saldi:

https://api.trackonline.com/api/v1/balance?locations=A&locations=B&onlyProcessed=true&excludeZeroBalance=true&apikey=xxx

Laten we ons nu eens voorstellen dat je niet het saldo wilt dat je hebt met A en B, maar eerder het saldo dat A heeft met B. Daarom moet je de URL**/ api / v1 / saldo / tegenpartij**als volgt gebruiken:

https://api.trackonline.com/api/v1/balance/counterpart?location=A&counterparts=B&onlyProcessed=true&excludeZeroBalance=true&apikey=xxx

# Batch berekening

# GET Batch berekening(en)

Om een gefilterde lijst met batch berekeningen op te halen, kunnen de volgende parameters worden gebruikt:

# GET Download batch berekeningsresultaat

Verder is het mogelijk om het volledige batch berekeningsresultaat te downloaden.

# GET Document(en) voor batch berekening(en)

Om een gefilterde lijst met batch berekeningsdocumenten op te halen, kunnen de volgende parameters worden gebruikt:

# GET Download batch berekeningsresultaat document

Verder is het mogelijk om een resultaatdocument van een enkele batch berekening te downloaden.

# API-antwoorden

Hieronder staan ​​de mogelijke reacties op de bovenstaande aanroepen.

Als u meer gegevens nodig heeft, zoals specifieke modellen die hierboven niet worden uitgelegd, raadpleegt u de volgende sectie.

# Online API-documentatie

Bezoek de volgende link voor online documentatie van de verschillende methoden die kunnen worden gebruikt: Online API-documentatieopen in new window

In de online API-documentatie kunt u uw API-sleutel gebruiken om uw verzoek te autoriseren door op de autorisatieknop te drukken en uw API-sleutelreeks in te voeren.

Extra informatie over de parameters en modellen van de methoden vindt u ook op deze pagina. In onderstaand voorbeeld leggen we uit waar u deze informatie kunt vinden.

# Informatie over methoden en parameters

Klik eerst op een van de methoden. In dit voorbeeld klikken we op de 'POST'-methode van de' item definitie'-controller. Zie onderstaande afbeelding.

# POST-methode van de item definitie controller

Dit opent de POST-methode. Nu kunt u de naam en beschrijving van de parameters en de antwoorden zien.

Ten tweede, om de beschrijving van elke parameter te zien, klikt u op Model (naast 'Voorbeeldwaarde') zoals weergegeven in de onderstaande afbeelding.

# Model van de item definitie controller

Derdeklik op een van de modellinks. In dit geval wordt slechts één link getoond, de ItemDefinitionDto-link. Zie onderstaande afbeelding.

# Modellink

De link ontvouwt zich en alle parameters van het model worden nu getoond. In de kolom 'De item definitie' vind je een omschrijving van elke parameter. Ook het type, maximum en minimum en meer details worden hier beschreven.

# Parameternamen en beschrijvingen