# CargoSoft API

# About the CargoSoft API

## General

> Attention: Since our API is still under development, endpoints may well change, or object structures may change. Of course, we try to avoid this as much as possible, but we cannot guarantee it. So that you have the possibility to react in time, we will soon offer you a possibility to subscribe to a newsletter. We would then inform all subscribers when something will change in the API. We are currently still looking for an integrable solution for newsletters, which can be used to subscribe and unsubscribe at this place. Until then, we would like to ask you to send us an email to support@cargosoft.de with the request that we inform you when there are planned changes to the API.

## Changelog
This page documents all business-relevant changes to our API.

| Category       | Endpoint / Area            | Change                                                                                                 | Impact and required action                                       | Version |
|----------------|----------------------------|--------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|---|
| **Added**      | `POST` /cargosoft/shipment | Added new shipment create endpoint.                                                                    | No changes to existing integrations are required.                | 2026.1 |
| **Added**      | Use cases                  | Added new use case to create a shipment - [see](#section/use-cases/create-a-shipment)                          | No changes to existing integrations are required.                | 2026.1 |
| **Added**      | Basic data                 | Added new edi code conversion endpoints.                                                               | No changes to existing integrations are required.                | 2026.1 |
| **Added**      | E-File                     | Added new E-File endpoints.                                                                            | No changes to existing integrations are required.                | 2026.1 |
| **Deprecated** | ShipmentEventQualifier     | The shipment event qualifer `TRANSSHIPMENT` is now deprecated and will be removed in a future version. | Use the `TRANSSHIPMENT_ARRIVAL` shipment event qualifer instead. | 2026.1 |



### Category definitions

| Category | Meaning |
|---|---|
| **Breaking change** | A non-backward-compatible change that may require integration updates |
| **Added** | A new feature, endpoint, field, or supported value |
| **Changed** | A backward-compatible change to existing behavior |
| **Deprecated** | A feature is still available but will be removed in the future |
| **Removed** | A feature, endpoint, or field has been removed |
| **Fixed** | A bug fix without an intended breaking interface change |

## Authorization

<p id='CHAPTER_AUTHORIZATION'></p>
The following chapter will explain the authorization prozess to access the CargoSoft API endpoints. The use case figure below shows a common example how to retrieve the JWT and how to use it.

![Authorization][SeqAuthorization]

[SeqAuthorization]: ./resources/Seq_authentifizierung.svg "Use case Authorization!"

### Retrieve a token

First of all each client has to request a bearer Java Web Toke (JWT) from the CargoSoft API. To receive a JWT, username
and password are required. Username and password can only be created by CargoSoft.
For more details [see](#operation/retrieveAuthToken).

> Please note: The JWT is valid for 24 hours. After that you have to request a new one.

### Access API endpoints

To access the CargoSoft API endpoint, a JWT is required. The JWT has to be sent in the HTTP authorization header.

**Example**: This example shows a minimal curl with a bearer authorization header. The token is not valid because we
only want to illustrate the structure.

```
curl --location --request POST 'https://api-demo.cargosoft.de/cargosoft/shipment/lookup' \
--header 'Authorization: Bearer eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1cGRhdGUiLCJjYXJnb3NvZnQtand0LNjc2NDQ1NTAzfQ.mK82rjSu0ltd0bf3mvXUqwpME05ck5OEuqnzsAQ8WPFPo' \
--data-raw '[]'"
```

> Attention: Your user may be restricted. The CargoSoft API uses a permission system to grant access to the
> CargoSoft API endpoint. If your user is restricted or it's not allowed to use an endpoint you need please contact our
> support.

### Access webhook

The webhook uses basic auth as its authorization type.

**Example**: This example shows a minimal curl request, to access the webhook. The basic auth is not valid.

```
curl --location --request POST 'https://api-demo.cargosoft.de/external/webhook' \
--header 'Authorization: Basic cG9ydg53xcvgawawb3J0YmFzZWNj' \
--data-raw '{}'"
```

> Please note: Your user needs a special role to access the webhook endpoint via basic auth.

## CRUD

The CargoSoft API uses CRUD operations. We attempt to implement each CRUD operation for each functional
group of endpoints if it makes sense. The delete operation is one of the most sensitive function and will not
available to each function group.

### Lookup

The CargoSoft API extends the CRUD retrieve operations with lookup operations. Each functional group of endpoints should
have a lookup method implemented.
Lookups should be used to search functional objects with given criteria named identifiers. The identifiers may be
different to each functional group. To find out which functional identifier are possible, please take a look at the
corresponding functional group.

The identifier will be sent in the request body to the API lookup endpoint. An identifier contains the following
three information:

1. _match_mode_: The match mode can alter the behaviour, how the criteria is compared against the object in the database
   are **[EQUALS, CONTAINS, IN, OR, GT, LT, GE, LE]**.
2. _key_: The key of the criteria for the functional object to lookup. To find out which keys are possible, please check
   the
   corresponding implementation.
3. _value_: The value of the criteria.

**Example**: Lookup request body to search a shipment

```json
[
  {
    "match_mode": "EQUALS",
    "key": "MBL",
    "value": "MASTER_12345"
  },
  {
    "match_mode": "EQUALS",
    "key": "MODE_OF_TRANSPORT",
    "value": "SEA"
  }
]
```

> Please note: When using one of any lookup methods, please define search criteria as precisely as possible to limit the
> result of objects.

The lookup may contain ordering by one or more criteria. The ordering will passed as a query parameter.

The result set of a lookup includes zero up to n functional objects depending on the search criteria.
Each functional object contains an ID. The ID can be used to retrieve additional information by passing the id as a path
parameter of the retrieve endpoint.

**Example**: Lookup a shipment and retrieve all shipment events

1. Looking up a shipment with given criteria, for instance with the BL number. For more details
   please [see](#operation/lookup).
2. Extract the ID of the shipment result object.
3. Call the [Events](#operation/{id}/events) endpoint with the shipment ID as path parameter.

### Pagination

Most endpoints of the CargoSoft API use pagination mechanics.

The pagination information will be sent as a request query parameter to the API endpoint. The pagination contains the
following two query parameter:
1. _page_no_: The current number of the page
2. _page_size_: The size of the page

**Example**: Lookup a shipment with pagination query parameter
```
curl --location --request POST 'https://api-demo.cargosoft.de/cargosoft/shipment/lookup?page_no=1&page_size=5' \
--header 'Authorization: Bearer eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1cGRhdGUiLCJjYXJnb3NvZnQtand0LNjc2NDQ1NTAzfQ.mK82rjSu0ltd0bf3mvXUqwpME05ck5OEuqnzsAQ8WPFPo' \
--header 'Content-Type: application/json' \
--data '[
    {
        "match_mode": "EQUALS",
        "key": "MBL",   
        "value": "MASTER_12345"
    },
   {
        "match_mode": "EQUALS",
        "key": "MODE_OF_TRANSPORT",
        "value": "SEA"
    }
]'
```

The response contains two additional headers:
1. _X-Page-Count_: The total number of pages.
2. _X-Row-Count_: The total number of found objects.

With these both headers it is possible to scroll through a result set.

## Testing

For testing purposes CargoSoft hosted a server with the last released CargoSoft API.

**URL**: https://api-demo.cargosoft.de

To use the test environment, please use the "Try it" console in this documentation. Login credentials are needed to use
the test API. The credentials have to be requested from the CargoSoft support. The received information grants access to
a
test account which should be able to use all endpoints. If any endpoint is restricted, please contact CargoSoft. Please
have in mind that the test environment will be reset every night!

# Use cases

## Retrieve a shipment

To retrieve a shipment, the [lookup](#operation/lookup) endpoint of the shipment functional group is one of
the common possibilities that should be used. The following figure shows the use case to look up a shipment. To keep the
figure simple, the authorization process is referred.

![RetrieveShipment][SeqRetrieveShipment]

[SeqRetrieveShipment]: ./resources/Seq_retrieve_shipment.svg "Use case to retrieve a shipment"

1. To access the lookup endpoint a JWT is needed. For more details how to retrieve a JWT [see](#CHAPTER_AUTHORIZATION).
2. When a JWT is present, the shipment lookup endpoint can be called. Shipment identifier have to be sent in the request
   body to reduce the response result. For a complete list of shipment identifier
   see [here](#operation/lookup).

## Retrieve shipment status

CargoSoft has different pools in which status information are stored. These are described in detail in the next
subsections. However, in order to understand the differences
exactly, the following graphic tries to clarify how the status message flow works.

![ShipmentStatus][useCaseShipmentStatus]

[useCaseShipmentStatus]: ./resources/Use_case_shipment_status.svg "Use case to retrieve shipment events"

### Shipment provider status

These status messages come from external status providers and service providers who supply CargoSoft with status
information.
They cannot be entered or changed by CargoSoft employees by hand. A shipment provider status always represents exactly
one state - planned / estimated or the actual date and time (depending on the name of the status). The codes of the
statuses are defined by the providers and are variable depending on the provider.

> Please note: There is no endpoint to retrieve provider status from the CargoSoft API yet. This endpoint will be
> implemented in a later release.

### Shipment status

CargoSoft customers can define this status code themselves. In addition, the shipment provider statuses can be mapped
into a shipment status if the CargoSoft customer configured his basic data accordingly. Here, for example, it can be
defined that the status
ABC of provider XYZ has to be processed as shipment status ETA. In this case ETA would be a freely defined code for the
status. Therefore, there is no list of valid codes.

With this status, there are also two forms of date information per data record. Once a planned and an actual one. This
means that a status ETA, although obviously planned, can contain an actual date. However, this is due to the recording
of the customer's data.

The CargoSoft customer can add this status information manually, but an existing record can no longer be changed.

> Please note: There is no endpoint to retrieve CargoSoft status from the CargoSoft API yet. This endpoint will be
> implemented in a later release.

### Shipment events

Shipment events are status events that are defined by CargoSoft. These events are fixed and can always be called up -
unless there is no data available for the shipment. For a complete list of shipment event codes
see [here](#operation/retrieveEvents).
A shipment event can be created automatically from a shipment or provider status if this is set in the CargoSoft master
data. A status always represents exactly one instance - planned or actual and the information can be changed at any time
by hand, but also by background processes.

![RetrieveShipmentEvents][SeqRetrieveShipmentEvents]

[SeqRetrieveShipmentEvents]: ./resources/Seq_retrieve_shipment_event.svg "Use case to retrieve shipment events"

## Create a shipment

<p id='CHAPTER_SHIPMENT'></p>

To create a new shipment, the [create](#operation/createShipment) endpoint of the shipment functional group has to be
used. The following figure shows the use case to create a shipment. To keep the figure simple, the authorization process is referred.

![CreateShipment][SeqCreateShipment]

[SeqCreateShipment]: ./resources/Seq_create_shipment.svg "Use case to create a shipment"

1. To access the create endpoint a JWT is needed. For more details how to retrieve a JWT [see](#CHAPTER_AUTHORIZATION).
2. Based on the authenticated API user, the CargoSoft API determines the EDI partner to associate with the new
   shipment: the EDI partner's matchcode has to be identical to the API username. If no EDI partner exists for
   the API user, the request is rejected and no shipment is created.
3. The determined EDI partner's settings are used, where configured, to fill in values that are otherwise
   required to generate the shipment number - see [EDI-Partner](#CHAPTER_EDIPARTNER_SETTINGS)
   below for the exact keys and their fallback rules.
4. The shipment is created together with any nested data supplied in the same request body - goods, containers,
   addon field values, order memo lines, and so on. A memo text longer than the maximum line length is
   automatically wrapped across several consecutive memo lines - see the [lookup](#operation/lookup) endpoint
   of the shipment memo functional group to retrieve them independently afterwards. If any of that nested data
   fails validation (for example an addon field value referencing a matchcode that doesn't exist in the master
   data), the whole shipment creation is rejected and nothing is created.
5. Once the shipment has been created, the shipment is returned as response to the request. 
   The shipment response contains the unique shipment ID and the CargoSoft shipment number. 


### EDI-Partner settings

<p id='CHAPTER_EDIPARTNER_SETTINGS'></p>
Generating a shipment number requires three pieces of information: the shipment number definition (posdef),
the main department, and the sub department. Each of them can be configured individually as a setting on the
EDI partner determined for the request (see step 2 above). A setting configured on the EDI partner always
takes precedence; an empty or blank setting value is treated the same as if the setting wasn't configured at
all. Each of the three keys is resolved independently of the other two - a missing/invalid value for one key
never prevents the fallback for a different key from being used. Any other, unrelated qualifier configured on
the EDI partner is ignored.

| Key                            | Meaning                                     | Fallback if not configured (or blank) on the EDI partner                                                                    |
|----------------------------------|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `SHIPMENT_NUMBER_DEFINITION_VERSION`    | The shipment number definition version to use (`posdef_t.version`). | The `shipment_number_definition_version` supplied in the request body, if present; otherwise the CargoSoft client's own default (`firma_t.posnr_version`). |
| `MAINDEPARTMENT`                | The main department to use for shipment numbering. | The `maindepartment` supplied in the request body. If neither is present, the request is rejected. |
| `SUBDEPARTMENT`                 | The sub department to use for shipment numbering. | The `subdepartment` supplied in the request body. If neither is present, the request is rejected. |

> Please note: if a request doesn't need to rely on the EDI partner's settings at all - for example while
> testing - `shipment_number_definition_version`, `maindepartment` and `subdepartment` can simply be supplied
> directly in the request body instead.

## EDI code conversion

An EDI code conversion translates an EDI partner's own code (for example for a charge type or packaging code)
into the corresponding CargoSoft internal code, or vice versa, depending on direction. They are looked up with
the [lookup](#operation/lookup) endpoint of the code conversion functional group, using a combination of the
`EDIPARTNER`, `DIRECTION`, `CODETYPE` and `SOURCECODE` identifiers.

Two identifier combinations are served from a cache instead of querying the database on every request, since
this master data changes very rarely:

- `EDIPARTNER` + `DIRECTION` + `CODETYPE`: returns every code conversion configured for that EDI partner's
  table/direction.
- `EDIPARTNER` + `DIRECTION` + `CODETYPE` + `SOURCECODE`: returns the one specific conversion for that source
  code.

Omitting `EDIPARTNER` from a `DIRECTION` + `CODETYPE` + `SOURCECODE` lookup returns every matching conversion
across all EDI partners that happen to share the same source code - also served from the cache. Any other
identifier combination is looked up directly against the database.

> Please note: the `DIRECTION` identifier's value must be the raw single-character code as stored in the
> CargoSoft TMS (`E` or `S`), not the `direction` value (`RECEIVE`/`SEND`) shown on the response object.

Version: 2026.1

## Servers

Test CargoSoft API server.
```
https://api-demo.cargosoft.de
```

## Security

### JavaWebToken




Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

 - [CargoSoft API](https://api-cargosoft.redocly.app/_bundle/@2026.1/openapi.yaml)

## Basic data

 - [POST /cargosoft/basicdata/codeconverter/lookup](https://api-cargosoft.redocly.app/2026.1/openapi/basic-data/lookup.md): Looks up EDI code conversions (edicodes_t) by EDI partner, direction, code table/type and/or source code. The DIRECTION identifier value must be the raw single-character edicodes_t.richtung code ("E"
 - [GET /cargosoft/basicdata/codeconverter](https://api-cargosoft.redocly.app/2026.1/openapi/basic-data/retrieveall.md): Scroll through all existing EDI code conversion records.
 - [GET /cargosoft/basicdata/codeconverter/{id}](https://api-cargosoft.redocly.app/2026.1/openapi/basic-data/retrievebyid.md): Retrieve a specific EDI code conversion record with the CargoSoft database id.
## Shipment

 - [POST /cargosoft/shipment](https://api-cargosoft.redocly.app/2026.1/openapi/shipment/createshipment.md): Create a new shipment.
 - [POST /cargosoft/shipment/lookup](https://api-cargosoft.redocly.app/2026.1/openapi/shipment/lookup_2.md): This endpoint looks up shipments. The result should be limit by using search criterias in the request body. For a complete list of search criteria see the ShipmentIdentifier enumeration below. Dependi
 - [GET /cargosoft/shipment/{id}/airmaincarriage](https://api-cargosoft.redocly.app/2026.1/openapi/shipment/retrieveairmaincarriage.md): Retrieve the airfreight main carriage of the shipment with additional details. The CargoSoft Shipment ID is needed to retrieve the main carriage.
 - [GET /cargosoft/shipment/{id}](https://api-cargosoft.redocly.app/2026.1/openapi/shipment/retrievebyid_2.md): Retrieve a specific shipment with the CargoSoft database id.
 - [GET /cargosoft/shipment/{id}/events](https://api-cargosoft.redocly.app/2026.1/openapi/shipment/retrieveevents.md): This endpoint retrieves all events of the shipment. To retrieve the events, the shipment id is needed. It is possible that not all events are included in the response because they are not entered or k
 - [GET /cargosoft/shipment/{id}/seamaincarriage](https://api-cargosoft.redocly.app/2026.1/openapi/shipment/retrieveseamaincarriage.md): Retrieve the main carriage of the shipment with additional details.
 - [POST /cargosoft/shipment/{shipmentId}/event](https://api-cargosoft.redocly.app/2026.1/openapi/shipment/create_1.md): Create a shipment event of the given event type.
 - [PUT /cargosoft/shipment/{shipmentId}/event/{id}](https://api-cargosoft.redocly.app/2026.1/openapi/shipment/update.md): Update the event of the given event type.
## ShipmentMemo

 - [POST /cargosoft/shipment/memo/lookup](https://api-cargosoft.redocly.app/2026.1/openapi/shipmentmemo/lookup_3.md): Looks up order memo lines (eamemo_t) attached to a shipment, typically by client and shipment_number together (the shipment they were created for).
 - [GET /cargosoft/shipment/memo](https://api-cargosoft.redocly.app/2026.1/openapi/shipmentmemo/retrieveall_1.md): Scroll through all existing shipment memo line records.
 - [GET /cargosoft/shipment/memo/{id}](https://api-cargosoft.redocly.app/2026.1/openapi/shipmentmemo/retrievebyid_3.md): Retrieve a specific shipment memo line record with the CargoSoft database id.
## E-File

 - [POST /cargosoft/efile](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/create.md): Stores a base64 encoded document in E-File and links it to the supplied references and roles.
 - [GET /cargosoft/efile/{id}/reference](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/retrievereferencesfromdocument.md): Retrieves all references linked to an E-File document.
 - [POST /cargosoft/efile/{id}/reference](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/createreferencefordocument.md): Adds a reference, such as a shipment or address reference, to an existing E-File document.
 - [DELETE /cargosoft/efile/{id}/reference](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/deletereferencefromdocument.md): Removes a reference from an existing E-File document.
 - [GET /cargosoft/efile/{id}/role](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/retrieverolesfromdocument.md): Retrieves all authorization roles linked to an E-File document.
 - [POST /cargosoft/efile/{id}/role](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/createrolefordocument.md): Adds an authorization role to an existing E-File document.
 - [DELETE /cargosoft/efile/{id}/role](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/deleterolefromdocument.md): Removes an authorization role from an existing E-File document.
 - [GET /cargosoft/efile/{id}](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/retrievebyid_1.md): Retrieves a single E-File document by its document ID.
 - [DELETE /cargosoft/efile/{id}](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/delete.md): Deletes an E-File document by its document ID.
 - [POST /cargosoft/efile/lookup](https://api-cargosoft.redocly.app/2026.1/openapi/e-file/lookup_1.md): Looks up electronic documents such as PDF files by the supplied lookup identifiers.
## Authorization

 - [POST /auth/token](https://api-cargosoft.redocly.app/2026.1/openapi/authorization/retrieveauthtoken.md): Retrieve a Java Web Token to authenticate against the API