Download OpenAPI specification:Download
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.
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.
Please note: The JWT is valid for 24 hours. After that you have to request a new one.
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.
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.
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.
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:
Example: Lookup request body to search a shipment
[
{
"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
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:
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:
With these both headers it is possible to scroll through a result set.
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!
To retrieve a shipment, the 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.
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.
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.
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 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. 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.
Scroll through all existing records.
Records retrieved
No record found
Internal server error
[- {
- "id": 0,
- "row": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "sequential_number": 0,
- "shipment_number": "string",
- "client": "string",
- "billing_code": "string",
- "amount": 0,
- "tax_code": "string",
- "currency": "string",
- "activity_type": "string",
- "posting_text": "string",
- "vessel_exchange_rate": 0,
- "vessel_currency": "string",
- "vessel_inverse_rate": true
}
]
Create a new record
Model of the record you want to create
Record created
Internal server error
{- "id": 0,
- "row": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "sequential_number": 0,
- "shipment_number": "string",
- "client": "string",
- "billing_code": "string",
- "amount": 0,
- "tax_code": "string",
- "currency": "string",
- "activity_type": "string",
- "posting_text": "string",
- "vessel_exchange_rate": 0,
- "vessel_currency": "string",
- "vessel_inverse_rate": true
}
{- "error_code": {
- "errorMessage": "string"
}, - "error_message": "string",
- "error_source": "string"
}
Find a existing record by given identifiers
page_no | integer <int32> Default: 0 The page number for pagination. | ||||||
page_size | integer <int32> Default: 50 The page size for pagination. | ||||||
order_by | Array of strings The order by for ordering API results sending back as response. | ||||||
order_mode | Array of strings The order mode for ordering API results sending back as response.
|
key | string (ShipmentIdentifier) Identifier key. For instance a ShipmentIdentifier
| ||||||||||||||||||||||||||||||||
match_mode | string Default: "EQUALS" The match mode.
| ||||||||||||||||||||||||||||||||
value | string The value of the identifier. |
Records retrieved
No records found
Internal server error
[- {
- "key": "CLIENT",
- "match_mode": "EQUALS"
}
]
[- {
- "id": 0,
- "row": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "sequential_number": 0,
- "shipment_number": "string",
- "client": "string",
- "billing_code": "string",
- "amount": 0,
- "tax_code": "string",
- "currency": "string",
- "activity_type": "string",
- "posting_text": "string",
- "vessel_exchange_rate": 0,
- "vessel_currency": "string",
- "vessel_inverse_rate": true
}
]
Find a existing record by it's database id
Record retrieved
No record found
Internal server error
{- "error_code": {
- "errorMessage": "string"
}, - "error_message": "string",
- "error_source": "string"
}
Create a new record
Model of the record you want to create
id | integer <int32> The technical id of the Invoice | ||||||||||
client required | string The CargoSoft client | ||||||||||
office | string The CargoSoft office | ||||||||||
corporation | string The CargoSoft corporation | ||||||||||
language | string The language of the invoice | ||||||||||
barcode | string The barcode of the invoice | ||||||||||
currency required | string The currency of the invoice, represented in ISO codes | ||||||||||
amount | number The net amount of the invoice. | ||||||||||
shipment_number | string The shipment number for the CargoSoft shipment. Do not fill in the shipment number when importing incoming invoices. | ||||||||||
invoice_type | string The invoice type within CargoSoft for an invoice. The following types are permitted:
| ||||||||||
invoice_number | integer <int64> The CargoSoft invoice number can be generated via a number range during import. | ||||||||||
invoice_date | string <date> The invoice date | ||||||||||
accounting_period | integer <int32> The accounting periode in format YYYYMM | ||||||||||
object (PrintedMatchcodeAddress) The invoice address with the CargoSoft address number | |||||||||||
invoice_reference | string The invoice reference of the invoicing party. | ||||||||||
exchange_rate | number The exchange rate of the invoice | ||||||||||
processed_flag | string A flag to determine whether the 'Batchfaktura' background process should process the invoice. This technical flag should not be filled in. | ||||||||||
tax_amount | number The total tax amount of an invoice in the currency of the invoice. | ||||||||||
gross_amount | number The gross amount of an invoice in the invoice's currency. | ||||||||||
created_date_time | string <date-time> The creation date of the invoice | ||||||||||
sequential_number | integer <int32> A sequential number for an invoice. This is a technical number and should not be filled in. | ||||||||||
employee_login | string The CargoSoft login name of the user who records the invoice. | ||||||||||
collective_invoice | boolean A flag to determine if an invoice is a collective invoice. All invoices are collective invoices ('true'). | ||||||||||
posting_text | string The posting text of the invoice | ||||||||||
booked | boolean A flag to determine if an invoice is booked. All invoices are not booked ('false'). | ||||||||||
cancelled_invoice | boolean A flag to determine if an invoice is a cancellation. For invoice types LR/LG, it's 'false'; for types SE/SL, it's 'true'. | ||||||||||
cancelled_invoice_number | integer <int64> The CargoSoft invoice number of an invoice that needs to be cancelled - the original CargoSoft invoice number. | ||||||||||
corrected_invoice | boolean A flag to determine if an invoice is corrected. | ||||||||||
corrected_invoice_number | number The CargoSoft invoice number of an invoice that needs to be corrected - the original CargoSoft invoice number. | ||||||||||
allocation | string The allocation of an invoice: 'AUFW' for costs, 'ERL' for revenue. | ||||||||||
paid | boolean A flag to determine if an invoice has already been paid. | ||||||||||
payment_condition | string The CargoSoft payment code of an invoice. | ||||||||||
due_date_time | string <date-time> The due date of the invoice. | ||||||||||
service_date | string <date-time> The service date of the invoice | ||||||||||
cancelled_invoice_reference | string The invoice reference from the invoicing party that needs to be cancelled. | ||||||||||
Array of objects (InvoiceLine) The associated invoice lines. |
Record created
Internal server error
{- "id": 0,
- "client": "string",
- "office": "string",
- "corporation": "string",
- "language": "string",
- "barcode": "string",
- "currency": "string",
- "amount": 0,
- "shipment_number": "string",
- "invoice_type": "R",
- "invoice_number": 0,
- "invoice_date": "2019-08-24",
- "accounting_period": 0,
- "invoice_address": {
- "address_type": "string",
- "address_number": 0,
- "printed_address": {
- "line_1": "string",
- "line_2": "string",
- "line_3": "string",
- "line_4": "string",
- "line_5": "string"
}
}, - "invoice_reference": "string",
- "exchange_rate": 0,
- "processed_flag": "string",
- "tax_amount": 0,
- "gross_amount": 0,
- "created_date_time": "2019-08-24T14:15:22Z",
- "sequential_number": 0,
- "employee_login": "string",
- "collective_invoice": true,
- "posting_text": "string",
- "booked": true,
- "cancelled_invoice": true,
- "cancelled_invoice_number": 0,
- "corrected_invoice": true,
- "corrected_invoice_number": 0,
- "allocation": "string",
- "paid": true,
- "payment_condition": "string",
- "due_date_time": "2019-08-24T14:15:22Z",
- "service_date": "2019-08-24T14:15:22Z",
- "cancelled_invoice_reference": "string",
- "invoice_lines": [
- {
- "id": 0,
- "row": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "sequential_number": 0,
- "shipment_number": "string",
- "client": "string",
- "billing_code": "string",
- "amount": 0,
- "tax_code": "string",
- "currency": "string",
- "activity_type": "string",
- "posting_text": "string",
- "vessel_exchange_rate": 0,
- "vessel_currency": "string",
- "vessel_inverse_rate": true
}
]
}
{- "id": 0,
- "client": "string",
- "office": "string",
- "corporation": "string",
- "language": "string",
- "barcode": "string",
- "currency": "string",
- "amount": 0,
- "shipment_number": "string",
- "invoice_type": "R",
- "invoice_number": 0,
- "invoice_date": "2019-08-24",
- "accounting_period": 0,
- "invoice_address": {
- "address_type": "string",
- "address_number": 0,
- "printed_address": {
- "line_1": "string",
- "line_2": "string",
- "line_3": "string",
- "line_4": "string",
- "line_5": "string"
}
}, - "invoice_reference": "string",
- "exchange_rate": 0,
- "processed_flag": "string",
- "tax_amount": 0,
- "gross_amount": 0,
- "created_date_time": "2019-08-24T14:15:22Z",
- "sequential_number": 0,
- "employee_login": "string",
- "collective_invoice": true,
- "posting_text": "string",
- "booked": true,
- "cancelled_invoice": true,
- "cancelled_invoice_number": 0,
- "corrected_invoice": true,
- "corrected_invoice_number": 0,
- "allocation": "string",
- "paid": true,
- "payment_condition": "string",
- "due_date_time": "2019-08-24T14:15:22Z",
- "service_date": "2019-08-24T14:15:22Z",
- "cancelled_invoice_reference": "string",
- "invoice_lines": [
- {
- "id": 0,
- "row": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "sequential_number": 0,
- "shipment_number": "string",
- "client": "string",
- "billing_code": "string",
- "amount": 0,
- "tax_code": "string",
- "currency": "string",
- "activity_type": "string",
- "posting_text": "string",
- "vessel_exchange_rate": 0,
- "vessel_currency": "string",
- "vessel_inverse_rate": true
}
]
}
Scroll through all existing records.
Records retrieved
No record found
Internal server error
[- {
- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
]
Create a new record
Model of the record you want to create
id | integer <int32> | ||||||||||
client | string The CargoSoft client | ||||||||||
shipment_number | string The CargoSoft shipment number | ||||||||||
fk_voucher_id | integer <int32> ID of the voucher | ||||||||||
impersonal_account | string The ledger account of the booking line. | ||||||||||
amount_local | number The net amount of the booking line in home currency. | ||||||||||
tax_code | string The tax code of the booking line. | ||||||||||
amount_foreign | number The net amount of the booking line in foreign currency. | ||||||||||
posting_text | string The posting text of the booking line. | ||||||||||
cost_center | string The cost center of the booking line | ||||||||||
differing_accounting_period | string Booking period per booking line - generated by the activity month of the Cargosoft shipment number. | ||||||||||
tax_amount_local | number The tax amount of the booking line in home currency. | ||||||||||
tax_amount_foreign | number The tax amount of the booking line in foreign currency. | ||||||||||
invoice_number | integer <int64> The CargoSoft voucher number | ||||||||||
invoice_type | string The invoice type within CargoSoft for an invoice. The following types are permitted:
| ||||||||||
activity_type | string The Cargosoft activity type of the booking line. | ||||||||||
cost_unit | string not available | ||||||||||
billing_code | string The Cargosoft billing code of the booking line. |
Successful
Internal server error
{- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
{- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
Find a existing record by given identifiers
page_no | integer <int32> Default: 0 The page number for pagination. | ||||||
page_size | integer <int32> Default: 50 The page size for pagination. | ||||||
order_by | Array of strings The order by for ordering API results sending back as response. | ||||||
order_mode | Array of strings The order mode for ordering API results sending back as response.
|
key | string (ShipmentIdentifier) Identifier key. For instance a ShipmentIdentifier
| ||||||||||||||||||||||||||||||||
match_mode | string Default: "EQUALS" The match mode.
| ||||||||||||||||||||||||||||||||
value | string The value of the identifier. |
Records retrieved
No records found
Internal server error
[- {
- "key": "CLIENT",
- "match_mode": "EQUALS"
}
]
[- {
- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
]
Find a existing record by it's database id
Record retrieved
No record found
Internal server error
{- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
Scroll through all existing records.
Records retrieved
No record found
Internal server error
[- {
- "id": 0,
- "client": "string",
- "currency": "string",
- "office": "string",
- "shipment_number": "string",
- "invoice_number": 0,
- "invoice_type": "R",
- "journal_number": 0,
- "accounting_period": "string",
- "invoice_address": {
- "address_type": "string",
- "address_number": 0
}, - "gross_amount_local": 0,
- "tax_amount_local": 0,
- "gross_amount_foreign": 0,
- "tax_amount_foreign": 0,
- "exchange_rate": 0,
- "posting_text": "string",
- "term_of_payment": "string",
- "due_date": "2019-08-24",
- "invoice_date": "2019-08-24",
- "invoice_reference": "string",
- "transfer_date": "2019-08-24T14:15:22Z",
- "employee_login": "string",
- "cancelled_invoice_number": 0,
- "allocation": "string",
- "corrected_invoice": true,
- "corrected_invoice_number": true,
- "barcode": "string",
- "sequential_number": 0,
- "voucher_lines": [
- {
- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
]
}
]
Create a new record
Model of the record you want to create
id | integer <int32> | ||||||||||
client | string The CargoSoft client | ||||||||||
currency | string The currency of the voucher represented in ISO codes | ||||||||||
office | string The office | ||||||||||
shipment_number | string The shipment number of the shipment. This number may unique in combination of the client property. | ||||||||||
invoice_number | integer <int64> The CargoSoft invoice number generated by number ranges. | ||||||||||
invoice_type | string The invoice type within CargoSoft for an invoice. The following types are permitted:
| ||||||||||
journal_number | integer <int32> The journal number is a consecutive number and marks all vouchers they have got exported. The number is generated via CargoSoft number range | ||||||||||
accounting_period | string The accounting periode in format YYYYMM | ||||||||||
object (AddressMatchcode) The invoice address (biller or invoice recipient) with the CargoSoft address number | |||||||||||
gross_amount_local | number The gross amount of a voucher in home currency. | ||||||||||
tax_amount_local | number The total tax amount of a voucher in home currency. | ||||||||||
gross_amount_foreign | number The gross amount of a voucher in foreign currency. | ||||||||||
tax_amount_foreign | number The total tax amount of a voucher in foreign currency. | ||||||||||
exchange_rate | number The exchange rate of the voucher | ||||||||||
posting_text | string The posting text of the voucher | ||||||||||
term_of_payment | string The CargoSoft payment code of the voucher. | ||||||||||
due_date | string <date> The due date of the voucher. | ||||||||||
invoice_date | string <date> The voucher date | ||||||||||
invoice_reference | string The voucher reference of the biller. | ||||||||||
transfer_date | string <date-time> The date of exporting the voucher | ||||||||||
employee_login | string The CargoSoft login name of the user who recorded the voucher. | ||||||||||
cancelled_invoice_number | number The CargoSoft number of the voucher which has been cancelled - the original CargoSoft invoice number. | ||||||||||
allocation | string The allocation of an invoice: 'AUFW' for costs, 'ERL' for revenue. | ||||||||||
corrected_invoice | boolean A flag to determine if an invoice is corrected. | ||||||||||
corrected_invoice_number | boolean The CargoSoft number of the voucher which has been corrected - the original CargoSoft invoice number. | ||||||||||
barcode | string The barcode of the voucher. | ||||||||||
sequential_number | integer <int32> Internal counter. | ||||||||||
Array of objects (VoucherLine) |
Record created
Internal server error
{- "id": 0,
- "client": "string",
- "currency": "string",
- "office": "string",
- "shipment_number": "string",
- "invoice_number": 0,
- "invoice_type": "R",
- "journal_number": 0,
- "accounting_period": "string",
- "invoice_address": {
- "address_type": "string",
- "address_number": 0
}, - "gross_amount_local": 0,
- "tax_amount_local": 0,
- "gross_amount_foreign": 0,
- "tax_amount_foreign": 0,
- "exchange_rate": 0,
- "posting_text": "string",
- "term_of_payment": "string",
- "due_date": "2019-08-24",
- "invoice_date": "2019-08-24",
- "invoice_reference": "string",
- "transfer_date": "2019-08-24T14:15:22Z",
- "employee_login": "string",
- "cancelled_invoice_number": 0,
- "allocation": "string",
- "corrected_invoice": true,
- "corrected_invoice_number": true,
- "barcode": "string",
- "sequential_number": 0,
- "voucher_lines": [
- {
- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
]
}
{- "id": 0,
- "client": "string",
- "currency": "string",
- "office": "string",
- "shipment_number": "string",
- "invoice_number": 0,
- "invoice_type": "R",
- "journal_number": 0,
- "accounting_period": "string",
- "invoice_address": {
- "address_type": "string",
- "address_number": 0
}, - "gross_amount_local": 0,
- "tax_amount_local": 0,
- "gross_amount_foreign": 0,
- "tax_amount_foreign": 0,
- "exchange_rate": 0,
- "posting_text": "string",
- "term_of_payment": "string",
- "due_date": "2019-08-24",
- "invoice_date": "2019-08-24",
- "invoice_reference": "string",
- "transfer_date": "2019-08-24T14:15:22Z",
- "employee_login": "string",
- "cancelled_invoice_number": 0,
- "allocation": "string",
- "corrected_invoice": true,
- "corrected_invoice_number": true,
- "barcode": "string",
- "sequential_number": 0,
- "voucher_lines": [
- {
- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
]
}
Find existing records by given identifiers
page_no | integer <int32> Default: 0 The page number for pagination. | ||||||
page_size | integer <int32> Default: 50 The page size for pagination. | ||||||
order_by | Array of strings The order by for ordering API results sending back as response. | ||||||
order_mode | Array of strings The order mode for ordering API results sending back as response.
|
key | string (ShipmentIdentifier) Identifier key. For instance a ShipmentIdentifier
| ||||||||||||||||||||||||||||||||
match_mode | string Default: "EQUALS" The match mode.
| ||||||||||||||||||||||||||||||||
value | string The value of the identifier. |
Records retrieved
No records found
Internal server error
[- {
- "key": "CLIENT",
- "match_mode": "EQUALS"
}
]
[- {
- "id": 0,
- "client": "string",
- "currency": "string",
- "office": "string",
- "shipment_number": "string",
- "invoice_number": 0,
- "invoice_type": "R",
- "journal_number": 0,
- "accounting_period": "string",
- "invoice_address": {
- "address_type": "string",
- "address_number": 0
}, - "gross_amount_local": 0,
- "tax_amount_local": 0,
- "gross_amount_foreign": 0,
- "tax_amount_foreign": 0,
- "exchange_rate": 0,
- "posting_text": "string",
- "term_of_payment": "string",
- "due_date": "2019-08-24",
- "invoice_date": "2019-08-24",
- "invoice_reference": "string",
- "transfer_date": "2019-08-24T14:15:22Z",
- "employee_login": "string",
- "cancelled_invoice_number": 0,
- "allocation": "string",
- "corrected_invoice": true,
- "corrected_invoice_number": true,
- "barcode": "string",
- "sequential_number": 0,
- "voucher_lines": [
- {
- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
]
}
]
Find a existing record by it's database id
Successful
No record found
Internal server error
{- "id": 0,
- "client": "string",
- "currency": "string",
- "office": "string",
- "shipment_number": "string",
- "invoice_number": 0,
- "invoice_type": "R",
- "journal_number": 0,
- "accounting_period": "string",
- "invoice_address": {
- "address_type": "string",
- "address_number": 0
}, - "gross_amount_local": 0,
- "tax_amount_local": 0,
- "gross_amount_foreign": 0,
- "tax_amount_foreign": 0,
- "exchange_rate": 0,
- "posting_text": "string",
- "term_of_payment": "string",
- "due_date": "2019-08-24",
- "invoice_date": "2019-08-24",
- "invoice_reference": "string",
- "transfer_date": "2019-08-24T14:15:22Z",
- "employee_login": "string",
- "cancelled_invoice_number": 0,
- "allocation": "string",
- "corrected_invoice": true,
- "corrected_invoice_number": true,
- "barcode": "string",
- "sequential_number": 0,
- "voucher_lines": [
- {
- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
]
}
Scroll through all existing records.
Records retrieved
No record found
Internal server error
[- {
- "id": 0,
- "client": "string",
- "currency": "string",
- "office": "string",
- "shipment_number": "string",
- "invoice_number": 0,
- "invoice_type": "R",
- "journal_number": 0,
- "accounting_period": "string",
- "invoice_address": {
- "address_type": "string",
- "address_number": 0
}, - "gross_amount_local": 0,
- "tax_amount_local": 0,
- "gross_amount_foreign": 0,
- "tax_amount_foreign": 0,
- "exchange_rate": 0,
- "posting_text": "string",
- "term_of_payment": "string",
- "due_date": "2019-08-24",
- "invoice_date": "2019-08-24",
- "invoice_reference": "string",
- "transfer_date": "2019-08-24T14:15:22Z",
- "employee_login": "string",
- "cancelled_invoice_number": 0,
- "allocation": "string",
- "corrected_invoice": true,
- "corrected_invoice_number": true,
- "barcode": "string",
- "sequential_number": 0,
- "voucher_lines": [
- {
- "id": 0,
- "client": "string",
- "shipment_number": "string",
- "fk_voucher_id": 0,
- "impersonal_account": "string",
- "amount_local": 0,
- "tax_code": "string",
- "amount_foreign": 0,
- "posting_text": "string",
- "cost_center": "string",
- "differing_accounting_period": "string",
- "tax_amount_local": 0,
- "tax_amount_foreign": 0,
- "invoice_number": 0,
- "invoice_type": "R",
- "activity_type": "string",
- "cost_unit": "string",
- "billing_code": "string"
}
]
}
]
The following chapter will give you an overview about the shipment endpoints and their function.
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. Depending on the search criteria you will receive zero up to n shipments.
page_no | integer <int32> Default: 0 The page number for pagination. | ||||||||||||||||||||||||||||||||
page_size | integer <int32> Default: 50 The page size for pagination. | ||||||||||||||||||||||||||||||||
order_by | Array of strings (ShipmentIdentifier) The order by for ordering API results sending back as response.
| ||||||||||||||||||||||||||||||||
order_mode | Array of strings The order mode for ordering API results sending back as response.
|
The equals identifier should use to match the value exactly.
key | string (ShipmentIdentifier) Identifier key. For instance a ShipmentIdentifier
| ||||||||||||||||||||||||||||||||
match_mode | string Default: "EQUALS" The match mode.
| ||||||||||||||||||||||||||||||||
value | string The value of the identifier. |
Records found
TBD
[- {
- "match_mode": "EQUALS",
- "key": "CLIENT",
- "value": "001"
}, - {
- "match_mode": "EQUALS",
- "key": "MBL",
- "value": "MASTER_12345"
}, - {
- "match_mode": "EQUALS",
- "key": "DIRECTION",
- "value": "E"
}, - {
- "match_mode": "EQUALS",
- "key": "MODE_OF_TRANSPORT",
- "value": "SEA"
}
]
TBD
{- "id": 6843241,
- "client": "001",
- "direction": "E",
- "department": "BRE",
- "numberOfGoods": 5,
- "shipment_number": "BRE-001-12012023-876",
- "master_reference": "MASTER_12345",
- "house_reference": "HOUSE_0988976",
- "bl_type": "HBL",
- "mode_of_transport": "SEA",
- "month_of_service": "202301"
}
Retrieve the airfreight main carriage of the shipment with additional details. The CargoSoft Shipment ID is needed to retrieve the main carriage.
Record retrieved
Internal server error
This example contains 2 legs for an export airfright shipment.
[- {
- "origin": {
- "location": {
- "codes": [
- {
- "type": "IATA",
- "code": "BRE"
}
], - "name": "Bremen",
- "latitude": null,
- "longitude": null
}, - "estimated_datetime": {
- "date": "2023-11-17",
- "time": "13:00:00",
- "zone_offset": "+01:00"
}, - "actual_datetime": {
- "date": "2023-11-17",
- "time": "13:30:00",
- "zone_offset": "+01:00"
}
}, - "destination": {
- "location": {
- "codes": [
- {
- "type": "IATA",
- "code": "FRA"
}
], - "name": null,
- "latitude": null,
- "longitude": null
}, - "estimated_datetime": {
- "date": "2023-11-18",
- "time": "05:00:00",
- "zone_offset": "+01:00"
}, - "actual_datetime": {
- "date": "2023-11-18",
- "time": "05:15:00",
- "zone_offset": "+01:00"
}
}, - "leg_no": 1,
- "flight_no": "985472",
- "airline_awb_code": "438577456345",
- "airline_name": "AC"
}, - {
- "origin": {
- "location": {
- "codes": [
- {
- "type": "IATA",
- "code": "FRA"
}
], - "name": null,
- "latitude": null,
- "longitude": null
}, - "estimated_datetime": {
- "date": "2023-11-22",
- "time": "18:00:00",
- "zone_offset": "+01:00"
}, - "actual_datetime": {
- "date": "2023-11-18",
- "time": "18:45:00",
- "zone_offset": "+01:00"
}
}, - "destination": {
- "location": {
- "codes": [
- {
- "type": "IATA",
- "code": "NYC"
}
], - "name": null,
- "latitude": null,
- "longitude": null
}, - "estimated_datetime": {
- "date": "2023-11-19",
- "time": null,
- "zone_offset": null
}, - "actual_datetime": {
- "date": "2023-11-19",
- "time": null,
- "zone_offset": null
}
}, - "leg_no": 2,
- "flight_no": "837265437",
- "airline_awb_code": "438577456345",
- "airline_name": "AC"
}
]
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 know in the shipment unitil now. To retrive the shipment id, use the lookup endpoint of this chapter.
Records found
TBD
[- {
- "event": "PICKUP",
- "type": "ACTUAL",
- "shipment_id": 318283,
- "date_time": {
- "date": "2023-01-21",
- "time": "13:00:00",
- "zone_offset": "+01:00"
}, - "location": {
- "codes": [
- {
- "type": "UNLOC",
- "code": "DEBRE"
}, - {
- "type": "CARGOSOFT",
- "code": "DEBRE"
}
], - "name": "Bremen",
- "latitude": null,
- "longitude": null
}
}, - {
- "event": "PICKUP",
- "type": "ESTIMATED",
- "shipment_id": 318283,
- "date_time": {
- "date": "2023-01-21",
- "time": "09:00:00",
- "zone_offset": "+01:00"
}, - "location": {
- "codes": [
- {
- "type": "UNLOC",
- "code": "DEBRE"
}, - {
- "type": "CARGOSOFT",
- "code": "DEBRE"
}
], - "name": "Bremen",
- "latitude": null,
- "longitude": null
}
}, - {
- "event": "POL_ARRIVAL",
- "type": "ACTUAL",
- "shipment_id": 318283,
- "date_time": {
- "date": "2023-01-23",
- "time": "11:00:00",
- "zone_offset": "+01:00"
}, - "location": {
- "codes": [
- {
- "type": "UNLOC",
- "code": "DEHAM"
}
], - "name": "HAMBURG",
- "latitude": null,
- "longitude": null
}
}, - {
- "event": "POL_ARRIVAL",
- "type": "ESTIMATED",
- "shipment_id": 318283,
- "date_time": {
- "date": "2023-01-23",
- "time": "10:00:00",
- "zone_offset": "+01:00"
}, - "location": {
- "codes": [
- {
- "type": "UNLOC",
- "code": "DEHAM"
}
], - "name": "HAMBURG",
- "latitude": null,
- "longitude": null
}
}
]
Retrieve the main carriage of the shipment with additional details.
Record retrieved
Internal server error
[- {
- "origin": {
- "location": {
- "codes": [
- {
- "type": "CARGOSOFT",
- "code": "string"
}
], - "name": "string",
- "latitude": 0,
- "longitude": 0
}, - "estimated_datetime": {
- "date": "string",
- "time": {
- "hour": 0,
- "minute": 0,
- "second": 0,
- "nano": 0
}, - "zone_offset": {
- "totalSeconds": 0,
- "id": "string",
- "rules": {
- "fixedOffset": true,
- "transitions": [
- {
- "offsetBefore": { },
- "offsetAfter": { },
- "overlap": null,
- "instant": null,
- "duration": { },
- "gap": null,
- "dateTimeAfter": null,
- "dateTimeBefore": null
}
], - "transitionRules": [
- {
- "month": null,
- "timeDefinition": null,
- "standardOffset": { },
- "offsetBefore": { },
- "offsetAfter": { },
- "dayOfWeek": null,
- "dayOfMonthIndicator": null,
- "localTime": null,
- "midnightEndOfDay": null
}
]
}
}
}, - "actual_datetime": {
- "date": "string",
- "time": {
- "hour": 0,
- "minute": 0,
- "second": 0,
- "nano": 0
}, - "zone_offset": {
- "totalSeconds": 0,
- "id": "string",
- "rules": {
- "fixedOffset": true,
- "transitions": [
- {
- "offsetBefore": { },
- "offsetAfter": { },
- "overlap": null,
- "instant": null,
- "duration": { },
- "gap": null,
- "dateTimeAfter": null,
- "dateTimeBefore": null
}
], - "transitionRules": [
- {
- "month": null,
- "timeDefinition": null,
- "standardOffset": { },
- "offsetBefore": { },
- "offsetAfter": { },
- "dayOfWeek": null,
- "dayOfMonthIndicator": null,
- "localTime": null,
- "midnightEndOfDay": null
}
]
}
}
}, - "revised_datetime": {
- "date": "string",
- "time": {
- "hour": 0,
- "minute": 0,
- "second": 0,
- "nano": 0
}, - "zone_offset": {
- "totalSeconds": 0,
- "id": "string",
- "rules": {
- "fixedOffset": true,
- "transitions": [
- {
- "offsetBefore": { },
- "offsetAfter": { },
- "overlap": null,
- "instant": null,
- "duration": { },
- "gap": null,
- "dateTimeAfter": null,
- "dateTimeBefore": null
}
], - "transitionRules": [
- {
- "month": null,
- "timeDefinition": null,
- "standardOffset": { },
- "offsetBefore": { },
- "offsetAfter": { },
- "dayOfWeek": null,
- "dayOfMonthIndicator": null,
- "localTime": null,
- "midnightEndOfDay": null
}
]
}
}
}, - "estimated_datetime_until": {
- "date": "string",
- "time": {
- "hour": 0,
- "minute": 0,
- "second": 0,
- "nano": 0
}, - "zone_offset": {
- "totalSeconds": 0,
- "id": "string",
- "rules": {
- "fixedOffset": true,
- "transitions": [
- {
- "offsetBefore": { },
- "offsetAfter": { },
- "overlap": null,
- "instant": null,
- "duration": { },
- "gap": null,
- "dateTimeAfter": null,
- "dateTimeBefore": null
}
], - "transitionRules": [
- {
- "month": null,
- "timeDefinition": null,
- "standardOffset": { },
- "offsetBefore": { },
- "offsetAfter": { },
- "dayOfWeek": null,
- "dayOfMonthIndicator": null,
- "localTime": null,
- "midnightEndOfDay": null
}
]
}
}
}
}, - "destination": {
- "location": {
- "codes": [
- {
- "type": "CARGOSOFT",
- "code": "string"
}
], - "name": "string",
- "latitude": 0,
- "longitude": 0
}, - "estimated_datetime": {
- "date": "string",
- "time": {
- "hour": 0,
- "minute": 0,
- "second": 0,
- "nano": 0
}, - "zone_offset": {
- "totalSeconds": 0,
- "id": "string",
- "rules": {
- "fixedOffset": true,
- "transitions": [
- {
- "offsetBefore": { },
- "offsetAfter": { },
- "overlap": null,
- "instant": null,
- "duration": { },
- "gap": null,
- "dateTimeAfter": null,
- "dateTimeBefore": null
}
], - "transitionRules": [
- {
- "month": null,
- "timeDefinition": null,
- "standardOffset": { },
- "offsetBefore": { },
- "offsetAfter": { },
- "dayOfWeek": null,
- "dayOfMonthIndicator": null,
- "localTime": null,
- "midnightEndOfDay": null
}
]
}
}
}, - "actual_datetime": {
- "date": "string",
- "time": {
- "hour": 0,
- "minute": 0,
- "second": 0,
- "nano": 0
}, - "zone_offset": {
- "totalSeconds": 0,
- "id": "string",
- "rules": {
- "fixedOffset": true,
- "transitions": [
- {
- "offsetBefore": { },
- "offsetAfter": { },
- "overlap": null,
- "instant": null,
- "duration": { },
- "gap": null,
- "dateTimeAfter": null,
- "dateTimeBefore": null
}
], - "transitionRules": [
- {
- "month": null,
- "timeDefinition": null,
- "standardOffset": { },
- "offsetBefore": { },
- "offsetAfter": { },
- "dayOfWeek": null,
- "dayOfMonthIndicator": null,
- "localTime": null,
- "midnightEndOfDay": null
}
]
}
}
}, - "revised_datetime": {
- "date": "string",
- "time": {
- "hour": 0,
- "minute": 0,
- "second": 0,
- "nano": 0
}, - "zone_offset": {
- "totalSeconds": 0,
- "id": "string",
- "rules": {
- "fixedOffset": true,
- "transitions": [
- {
- "offsetBefore": { },
- "offsetAfter": { },
- "overlap": null,
- "instant": null,
- "duration": { },
- "gap": null,
- "dateTimeAfter": null,
- "dateTimeBefore": null
}
], - "transitionRules": [
- {
- "month": null,
- "timeDefinition": null,
- "standardOffset": { },
- "offsetBefore": { },
- "offsetAfter": { },
- "dayOfWeek": null,
- "dayOfMonthIndicator": null,
- "localTime": null,
- "midnightEndOfDay": null
}
]
}
}
}, - "estimated_datetime_until": {
- "date": "string",
- "time": {
- "hour": 0,
- "minute": 0,
- "second": 0,
- "nano": 0
}, - "zone_offset": {
- "totalSeconds": 0,
- "id": "string",
- "rules": {
- "fixedOffset": true,
- "transitions": [
- {
- "offsetBefore": { },
- "offsetAfter": { },
- "overlap": null,
- "instant": null,
- "duration": { },
- "gap": null,
- "dateTimeAfter": null,
- "dateTimeBefore": null
}
], - "transitionRules": [
- {
- "month": null,
- "timeDefinition": null,
- "standardOffset": { },
- "offsetBefore": { },
- "offsetAfter": { },
- "dayOfWeek": null,
- "dayOfMonthIndicator": null,
- "localTime": null,
- "midnightEndOfDay": null
}
]
}
}
}
}, - "leg_no": 0,
- "mot": "string",
- "voyage_no": "string",
- "imo_code": "string",
- "vessel_name": "string",
- "vessel_flag": "string",
- "call_sign": "string"
}
]
Retrieve the airfreight main carriage of the shipment with additional details. The CargoSoft Shipment ID is needed to retrieve the main carriage.
Record retrieved
Internal server error
This example contains 2 legs for an export airfright shipment.
[- {
- "origin": {
- "location": {
- "codes": [
- {
- "type": "IATA",
- "code": "BRE"
}
], - "name": "Bremen",
- "latitude": null,
- "longitude": null
}, - "estimated_datetime": {
- "date": "2023-11-17",
- "time": "13:00:00",
- "zone_offset": "+01:00"
}, - "actual_datetime": {
- "date": "2023-11-17",
- "time": "13:30:00",
- "zone_offset": "+01:00"
}
}, - "destination": {
- "location": {
- "codes": [
- {
- "type": "IATA",
- "code": "FRA"
}
], - "name": null,
- "latitude": null,
- "longitude": null
}, - "estimated_datetime": {
- "date": "2023-11-18",
- "time": "05:00:00",
- "zone_offset": "+01:00"
}, - "actual_datetime": {
- "date": "2023-11-18",
- "time": "05:15:00",
- "zone_offset": "+01:00"
}
}, - "leg_no": 1,
- "flight_no": "985472",
- "airline_awb_code": "438577456345",
- "airline_name": "AC"
}, - {
- "origin": {
- "location": {
- "codes": [
- {
- "type": "IATA",
- "code": "FRA"
}
], - "name": null,
- "latitude": null,
- "longitude": null
}, - "estimated_datetime": {
- "date": "2023-11-22",
- "time": "18:00:00",
- "zone_offset": "+01:00"
}, - "actual_datetime": {
- "date": "2023-11-18",
- "time": "18:45:00",
- "zone_offset": "+01:00"
}
}, - "destination": {
- "location": {
- "codes": [
- {
- "type": "IATA",
- "code": "NYC"
}
], - "name": null,
- "latitude": null,
- "longitude": null
}, - "estimated_datetime": {
- "date": "2023-11-19",
- "time": null,
- "zone_offset": null
}, - "actual_datetime": {
- "date": "2023-11-19",
- "time": null,
- "zone_offset": null
}
}, - "leg_no": 2,
- "flight_no": "837265437",
- "airline_awb_code": "438577456345",
- "airline_name": "AC"
}
]