{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"0101f7de-699e-41bf-97e8-ff2abff43450","name":"XConvert API","description":"Please use the XConvert API to interact with the Logenios Freight Exchange platform. If there are questions regarding this API please feel free to contact the Logenios team.\r\n\r\n# Prerequisites\r\nIn order to use the Logenios xConvert API, you need an active Logenios account. This account can be created free of charge on our [Register web-page](https://app.logenios.com/account/register). Please note that user accounts are not synchronized between our beta and our production environment. If you want to use the beta environment for development, you need a separate account which can be created [here]( https://beta.app.logenios.com/account/register). \r\nOnce you have a valid Logenios account, you can execute the samples provided in this document. Those samples can be executed via postman or swagger ui. However, please use those samples only for learning purposes or small scripts. For integrating Logenios in your software, please generate an API-Client using the provided swagger file available [here](https://beta.app.logenios.com/apidocs/swagger.json)\r\n\r\n# Generating an API client\r\nWe offer a full specification of the REST APIs via a Swagger 2.0 (OpenAPI) specification file. This file can be used by the Swagger-UI project \r\nto display the API and generate full clients in various languages like C#, Java, Python and so on. \r\nFor simple code generation you can try the [Swagger online editor](https://editor.swagger.io/). \r\nTo automate the code generation process for future API changes, we recommend to integrate \r\nthe [OpenAPITools generator](https://github.com/OpenAPITools/openapi-generator) to your build process. Visual Studio 2017 also provides a swagger code generator. \r\nIn VS2017 this feature is available if you right-click on your project, select \"Add\" and then \"REST API Client\". If this menu entry is not available, please update your Visual Studio.\r\n\r\n# Change-Log\r\n| Date     | By          | Description                                       |\r\n|:---------|:------------|:--------------------------------------------------|\r\n| 03.02.19 | F. Englert  | Added field descriptions                          |\r\n| 02.02.19 | F. Englert  | Added API for customer defined address mapping    |\r\n| 05.01.19 | F. Englert  | Added timestamp fields for each status code       |\r\n| 16.12.18 | F. Englert  | Deprecated totalAmount in favour of totalQuantity |\r\n| 28.11.18 | F. Englert  | Extended Description Client Generation            |\r\n| 28.11.18 | F. Englert  | Modified Parameters of Register Object            |\r\n| 19.11.18 | T. Plumhoff | Proof-Reading                                     |\r\n| 19.11.18 | M. Grau     | Removed – and _ from API Endpoints                |\r\n| 16.11.18 | J. Mammri   | Ported this document from Word to Postman         |\r\n| 04.10.18 | M. Grau     | Added Description of Attachments                  |\r\n| 18.09.18 | F. Englert  | General Description                               |\r\n\r\n# Scope of the Logenios xConvert API\r\n\r\nOur Logenios platform is intended for sharing information between logistics companies. Therefore, we provide means to exchange transport orders as well as tracking information with partner companies. Our API provides means for the following requirements:\r\n1.\tIntegration between ERP systems of shippers and TMS systems of logistic companies and providing track- and trace functionalities for shippers.\r\n2.\tIntegration between TMS systems of different software vendors and logistic companies. \r\n3.\tTelematic integration for enhanced sub-contractor management and provisioning of live information on the transport order status. \r\n\r\n\r\n![scope of the Logenios xConvert API](https://beta.app.logenios.com/apidocs/images/Logenios_Scope_of_API.png \"Scope of the Logenios xConvert API\")\r\n\r\nIn order to provide this functionality, the xConvert API provides the following building blocks:\r\n1.\tCreate or update transport orders and assign them to vehicles or other logistics companies.\r\n2.\tFetch transport orders which are assigned to the current company and submit status changes, tracking data or attachments to inform partners of the execution status.\r\n3.\tRetrieve status changes, tracking data or attachments for observed transport orders which are executed by partner companies.\r\n4.\tAdditionally, the xConvert API provides endpoints to create, modify or delete relevant account data, configuration options or partner companies\r\n\r\n\r\n## Description of the xConvert Data Model\r\n\r\nThe TransportOrder object contains relevant information of a shipment of one or more goods from one or more loading locations to one or more unloading locations. It may contain vias where the freight is exchanged. In order to encapsulate this information, the TransportOrder object contains a hierarchy of stop locations describing at which places freight should be loaded or unloaded or at which places the truck should enter or leave intermodal transportation facilities like trains or ferries. Those stop locations are grouped in transports which can be sub-assigned to other transport companies.\r\nAdditionally, the TransportOrder object has a hierarchy describing the freight to be transported. On the highest level it contains a list of freight elements. If needed, those freight elements can be composed of packets which itself can consist of packet items. \r\nThe stop locations and freight lists are mapped via stop action. The stop action describes which freight is loaded or unloaded at a particular stop location.\r\n\r\n\r\n![scope of the Logenios xConvert API](https://beta.app.logenios.com/apidocs/images/logenios_er_transport_order.png \"Structure of the TransportOrder object\")\r\n\r\n\r\n## Creating and Updating outbound Transport Orders \r\n\r\nIn the last section, we introduced the structure of the transport order. This transport order object is intended to be exchanged between different parties like:\r\n- Shipper and Transportation company\r\n- Transportation company and another transportation company\r\n- Transportation company and freight receiver\r\n\r\nIn this section a we give a brief description on how to create and update a transport order, which should be exchanged with a third party. From an api-users point of view, those shipments are outbound. \r\nIn order to create a transport order, please use the createTransportOrder operation. This operation expects a transport order object as parameter. This transport order object may contain references to the target company which should execute the transport order. If a target company is specified, the transport order is created with status “ACKNOWLEDGING”. Further, the receiving company is asked whether it will accept or reject the order.\r\n\r\nAs result of the createTransportOrder operation, a poupulated transport-order object is returned. This object contains the current status and a proper transport order id. Either this transport-order-id or the external transport-order-id must be used to identify this transport order object. The uniqueness of the externalTransportOrderId must be managed on the client side. \r\nShould it be required to store additional tracking information, the API operations replaceAdditionalData with the markedAsPrivate-flag may be used. \r\n\r\nThe transport order may be modified using the modifyTransportOrder operation. Modifying the transport order is prohibited if the transport order has reached a state “EXECUTING”, “CANCELED” or “DONE”.\r\n\r\n\r\n## Retrieving inbound TransportOrders and Status Messages\r\n\r\nInbound transport orders which should be executed by the company of the api-user or status changes of any relevant transport orders are encapsulated as events and inserted in a message queue. \r\nIn order to stay up to date, an API-client may process all messages from its message queue. Fetching messages from the message queue happens in a two step operation. First an api client must fetch a batch of messages using the fetchAllQueuedEvents operation. Then, after processing those events it must remove each event using the deleteQueuedEvent Method. \r\nNote: The api client will receive always the same batch of events unless it explicitly removes them from the event queue. Events older than 2 weeks are automatically purged from the event queue. \r\n\r\n### Structure of events\r\n![Structure of xConvert events](https://beta.app.logenios.com/apidocs/images/logenios_er_events.png \"Structure of the QueuedEvent object\")\r\n\r\n\r\nAn queuedEvent objects as stated in the figure above describes a significant happening which requires the exchange of information between cooperating parties. Currently, there are two kinds of events:\r\n1.\tPosition events generated if a vehicle executing a transport-order moves \r\n2.\tTransportOrder events which are generated if a transport order is modified \r\n\r\nHints:\r\n-\tThe list of events may further be extended. \r\n-\tThere are no compound events combining events of different kind in a single queuedEvent object. \r\n\r\nA position even simply contains a relation of the transportOrderId with the executing vehicle in addition to the current position of the vehicle. The frequency of those evens depends on the configuration of the telematic device generating those events. \r\nA transportOrderEvent compounds a copy of the full transport order object with a TransportOrderChange object describing which changes happened to the transport order. The type property of this object describes which kind of change has caused the generation of this event and the modifiedObject-Property contains a copy of the changed part of a transport order. \r\n\r\nExample 1:\r\nThe status of TransportOrder with id LOG-X1 was changed using the submitStatus operation. More precisely, the status of freight with freightId F1 was changed to DELIVERED. \r\nThen the ChangeType is set to STATUS_UPDATE_FREIGHT and the modified freight object is copied to the property modifiedObject.freight. All other properties of modifiedObject are set to NULL.\r\n\r\n\r\n### Source of Transport Order Changes\r\n\r\n| Change Type                  | Caused by api call   |\r\n|:-----------------------------|:---------------------|\r\n| CREATE                       | createTransportOrder |\r\n| UPDATE                       | modifyTransportOrder |\r\n| STORNO                       | cancelTransportOrder |\r\n| ATTACHMENT_ADD               | addAttachment        |\r\n| ATTACHMENT_DELETE            | deleteAttachment     |\r\n| ASSIGN_VEHICLE               | assignTransportOrder |\r\n| ASSIGN_COMPANY               | assignTransportOrder |\r\n| STATUS_UPDATE_TRANSPORTORDER | submitStatus         |\r\n| STATUS_UPDATE_STOP_LOCATION  | submitStatus         |\r\n| STATUS_UPDATE_STOP_ACTION    | submitStatus         |\r\n| STATUS_UPDATE_FREIGHT        | submitStatus         |\r\n\r\n\r\n\r\n\r\n\r\n## Identification of Transport Order Elements\r\n\r\nIn order to identify elements of the TransportOrder (like a StopLocation), the full path to the selected element of the transport order must be specified. E.g. if a single stop location should be referenced, the request must contain the transportOrderId, the transportId and the stopId. The following table describes which fields must be specified in order to address selected elements of the transport order:\r\n\r\n| transportOrderId | transportId | stopId   | actionId | freightId | Selected element     |\r\n|:-----------------|:------------|:---------|:---------|:----------|:---------------------|\r\n| Required         | Null        | Null     | null     | Null      | TransportOrderStatus |\r\n| Required         | Required    | null     | null     | null      | TransportStatus      |\r\n| Required         | Required    | Required | null     | Null      | StopLocationStatus   |\r\n| Required         | Required    | Required | Required | Null      | StopActionStatus     |\r\n| Required         | null        | null     | null     | Required  | FreightStatus        |\r\n\r\n\r\nThis information is relevant for submitting status changes, for adding attachments or for modifying additional data objects. \r\n\r\n\r\n## Submitting status updates\r\n\r\nThe TransportOrder, StopLocation, StopAction and Freight objects have a status which describes the current execution state of those elements. In order to submit a new status for one of those objects, the API operation submitStatus must be used. \r\n\r\n### Status codes for the Transport Order\r\n\r\n| Status        | Description                                                                                                                       |\r\n|:--------------|:----------------------------------------------------------------------------------------------------------------------------------|\r\n| CREATED       | Initial status after creating the transport order                                                                                 |\r\n| DISPATCHING   | Waiting for a target company or an executing vehicle to be assigned                                                               |\r\n| ACKNOWLEDGING | A company was assigned to execute the transport order but it did not respond whether it will accept or reject the transport order |\r\n| ACCEPTED      | The assigned company has accepted the transport order                                                                             |\r\n| REJECTED      | The assigned company has rejected the transport order                                                                             |\r\n| EXECUTING     | The execution of the transport order has started.                                                                                 |\r\n| DONE          | The execution of the transport order is finished.                                                                                 |\r\n| CANCELED      | The transport order was canceled                                                                                                  |\r\n\r\n![Status changes of the transport order object](https://beta.app.logenios.com/apidocs/images/transport_order_status.png \"Status changes of the transport order object\")\r\n\r\n\r\n### Status Codes for the Stop Location\r\n\r\n| Status      | Description                                                                        |\r\n|:------------|:-----------------------------------------------------------------------------------|\r\n| PLANNED     | The stop location is planned                                                       |\r\n| APPROACHING | The truck who will fulfill the order has started to approach the stop location     |\r\n| ARRIVED     | The truck who will fulfill the order has arrived at the stop location              |\r\n| DEPARTED    | The truck who will fulfill the order has departed from the stop location           |\r\n| CANCELED    | The stop location was canceled and will not be approached by a truck               |\r\n\r\n\r\n![Status changes of the transport order object](https://beta.app.logenios.com/apidocs/images/location_status.png \"Status changes of the stop location object\")\r\n\r\n\r\n### Status Codes for the Stop Action\r\n\r\n| Status      | Description                                                             |\r\n|:------------|:------------------------------------------------------------------------|\r\n| PLANNED     | An action is planned to be executed at the parental stop location       |\r\n| IN_PROGRESS | The execution of the planned action has started but is not yet finished |\r\n| DONE        | The planned action is now executed                                      |\r\n| CANCELED    | The action was canceled and will not be executed                        |\r\n\r\n\r\n![Status changes of the transport order object](https://beta.app.logenios.com/apidocs/images/action_status.png \"Status changes of the stop action object\")\r\n\r\n\r\n### Status codes for the Freight\r\n\r\n| Status     | Description                              |\r\n|:-----------|:-----------------------------------------|\r\n| PLANNED    | The freight is planned to be transported |\r\n| LOADING    | Loading the freight has started          |\r\n| NOT_LOADED | The freight could not be loaded          |\r\n| LOADED     | The freight was loaded                   |\r\n| UNLOADING  | Unloading the freight has started        |\r\n| DELIVERED  | The freight was successfully delivered   |\r\n| REJECTED   | The freight was rejected by the receiver |\r\n\r\n\r\n![Status changes of the transport order object](https://beta.app.logenios.com/apidocs/images/freight_status.png \"Status changes of the freight object\")\r\n\r\n\r\n\r\n\r\n# Management of attachments\r\n\r\nAttachments are not directly stored in TransportOrder  objects. Instead, all Transport Order Elements (e.g. TransportOrder, Transport, StopLocation, StopAction or Freight) can point to file attachments. In order to add an attachment a two step process is required:\r\n1. A (currently empty) Attachment Object containing the file name must be added to an transport order element or directly specified on transport order creation.\r\n2. The xConvert API then returns an Upload URL which should be used to actually upload the attachment file content\r\n\r\n\r\n## Example: Specify attachments on createTransportOrder\r\n1) During creation of a new transport order, the attachment list can be populated with attachments which should be added to this transport order.\r\n```json\r\n{\r\n  \"_id\": \"5ba0b50bf9877c2ae47fc4ad\",\r\n   \"attachments\" : [\r\n        {\r\n            \"attachmentId\" : \"id1\",\r\n            \"name\" : \"test.pdf\"\r\n        },\r\n        {\r\n            \"attachmentId\" : \"id2\",\r\n            \"name\" : \"test.pdf\"\r\n        }\r\n    ]\r\n}\r\n```\r\n2) After creation of the TransportOrder you have to upload the attachments to Logenios. To upload the attachments you have to get an pre-signed upload url using the endpoint GET getAttachmentUploadUrl. The upload url is valid for 30 minutes.\r\n3) To actually upload an attachment, you could use curl with the following parameters:\r\n```sh\r\ncurl -v -T <file> <pre-signed upload URL from step 2>\r\n```\r\n4) After uploading the file you can access it using a 30 minutes valid download url generated by the operation getAttachmentDownloadUrl.\r\n\r\n## Adding attachments to an existing transport oder\r\nThe following steps are required if you want to add an additional attachment to an already existing transport order.\r\n\r\n1) First, you have to add the attachment using the operation addAttachment\r\n2) As an answer you receive a pre-signed upload url. This url has an expiry time of 30 minutes.\r\n3) Upload the file to the retrieved upload url.\r\n\r\n## Removing attachments\r\nYou can delete attachments using the operation deleteAttachment","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"4503630","team":195181,"collectionId":"0101f7de-699e-41bf-97e8-ff2abff43450","publishedId":"S11ByNFz","public":true,"publicUrl":"https://docs.logenios.com","privateUrl":"https://go.postman.co/documentation/4503630-0101f7de-699e-41bf-97e8-ff2abff43450","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","version":"8.10.0","publishDate":"2019-02-16T09:33:34.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"LIVE AMAZON","id":"60a40cd6-707a-4a49-992e-ff41ca4c2037","owner":"3889139","values":[{"key":"URL","value":"https://app.logenios.com","description":"","type":"text","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/46f59fe58779270ee2d93ecea8a5ef0a6af69237c8da4f4990c82616ed408ab2","favicon":"https://res.cloudinary.com/postman/image/upload/v1542356762/team/iswwej3vv5sn98pzipww.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"LIVE AMAZON","value":"3889139-60a40cd6-707a-4a49-992e-ff41ca4c2037"}],"canonicalUrl":"https://docs.logenios.com/view/metadata/S11ByNFz"}