Introduction

This documentation provides guidance on using the CMRSoftware API. The CMRSoftware API is a RESTful web service that enables the creation, modification, and listing of CMR consignment notes. The CMRSoftware API offers endpoint for performing various operations. The endpoint is accessible through HTTP methods and returns responses in JSON or XML format.

The documentation includes:

• Authentication process

• Description and usage of endpoints

• Request and response samples

• Error messages and their handling

Technical requirements and examples are also provided to facilitate easy integration of the CMRSoftware API into your applications.

Authentication Process

To use the CMRSoftware API, each request must be authenticated. The authentication process is as follows:

1. Token-Based Authentication: Each request requires a valid API token, which must be sent in the HTTP headers.

2. Unique Request ID: Optionally, a unique request ID can be sent in the headers to help track requests.

API URL

 

Copy✅

Sandbox API URL

 

Copy✅
The Sandbox is a testing environment that simulates the live production environment.

API Token Management

• The API token can be found on the API dashboard page.

• If needed, a new token can be generated using the Regenerate button, but the token in the header must be updated accordingly.

• It can be configured to accept requests from all IP addresses or only from specified IP addresses.

Example of Setting HTTP Headers

Copy✅

1 POST /api/ HTTP/1.1 2 Host: www.cmrsoftware.com 3 Authorization: Bearer {YOUR_API_TOKEN} 4 Content-Type: application/json 5 X-Request-ID: {YOUR_UNIQUE_REQUEST_ID}

• Authorization: The Bearer {YOUR_API_TOKEN} header provides authentication.

• Content-Type: The request and response format can be application/json or application/xml.

• X-Request-ID: (Optional) A unique identifier to help track requests.

Each response is authenticated based on the token provided in the Authorization header and will be in the format specified by the Content-Type header.

Requests and Responses

Sending a Request to the API Endpoint

The JSON or XML request should be sent using the POST method to the API endpoint.

The structure of requests and responses in JSON and XML is the same (except for the XML root element). A request consists of two parts: the header part containing the operation and the request part containing the sent data.

Example Request

JSON Format

Copy✅

1 header": { 2 "operation": "download" 3 }, 4 "request":{"serial":"ABC 541307"} 5 }

XML format

Copy✅

1 <?xml version='1.0'?> 2 <cmr> 3 <header> 4 <operation>download</operation> 5 </header> 6 <request> 7 <serial>ABC 541307</serial> 8 </request> 9 </cmr>

Operations

The operation tag in the header can have the following values:

• create: To create a new CMR waybill.

• preview: To preview a CMR waybill.

• draft: To save a CMR waybill as a draft.

• modify: To modify an existing draft CMR waybill.

• finalize: To finalize a CMR waybill.

• list: To list all CMR waybills.

• download: To download CMR waybill.

• getdata: To retrieve data for a specific CMR waybill.

Each request must include the appropriate operation value in the header and the relevant data in the request body. The response will be the same format specified in the Content-Type header of the request.

Operation	XSD and XML/JSON example	Description	Same feature on CMRSoftware Online
create	xsd xml json	Create PDF CMR waybill. No longer possible to modify	New CMR waybill → Save & Print
preview	xsd xml json	PDF Preview without serial number	New CMR waybill → Preview
draft	xsd xml json	Create a draft waybill with serial number	New CMR waybill → Save
modify	xsd xml json	Data update on draft	Edit -> Save
finalize	xsd xml json	Finalize and close a draft and create a PDF CMR waybill. No longer possible to modify	Edit → Save &Print
list	xsd xml json	List of CMR Waybills	History
download	xsd xml json	Download a PDF CMR Waybill	History → Print
getdata	xsd xml json	Data of the specified waybill	History → Load as new (Clone)

modify, finalize all data must be resubmitted, if a field is not submitted, it will be empty.

Request data types

create, preview, draft, modify, finalize

Field no.	Field	JSON / XML markup	Type	Mandatory
1	Sender (name, address, country)	sender	string
2	Consignee (name, address, country)	consignee	string
3	Place of delivery of the goods (place, country)	place_of_delivery	string
4	Place of taking over the goods (place, country, date)	loading_place	string
4	Date of taking over the goods	loading_date	date YYYY-MM-DD
5	Annexed documents	annexed_documents	string
6	Marks and numbers	marks_and_numbers	normalizedString
7	Number of packages	number_of_packages	integer
8	Method of packing	method_of_packing	normalizedString
9	Nature of the goods	nature_of_the_goods	normalizedString
10	Statistical number	statistical_number	normalizedString
11	Gross weight kg	weight	float(11,3)
12	Volume m3	volume	float(11,3)
13	Sender's instructions (Customs and other formalities)	senders_instructions	string
14	Directions as to freight payment	freight_payment	string
14	Freight paid	freight_paid	boolean
14	Freight to be paid	freight_to_be_paid	boolean
16	Carrier (name, address, country)	carrier	string
17	Successive carriers (name, address, country)	successive_carriers	string
18	Carrier's reservations and obserations	carriers_reservations_and_obserations	string
19	Special agreements	special_agreements	string
21	Established in	established	normalizedString
21	Established on	established_date	date YYYY-MM-DD
22	Signature and stamp of the sender	signature_sender	base64 encoded jpg image
23	Signature and stamp of the carrier	signature_carrier	base64 encoded jpg image
	Class	class	normalizedString
	Number	number	normalizedString
	Letter	letter	normalizedString
	ADR	adr	normalizedString
16	Tractor license plate	tractor_license_plate	normalizedString
16	Trailer license plate	trailer_license_plate	normalizedString
	ISO 639-1 Language Code 1	lang1	enum ("bg", "cs", "de", "en", "es", "fi", "fr", "hu", "it", "nl", "pl", "ro", "sk","sr")	*
	ISO 639-1 Language Code 2	lang2	enum ("bg", "cs", "de", "en", "es", "fi", "fr", "hu", "it", "nl", "pl", "ro", "sk","sr")	*
25	Custom field 1	cmr25_custom_name	normalizedString
26	Custom field 2	cmr26_custom_name	normalizedString
25	Custom field 1 value	cmr25_custom_value	string
26	Custom field 2 value	cmr26_custom_value	string
	Copy for the Sender	copy_sender	Integer minInclusive = 0 maxInclusive = 8	*
	Copy for the Carrier	copy_carrier	Integer minInclusive = 0 maxInclusive = 8	*
	Copy for the Consignee	copy_consignee	Integer minInclusive = 0 maxInclusive = 8	*
	Copies	copies	Integer minInclusive = 0 maxInclusive = 8	*
22	Signature and stamp of the sender	stamp_sender	Base64 encoded JPEG image
23	Signature and stamp of the carrier	stamp_carrier	Base64 encoded JPEG image

list

No data.

download, getdata

Serial (string)

Response

The response header part includes the operation, the request ID, and the result of the operation. In the result part, it contains the result corresponding to the request or, if the operation failed, the error message.

JSON Format example

Copy✅

1 { 2 "header": { 3 "operation": "list", 4 "request_id": "86067", 5 "resultcode": "SUCCES" 6 }, 7 "result": { 8 "cmrwaybill": [ 9 { 10 "status": "Draft", 11 "serial": "VHB 541313", 12 "established_date": "2024-08-02" 13 }, 14 { 15 "status": "Draft", 16 "serial": "VHB 541312", 17 "established_date": "2023-03-16" 18 } 19 ] 20 } 21 }

XML format example

Copy✅

1 <?xml version="1.0" encoding="UTF-8"?> 2 <cmr> 3 <header> 4 <operation>N/A</operation> 5 <request_id>92603</request_id> 6 <status>ERROR</status> 7 </header> 8 <result> 9 <msg>XML does not validate against the XSD schema.</msg> 10 </result> 11 </cmr>

Operation	Respopnse
create, finalize, download	Serial and a base64 encoded PDF waybill
draft, modify	Serial and base64 encoded PDF waybill preview
preview	Base64 encoded PDF waybill preview

JSON Format example

Copy✅

1 { 2 "header": { 3 "operation": "create", 4 "request_id": "35088", 5 "status": "SUCCES" 6 }, 7 "result": { 8 "serial": "VHB 541315", 9 "pdf": "{BASE64_encoded_PDF}" 10 } 11 }

XML Format example

Copy✅

1 <?xml version="1.0" encoding="UTF-8"?> 2 <cmr> 3 <header> 4 <operation>create</operation> 5 <request_id>788656548</request_id> 6 <resultcode>SUCCES</resultcode> 7 </header> 8 <result> 9 <serial>VHB 541311</serial> 10 <pdf>{BASE64_encoded_PDF}</pdf> 11 </result> 12 </cmr>

In the above examples:

• header: Contains metadata about the request.

  • operation: The operation that was performed.

  • requestId: The unique request ID that was sent with the request (X-Request-ID: {UNIQUE_REQUEST_ID}).

  • status: The status of the operation (success or error).

• response: Contains the result of the request.

  • result: The data resulting from the request or an error message if the operation failed.

Error Messages

Error messages returned by the API can be tracked on the API Log page. Here, you can view both the request and the response, including any error messages. The logged information is useful for diagnosing and addressing potential issues.

Sandbox error messages can be tracked on the Sandbox Log page.

Log Features

• View Requests and Responses: Every API call is logged with both the request and the response, including any error messages.

• Filter by Operation Types: Logged entries can be filtered by operation types, making it easy to locate errors related to specific operations.

This section enables quick identification of errors and allows for necessary corrections by providing detailed tracking of the API calls.

Integrations in your system

cURL Example

Copy✅

1 curl -X POST https://www.cmrsoftware.com/api/ \ 2 -H "Authorization: Bearer {YOUR_API_TOKEN}" \ 3 -H "Content-Type: application/xml" \ 4 -H "X-Request-ID: {YOUR_UNIQUE_REQUEST_ID}" \ 5 --data-binary "@path/to/your/cmr.xml"

Explanation:

• -X POST: Specifies the HTTP method as POST.

• https://www.cmrsoftware.com/api/: The URL endpoint of the API.

• -H "Authorization: Bearer {YOUR_API_TOKEN}": The authorization header with your API token.

• -H "Content-Type: application/xml": Specifies that the content type is XML.

• -H "X-Request-ID: {YOUR_UNIQUE_REQUEST_ID}": (Optional) Includes a unique request ID for tracking purposes.

• --data-binary "@path/to/your/file.xml": Sends the contents of the XML file located at path/to/your/cmr.xml.

Replace {YOUR_API_TOKEN}, {YOUR_UNIQUE_REQUEST_ID}, and the file path with your actual values. This command will send the XML file as the body of the POST request to the specified API endpoint.

SAP: Executing an API Request and Processing the Response

This section outlines how to send an API request in SAP, handle the response, and save a Base64-encoded PDF file from the response as a binary file on the server.

ABAP Code Example for API Request and Response Processing

Copy✅

1 DATA: lv_url TYPE string VALUE 'https://www.cmrsoftware.com/api/', 2 lv_token TYPE string VALUE '{YOUR_API_TOKEN}', 3 lv_request_id TYPE string VALUE '{YOUR_UNIQUE_REQUEST_ID}', 4 lv_xml_data TYPE string, 5 lv_xml_response TYPE string, 6 lv_pdf_base64 TYPE string, 7 lv_pdf_xstring TYPE xstring, 8 lv_filename TYPE string VALUE '/usr/sap/tmp/cmr_response.pdf', 9 lv_http_client TYPE REF TO if_http_client, 10 lv_document TYPE REF TO if_ixml_document, 11 lv_element TYPE REF TO if_ixml_element, 12 lv_parser TYPE REF TO cl_ixml. 13 14 " Load XML data to be sent in the request 15 lv_xml_data = '<root>...</root>'. " Your XML structure here 16 17 " Create HTTP client 18 CALL METHOD cl_http_client=>create_by_url 19 EXPORTING 20 url = lv_url 21 IMPORTING 22 client = lv_http_client 23 EXCEPTIONS 24 argument_not_found = 1 25 plugin_not_active = 2 26 internal_error = 3 27 others = 4. 28 29 IF sy-subrc <> 0. 30 WRITE: 'Error creating HTTP client'. 31 RETURN. 32 ENDIF. 33 34 " Set HTTP headers 35 CALL METHOD lv_http_client->request->set_header_field 36 EXPORTING 37 name = 'Authorization' 38 value = |Bearer { lv_token }|. 39 40 CALL METHOD lv_http_client->request->set_header_field 41 EXPORTING 42 name = 'Content-Type' 43 value = 'application/xml'. 44 45 CALL METHOD lv_http_client->request->set_header_field 46 EXPORTING 47 name = 'X-Request-ID' 48 value = lv_request_id. 49 50 " Send XML data in the POST request 51 CALL METHOD lv_http_client->request->set_cdata 52 EXPORTING 53 data = lv_xml_data. 54 55 " Send the request 56 CALL METHOD lv_http_client->send 57 EXCEPTIONS 58 http_communication_failure = 1 59 http_invalid_state = 2 60 http_processing_failed = 3 61 others = 4. 62 63 IF sy-subrc <> 0. 64 WRITE: 'Error sending HTTP request'. 65 RETURN. 66 ENDIF. 67 68 " Receive the response 69 CALL METHOD lv_http_client->receive 70 EXCEPTIONS 71 http_communication_failure = 1 72 http_invalid_state = 2 73 http_processing_failed = 3 74 others = 4. 75 76 IF sy-subrc <> 0. 77 WRITE: 'Error receiving HTTP response'. 78 RETURN. 79 ENDIF. 80 81 lv_xml_response = lv_http_client->response->get_cdata( ). 82 83 " Parse the XML response 84 lv_parser = cl_ixml=>create( ). 85 lv_document = lv_parser->create_document( xml = lv_xml_response ). 86 87 " Extract the Base64 encoded PDF from the XML response 88 lv_element = lv_document->find_from_name( name = 'pdf' ). 89 IF lv_element IS BOUND. 90 lv_pdf_base64 = lv_element->get_value( ). 91 ENDIF. 92 93 " Decode the Base64 encoded PDF 94 CALL FUNCTION 'SCMS_BASE64_DECODE_STR' 95 EXPORTING 96 input = lv_pdf_base64 97 IMPORTING 98 output = lv_pdf_xstring. 99 100 " Save the decoded PDF to a file 101 OPEN DATASET lv_filename FOR OUTPUT IN BINARY MODE. 102 IF sy-subrc = 0. 103 TRANSFER lv_pdf_xstring TO lv_filename. 104 CLOSE DATASET lv_filename. 105 ENDIF. 106

Explanation

1. XML Request Preparation: Load the XML data to be sent in the lv_xml_data variable.

2. HTTP Client Creation: Create the HTTP client using the cl_http_client=>create_by_url method.

3. Setting HTTP Headers: Set the required headers, including Authorization, Content-Type, and X-Request-ID.

4. Sending the Request: The XML data is sent as part of a POST request.

5. Receiving the Response: The API response is captured in lv_xml_response.

6. Parsing the XML Response: The response is parsed using the cl_ixml interface, and the Base64 encoded PDF is extracted.

7. Decoding the Base64 PDF: Use the SCMS_BASE64_DECODE_STR function module to decode the Base64 string into an xstring.

8. Saving the PDF File: Finally, the decoded PDF is written to a file using the OPEN DATASET and TRANSFER statements.

Notes

• Replace the placeholders such as {YOUR_API_TOKEN}, {YOUR_UNIQUE_REQUEST_ID}, and the file paths with actual values.

• The SCMS_BASE64_DECODE_STR function module is used to decode the Base64 encoded data.

• The cl_ixml interface is utilized for parsing the XML document to extract the relevant information.

This process outlines how to execute an API request, handle the response, decode a Base64 encoded PDF, and save it as a file within an SAP environment using ABAP.

Python Sending Request and Saving Base64 Encoded PDF

Here’s a Python example demonstrating how to send a request to the API, process the response, decode the Base64 encoded PDF, and save it to a file named CMR serial.pdf.

Copy✅

1 import requests 2 import base64 3 import xml.etree.ElementTree as ET 4 5 def read_xml(file_path): 6 with open(file_path, 'r', encoding='utf-8') as file: 7 return file.read() 8 9 def send_xml_to_api(xml_data, api_url): 10 11 token = 'YOUR_API_TOKEN' 12 13 # Replace with your actual request ID 14 request_id = 'YOUR_UNIQUE_REQUEST_ID' 15 16 headers = { 17 'Authorization': f'Bearer {token}', 18 'Content-Type': 'application/xml', 19 'X-Request-ID': request_id 20 } 21 22 response = requests.post(api_url, data=xml_data.encode('utf-8'), headers=headers) 23 response.raise_for_status() # Raise an exception for HTTP errors 24 return response.text 25 26 def parse_response_and_save_pdf(response_xml): 27 root = ET.fromstring(response_xml) 28 serial = root.find('.//serial').text 29 base64_pdf = root.find('.//pdf').text 30 31 pdf_data = base64.b64decode(base64_pdf) 32 file_name = f"/path/to/CMR/CMR {serial}.pdf" 33 34 with open(file_name, 'wb') as pdf_file: 35 pdf_file.write(pdf_data) 36 37 print(f"PDF saved as {file_name}") 38 39 def main(): 40 xml_file_path = '/path/to/cmr.xml' # Replace with your XML file path 41 api_url = 'https://www.cmrsoftware.com/api/' 42 43 xml_data = read_xml(xml_file_path) 44 response_xml = send_xml_to_api(xml_data, api_url) 45 46 # print("API Response:") 47 # print(response_xml) 48 49 parse_response_and_save_pdf(response_xml) 50 51 if __name__ == "__main__": 52 main()

Explanation

• API Endpoint and Headers:

  • Set the url to the API endpoint.

  • Define the headers, including the Authorization token, Content-Type, and a unique X-Request-ID.

• Sending the POST Request:

  • Use the requests.post() method to send the request to the API endpoint.

• Processing the Response:

  • Check if the response status is 200 (successful).

  • Parse the JSON response to extract the serial number and the Base64 encoded PDF.

• Decoding and Saving the PDF:

  • Decode the Base64 encoded PDF using base64.b64decode().

  • Create the file name using the extracted serial number.

  • Write the decoded PDF data to a file using the with open() context manager in binary mode (wb).