Strona może być nieaktualna
Nikt jej nie zmieniał od 55 miesięcy (ostatni commit: 2022-04-04, Dariusz). Jeśli opisuje stan, którego już nie ma, zgłoś ją jako nieaktualną.
JSON REST API v1 - integration options¶
The API provided by the Logintegra's Time Windows system allows basic operations to be performed by the internal systems of contractors. All requests should be encrypted using HTTPS.
1. Message structure¶
API uses HTTP verbs to describe actions:
HTTP GET- retrieving resourcesHTTP POST- authentication and creating resourcesHTTP PUT- updating resourcesHTTP DELETE- deleting resources
Every message except login requires the authorization token in the Authorization header
where access_token is given in response of the login method (see Authentication chapter).
If the request is meant to save data in the Time Windows system (usually POST and PUT), the Content-Type: application/json header should be present as well.
Responses¶
Analysis of responses should first be based on HTTP codes received from the system. Currently supported codes are:
200 OK- request has succeeded, e.g. the response contains the requested data201 Created- new resource has been created400 Bad Request- invalid request - the request couldn't be handled by the server due to an error perceived as a user error (e.g. incorrect query syntax).401 Unauthorized- resource that requires authentication has been requested by unauthorized client, e.g. no valid token has been provided (see Authentication)403 Forbidden- the server understood the request, but the security configuration prevents it from returning the requested resource404 Not Found- the server did not find the resource by the given URL or anything that would indicate the existence of such resource in the past422 Unprocessable Entity- the server understood the request, but the data does not meet the validation rules500 Internal Server Error- the server encountered unexpected difficulties that prevented the request from being processed504 Gateway Timeout- the request has been taking too long and the server has stopped processing it
See also: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
The response format is meant to follow Google's style guide described in https://google.github.io/styleguide/jsoncstyleguide.xml.
2. Authentication and authorization¶
Note: For testing purposes it is possible to use the login and password of any user registered in the Time Windows system, but in order to fully use the API, it is necessary to create a user with a special role. To do this, contact Customer Service by writing to info@logintegra.com.
Logging into the system is performed by sending a JSON document with the content
{
"username": "[email protected]",
"password": "secret"
}
to
In case of failure the message HTTP 401 Unauthorized will be returned, which means that
- the login details (login or password) were incorrect,
- the user with given username does not exist in the system,
- or the user with given username has been deleted.
If the login details are correct, the code HTTP 200 OK and a following reply will be sent
{
"username": "[email protected]",
"roles": [],
"access_token": "XXX",
"token_type": "Bearer"
}
The most important element of the response is the access_token node, which value will be used for authorization when sending subsequent requests - in the header of each request the node Authorization: Bearer XXX should be present, where XXX is the value of access_token from login response. Without this header, the HTTP 401 Unauthorized response will always be returned.
The access_token is valid for 24 hours after the last use. If the token has expired, it's necessary to log-in to the system again to receive the new token.
3. Available operations¶
Checking system availability¶
Request:
Possible responses:
HTTP 200- the system is working properlyHTTP 500- internal server errorHTTP 504- the system is overloaded and cannot work properlyTime out- the system is unavailable
If the system works properly, the following information will also be returned:
{
"status": "running",
"version": "2.38.1", // Current version of the application
"date": "2019-01-01T11:23:23Z" // Current date on the server
}
Creating transport¶
Before created transport should first be chosen TRANSPORT_IDENTIFIER_TYPE. Possible options:
* ERP_IDENTIFIER
* ALT_IDENTIFIER
* ID

For ALT or ERP identifier option, transport created by API should have unique identifier. Message when somebody tries multiplication identifier :
The operation has failed. An order with the alt identifier number "X" already exists in the platform
Request¶
HTTP POST
https://apollo.logintegra.com/apollo/api/transports/
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
{
"erpIdentifier": "AA3423", // Transport number in the customer's system
"altIdentifier": "84374753", // Additional number in the customer's system
"description": "Note: Sideways loading only!", // Transport description
"tradesman": "[email protected]", // The name of the user responsible for carrying out the transport on the client's side
"carrierCompany": {
// The carrier that will be assigned to the transport can be specified using one of the fields below.
// This node may be omitted if the carrier should be assigned in the "Time Windows" system.
// Each of the following nodes is optional and can be used interchangeably.
// It is recommended to send one node of choice. The search of carrier takes place in the following order:
// `id`, `contractorNumber`, and finally `shortName`.
// If two nodes are given, e.g. `contractorNumber` and` shortName`, and the object is not found after the `contractorNumber` field, an error will be returned.
// NOTE: The carrier must already exist in the "Time Windows" system before it can be assigned to the transport.
"id": "3421231", // Carrier id in the "Time Windows" system
"contractorNumber": "UID94392", // Carrier number entered in the "Companies" tab
"shortName": "ABC" // Short name of the carrier's company
},
"principalCompany": {
// Transport owner. It is necessary to provide at least one of the following nodes; they can be used interchangeably.
id: "76084423",
alias: "principal" // Identifying name, determined during deployment
},
"transportType": {
// The "Time Windows" system enables handling of various types of transport, e.g. Deliveries, Loadings, Couriers, or Own Pickups.
// Each type of transport may have different statuses and additional form fields.
// It is necessary to provide at least one of the following nodes; they can be used interchangeably
"id": "2423123",
"alias": "OWN_COLLECTION" // Identifying name, determined during deployment
},
"steps": [
// List of steps (stages) which make up the transport; in most cases it will be one item.
// A larger number of steps can be given e.g. in the case of transfers between warehouses or orders with the necessary customs service outside the loading place.
{
"stepTypeName": "load", // One of the values: load/unload
"orderInTransport": "0", // Order in the sequence of steps; for one-step transports it should be 0
"documentIdentifier": "", // Document number (e.g. WZ/PZ in Poland)
"minAdviceDate": "2019-02-23T17:00:00Z", // The earliest possible date when the car can be serviced by the warehouse
"maxAdviceDate": "2019-02-23T21:00:00Z", // The latest possible date when the car can be serviced by the warehouse
"arrivalDate": "2019-02-23T21:00:00Z", //Delivery date ordered / Pick up date
"quantity": "121.2", // Number of pallets or other collective packaging
"volume": "21.1", // Volume of goods including packaging
"weight": "15.3", // Weight of goods including packaging
"company": {
// Contractor (supplier or recipient) of the goods assigned to the transport.
// Searching and assigning of a contractor works the same way as searching and assigning of a carrier.
// NOTE: Contractor must already exist in the "Time Windows" system before it can be assigned to transport.
"id": "23123", // Contractor id in the "Time Windows" system
"contractorNumber": "K942823", // Contractor number entered in the 'Companies' tab
"shortName": "XYZ" // Short name of the contractor's company
},
"warehouse": {
// The warehouse in which loading or unloading will be carried out.
// The choice of warehouse works similarly to the choice of carrier, i.e. it is sufficient to provide one of the following fields.
// The user who will be choosing the exact date of service in "Time Windows" will be redirected to the schedule assigned to this warehouse.
// NOTE: The warehouse must already exist in the "Time Windows" system before it can be assigned to transport.
"id": "1231",
"idx" : "1", // Warehouse number (if the company has only one warehouse, it can always be 0); the order can be determined in the application
"name": "Packaging Warehouse" // The name of the warehouse in the "Time Windows" system
}
}
],
"customFields": [
// Additional fields defined during deployment
{
"definitionName": "Item temperature",
"value": "7"
},
{
"definitionName": "Level of preparation",
"value": "80%"
}
]
}
Possible responses¶
If the transport is saved correctly, the response message will contain the code HTTP 200 OK with a following JSON document:
{
"id": "32421231", // Transport id
"erpIdentifier": "AA3423", // Transport number in the customer's system
"altIdentifier": "84374753", // Additional number in the customer's system
"description": "Note: Sideways loading only!", // Transport description
"tradesman": "[email protected]", // The name of the user responsible for carrying out the transport on the client's side
"carrierCompany": {
// Unlike the request to create or edit transport, all nodes below will be sent
"id": "3421231", // Carrier id in the "Time Windows" system
"contractorNumber": "UID94392", // Carrier number entered in the "Companies" tab
"shortName": "ABC" // Short name of the carrier's company
},
"transportType": {
// Unlike the request to create or edit transport, all nodes below will be sent
"id": "2423123",
"name": "OWN_COLLECTION"
},
"steps": [
{
"id": 123456789,
"stepTypeName": "load", // One of the values: load/unload
"orderInTransport": "0", // Order in the sequence of steps; for one-step transports it should be 0
"documentIdentifier": "", // Document number (e.g. WZ/PZ in Poland)
"minAdviceDate": "2019-02-23T17:00:00Z", // The earliest possible date when the car can be serviced by the warehouse
"maxAdviceDate": "2019-02-23T21:00:00Z", // The latest possible date when the car can be serviced by the warehouse
"arrivalDate": "2019-02-23T21:00:00Z", //Delivery date ordered / Pick up date
"quantity": "121.2", // Number of pallets or other collective packaging
"volume": "21.1", // Volume of goods including packaging
"weight": "15.3", // Weight of goods including packaging
"company": {
// Unlike the request to create or edit transport, all nodes below will be sent
"id": "23123", // Contractor id in the "Time Windows" system
"contractorNumber": "K942823", // Contractor number entered in the 'Companies' tab
"shortName": "XYZ" // Short name of the contractor's company
},
"warehouse": {
// Unlike the request to create or edit transport, all nodes below will be sent
"id": "1231",
"idx" : "1", // Warehouse number (if the company has only one warehouse, it can always be 0); the order can be determined in the application
"name": "Packaging Warehouse" // The name of the warehouse in the "Time Windows" system
},
"address": {
// Loading or unloading address
"id": "74727",
"recipient": "PolPak", //Recipient of loading or unloading
"street": "Sap 23", // Street of loading or unloading
"postal": "12345", // Postal of loading or unloading
"city": "Krynica Morska", // City of loading or unloading
"country": "PL" // Country of loading or unloading
}
}
],
"checkpoints": [
// List of statuses that have been created for this transport.
// The number of statuses, their names and business significance depend on the configuration defined during implementation.
{
// Status confirmed automatically when creating transport
"id": "38651834", // Status id
"idx": "0", // Status order
"checkpointName": "Transport created", // Name
"confirmator": "[email protected]", // Name of the user who confirmed the status
"expectedDate": "2019-03-02T09:12:34Z", // The latest confirmation date that will not indicate the delay
"executionDate": "2019-03-02T09:12:34Z",// Actual confirmation date of status
"alias": "ORDER_CREATED"
},
{
// A status that has not yet been confirmed and is waiting for the appropriate action to be taken in the "Time Windows" system
"id": "38651834",
"idx": "1",
"checkpointName": "Advice saved",
"confirmator": null,
"expectedDate": "2019-03-02T12:00:00Z",
"executionDate": null,
"alias": "ADVICE_SAVED"
}
],
"customFields": [
// Additional fields defined during deployment
{
"definitionName": "Item temperature",
"value": "7"
},
{
"definitionName": "Level of preparation",
"value": "80%"
}
]
}
More examplary requests and responses may be found in examples file.
Validation errors¶
Validation of values in the node "step.address"¶
"address": {
// Loading or unloading address
"id": "74727",
"recipient": "PolPak", //Recipient of loading or unloading
"street": "Sap 23", // Street of loading or unloading
"postal": "12345", // Postal of loading or unloading
"city": "Krynica Morska", // City of loading or unloading
"country": "PL" // Country of loading or unloading
},
Validations¶
- Validation to make it mandatory - all fields are mandatory.
- Country validation - only available in the database
- Validation for the length of the given data - the maximum length of 255 characters
Feedback¶
In the absence of a value:
Invalid address
In case of wrong country code:
Invalid country code
Validation of values in the node „step.company”¶
One of the fields is mandatory id, contractorNumber, shortName.
Feedback¶
In the absence of a value: Niepoprawne dane firmy
Validation of values in the node „step.warehouse”¶
One of the fields is mandatory id, idx, name.
Transport with one step: we are checking transportType#requiresWarehouse flag and if it equals true - "warehouse" field is required.
Transport with multiple steps: one of the fields "warehouse" or "address" is required in every step.
Feedback¶
In the absence of a value: Niepoprawne dane magazynu
Validation of values in the node „step”¶
| Field name | Validation | Feedback |
|---|---|---|
| stepTypeName | Mandatory field. Allowed values: load or unload | If no value is provided: There is no value in the "stepTypeName" field, which is mandatory. In case of an incorrect value: Invalid value in the "stepTypeName" field. Acceptable values are: "load", "unload". |
| orderInTransport | Mandatory field. The set of values from this field should contain successive natural numbers (including zero), values cannot repeat. For n-steps, the acceptable values will be: 0, 1, ..., n-1. | If no value is provided: There is no value in the "orderInTransport" field, which is mandatory. In case of an incorrect value: Invalid values in the orderInTransport field. In one message with n steps can be following values: 0,1,2, ..., n-1 (without repetition). |
| documentIdentifier | Any text, up to 255 characters | Property "documentIdentifier" exceeds the maximum size of 255 characters |
| minAdviceDate | to do A-7604 | |
| maxAdviceDate | to do A-7604 | |
| quantity | to do A-7604 | |
| volume | to do A-7604 | |
| weight | to do A-7604 |
Validation in "customFields" node¶
In customFields node list of custom fields is sent. First validation is checking if custom field with given name or english name exists for given transport type.
Then format of the custom field value is being checked:
- text fields - no format validation,
- numeric fields - valid number (positive, negative, floating-point - dot is the separator),
- select fields - valid option from options available in local language or english,
- date fields - valid date in one of following formats: "dd.MM.yyyy HH:mm", "dd.MM.yyyy", "yyyy-MM-dd'T'HH
ss'Z'"
- datetime fields - valid datetime in one of following formats: "dd.MM.yyyy HH:mm", "yyyy-MM-dd'T'HH
ss'Z'"
Updating transport¶
Request¶
HTTP PUT
https://apollo.logintegra.com/apollo/api/transports/$transportId
or
https://apollo.logintegra.com/apollo/api/transports/$erpIdentifier
or
https://apollo.logintegra.com/apollo/api/transports/$altIdentifier
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
The variable $transportId is the transport id number in the "Time Windows" system returned in the nodeid of transport creation response (see Creating transport).
Usage of the $erpIdentifier and $altIdentifier variables is only possible if these fields have unique values.
Which field will be used to identify the transport will be determined during deployment of application as a system setting - Setting.TRANSPORT_IDENTIFIER_TYPE
In the transport edit request, remember to enter the ID number for each step you want to edit, for example:
(...)
"steps": [
{
"id": 123456789, // id received after creation of the transport
"address": {
"city": "Krynica Morska",
"country": "PL",
"id": 249672726,
"postal": "12345",
"recipient": "TESTOWY222",
"street": "Sap 23"
},
(...)
The rest of the query is structured in the same way as for the creation of the transport. The system does not support the ability to send only changed fields. It is necessary to send the full JSON document after each edition in the client's system.
Possible responses¶
- If the transport changes are saved correctly, the
HTTP 200 OKmessage will be returned with the same content as when creating a new transport - In case of sending incorrect data, the message
HTTP 422 Unprocessable Entitywill be returned, the content of which will contain a list of errors as in the case of creating a new transport - In the absence of a valid token (
access_token), theHTTP 401 Unauthorizedmessage will be returned - In case of lack of permission to edit transport, the message
403 Forbiddenwill be returned - If the transport with the given identifier is not found, the message
HTTP 404 Not Foundwill be returned - If more than one transport with the given identifier is found, the message
HTTP 422 Unprocessable Entitywill be returned
Getting a list of current transports¶
Request¶
HTTP GET
https://apollo.logintegra.com/apollo/api/transports
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
Possible responses¶
In response, a list of currently available transports will be returned. These are transports that have not been deleted or archived. The structure of the transport data will be the same as for the response to the creation of a new transport. This function is not recommended for updating the data of individual transports on the basis of regular querying due to the large amount of returned data and potentially longer response time.
In the absence of a valid token (access_token), the HTTP 401 Unauthorized message will be returned.
Getting information about recently updated transports¶
Request¶
HTTP GET
https://apollo.logintegra.com/apollo/api/transports/updates/$durationInSeconds
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
The variable $durationInSeconds defines the period from which changes should be included. It is recommended to use this function for regular data querying.
It is important to consider the time it takes to send, receive, and process a request when implementing polling, and not to make further requests before receiving a response to the previous one.
Suggested workflow:
- Save the current time
- Send a request to the "Time Windows" system for a list of all active transports
- Process responses
- Schedule a request for updated transports (
../api/transports/updates/$durationInSeconds) in a few minutes - Wait..
- Calculate the period to ask about: current time - saved time of previous request + error margin*
- Save the current time
- Send a request for recently updated transports (
../api/transports/updates/$durationInSeconds) - Process responses
- Return to step 4
- error margin - 10 seconds is a suggested value
Possible responses¶
In response, a list of transports that have been updated in the last $durationInSeconds seconds will be returned.
The structure of the transport data will be the same as when creating a new transport.
In the absence of a valid token (access_token), the HTTP 401 Unauthorized message will be returned.
Statuses confirmation¶
Request¶
HTTP PUT
https://apollo.logintegra.com/apollo/api/transports/$transportId/confirm/$alias
or
https://apollo.logintegra.com/apollo/api/transports/$erpIdentifier/confirm/$alias
or
https://apollo.logintegra.com/apollo/api/transports/$altIdentifier/confirm/$alias
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
The variable $alias is the name - determined during deployment of the system - of the status that needs to be confirmed.
The current server date will be used as the status confirmation date. The user used during authorization will be selected as the person confirming the status.
Setting Setting.TRANSPORT_IDENTIFIER_TYPE defines which identifier (transportId, erpIdentifier or altIdentifier) should be used to find transport to approve checkpoint.
Possible responses¶
- If the status is confirmed correctly, the
HTTP 200 OKmessage will be returned - In the absence of a valid token, the
HTTP 401 Unauthorizedmessage will be returned - In case of lack of permission to the transport or status confirmation, the
403 Forbiddenmessage will be returned - If the transport with the given identifier is not found or the appropriate status is not found, the
HTTP 404 Not Foundmessage will be returned - If more than one transport with the given identifier is found, the
HTTP 422 Unprocessable Entitymessage will be returned
Creating/editing of advice data¶
To create/edit advice data the creation/edition transport request has to contain "advice" node:
{
"id": "32421231",
"erpIdentifier": "AA3423",
"altIdentifier": "84374753",
"description": "Uwaga: Załadunek tylko bokiem",
(..)
"advice": {
"driverName": "GRAD PIOTR", //driver nane
"carRegistrationNumber": "WGM11150", //car registration number
"trailerRegistrationNumber": "WZ2303R", //trailer registration number
"documentNumber": "ATD212324", //driver document number
"documentType": "ID_CARD", //driver document type: PASSPORT or ID_CARD
"driverMobilePhoneNumber": "600284363", // driver phone number
"driverMobilePhonePrefix": "48", // driver phone number prefix
"personalDataProcessingConsent": "true", // consent to the processing of personal data
"termsOfConditionsAccepted": "true" // consent to the terms of conditions, required depending on settings `SHOW_TERMS_OF_CONDITIONS_ACCEPTED`
},
(..)
}
If request does not contain "advice" node, and the transport has added advice on Logintegra platform, advice data will be copied from database - there is no possibility of removing existing advice via API.
Creating/editing of time window¶
To create/edit time window request has to contain "timeWindow" node in corresponding step.
{
"id": "32421231",
"erpIdentifier": "AA3423",
"altIdentifier": "84374753",
"description": "Uwaga: Załadunek tylko bokiem",
(..)
"steps": [
{
"stepTypeName": "load",
"orderInTransport": "0",
(..)
"timeWindow": {
"ramp": "Slot nr 1", // name of the ramp
"start": "2019-03-04T12:30:00Z" // time window start
},
(..)
}
],
(..)
}
End of the time window will be calculated by the platform according to company settings.
If "timeWindow" node is not sent, and the order has time window on the platform, time window data will be copied from the database - there is no possibility of deleting time window via API.
Free slots request¶
To obtain information about first free slots in warehouse schedule following request needs to be sent:
HTTP POST
https://apollo.logintegra.com/apollo/api/time-windows/suggest
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
{
"principalCompany": {
"id": "", // id of the principal company
"alias": "semmelrock" // alias of the principal company
},
"transportType": {
"id": "", // id of the transport type
"alias": "LOADING" // alias of the transport type
},
"warehouse": {
"id": "", // id of the warehouse
"name": "Magazyn Gdynia" // name of the warehouse
},
"searchStart": "2021-08-05T12:00:00Z", // begin of the time span to find free slot
"searchStop": "2021-08-05T17:00:00Z" // end of the time span to find free slot
}
In principalCompany node id and/or alias of the principal company needs to be sent.
In transportType node id and/or alias of the transport type needs to be sent.
In warehouse node id and/or name of the warehouse needs to be sent.
In the response there is a list of suggested free slots for a time window:
{
"slots": [
{
"start": "2021-08-05T12:00:00Z",
"stop": "2021-08-05T13:00:00Z",
"ramp": {
"id": 222498499,
"warehouse": {
"id": 222498476,
"name": "Magazyn Gdynia"
},
"name": "1/A",
"shortName": "1/A"
}
},
{
"start": "2021-08-05T12:00:00Z",
"stop": "2021-08-05T13:00:00Z",
"ramp": {
"id": 222498595,
"warehouse": {
"id": 222498476,
"name": "Magazyn Gdynia"
},
"name": "2/A",
"shortName": "2/A"
}
}
]
}
Ostatnia zmiana: 2022-04-04 · Dariusz
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e