NAV
http python

Introduction

This is the API documentation for 24translate Translation Distribution System (TDS). TDS provides an extensive API that allows to connect any kind of software such as

All API calls are REST compliant and use the following HTTP methods:

The main entities of the API as well as its properties and endpoints are documented in the API reference.

Getting Started

Send requests to the API

All HTTP requests sent to the server should have HTTP header Authorization: Bearer, see Authentication guide. Most of our API endpoints expect parameters such as orderNumber or documentId in URL path and/or in request body as JSON. Most endpoints will provide a response in JSON format.

import requests
import json

url='https://api.24translate.ch/api/order'
order_info={
 "sourceLanguage": "en-US",
 "targetLanguage": "de-DE",
 "productName": "mycompany_good",
 "specialisationCode": "mycompany_pr"
}
# auth_hook hook defined in Authentication guide.
r = requests.post(url, json = order_info, auth=auth_hook)
orderNumber=json.loads(r.text).get('orderNumber')

To use the API, it is required to send HTTP requests to the API endpoints and process the responses.

In order to use our API, you need the following access information provided by us: customer_uuid and secret_api_token. You can generate an authentication token as described in Authentication guide. For every HTTP-request, it is necessary to put the generated token in the Authorization: Bearer {generated-token} HTTP-header.

Authentication guide

from requests.auth import AuthBase
import jwt
import datetime


class ApiAuth(AuthBase):
 def __init__(self, customer_uuid, secret_api_token):
  self.customer_uuid = customer_uuid
  self.secret_api_token = secret_api_token

 def encode_auth_token(self):
  payload = {
   'exp': datetime.datetime.utcnow() + datetime.timedelta(days=0, seconds=1000),
   'iat': datetime.datetime.utcnow(),
   'sub': self.customer_uuid
  }
  return jwt.encode(
   payload,
   self.secret_api_token,
   algorithm='HS256'
  )


 def __call__(self, r):
  r.headers['Authorization'] = 'Bearer ' + self.encode_auth_token().decode("utf-8")
  return r

auth_hook=ApiAuth(customer_uuid='21a9ddbb-3b8a-4ed3-84c7-4c7ba061189e', secret_api_token='6e3780b4-b820-4669-af3e-9171c4157c7e')

The API can only be used by registered 24translate customers who have been provided with a customer_uuid and secret_api_token.

Your account manager can provide you with the following information in order for you to be able to generate JWT tokens:

Our API uses JWT (JSON Web Token) for authentication with HMAC SHA-256 (HS256) as cryptographic algorithm. Algorithms HS384 and HS512 are also supported. The Bearer token for every HTTP request sent to our API endpoints should be generated by the customer using payload as described below and using the provided secret_api_token as the secret token. See an example in Python.

The Payload has the following attributes:

For each API request, please use the header 'Authorization' with the value 'Bearer' along with the encoded token. For example: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8

The following example shows a request to create an initial order:

POST /api/order HTTP/1.1
Accept: */*
Connection: keep-alive
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8

{"sourceLanguage": "en-US", "targetLanguage": "de-DE", "productName": "mycompany_quick", "specialisationCode": "mycompany_pr"}

The server will respond with the status code 201, the location of the status page and the generated orderNumber in JSON format:

HTTP/1.1 201 Created
Location: https://api.24translate.ch/api/order/CHS-1003334
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 03 Sep 2020 07:52:23 GMT
Server: 24t
{"orderNumber":"CHS-1003334"}

Basic order workflow

This chapter lists all necessary steps to create a translation order. For more information on optional functions, please refer to the chapter Advanced Usage.

Workflow of the order

When an order is created, an order status is always created at the same time. This status changes within the process. Initially, the status of a new order is DOCUMENTS_MISSING. The status of a delivered order is DELIVERED.

The order status can be called regularly via the request GET /status.

All status states are shown in the following flow chart: Order workflow

If your order status is INVALID, you can find details about which of the uploaded source documents caused the problem by using the endpoint GET /order/{orderNumber}/sourceDocuments.

The steps are listed in chronological order for each variant. For more details on objects, properties and endpoints, please refer to the relevant documentation.

1. Create an initial order

For each request, please insert the generated JWT Token in the HTTP-header 'Authorization: Bearer'. Please refer to the documentation for more details: Authentication guide.

For more details about the request attributes sourceLanguage, targetLanguage, specialisationCode, productName, deliveryMode, securityLevel please refer to the documentation: Advanced Usage.

POST /api/order HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8

{
  "sourceLanguage": "de-DE",
  "targetLanguage": "fr-FR",
  "specialisationCode": "customer_marketing",
  "productName": "customer_good",
  "deliveryMode": "_48_HOURS",
  "securityLevel": "customer_public"
}
To view the examples
please switch to the
code examples in http.

Request

Create an initial order by providing the required information for your translation. Create a POST request for the endpoint /order. Insert the order request parameters in the request body.

HTTP/1.1 201 Created
Location: https://api.24translate.ch/api/order/CHS-1003334
Content-Type: application/json;charset=UTF-8
{
    "orderNumber": "CHS-1003334"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{"items":[{"statusCode":130,"statusType":"INVALID_TARGET_LANGUAGE","statusMessage":"targetLanguage: INVALID"}]}
To view the examples
please switch to the
code examples in http.

Response

ResponseCode: 201

The Response is a OrderResponse. Please remember the orderNumber. You will need it to reference your order throughout the process.

ResponseCode: 400

If an order cannot be created due to validation errors, the response is a StatusItems. Please correct the input and try again.

For more details, please refer to the documentation: POST /order

2. Add source documents to your order

POST /api/order/CHS-1003334/sourceDocument HTTP/1.1
Content-Length: 194
Content-Type: multipart/form-data; boundary=ea68e150b02947e0ab250a9edcc10ec6
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjY2MDgsImlhdCI6MTU5OTEyNTYwOCwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.SLfqwAbLlhOUojS2kt0bTuo_2e4gshC84DdXIILpvbI
--ea68e150b02947e0ab250a9edcc10ec6
Content-Disposition: form-data; name="file"; filename="words8.txt"

word1 word2 word3 word4 word5 word6 word7 word8 
--ea68e150b02947e0ab250a9edcc10ec6--

Request

The next step is to upload the documents to be translated. We support various file types such as docx, xliff, ... . There are two ways of uploading multiple documents:

  1. Upload them one by one (one POST request per document).
  2. Zip them and upload the archive via POST request.

Create a POST request for the endpoint /order/{orderNumber}/sourceDocument. Add the source document in the body.

For XML/XHTML documents, you can specify which parts of the document should be translated by using ITS rules https://www.w3.org/TR/its20/ encoded in base64 and provided in request parameter itsRules.

For example: in order to only translate the text in <itemMT> elements in the source document and skip the text in <itemNT> elements, use the following ITS rules:

<?xml version="1.0" ?>
<its:rules version="2.0" xmlns:its="http://www.w3.org/2005/11/its">
  <its:translateRule selector="//itemMT" translate="yes"/>
  <its:translateRule selector="//itemNT" translate="no"/>
</its:rules>

that should be provided as base64-encoded in itsRules parameter in HTTP POST request: PD94bWwgd ... z4KCg==

POST /api/order/CHS-1003334/sourceDocument HTTP/1.1
Content-Length: 783
Content-Type: multipart/form-data; boundary=d0ac105e454340f88718d8aae12da045
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MDU2MDIyNjgsImlhdCI6MTYwNTYwMTI2OCwic3ViIjoiMzVhNGVhMWYtYjUwYi00NmNiLWIxYjctY2Q0NmEyNzdlNGZmIn0.mDfjHsssSUzM3DvE0334Lc5FDxSbavf50xVDNJQMrIc
--d0ac105e454340f88718d8aae12da045
Content-Disposition: form-data; name="md5Checksum"

2b790e15fb067ab6c1d2f61b6b474951
--d0ac105e454340f88718d8aae12da045
Content-Disposition: form-data; name="itsRules"

PD94bWwgdmVyc2lvbj0iMS4wIiA/Pgo8aXRzOnJ1bGVzIHZlcnNpb249IjIuMCIgeG1sbnM6aXRz
PSJodHRwOi8vd3d3LnczLm9yZy8yMDA1LzExL2l0cyI+CiA8aXRzOnRyYW5zbGF0ZVJ1bGUgc2Vs
ZWN0b3I9Ii8vaXRlbU1UIiB0cmFuc2xhdGU9InllcyIvPgogPGl0czp0cmFuc2xhdGVSdWxlIHNl
bGVjdG9yPSIvL2l0ZW1OVCIgdHJhbnNsYXRlPSJubyIvPgo8L2l0czpydWxlcz4KCg==
--d0ac105e454340f88718d8aae12da045
Content-Disposition: form-data; name="file"; filename="itsdoc1.xml"

<root>\n<item>\n\t<itemMT>Please translate this text</itemMT>\n\t<itemNT>Please do not translate this text</itemNT>\n</item>\n</root>

--d0ac105e454340f88718d8aae12da045--

HTTP/1.1 200 OK
{
  "documentId": 456,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 194,
  "status": "CHECKING",
  "statusMessage": "Valid",
  "errorCode": null
}
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 200

The Response is a SourceDocumentResponse. Please remember the documentId as you will need it to reference your order for other requests. We use md5Checksum to validate if the upload was successful.

For more details, please refer to the documentation: POST /order/{orderNumber}/sourceDocument

3. Get order status

GET /api/order/CHS-1003334/status HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8
To view the examples 
please switch to the 
code examples in http.

Request

Create a GET status request if you wish to receive a status information for your order. Execute a GET request to the endpoint /order/{orderNumber}/status.

HTTP/1.1 200 OK
"VALID"
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 200

The response is a string OrderStatus. We check all the uploaded documents for structural errors. If there aren't any, the response will be VALID; you can now commit your order. Repeat the request in regular intervals (5-30-600sec) until the response is either VALID or INVALID. 3 months after the delivery, the order will be ARCHIVED and its documents will not be available any more.

To get more details about which of the uploaded documents caused the status to be INVALID, please refer to the documentation: GET /order/{orderNumber}/sourceDocuments

For more details, please refer to the documentation: GET /order/{orderNumber}/status

4. Get a quote

GET /api/order/CHS-1003334/quote HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8
To view the examples 
please switch to the 
code examples in http.

Request

Once you uploaded all the documents to be translated and if the status of your order is VALID, you can ask for a quote.

To get a quote for your order, please create a GET /api/order/CHS-1003334/quote request.

HTTP/1.1 200 OK
{
  "currency": "EUR",
  "grossAmount": 143.20,
  "minimumPrice": true,
  "netAmount": 123.45,
  "taxAmount": 19.75,
  "taxRate": 16,
  "totalDiscountPercent": 23.45,
  "volume": 40,
  "volumeType": "LINE"
}
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 200

You will receive a response of type QuoteResponse with all quote details such as the price and the total volume of the documents.

For more details, please refer to the documentation: GET /order/{orderNumber}/quote

5. Transfer the order request into an order

PUT /api/order/CHS-1003334/place HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8
To view the examples 
please switch to the 
code examples in http.

Request

Once you uploaded all the documents to be translated and the initial order information is ready, you can transfer the order request into an actual order. As soon as this is done, we will start to work on your documents. The order status now changes to WORKING. The status will change to DELIVERED once the translated documents are ready to be downloaded. It is not possible to PUT an order into this state more than once.

By sending this request, you agree to be charged for the order.

Execute a PUT request on the endpoint /order/{orderNumber}/place.

HTTP/1.1 201 Created
{
  "orderNumber": "CHS-1003334"
}
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 200, 201

Response code 201 means that the order has been placed successfully.

Response code 200 means that the order had already been placed before this request was sent. The response is a OrderResponse.

For more details, please refer to the documentation: PUT /order/{orderNumber}/place

6. (for testing) Get delivery immediately

POST /api/order/CHS-1003334/deliverImmediately HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8
To view the examples 
please switch to the 
code examples in http.

Request

In our test environment we have established a feature to help you test faster by emulating the translation of the documents. To have your translation delivered immediatly after sending a /order/place request, please call /order/{orderNumber}/deliverImmediately. The status of the order will then change to DELIVERED and you can proceed to the next step order/{orderNumber}/targetDocuments.

Execute a POST request to the endpoint /order/{orderNumber}/deliverImmediately.

HTTP/1.1 201 OK
Location: https://api.24translate.ch/api/order/CHS-1003334/targetDocuments
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 201

Responsecode 201 signals that everything has worked fine. Continue with steps GET /order/{orderNumber}/status or GET /order/{orderNumber}/targetDocuments

For more details, please refer to the documentation: POST /order/{orderNumber}/deliverImmediately

7. Get order status by orderNumber until the order is delivered

GET /api/order/CHS-1003334/status HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8
To view the examples 
please switch to the 
code examples in http.

Request

It is possible to monitor the status of the order.

To do so, please execute a GET request on the endpoint /order/{orderNumber}/status.

HTTP/1.1 200 OK
"DELIVERED"
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 200

The response is a string OrderStatus.

If the translation of the documents has been finished, the status response will be set to DELIVERED which means the documents are ready to be picked up. Repeat the request in regular intervals until the order status is DELIVERED.

For more details, please refer to the documentation: GET /order/{orderNumber}/status

8. Get a list of target documents

GET /api/order/CHS-1003334/targetDocuments HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8
To view the examples 
please switch to the 
code examples in http.

Request

In order to download the translated documents, you first need to get a list of the target documents. To do so, please execute a GET request on the endpoint /order/{orderNumber}/targetDocuments.

HTTP/1.1 200 OK
{
    "items": [
        {
            "documentId": 223658,
            "sourceDocumentId" : 223655,
            "filename": "words8.txt",
            "filesize": 52,
            "uri": "https://api.24translate.ch/api/order/CHS-1003334/targetDocument/223658/content"
        }
    ]
}
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 200

The response is a JSON Array with TargetDocumentResponse. For each target document, the response contains an uri that can be used to download the translated document.

For more details, please refer to the documentation: GET /order/{orderNumber}/targetDocuments

9. Download translated documents

With the target document URI(s) received by executing the previous step, you can now download the translated document(s). It is possible to build the URI manually by applying the orderNumber and the documentId:

GET /api/order/CHS-1003334/targetDocument/223658/content HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8
To view the examples 
please switch to the 
code examples in http.

Request

Execute a GET request for the endpoint /order/{orderNumber}/targetDocument/{documentId}/content.

HTTP/1.1 200 OK
Content-disposition: attachment; filename="words8_DE.txt";
Content-Type: text/plain;charset=UTF-8
Content-Length: 52

"This is your translated text"
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 200

The Response is a string with the content of the translated document.

For more details, please refer to the documentation: GET /order/{orderNumber}/targetDocument/{documentId}/content

10. Get list of source documents

You can check the list of uploaded source documents, get their filesize, MD5 checksum and validation status.

It is possible to build the URI manually by applying the orderNumber:

GET /api/order/CHS-1003334/sourceDocuments HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjAzNDUsImlhdCI6MTU5OTExOTM0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.PCZbNg26V8o4cbhSAX08XGciF59_ykuGttkO-9a1Ia8
To view the examples 
please switch to the 
code examples in http.

Request

Execute a GET request for the endpoint /order/{orderNumber}/sourceDocuments.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "items": [
    {
      "documentId": 236696,
      "filename": "words8.txt",
      "md5Checksum": "8387481811ca557a3dcd9f6172830928",
      "filesize": 48,
      "status": "VALID",
      "statusMessage": "Valid",
      "errorCode": null
    },
    {
      "documentId": 236695,
      "filename": "Extraction_Fails_Macro.doc",
      "md5Checksum": "56c28c2ed0353f4a87eb98ac1913215e",
      "filesize": 108032,
      "status": "INVALID",
      "statusMessage": "Automatic processing not possible. Xliff transformation failed.",
      "errorCode": 2101
    }
  ]
}
To view the examples 
please switch to the 
code examples in http.

Response

Responsecode: 200

The Response is a string with the list of source documents and their details.

For more details, please refer to the documentation: GET /order/{orderNumber}/sourceDocuments

Advanced Usage

In the chapter Basic order workflow we described the first steps to create an order using our API. The following chapter will give you more information about the advanced usage of the API. This includes the handling of customer-specific parameters as well as the handling of optional methods and variables that are helpful in individual cases.

Get language Code

In the POST /api/order request, please set the sourceLanguage and the targetLanguage for your order. The format of these values is mostly BCP-47 code. We support many languages and language combinations. However, there are also a few that we cannot provide. For specific questions about exotic languages and language combinations, please contact your account manager.

To view all valid values for you, please use the GET endpoints GET /list/sourceLanguages and GET /list/targetLanguages.

The following are some example language codes: de-DE en-GB fr-FR it-IT de-CH

POST /api/order HTTP/1.1
Content-Type: application/json
{
...
  "sourceLanguage": "de-DE",
  "targetLanguage": "fr-FR",
...
}
To view the examples 
please switch to the 
code examples in http.

For more details, please refer to the documentation: OrderRequest:Language

Get order specialisations

In the POST /api/order request, please set the specialisationCode to indicate the specialisation of the documents. The information provided by the specialisation is used to ensure the best quality of the translation. With our customers, we discuss what is the right choice of specialisation and define corresponding values which are specified here in the attribute. Please talk to your account manager about specialisationCode.

To view all valid values for you, please use the GET endpoint GET /list/specialisations.

POST /api/order HTTP/1.1
Content-Type: application/json
{
...
  "specialisationCode": "customer_marketing",
...
}
To view the examples 
please switch to the 
code examples in http.

For more details, please refer to the documentation: OrderRequest:specialisationCode

Get productName

In the POST /api/order request, please set a productName which refers to the services i.e. order types that we offer. We have different products that define the service and quality of the order. These are e.g. 'translation and proofreading’. Please select the productName that best suits your requirements. To best meet the needs of our customers, we define customized products. Please contact your account manager to discuss the appropriate products and ask for your productName(s).

If you choose a product that uses machine translation, not all OrderRequest:securityLevels are available.

To view all valid values for you, please use the GET endpoints GET /list/products.

POST /api/order HTTP/1.1
Content-Type: application/json
{
  "productName": "customer_good",
}
To view the examples 
please switch to the 
code examples in http.

For more details, please refer to the documentation: OrderRequest:productName.

Get deliveryMode

In the POST /api/order request, you can set a deliveryMode or directly a desiredDeliryDate. Both together is not possible. The deliveryMode refers to the delivery time in our system.

To view all valid values for deliveryMode, please use the GET endpoints GET /list/deliveryModes.

POST /api/order HTTP/1.1
Content-Type: application/json
{
  "deliveryMode": "_48_HOURS",
}
To view the examples 
please switch to the 
code examples in http.

For more details, please refer to the documentation: OrderRequest:deliveryMode.

Get securityLevel

In the POST /api/order request, you can set a securityLevel. The securityLevel refers to the security requirements needed for the order.

If you choose a securityLevel with higher security requirements, machine translation will not be available as a OrderRequest:productName.

To view all valid values for securityLevel, please use the GET endpoints GET /list/securityLevels.

POST /api/order HTTP/1.1
Content-Type: application/json
{
  "securityLevel": "mycompany_public",
}
To view the examples 
please switch to the 
code examples in http.

For more details, please refer to the documentation: OrderRequest:securityLevel.

Add reference documents

POST /api/order/CHS-1003334/referenceDocument HTTP/1.1
Content-Length: 194
Content-Type: multipart/form-data; boundary=ea68e150b02947e0ab250a9edcc10ec6
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjY2MDgsImlhdCI6MTU5OTEyNTYwOCwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.SLfqwAbLlhOUojS2kt0bTuo_2e4gshC84DdXIILpvbI
--ea68e150b02947e0ab250a9edcc10ec6
Content-Disposition: form-data; name="file"; filename="glossary.txt"

word1 word2 word3 word4 word5 word6 word7 word8 
--ea68e150b02947e0ab250a9edcc10ec6
Content-Disposition: form-data; name="md5Checksum"

2b790e15fb067ab6c1d2f61b6b474951
--ea68e150b02947e0ab250a9edcc10ec6
Content-Disposition: form-data; name="documentType"

glossary
--ea68e150b02947e0ab250a9edcc10ec6--

Request

You can optionally upload reference documents to be used during the translation process using the following documentTypes: translationMemory, glossary, parallelText, originalSourceDocument, styleGuide, miscellaneous. Reference documents can only be used in human translation orders.

If you want to upload more than one document, please use one POST request per document.

Create a POST request for the endpoint /order/{orderNumber}/referenceDocument. Add the reference document in the body.

HTTP/1.1 200 OK
{
  "documentId": 456,
  "filename": "glossary.txt",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 194,
  "documentType": "glossary"
}
To view the examples
please switch to the
code examples in http.

Response

Responsecode: 200

The Response is a ReferenceDocumentResponse. Please remember the documentId as you will need it to reference your order for other requests. We use md5Checksum to validate if the upload was successful.

For more details, please refer to the documentation: POST /order/{orderNumber}/referenceDocument

API Reference

24translate TDS API

Version: v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Base URLs:

Email: Support

API Reference: order

Can trigger every task in the order lifecycle. An order can be created as an enquiry, which is basically an order in states DOCUMENTS_MISSING, CHECKING, INVALID, VALID.

POST /order

Example URL: https://api.24translate.ch/api/order

Create an initial order without source documents.

Code samples


POST /api/order HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Content-Type: application/json
Accept: application/json


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.24translate.ch/api/order', headers = headers)

print(r.json())

Creates a unique order with a unique ID. This ID is used as reference for any further operations. Upload files with POST /order/{orderNumber}/sourceDocument

Body parameter

{
  "sourceLanguage": "en-US",
  "targetLanguage": "de-DE",
  "specialisationCode": "mycompany_marketing",
  "productName": "mycompany_good",
  "desiredDeliveryTime": "2016-01-01T12:00:00+01:00",
  "deliveryMode": "EXPRESS",
  "securityLevel": "mycompany_public",
  "comment": "Please do not translate italic text",
  "specialFields": [
    {
      "key": "costCenters",
      "value": "CC-12345"
    }
  ]
}

Parameters

Name In Type Required Description
body body OrderRequest true Initial order request with mandatory attributes such as source language and target language. For each request either the deliveryMode or the desiredDeliveryTime can be specified.

Example responses

201 Response

{
  "orderNumber": "CHS-1003334"
}

Responses

Status Meaning Description Schema
201 Created The order has been created OrderResponse
400 Bad Request Invalid order input data. The body contains a list of validation errors. StatusItems
401 Unauthorized Auth failed StatusItems

Response Schema

Status Code 201: OrderResponse

Name Type Required Description.
» orderNumber OrderNumber true Order number for reference.

Status Code 400: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /order/{orderNumber}

Example URL: https://api.24translate.ch/api/order/{orderNumber}

Get quote+status+info by orderNumber

Code samples


GET /api/order/{orderNumber} HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/order/{orderNumber}', headers = headers)

print(r.json())

Returns the quote for an order as the price with detailed information.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

200 Response

{
  "status": "VALID",
  "quote": {
    "currency": "EUR",
    "grossAmount": 143.2,
    "minimumPrice": true,
    "netAmount": 123.45,
    "taxAmount": 19.75,
    "taxRate": 16,
    "totalDiscountPercent": 23.45,
    "volume": 0,
    "volumeType": "LINE"
  },
  "info": {
    "attributes": {
      "sourceLanguage": "en-US",
      "targetLanguage": "de-DE",
      "specialisationCode": "mycompany_marketing",
      "productName": "mycompany_good",
      "desiredDeliveryTime": "2016-01-01T12:00:00+01:00",
      "deliveryMode": "EXPRESS",
      "securityLevel": "mycompany_public",
      "comment": "Please do not translate italic text",
      "specialFields": [
        {
          "key": "costCenters",
          "value": "CC-12345"
        }
      ]
    },
    "estimatedDeliveryTime": "2016-01-01T12:00:00+01:00",
    "actualDeliveryTime": "2016-01-01T11:59:00+01:00"
  }
}

Responses

Status Meaning Description Schema
200 OK Quote data OrderFullInfo
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems

Response Schema

Status Code 200: OrderFullInfo

Name Type Required Description.
» status OrderStatus false Once you create an order, it will be in state DOCUMENTS_MISSING. You need to upload sourceDocuments in order to reach status VALID, after which you can place an an order and will transition to WORKING and later DELIVERED once targetDocuments are ready to be downloaded. Order will be ARCHIVED 3 months after the delivery date and its documents will not be available.
» quote QuoteResponse false Provides information about volume and price of an order. The quote response is not available for an order in states INVALID or CHECKING or DOCUMENT_MISSING.
»» currency string true The currency of the price.
»» grossAmount number(double) true The gross amount of the offer.
»» minimumPrice boolean true If 'true', this is a minimum price.
»» netAmount number(double) true The net amount of the offer.
»» taxAmount number(double) true The total tax amount, depending on both the net and gross amount.
»» taxRate number(double) true The tax rate of the offer price.
»» totalDiscountPercent number(double) true The price discount in percent based on the CAT analysis result and the customer tm discount settings.
»» volume integer(int32) false Volume of all documents.
»» volumeType string false TBD
» info OrderInfo false Represents information about the order.
»» attributes OrderRequest false none
»»» sourceLanguage string true The BCP-47 code of the source language.
»»» targetLanguage string true The BCP-47 code of the target language.
»»» specialisationCode string true The specialisation of the source text. Please contact your account manager for valid inputs.
»»» productName string true The name of the translation product. Please contact your account manager for valid input values.
»»» desiredDeliveryTime string false The date and time of the desired delivery as a ISO 8601 compliant string. Either deliveryMode or desiredDeliveryTime attribute should be provided, but not both.
»»» deliveryMode string false The different deliveryModes are used to indicate the typical delivery times. Either deliveryMode or desiredDeliveryTime attribute should be provided, but not both.
»»» securityLevel string false The securityLevel refers to the security requirements necessary for the order.
»»» comment string false A comment for our operators / translators
»»» specialFields [SpecialField] false [Special fields are used to add customer-specific attributes to an order, for example costCenters. Key has to be non-empty.]
»»»» key string false none
»»»» value string false none
»» estimatedDeliveryTime string false The date and time of the estimated delivery as a ISO 8601 compliant string. This attribute is not available for an order in states INVALID or CHECKING or DOCUMENT_MISSING.
»» actualDeliveryTime string false The date and time of the actual delivery as a ISO 8601 compliant string.

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

DELETE /order/{orderNumber}

Example URL: https://api.24translate.ch/api/order/{orderNumber}

Delete an order before it has been placed.

Code samples


DELETE /api/order/{orderNumber} HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.24translate.ch/api/order/{orderNumber}', headers = headers)

print(r.json())

Deletes an order by orderNumber. This can only be done if the order hasn't been placed yet.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

401 Response

{
  "items": [
    {
      "statusCode": 1999,
      "statusType": "OTHER",
      "statusMessage": "Details about the error"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK, the requested order has been deleted. None
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
412 Precondition Failed Forbidden - the status of the order is not VALID, CHECKING, INVALID or DOCUMENTS_MISSING. It is not possible to delete an order once it has been placed. StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

PATCH /order/{orderNumber}

Example URL: https://api.24translate.ch/api/order/{orderNumber}

Modify order data.

Code samples


PATCH /api/order/{orderNumber} HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Content-Type: application/json
Accept: application/json


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.patch('https://api.24translate.ch/api/order/{orderNumber}', headers = headers)

print(r.json())

Modify the basic order information.

Body parameter

{
  "sourceLanguage": "en-US",
  "targetLanguage": "de-DE",
  "specialisationCode": "mycompany_marketing",
  "productName": "mycompany_good",
  "desiredDeliveryTime": "2016-01-01T12:00:00+01:00",
  "deliveryMode": "EXPRESS",
  "securityLevel": "mycompany_public",
  "comment": "Please do not translate italic text",
  "specialFields": [
    {
      "key": "costCenters",
      "value": "CC-12345"
    }
  ]
}

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.
body body OrderRequest true Order request with basic information for an order.

Example responses

201 Response

{
  "orderNumber": "CHS-1003334"
}

Responses

Status Meaning Description Schema
200 OK OK None
201 Created The order is patched OrderResponse
400 Bad Request Invalid order input data. The body contains a list of validation errors. StatusItems
401 Unauthorized Auth failed StatusItems

Response Schema

Status Code 201: OrderResponse

Name Type Required Description.
» orderNumber OrderNumber true Order number for reference.

Status Code 400: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

POST /order/{orderNumber}/sourceDocument

Example URL: https://api.24translate.ch/api/order/{orderNumber}/sourceDocument

Add a source document to an order

Code samples


POST /order/CHS-1003334/sourceDocument HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Content-Type: multipart/form-data; boundary=6308f7b26cf95f88b92efa9b627007a8
--6308f7b26cf95f88b92efa9b627007a8
Content-Disposition: form-data; name="md5Checksum"

157220d547d9045e3a0daa0d14665f8f
--6308f7b26cf95f88b92efa9b627007a8
Content-Disposition: form-data; name="file"; filename="document.doc"
binaryData
--6308f7b26cf95f88b92efa9b627007a8--


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g'
}

files = {'file': open('document.doc','rb')}
r = requests.post('https://api.24translate.ch/api/order/CHS-1003334/sourceDocument', headers = headers, data={'md5Checksum':'25912deacc5d55528e223ec7b99705cc'}, files=files)

print(r.json())

Upload a source document for translation. You can upload one document per POST request. It is also possible to upload a zip archive containing multiple documents. You can also send an md5 checksum to ensure correct file transfer. The order status must be INVALID, DOCUMENTS_MISSING, CHECKING or VALID. File size is limited to 100 MB.

Body parameter

file: string
md5Checksum: string
itsRules: string

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.
body body object false none
» file body string(binary) true file
» md5Checksum body string false The md5 checksum of the file.
» itsRules body string false Optional parameter to specify which parts of the uploaded XML document should be translated. ITS-rules in https://www.w3.org/TR/its20/ format, <its:rules> is expected as the root element. The resulting XML should be encoded in base64.

Example responses

200 Response

{
  "documentId": 182704,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 456383,
  "status": "CHECKING",
  "statusMessage": "Checking document",
  "errorCode": null,
  "itsRulesBase64": null
}

Responses

Status Meaning Description Schema
200 OK The document metadata of the added document UploadedSourceDocumentResponse
400 Bad Request Document content is not readable or the md5 checksum failed. None
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
410 Gone The order has been deleted StatusItems
412 Precondition Failed Forbidden - the status of the order is not DOCUMENTS_MISSING, INVALID, VALID or CHECKING. StatusItems
413 Payload Too Large The file size limit is exceeded. We support files up to 100 MB max. StatusItems
415 Unsupported Media Type Unsupported file type. StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 413: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 415: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

DELETE /order/{orderNumber}/sourceDocument/{documentId}

Example URL: https://api.24translate.ch/api/order/{orderNumber}/sourceDocument/{documentId}

Delete a source document by orderNumber and documentId

Code samples


DELETE /api/order/{orderNumber}/sourceDocument/{documentId} HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.24translate.ch/api/order/{orderNumber}/sourceDocument/{documentId}', headers = headers)

print(r.json())

Deletes a source document from an order. The status of the order must be DOCUMENTS_MISSING, INVALID, VALID or CHECKING.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.
documentId path DocumentId true documentId

Example responses

401 Response

{
  "items": [
    {
      "statusCode": 1999,
      "statusType": "OTHER",
      "statusMessage": "Details about the error"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK None
401 Unauthorized Auth error StatusItems
404 Not Found The requested source document doesn't exist StatusItems
410 Gone The order has been deleted StatusItems
412 Precondition Failed Forbidden - the status of the order is not DOCUMENTS_MISSING, INVALID, VALID or CHECKING. StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /order/{orderNumber}/sourceDocuments

Example URL: https://api.24translate.ch/api/order/{orderNumber}/sourceDocuments

Get a list of source documents for an order

Code samples


GET /api/order/{orderNumber}/sourceDocuments HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/order/{orderNumber}/sourceDocuments', headers = headers)

print(r.json())

Returns a list of all the source documents referring to a given orderNumber including automatic processing status and details. Please make sure status attribute is VALID in your client code to make sure the document can be automatically processed.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

200 Response

{
  "items": [
    {
      "documentId": 182704,
      "filename": "document.doc",
      "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
      "filesize": 456383,
      "status": "INVALID",
      "statusMessage": "Automatic processing not possible. Xliff transformation failed.",
      "errorCode": 2101,
      "itsRulesBase64": "PD94bWwgdmVyc2lvbj0iMS4wIiA/Pgo8aXRzOnJ1bGVzIHZlcnNpb249IjIuMCIgeG1sbnM6aXRzPSJodHRwOi8vd3d3LnczLm9yZy8yMDA1LzExL2l0cyI+CiA8aXRzOnRyYW5zbGF0ZVJ1bGUgc2VsZWN0b3I9Ii8vaXRlbU1UIiB0cmFuc2xhdGU9InllcyIvPgogPGl0czp0cmFuc2xhdGVSdWxlIHNlbGVjdG9yPSIvL2l0ZW1OVCIgdHJhbnNsYXRlPSJubyIvPgo8L2l0czpydWxlcz4KCg=="
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List of source documents SourceDocumentResponses
204 No Content No source documents have yet been uploaded to this order. None
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
410 Gone The order has been deleted StatusItems

Response Schema

Status Code 200: SourceDocumentResponses

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous DocumentResponse false none
»»» documentId DocumentId(int32) true Document ID for reference.
»»» filename string true The filename of the document.
»»» md5Checksum string true The md5 checksum of the document.
»»» filesize integer(int32) true The filesize of the document in byte.

and

Name Type Required Description.
»» anonymous object false none
»»» status string true none
»»» statusMessage string true none
»»» errorCode integer(int32) true Error code
»»» itsRulesBase64 any true ITS-rules in https://www.w3.org/TR/its20/ format, <its:rules> is expected as the root element.

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

POST /order/{orderNumber}/referenceDocument

Example URL: https://api.24translate.ch/api/order/{orderNumber}/referenceDocument

Add a reference document to an order

Code samples


POST /api/order/{orderNumber}/referenceDocument HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Content-Type: multipart/form-data
Accept: application/json


import requests
headers = {
  'Content-Type': 'multipart/form-data',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.24translate.ch/api/order/{orderNumber}/referenceDocument', headers = headers)

print(r.json())

Upload a reference document. You can upload one per POST request. It is also possible to upload a zip archive containing multiple documents. You can also send an md5 checksum to ensure correct file transfer. The order status must be INVALID, DOCUMENTS_MISSING, CHECKING or VALID. File size is limited to 100 MB.

Body parameter

file: string
documentType: parallelText
md5Checksum: string

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.
body body object false none
» file body string(binary) true file
» documentType body ReferenceDocumentType false Type of reference document.
» md5Checksum body string false The md5 checksum of the file.

Enumerated Values

Property Value

Example responses

200 Response

{
  "documentId": 182704,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 456383,
  "documentType": "parallelText"
}

Responses

Status Meaning Description Schema
200 OK The document metadata of the added document UploadedReferenceDocumentResponse
400 Bad Request Document content is not readable or the md5 checksum failed. None
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
410 Gone The order has been deleted StatusItems
412 Precondition Failed Forbidden - the status of the order is not DOCUMENTS_MISSING, INVALID, VALID or CHECKING. StatusItems
413 Payload Too Large The file size limit is exceeded. We support files up to 100 MB max. StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 413: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

DELETE /order/{orderNumber}/referenceDocument/{documentId}

Example URL: https://api.24translate.ch/api/order/{orderNumber}/referenceDocument/{documentId}

Delete a reference document by orderNumber and documentId

Code samples


DELETE /api/order/{orderNumber}/referenceDocument/{documentId} HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.24translate.ch/api/order/{orderNumber}/referenceDocument/{documentId}', headers = headers)

print(r.json())

Deletes a reference document from an order.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.
documentId path DocumentId true documentId

Example responses

401 Response

{
  "items": [
    {
      "statusCode": 1999,
      "statusType": "OTHER",
      "statusMessage": "Details about the error"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK None
401 Unauthorized Auth error StatusItems
404 Not Found The requested reference document doesn't exist StatusItems
410 Gone The order has been deleted StatusItems
412 Precondition Failed Forbidden - the status of the order is not DOCUMENTS_MISSING, INVALID, VALID or CHECKING. StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /order/{orderNumber}/referenceDocuments

Example URL: https://api.24translate.ch/api/order/{orderNumber}/referenceDocuments

Get a list of reference documents for an order

Code samples


GET /api/order/{orderNumber}/referenceDocuments HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/order/{orderNumber}/referenceDocuments', headers = headers)

print(r.json())

Returns a list of all reference documents referring to a given orderNumber.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

200 Response

{
  "items": [
    {
      "documentId": 182704,
      "filename": "document.doc",
      "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
      "filesize": 456383,
      "documentType": "parallelText"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List of reference documents ReferenceDocumentResponses
204 No Content No reference documents have yet been uploaded to this order. None
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
410 Gone The order has been deleted StatusItems

Response Schema

Status Code 200: ReferenceDocumentResponses

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous DocumentResponse false none
»»» documentId DocumentId(int32) true Document ID for reference.
»»» filename string true The filename of the document.
»»» md5Checksum string true The md5 checksum of the document.
»»» filesize integer(int32) true The filesize of the document in byte.

and

Name Type Required Description.
»» anonymous object false none
»»» documentType ReferenceDocumentType true Type of reference document.

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

POST /order/{orderNumber}/deliverImmediately

Example URL: https://api.24translate.ch/api/order/{orderNumber}/deliverImmediately

Deliver the order immediately (test-only).

Code samples


POST /api/order/{orderNumber}/deliverImmediately HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.24translate.ch/api/order/{orderNumber}/deliverImmediately', headers = headers)

print(r.json())

To be used in test environments only. Deliver the order immediately so that you can download target documents. The response includes HTTP-header Location with the URL of the targetDocuments endpoint.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

401 Response

{
  "items": [
    {
      "statusCode": 1999,
      "statusType": "OTHER",
      "statusMessage": "Details about the error"
    }
  ]
}

Responses

Status Meaning Description Schema
201 Created OK with Location to targetDocuemtns. None
401 Unauthorized Auth error StatusItems
403 Forbidden Operation cannot be used in production environment. StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
412 Precondition Failed Forbidden - the status of the order is not WORKING. It is not possible to deliver immediately if the order has not been placed yet or has already been delivered. StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 403: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /order/{orderNumber}/status

Example URL: https://api.24translate.ch/api/order/{orderNumber}/status

Get order status by orderNumber

Code samples


GET /api/order/{orderNumber}/status HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/order/{orderNumber}/status', headers = headers)

print(r.json())

Returns the status of the order

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

200 Response

"VALID"

Responses

Status Meaning Description Schema
200 OK Returns the status of the order. OrderStatus
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
410 Gone The order has been deleted StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /order/{orderNumber}/quote

Example URL: https://api.24translate.ch/api/order/{orderNumber}/quote

Get quote by orderNumber

Code samples


GET /api/order/{orderNumber}/quote HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/order/{orderNumber}/quote', headers = headers)

print(r.json())

Returns the quote for an order as the price with detailed information. The order status must be VALID.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The order ID is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

200 Response

{
  "currency": "EUR",
  "grossAmount": 143.2,
  "minimumPrice": true,
  "netAmount": 123.45,
  "taxAmount": 19.75,
  "taxRate": 16,
  "totalDiscountPercent": 23.45,
  "volume": 0,
  "volumeType": "LINE"
}

Responses

Status Meaning Description Schema
200 OK Quote data QuoteResponse
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
412 Precondition Failed The order isn't ready yet - its status must be VALID StatusItems

Response Schema

Status Code 200: QuoteResponse

Provides information about volume and price of an order. The quote response is not available for an order in states INVALID or CHECKING or DOCUMENT_MISSING.

Name Type Required Description.
» currency string true The currency of the price.
» grossAmount number(double) true The gross amount of the offer.
» minimumPrice boolean true If 'true', this is a minimum price.
» netAmount number(double) true The net amount of the offer.
» taxAmount number(double) true The total tax amount, depending on both the net and gross amount.
» taxRate number(double) true The tax rate of the offer price.
» totalDiscountPercent number(double) true The price discount in percent based on the CAT analysis result and the customer tm discount settings.
» volume integer(int32) false Volume of all documents.
» volumeType string false TBD

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /order/{orderNumber}/info

Example URL: https://api.24translate.ch/api/order/{orderNumber}/info

Get info by orderNumber

Code samples


GET /api/order/{orderNumber}/info HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/order/{orderNumber}/info', headers = headers)

print(r.json())

Returns detailed order information. The order status must be beyond INITIAL.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The order ID is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

200 Response

{
  "attributes": {
    "sourceLanguage": "en-US",
    "targetLanguage": "de-DE",
    "specialisationCode": "mycompany_marketing",
    "productName": "mycompany_good",
    "desiredDeliveryTime": "2016-01-01T12:00:00+01:00",
    "deliveryMode": "EXPRESS",
    "securityLevel": "mycompany_public",
    "comment": "Please do not translate italic text",
    "specialFields": [
      {
        "key": "costCenters",
        "value": "CC-12345"
      }
    ]
  },
  "estimatedDeliveryTime": "2016-01-01T12:00:00+01:00",
  "actualDeliveryTime": "2016-01-01T11:59:00+01:00"
}

Responses

Status Meaning Description Schema
200 OK Order information OrderInfo
401 Unauthorized Auth error StatusItems
404 Not Found The orderNumber doesn't exist StatusItems
412 Precondition Failed The order isn't ready yet - its status is INITIAL StatusItems

Response Schema

Status Code 200: OrderInfo

Represents information about the order.

Name Type Required Description.
» attributes OrderRequest false none
»» sourceLanguage string true The BCP-47 code of the source language.
»» targetLanguage string true The BCP-47 code of the target language.
»» specialisationCode string true The specialisation of the source text. Please contact your account manager for valid inputs.
»» productName string true The name of the translation product. Please contact your account manager for valid input values.
»» desiredDeliveryTime string false The date and time of the desired delivery as a ISO 8601 compliant string. Either deliveryMode or desiredDeliveryTime attribute should be provided, but not both.
»» deliveryMode string false The different deliveryModes are used to indicate the typical delivery times. Either deliveryMode or desiredDeliveryTime attribute should be provided, but not both.
»» securityLevel string false The securityLevel refers to the security requirements necessary for the order.
»» comment string false A comment for our operators / translators
»» specialFields [SpecialField] false [Special fields are used to add customer-specific attributes to an order, for example costCenters. Key has to be non-empty.]
»»» key string false none
»»» value string false none
» estimatedDeliveryTime string false The date and time of the estimated delivery as a ISO 8601 compliant string. This attribute is not available for an order in states INVALID or CHECKING or DOCUMENT_MISSING.
» actualDeliveryTime string false The date and time of the actual delivery as a ISO 8601 compliant string.

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

PUT /order/{orderNumber}/place

Example URL: https://api.24translate.ch/api/order/{orderNumber}/place

Transfer the order request into an order

Code samples


PUT /api/order/{orderNumber}/place HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://api.24translate.ch/api/order/{orderNumber}/place', headers = headers)

print(r.json())

Transfer the order request into an order. The order status must be VALID.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

200 Response

{
  "orderNumber": "CHS-1003334"
}

Responses

Status Meaning Description Schema
200 OK The order has already been placed. The body contains the order response. OrderResponse
201 Created The order has been placed. The body contains the order response. OrderResponse
401 Unauthorized Auth error StatusItems
410 Gone The order has been deleted. StatusItems
412 Precondition Failed Precondition failed. The order status must be VALID. StatusItems
500 Internal Server Error Internal error placing the order StatusItems

Response Schema

Status Code 200: OrderResponse

Name Type Required Description.
» orderNumber OrderNumber true Order number for reference.

Status Code 201: OrderResponse

Name Type Required Description.
» orderNumber OrderNumber true Order number for reference.

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 500: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /order/{orderNumber}/targetDocuments

Example URL: https://api.24translate.ch/api/order/{orderNumber}/targetDocuments

Get a list of target documents for an order

Code samples


GET /api/order/{orderNumber}/targetDocuments HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/order/{orderNumber}/targetDocuments', headers = headers)

print(r.json())

Returns a list of all the target documents referring to a given orderNumber. The order status must be DELIVERED.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.

Example responses

200 Response

{
  "items": [
    {
      "documentId": 182704,
      "filename": "document.doc",
      "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
      "filesize": 456383,
      "uri": "https://api.24translate.ch/api/order/127770/targetDocument/223658/content",
      "sourceDocumentId": 182702
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List of target documents TargetDocumentResponses
401 Unauthorized Auth Error StatusItems
410 Gone The order has been deleted StatusItems
412 Precondition Failed Forbidden - the status of the order is not DELIVERED StatusItems

Response Schema

Status Code 200: TargetDocumentResponses

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous DocumentResponse false none
»»» documentId DocumentId(int32) true Document ID for reference.
»»» filename string true The filename of the document.
»»» md5Checksum string true The md5 checksum of the document.
»»» filesize integer(int32) true The filesize of the document in byte.

and

Name Type Required Description.
»» anonymous object false none
»»» uri string true Uri to download the translated file.
»»» sourceDocumentId SourceDocumentId(int32) true Source Document ID for reference.

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /order/{orderNumber}/targetDocument/{documentId}/content

Example URL: https://api.24translate.ch/api/order/{orderNumber}/targetDocument/{documentId}/content

Handles a document download request

Code samples


GET /api/order/{orderNumber}/targetDocument/{documentId}/content HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: */*


import requests
headers = {
  'Accept': '*/*',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/order/{orderNumber}/targetDocument/{documentId}/content', headers = headers)

print(r.json())

Download the translated document. The status of the order must be DELIVERED.

Parameters

Name In Type Required Description
orderNumber path OrderNumber true The orderNumber is a unique reference for the order request. Use POST /order to create an orderNumber.
documentId path TargetDocumentId true The documentId is a unique reference for the document.

Example responses

200 Response

401 Response

{
  "items": [
    {
      "statusCode": 1999,
      "statusType": "OTHER",
      "statusMessage": "Details about the error"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Content of the translated document. Please use http-headers Content-Type. string
401 Unauthorized Auth Error StatusItems
404 Not Found The document could not be found StatusItems
410 Gone The order has been deleted StatusItems
412 Precondition Failed Forbidden - the status of the order is not DELIVERED StatusItems
500 Internal Server Error Internal error reading the document content StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 410: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 412: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 500: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

API Reference: ping

GET /ping

Example URL: https://api.24translate.ch/api/ping

Checks the availability of the API and - if Authorization header is provided - tests the authorization

Code samples


GET /api/ping HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: string


import requests
headers = {
  'Accept': 'string',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/ping', headers = headers)

print(r.json())

Returns check result

Example responses

200 Response

401 Response

{
  "items": [
    {
      "statusCode": 1999,
      "statusType": "OTHER",
      "statusMessage": "Details about the error"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK The API is reachable PingResponse
401 Unauthorized Auth failed StatusItems

Response Schema

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

API Reference: list

GET /list/products

Example URL: https://api.24translate.ch/api/list/products

List all valid products for a customer

Code samples


GET /api/list/products HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/list/products', headers = headers)

print(r.json())

List all valid products for the customer identified by the authentication. The product code can be used in the POST /order request.

Example responses

200 Response

{
  "items": [
    {
      "code": "qs_good",
      "description": "24translate \"good\""
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List products ProductListItems
401 Unauthorized Auth error StatusItems
404 Not Found No products found StatusItems

Response Schema

Status Code 200: ProductListItems

Collection of delivery mode items.

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous ListItem false none
»»» code string false none
»»» description string false none

and

Name Type Required Description.
»» anonymous object false none
»»» code any true none
»»» description any true none

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /list/specialisations

Example URL: https://api.24translate.ch/api/list/specialisations

List all valid specialisations for a customer

Code samples


GET /api/list/specialisations HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/list/specialisations', headers = headers)

print(r.json())

List all valid specialisations for the customer identified by the authentication. The specialisation code can be used in the POST /order request.

Example responses

200 Response

{
  "items": [
    {
      "code": "mycompany_law",
      "description": "Law"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List specialisations SpecialisationListItems
401 Unauthorized Auth error StatusItems
404 Not Found No specialisations found StatusItems

Response Schema

Status Code 200: SpecialisationListItems

Collection of specialisation items.

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous ListItem false none
»»» code string false none
»»» description string false none

and

Name Type Required Description.
»» anonymous object false none
»»» code any true none
»»» description any true none

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /list/sourceLanguages

Example URL: https://api.24translate.ch/api/list/sourceLanguages

List all valid source languages for a customer

Code samples


GET /api/list/sourceLanguages HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/list/sourceLanguages', headers = headers)

print(r.json())

List all valid source languages for the customer identified by the authentication. The source language code can be used in the POST /order request.

Example responses

200 Response

{
  "items": [
    {
      "code": "en-US",
      "description": "English (US)"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List source languages LanguageListItems
401 Unauthorized Auth error StatusItems
404 Not Found No source languages found StatusItems

Response Schema

Status Code 200: LanguageListItems

Collection of language code items.

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous ListItem false none
»»» code string false none
»»» description string false none

and

Name Type Required Description.
»» anonymous object false none
»»» code any true none
»»» description any true none

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /list/targetLanguages

Example URL: https://api.24translate.ch/api/list/targetLanguages

List all valid target languages for a customer

Code samples


GET /api/list/targetLanguages HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/list/targetLanguages', headers = headers)

print(r.json())

List all valid target languages for the customer identified by the authentication. The target language code can be used in the POST /order request.

Example responses

200 Response

{
  "items": [
    {
      "code": "en-US",
      "description": "English (US)"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List target languages LanguageListItems
401 Unauthorized Auth error StatusItems
404 Not Found No target languages found StatusItems

Response Schema

Status Code 200: LanguageListItems

Collection of language code items.

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous ListItem false none
»»» code string false none
»»» description string false none

and

Name Type Required Description.
»» anonymous object false none
»»» code any true none
»»» description any true none

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /list/deliveryModes

Example URL: https://api.24translate.ch/api/list/deliveryModes

List all valid delivery modes for a customer

Code samples


GET /api/list/deliveryModes HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/list/deliveryModes', headers = headers)

print(r.json())

List all valid delivery modes for the customer identified by the authentication. The delivery mode code can be used in the POST /order request.

Example responses

200 Response

{
  "items": [
    {
      "code": "_24_HOURS",
      "description": "24h"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List delivery modes DeliveryModeListItems
401 Unauthorized Auth error StatusItems
404 Not Found No delivery modes found StatusItems

Response Schema

Status Code 200: DeliveryModeListItems

Collection of delivery mode items.

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous ListItem false none
»»» code string false none
»»» description string false none

and

Name Type Required Description.
»» anonymous object false none
»»» code any true none
»»» description any true none

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

GET /list/securityLevels

Example URL: https://api.24translate.ch/api/list/securityLevels

List all valid security levels for a customer

Code samples


GET /api/list/securityLevels HTTP/1.1
Host: api.24translate.ch
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1OTkxMjg3NDUsImlhdCI6MTU5OTEyNzc0NSwic3ViIjoiMjFhOWRkYmItM2I4YS00ZWQzLTg0YzctNGM3YmEwNjExODllIn0.xGjsZc1uu9HbumD9PcRmcjHKJenb2AQgBRLZL8xI79g
Accept: application/json


import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.24translate.ch/api/list/securityLevels', headers = headers)

print(r.json())

List all valid security levels for the customer identified by the authentication. The security levels code can be used in the POST /order request.

Example responses

200 Response

{
  "items": [
    {
      "code": "mycompany_public",
      "description": "Public"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List of all valid security levels SecurityLevelListItems
401 Unauthorized Auth error StatusItems
404 Not Found No security levels found StatusItems

Response Schema

Status Code 200: SecurityLevelListItems

Collection of security level items.

Name Type Required Description.
» items [allOf] false none

allOf

Name Type Required Description.
»» anonymous ListItem false none
»»» code string false none
»»» description string false none

and

Name Type Required Description.
»» anonymous object false none
»»» code any true none
»»» description any true none

Status Code 401: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Status Code 404: StatusItems

Collection of status items.

Name Type Required Description.
» items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]
»» statusCode integer false none
»» statusType string false none
»» statusMessage string false none

Schemas

OrderRequest

{
  "sourceLanguage": "en-US",
  "targetLanguage": "de-DE",
  "specialisationCode": "mycompany_marketing",
  "productName": "mycompany_good",
  "desiredDeliveryTime": "2016-01-01T12:00:00+01:00",
  "deliveryMode": "EXPRESS",
  "securityLevel": "mycompany_public",
  "comment": "Please do not translate italic text",
  "specialFields": [
    {
      "key": "costCenters",
      "value": "CC-12345"
    }
  ]
}

Properties

Name Type Required Description
sourceLanguage string true The BCP-47 code of the source language.
targetLanguage string true The BCP-47 code of the target language.
specialisationCode string true The specialisation of the source text. Please contact your account manager for valid inputs.
productName string true The name of the translation product. Please contact your account manager for valid input values.
desiredDeliveryTime string false The date and time of the desired delivery as a ISO 8601 compliant string. Either deliveryMode or desiredDeliveryTime attribute should be provided, but not both.
deliveryMode string false The different deliveryModes are used to indicate the typical delivery times. Either deliveryMode or desiredDeliveryTime attribute should be provided, but not both.
securityLevel string false The securityLevel refers to the security requirements necessary for the order.
comment string false A comment for our operators / translators
specialFields [SpecialField] false [Special fields are used to add customer-specific attributes to an order, for example costCenters. Key has to be non-empty.]

Enumerated Values

Property Value
deliveryMode EXPRESS
deliveryMode _24_HOURS
deliveryMode _48_HOURS
deliveryMode _3_TO_5_DAYS

OrderInfo

{
  "attributes": {
    "sourceLanguage": "en-US",
    "targetLanguage": "de-DE",
    "specialisationCode": "mycompany_marketing",
    "productName": "mycompany_good",
    "desiredDeliveryTime": "2016-01-01T12:00:00+01:00",
    "deliveryMode": "EXPRESS",
    "securityLevel": "mycompany_public",
    "comment": "Please do not translate italic text",
    "specialFields": [
      {
        "key": "costCenters",
        "value": "CC-12345"
      }
    ]
  },
  "estimatedDeliveryTime": "2016-01-01T12:00:00+01:00",
  "actualDeliveryTime": "2016-01-01T11:59:00+01:00"
}

Represents information about the order.

Properties

Name Type Required Description
attributes OrderRequest false none
estimatedDeliveryTime string false The date and time of the estimated delivery as a ISO 8601 compliant string. This attribute is not available for an order in states INVALID or CHECKING or DOCUMENT_MISSING.
actualDeliveryTime string false The date and time of the actual delivery as a ISO 8601 compliant string.

OrderStatus

"VALID"

Once you create an order, it will be in state DOCUMENTS_MISSING. You need to upload sourceDocuments in order to reach status VALID, after which you can place an an order and will transition to WORKING and later DELIVERED once targetDocuments are ready to be downloaded. Order will be ARCHIVED 3 months after the delivery date and its documents will not be available.

Properties

Name Type Required Description
anonymous string false Once you create an order, it will be in state DOCUMENTS_MISSING. You need to upload sourceDocuments in order to reach status VALID, after which you can place an an order and will transition to WORKING and later DELIVERED once targetDocuments are ready to be downloaded. Order will be ARCHIVED 3 months after the delivery date and its documents will not be available.

Enumerated Values

Value
DOCUMENTS_MISSING
CHECKING
VALID
INVALID
REJECTED
WORKING
DELIVERED
ARCHIVED

OrderFullInfo

{
  "status": "VALID",
  "quote": {
    "currency": "EUR",
    "grossAmount": 143.2,
    "minimumPrice": true,
    "netAmount": 123.45,
    "taxAmount": 19.75,
    "taxRate": 16,
    "totalDiscountPercent": 23.45,
    "volume": 0,
    "volumeType": "LINE"
  },
  "info": {
    "attributes": {
      "sourceLanguage": "en-US",
      "targetLanguage": "de-DE",
      "specialisationCode": "mycompany_marketing",
      "productName": "mycompany_good",
      "desiredDeliveryTime": "2016-01-01T12:00:00+01:00",
      "deliveryMode": "EXPRESS",
      "securityLevel": "mycompany_public",
      "comment": "Please do not translate italic text",
      "specialFields": [
        {
          "key": "costCenters",
          "value": "CC-12345"
        }
      ]
    },
    "estimatedDeliveryTime": "2016-01-01T12:00:00+01:00",
    "actualDeliveryTime": "2016-01-01T11:59:00+01:00"
  }
}

Properties

Name Type Required Description
status OrderStatus false Once you create an order, it will be in state DOCUMENTS_MISSING. You need to upload sourceDocuments in order to reach status VALID, after which you can place an an order and will transition to WORKING and later DELIVERED once targetDocuments are ready to be downloaded. Order will be ARCHIVED 3 months after the delivery date and its documents will not be available.
quote QuoteResponse false This attribute is not available for an order in states INVALID or CHECKING or DOCUMENT_MISSING.
info OrderInfo false Represents information about the order.

DocumentResponse

{
  "documentId": 182704,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 456383
}

Properties

Name Type Required Description
documentId DocumentId true Document ID for reference.
filename string true The filename of the document.
md5Checksum string true The md5 checksum of the document.
filesize integer(int32) true The filesize of the document in byte.

SourceDocumentResponse

{
  "documentId": 182704,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 456383,
  "status": "INVALID",
  "statusMessage": "Automatic processing not possible. Xliff transformation failed.",
  "errorCode": 2101,
  "itsRulesBase64": "PD94bWwgdmVyc2lvbj0iMS4wIiA/Pgo8aXRzOnJ1bGVzIHZlcnNpb249IjIuMCIgeG1sbnM6aXRzPSJodHRwOi8vd3d3LnczLm9yZy8yMDA1LzExL2l0cyI+CiA8aXRzOnRyYW5zbGF0ZVJ1bGUgc2VsZWN0b3I9Ii8vaXRlbU1UIiB0cmFuc2xhdGU9InllcyIvPgogPGl0czp0cmFuc2xhdGVSdWxlIHNlbGVjdG9yPSIvL2l0ZW1OVCIgdHJhbnNsYXRlPSJubyIvPgo8L2l0czpydWxlcz4KCg=="
}

Properties

allOf

Name Type Required Description
anonymous DocumentResponse false none

and

Name Type Required Description
anonymous object false none
» status string true none
» statusMessage string true none
» errorCode integer(int32) true Error code
» itsRulesBase64 any true ITS-rules in https://www.w3.org/TR/its20/ format, <its:rules> is expected as the root element.

Enumerated Values

Property Value
status CHECKING
status INVALID
status VALID

UploadedSourceDocumentResponse

{
  "documentId": 182704,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 456383,
  "status": "CHECKING",
  "statusMessage": "Checking document",
  "errorCode": null,
  "itsRulesBase64": null
}

Properties

allOf

Name Type Required Description
anonymous SourceDocumentResponse false none

and

Name Type Required Description
anonymous object false none
» status any true none
» statusMessage any true none
» errorCode any true none
» itsRulesBase64 any false none

UploadedReferenceDocumentResponse

{
  "documentId": 182704,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 456383,
  "documentType": "parallelText"
}

Properties

None

SourceDocumentResponses

{
  "items": [
    {
      "documentId": 182704,
      "filename": "document.doc",
      "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
      "filesize": 456383,
      "status": "INVALID",
      "statusMessage": "Automatic processing not possible. Xliff transformation failed.",
      "errorCode": 2101,
      "itsRulesBase64": "PD94bWwgdmVyc2lvbj0iMS4wIiA/Pgo8aXRzOnJ1bGVzIHZlcnNpb249IjIuMCIgeG1sbnM6aXRzPSJodHRwOi8vd3d3LnczLm9yZy8yMDA1LzExL2l0cyI+CiA8aXRzOnRyYW5zbGF0ZVJ1bGUgc2VsZWN0b3I9Ii8vaXRlbU1UIiB0cmFuc2xhdGU9InllcyIvPgogPGl0czp0cmFuc2xhdGVSdWxlIHNlbGVjdG9yPSIvL2l0ZW1OVCIgdHJhbnNsYXRlPSJubyIvPgo8L2l0czpydWxlcz4KCg=="
    }
  ]
}

Properties

Name Type Required Description
items [SourceDocumentResponse] false none

ReferenceDocumentResponse

{
  "documentId": 182704,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 456383,
  "documentType": "parallelText"
}

Properties

allOf

Name Type Required Description
anonymous DocumentResponse false none

and

Name Type Required Description
anonymous object false none
» documentType ReferenceDocumentType true Type of reference document.

TargetDocumentResponse

{
  "documentId": 182704,
  "filename": "document.doc",
  "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
  "filesize": 456383,
  "uri": "https://api.24translate.ch/api/order/127770/targetDocument/223658/content",
  "sourceDocumentId": 182702
}

Properties

allOf

Name Type Required Description
anonymous DocumentResponse false none

and

Name Type Required Description
anonymous object false none
» uri string true Uri to download the translated file.
» sourceDocumentId SourceDocumentId true documentId of the original document.

TargetDocumentResponses

{
  "items": [
    {
      "documentId": 182704,
      "filename": "document.doc",
      "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
      "filesize": 456383,
      "uri": "https://api.24translate.ch/api/order/127770/targetDocument/223658/content",
      "sourceDocumentId": 182702
    }
  ]
}

Properties

Name Type Required Description
items [TargetDocumentResponse] false none

ReferenceDocumentResponses

{
  "items": [
    {
      "documentId": 182704,
      "filename": "document.doc",
      "md5Checksum": "25912deacc5d55528e223ec7b99705cc",
      "filesize": 456383,
      "documentType": "parallelText"
    }
  ]
}

Properties

Name Type Required Description
items [ReferenceDocumentResponse] false none

QuoteResponse

{
  "currency": "EUR",
  "grossAmount": 143.2,
  "minimumPrice": true,
  "netAmount": 123.45,
  "taxAmount": 19.75,
  "taxRate": 16,
  "totalDiscountPercent": 23.45,
  "volume": 0,
  "volumeType": "LINE"
}

Provides information about volume and price of an order. The quote response is not available for an order in states INVALID or CHECKING or DOCUMENT_MISSING.

Properties

Name Type Required Description
currency string true The currency of the price.
grossAmount number(double) true The gross amount of the offer.
minimumPrice boolean true If 'true', this is a minimum price.
netAmount number(double) true The net amount of the offer.
taxAmount number(double) true The total tax amount, depending on both the net and gross amount.
taxRate number(double) true The tax rate of the offer price.
totalDiscountPercent number(double) true The price discount in percent based on the CAT analysis result and the customer tm discount settings.
volume integer(int32) false Volume of all documents.
volumeType string false TBD

Enumerated Values

Property Value
volumeType LINE
volumeType WORD
volumeType PAGE
volumeType CHARACTER

OrderResponse

{
  "orderNumber": "CHS-1003334"
}

Properties

Name Type Required Description
orderNumber OrderNumber true Order number for reference.

PingResponse

"OK"

If the endpoint is called without "Authorization" header, returns "OK". If called with valid Authorization, returns "AUTHENTICATED".

Properties

Name Type Required Description
anonymous string false If the endpoint is called without "Authorization" header, returns "OK". If called with valid Authorization, returns "AUTHENTICATED".

Enumerated Values

Value
OK
AUTHENTICATED

StatusItem

{
  "statusCode": 1999,
  "statusType": "OTHER",
  "statusMessage": "Details about the error"
}

A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.

Properties

Name Type Required Description
statusCode integer false none
statusType string false none
statusMessage string false none

Enumerated Values

Property Value
statusType EMPTY_SOURCE_LANGUAGE
statusType EMPTY_PRODUCT
statusType EMPTY_TARGET_LANGUAGE
statusType EMPTY_SPECIALISATION
statusType INVALID_SOURCE_LANGUAGE
statusType INVALID_TARGET_LANGUAGE
statusType INVALID_LANGUAGE_COMBINATION
statusType INVALID_SPECIALISATION
statusType INVALID_DELIVERY_TIME
statusType INVALID_DELIVERY_TIME_FORMAT
statusType INVALID_DELIVERY_MODE
statusType INVALID_PRODUCT
statusType INVALID_SECURITY_LEVEL
statusType SOURCE_DOCUMENTS_NOT_VALID
statusType OTHER
statusType LIST_NO_PRODUCTS

StatusItems

{
  "items": [
    {
      "statusCode": 1999,
      "statusType": "OTHER",
      "statusMessage": "Details about the error"
    }
  ]
}

Collection of status items.

Properties

Name Type Required Description
items [StatusItem] false [A status item represents an error message or any other status, about which the user should know. statusType can be considered as a limited set of messages, with multiple statusCodes used under the same statusType and statusMessage provides details in a natural language.]

ListItem

{
  "code": "qs_good",
  "description": "24translate \"good\""
}

Properties

Name Type Required Description
code string false none
description string false none

DeliveryModeListItem

{
  "code": "_24_HOURS",
  "description": "24h"
}

Properties

allOf

Name Type Required Description
anonymous ListItem false none

and

Name Type Required Description
anonymous object false none
» code any true none
» description any true none

ProductListItem

{
  "code": "qs_good",
  "description": "24translate \"good\""
}

Properties

allOf

Name Type Required Description
anonymous ListItem false none

and

Name Type Required Description
anonymous object false none
» code any true none
» description any true none

SpecialisationListItem

{
  "code": "mycompany_law",
  "description": "Law"
}

Properties

allOf

Name Type Required Description
anonymous ListItem false none

and

Name Type Required Description
anonymous object false none
» code any true none
» description any true none

LanguageListItem

{
  "code": "en-US",
  "description": "English (US)"
}

Properties

allOf

Name Type Required Description
anonymous ListItem false none

and

Name Type Required Description
anonymous object false none
» code any true none
» description any true none

SecurityLevelListItem

{
  "code": "mycompany_public",
  "description": "Public"
}

Properties

allOf

Name Type Required Description
anonymous ListItem false none

and

Name Type Required Description
anonymous object false none
» code any true none
» description any true none

ListItems

{
  "items": [
    {
      "code": "qs_good",
      "description": "24translate \"good\""
    }
  ]
}

Collection of list items.

Properties

Name Type Required Description
items [ListItem] false none

DeliveryModeListItems

{
  "items": [
    {
      "code": "_24_HOURS",
      "description": "24h"
    }
  ]
}

Collection of delivery mode items.

Properties

Name Type Required Description
items [DeliveryModeListItem] false none

ProductListItems

{
  "items": [
    {
      "code": "qs_good",
      "description": "24translate \"good\""
    }
  ]
}

Collection of delivery mode items.

Properties

Name Type Required Description
items [ProductListItem] false none

SpecialisationListItems

{
  "items": [
    {
      "code": "mycompany_law",
      "description": "Law"
    }
  ]
}

Collection of specialisation items.

Properties

Name Type Required Description
items [SpecialisationListItem] false none

LanguageListItems

{
  "items": [
    {
      "code": "en-US",
      "description": "English (US)"
    }
  ]
}

Collection of language code items.

Properties

Name Type Required Description
items [LanguageListItem] false none

SecurityLevelListItems

{
  "items": [
    {
      "code": "mycompany_public",
      "description": "Public"
    }
  ]
}

Collection of security level items.

Properties

Name Type Required Description
items [SecurityLevelListItem] false none

SpecialField

{
  "key": "costCenters",
  "value": "CC-12345"
}

Special fields are used to add customer-specific attributes to an order, for example costCenters. Key has to be non-empty.

Properties

Name Type Required Description
key string false none
value string false none

OrderNumber

"CHS-1003334"

Order number for reference.

Properties

Name Type Required Description
anonymous string false Order number for reference.

SourceDocumentId

182702

Source Document ID for reference.

Properties

Name Type Required Description
anonymous integer(int32) false Source Document ID for reference.

DocumentId

182704

Document ID for reference.

Properties

Name Type Required Description
anonymous integer(int32) false Document ID for reference.

TargetDocumentId

182705

Document ID for reference.

Properties

Name Type Required Description
anonymous integer(int32) false Document ID for reference.

ReferenceDocumentType

"parallelText"

Type of reference document.

Properties

Name Type Required Description
anonymous string false Type of reference document.

Enumerated Values

Value
translationMemory
glossary
parallelText
originalSourceDocument
styleGuide
miscellaneous