CargoSoft API (2024.1)

Download OpenAPI specification:Download

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.

Authorization

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

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.

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

[
  {
    "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.
  2. Extract the ID of the shipment result object.
  3. Call the 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 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

  1. To access the lookup endpoint a JWT is needed. For more details how to retrieve a JWT see.
  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.

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

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. 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

Invoice Lines

CargoSoft Invoice Lines functionality

Retrieve all records

Scroll through all existing records.

SecurityJavaWebToken
Request
query Parameters
page_no
integer <int32>
Default: 0
page_size
integer <int32>
Default: 50
Responses
200

Records retrieved

204

No record found

500

Internal server error

get/cargosoft/accounting/invoiceline
Response samples
application/json
[
  • {
    }
]

Create record

Create a new record

SecurityJavaWebToken
Request
Request Body schema: application/json

Model of the record you want to create

id
integer <int32>

The technical id of the invoice line

row
integer <int32>

The line number is a sequential number, for example, 5, 10, 15, 20, and so on.

invoice_number
integer <int64>
invoice_type
string

The invoice type within CargoSoft for an invoice. The following types are permitted:

Enum Value Description
SE

Cancellation of incoming invoice

LR

Incoming invoice

SL

Cancellation of incoming credit note

LG

Incoming credit note

sequential_number
integer <int32>
shipment_number
string

The shipment number for the CargoSoft shipment.

client
required
string
billing_code
string

The CargoSoft billing code.

amount
number

The net amount in the currency of the invoice.

tax_code
string

The CargoSoft tax code.

currency
required
string

The invoice currency

activity_type
string

The CargoSoft activity type

posting_text
string

The posting text of the invoice row

vessel_exchange_rate
number

The vessel exchange rate per shipment number.

vessel_currency
string

The vessel currency per shipment number.

vessel_inverse_rate
boolean

A flag to determine if the currency should be imported as an inverse rate.

Responses
200

Record created

500

Internal server error

post/cargosoft/accounting/invoiceline
Request samples
application/json
{
  • "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
}
Response samples
application/json
{
  • "error_code": {
    },
  • "error_message": "string",
  • "error_source": "string"
}

Lookup record

Find a existing record by given identifiers

SecurityJavaWebToken
Request
query Parameters
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.

Items Enum: "CLIENT" "INVOICE_NUMBER"
order_mode
Array of strings

The order mode for ordering API results sending back as response.

Items Enum Value Description
ASC

ascending

DESC

descending

Request Body schema: application/json
Array
key
string (ShipmentIdentifier)

Identifier key. For instance a ShipmentIdentifier

Enum Value Description
SHIPMENT_ID

A foreign shipment ID of a third party system. This ID should be unique.

DIRECTION

Direction of the shipment. Possible values are [I, E]. I = import shipments, E = export shipments.

CREATION_DATE

System date when the shipment was created.

CUSTOMER_ADDRESS_NUMBER

CargoSoft address number of the customer address.

FILENUMBER

CargoSoft shipment number. The shipment number is unique in combination with the client.

CLIENT

The CargoSoft client.

HBL

House bl number of the Shipment.

MBL

Master bL number of the Shipment.

ADDRESS_REFERENCE

TBD

RUNNING_SEQUENCE_NUMBER

TBD

MONTH_OF_SERVICE

TBD

CUSTOMER_ADDRESS_TYPE

CargoSoft address type of the customer address. Possible values are [D, K, G, P, A]

ID

Unique database ID of the Shipment.

MODE_OF_TRANSPORT

The mode of the shipment. Possible values are [SEA, AIR, RD, RL].

SHIPMENT_CLOSED

Flag if the shipment is done. Possible values are [J, N].

match_mode
string
Default: "EQUALS"

The match mode.

Enum Value Description
OR

Or.

EQUALS

Equals.

IN

In.

LT

Lower than.

LE

Lower equals

CONTAINS

Contains

GT

Greater than.

GE

Greater equals

value
string

The value of the identifier.

Responses
200

Records retrieved

204

No records found

500

Internal server error

post/cargosoft/accounting/invoiceline/lookup
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
[
  • {
    }
]

Retrieve record

Find a existing record by it's database id

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>

Database id of the record you want to retrieve

Responses
200

Record retrieved

204

No record found

500

Internal server error

get/cargosoft/accounting/invoiceline/{id}
Response samples
application/json
{
  • "error_code": {
    },
  • "error_message": "string",
  • "error_source": "string"
}

Invoice

CargoSoft Invoice funcionality

Create record

Create a new record

SecurityJavaWebToken
Request
Request Body schema: application/json

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:

Enum Value Description
SE

Cancellation of incoming invoice

LR

Incoming invoice

SL

Cancellation of incoming credit note

LG

Incoming credit note

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.

Responses
200

Record created

500

Internal server error

post/cargosoft/accounting/invoice
Request samples
application/json
{
  • "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": {
    },
  • "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": [
    ]
}
Response samples
application/json
{
  • "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": {
    },
  • "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": [
    ]
}

retrieveInvoiceLines

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>
Responses
default

default response

get/cargosoft/accounting/invoice/{id}/lines

Voucher Lines

CargoSoft Voucher funcionality

Retrieve all records

Scroll through all existing records.

SecurityJavaWebToken
Request
query Parameters
page_no
integer <int32>
Default: 0
page_size
integer <int32>
Default: 50
Responses
200

Records retrieved

204

No record found

500

Internal server error

get/cargosoft/accounting/voucherline
Response samples
application/json
[
  • {
    }
]

Create record

Create a new record

SecurityJavaWebToken
Request
Request Body schema: application/json

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:

Enum Value Description
SE

Cancellation of incoming invoice

LR

Incoming invoice

SL

Cancellation of incoming credit note

LG

Incoming credit note

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.

Responses
200

Successful

500

Internal server error

post/cargosoft/accounting/voucherline
Request samples
application/json
{
  • "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"
}
Response samples
application/json
{
  • "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"
}

Lookup record

Find a existing record by given identifiers

SecurityJavaWebToken
Request
query Parameters
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.

Items Enum: "CLIENT" "INVOICE_NUMBER"
order_mode
Array of strings

The order mode for ordering API results sending back as response.

Items Enum Value Description
ASC

ascending

DESC

descending

Request Body schema: application/json
Array
key
string (ShipmentIdentifier)

Identifier key. For instance a ShipmentIdentifier

Enum Value Description
SHIPMENT_ID

A foreign shipment ID of a third party system. This ID should be unique.

DIRECTION

Direction of the shipment. Possible values are [I, E]. I = import shipments, E = export shipments.

CREATION_DATE

System date when the shipment was created.

CUSTOMER_ADDRESS_NUMBER

CargoSoft address number of the customer address.

FILENUMBER

CargoSoft shipment number. The shipment number is unique in combination with the client.

CLIENT

The CargoSoft client.

HBL

House bl number of the Shipment.

MBL

Master bL number of the Shipment.

ADDRESS_REFERENCE

TBD

RUNNING_SEQUENCE_NUMBER

TBD

MONTH_OF_SERVICE

TBD

CUSTOMER_ADDRESS_TYPE

CargoSoft address type of the customer address. Possible values are [D, K, G, P, A]

ID

Unique database ID of the Shipment.

MODE_OF_TRANSPORT

The mode of the shipment. Possible values are [SEA, AIR, RD, RL].

SHIPMENT_CLOSED

Flag if the shipment is done. Possible values are [J, N].

match_mode
string
Default: "EQUALS"

The match mode.

Enum Value Description
OR

Or.

EQUALS

Equals.

IN

In.

LT

Lower than.

LE

Lower equals

CONTAINS

Contains

GT

Greater than.

GE

Greater equals

value
string

The value of the identifier.

Responses
200

Records retrieved

204

No records found

500

Internal server error

post/cargosoft/accounting/voucherline/lookup
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
[
  • {
    }
]

Retrieve record

Find a existing record by it's database id

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>

Database id of the record you want to retrieve

Responses
200

Record retrieved

204

No record found

500

Internal server error

get/cargosoft/accounting/voucherline/{id}
Response samples
application/json
{
  • "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"
}

Voucher

CargoSoft Voucher funcionality

Retrieve all records

Scroll through all existing records.

SecurityJavaWebToken
Request
query Parameters
page_no
integer <int32>
Default: 0
page_size
integer <int32>
Default: 50
Responses
200

Records retrieved

204

No record found

500

Internal server error

get/cargosoft/accounting/voucher
Response samples
application/json
[
  • {
    }
]

Create record

Create a new record

SecurityJavaWebToken
Request
Request Body schema: application/json

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:

Enum Value Description
SE

Cancellation of incoming invoice

LR

Incoming invoice

SL

Cancellation of incoming credit note

LG

Incoming credit note

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)
Responses
200

Record created

500

Internal server error

post/cargosoft/accounting/voucher
Request samples
application/json
{
  • "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": {
    },
  • "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": [
    ]
}
Response samples
application/json
{
  • "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": {
    },
  • "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": [
    ]
}

Lookup record

Find existing records by given identifiers

SecurityJavaWebToken
Request
query Parameters
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.

Items Enum: "CLIENT" "INVOICE_NUMBER" "JOURNAL_NUMBER"
order_mode
Array of strings

The order mode for ordering API results sending back as response.

Items Enum Value Description
ASC

ascending

DESC

descending

Request Body schema: application/json
Array
key
string (ShipmentIdentifier)

Identifier key. For instance a ShipmentIdentifier

Enum Value Description
SHIPMENT_ID

A foreign shipment ID of a third party system. This ID should be unique.

DIRECTION

Direction of the shipment. Possible values are [I, E]. I = import shipments, E = export shipments.

CREATION_DATE

System date when the shipment was created.

CUSTOMER_ADDRESS_NUMBER

CargoSoft address number of the customer address.

FILENUMBER

CargoSoft shipment number. The shipment number is unique in combination with the client.

CLIENT

The CargoSoft client.

HBL

House bl number of the Shipment.

MBL

Master bL number of the Shipment.

ADDRESS_REFERENCE

TBD

RUNNING_SEQUENCE_NUMBER

TBD

MONTH_OF_SERVICE

TBD

CUSTOMER_ADDRESS_TYPE

CargoSoft address type of the customer address. Possible values are [D, K, G, P, A]

ID

Unique database ID of the Shipment.

MODE_OF_TRANSPORT

The mode of the shipment. Possible values are [SEA, AIR, RD, RL].

SHIPMENT_CLOSED

Flag if the shipment is done. Possible values are [J, N].

match_mode
string
Default: "EQUALS"

The match mode.

Enum Value Description
OR

Or.

EQUALS

Equals.

IN

In.

LT

Lower than.

LE

Lower equals

CONTAINS

Contains

GT

Greater than.

GE

Greater equals

value
string

The value of the identifier.

Responses
200

Records retrieved

204

No records found

500

Internal server error

post/cargosoft/accounting/voucher/lookup
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
[
  • {
    }
]

Retrieve record

Find a existing record by it's database id

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>

Database id of the record you want to retrieve

Responses
200

Successful

204

No record found

500

Internal server error

get/cargosoft/accounting/voucher/{id}
Response samples
application/json
{
  • "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": {
    },
  • "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": [
    ]
}

Retrieve all unprocessed vouchers

Scroll through all existing records.

SecurityJavaWebToken
Request
query Parameters
client
string
page_no
integer <int32>
Default: 0
page_size
integer <int32>
Default: 50
Responses
200

Records retrieved

204

No record found

500

Internal server error

get/cargosoft/accounting/voucher/unprocessed
Response samples
application/json
[
  • {
    }
]

Shipment

The following chapter will give you an overview about the shipment endpoints and their function.

Lookup for shipments

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.

SecurityJavaWebToken
Request
query Parameters
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.

Items Enum Value Description
SHIPMENT_ID

A foreign shipment ID of a third party system. This ID should be unique.

DIRECTION

Direction of the shipment. Possible values are [I, E]. I = import shipments, E = export shipments.

CREATION_DATE

System date when the shipment was created.

CUSTOMER_ADDRESS_NUMBER

CargoSoft address number of the customer address.

FILENUMBER

CargoSoft shipment number. The shipment number is unique in combination with the client.

CLIENT

The CargoSoft client.

HBL

House bl number of the Shipment.

MBL

Master bL number of the Shipment.

ADDRESS_REFERENCE

TBD

RUNNING_SEQUENCE_NUMBER

TBD

MONTH_OF_SERVICE

TBD

CUSTOMER_ADDRESS_TYPE

CargoSoft address type of the customer address. Possible values are [D, K, G, P, A]

ID

Unique database ID of the Shipment.

MODE_OF_TRANSPORT

The mode of the shipment. Possible values are [SEA, AIR, RD, RL].

SHIPMENT_CLOSED

Flag if the shipment is done. Possible values are [J, N].

order_mode
Array of strings

The order mode for ordering API results sending back as response.

Items Enum Value Description
ASC

ascending

DESC

descending

Request Body schema: application/json
Array
Any of:

The equals identifier should use to match the value exactly.

key
string (ShipmentIdentifier)

Identifier key. For instance a ShipmentIdentifier

Enum Value Description
SHIPMENT_ID

A foreign shipment ID of a third party system. This ID should be unique.

DIRECTION

Direction of the shipment. Possible values are [I, E]. I = import shipments, E = export shipments.

CREATION_DATE

System date when the shipment was created.

CUSTOMER_ADDRESS_NUMBER

CargoSoft address number of the customer address.

FILENUMBER

CargoSoft shipment number. The shipment number is unique in combination with the client.

CLIENT

The CargoSoft client.

HBL

House bl number of the Shipment.

MBL

Master bL number of the Shipment.

ADDRESS_REFERENCE

TBD

RUNNING_SEQUENCE_NUMBER

TBD

MONTH_OF_SERVICE

TBD

CUSTOMER_ADDRESS_TYPE

CargoSoft address type of the customer address. Possible values are [D, K, G, P, A]

ID

Unique database ID of the Shipment.

MODE_OF_TRANSPORT

The mode of the shipment. Possible values are [SEA, AIR, RD, RL].

SHIPMENT_CLOSED

Flag if the shipment is done. Possible values are [J, N].

match_mode
string
Default: "EQUALS"

The match mode.

Enum Value Description
OR

Or.

EQUALS

Equals.

IN

In.

LT

Lower than.

LE

Lower equals

CONTAINS

Contains

GT

Greater than.

GE

Greater equals

value
string

The value of the identifier.

Responses
200

Records found

post/cargosoft/shipment/lookup
Request samples
application/json

TBD

[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]
Response samples
application/json

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 airfreight shipment main carriage

Retrieve the airfreight main carriage of the shipment with additional details. The CargoSoft Shipment ID is needed to retrieve the main carriage.

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>
Responses
200

Record retrieved

500

Internal server error

get/cargosoft/shipment/{id}/airmaincarriage
Response samples
application/json

This example contains 2 legs for an export airfright shipment.

[
  • {
    },
  • {
    }
]

Retrieve shipment events

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.

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>

The shipment id.

Responses
200

Records found

get/cargosoft/shipment/{id}/events
Response samples
application/json

TBD

[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Retrieve seafreight shipment main carriage

Retrieve the main carriage of the shipment with additional details.

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>
Responses
200

Record retrieved

500

Internal server error

get/cargosoft/shipment/{id}/seamaincarriage
Response samples
application/json
[
  • {
    }
]

Shipment - Transport

Retrieve airfreight shipment main carriage

Retrieve the airfreight main carriage of the shipment with additional details. The CargoSoft Shipment ID is needed to retrieve the main carriage.

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>
Responses
200

Record retrieved

500

Internal server error

get/cargosoft/shipment/{id}/airmaincarriage
Response samples
application/json

This example contains 2 legs for an export airfright shipment.

[
  • {
    },
  • {
    }
]

Shipment goods description

retrieveMeasurements

SecurityJavaWebToken
Request
path Parameters
id
required
integer <int32>
Responses
default

default response

get/cargosoft/good/{id}/measurements

Authorization

Retrieve JWT

Retrieve a Java Web Token to authenticate against the API

Request
Request Body schema: application/x-www-form-urlencoded
username
required
string

Your username

password
required
string

Your password

Responses
200

Java Web Token

401

Wrong username and/or password

post/auth/token
Request samples
application/x-www-form-urlencoded
username=string&password=string
Response samples
application/json
{
  • "token": "string"
}