API docs by Redocly

TC.gate API (v1)

Download OpenAPI specification:Download

URL: https://trendcommerce.ch/

Introduction

You can access our API with the following URL:

https://api.tcgate.ch (PROD)
https://api-test.tcgate.ch (TEST)
https://api-sandbox.tcgate.ch (SANDBOX)

You can test our API with Swagger on following URL:

https://api-test.tcgate.ch/swagger/index.html (TEST)
https://api-sandbox.tcgate.ch/swagger/index.html (SANDBOX)

Back to top

Authentication

Every request has to be authenticated with a Bearer token using an Authorization header in the format:

Authorization: Bearer {token}

A token will assigned to the customer during our onboarding-process [settings->onboarding].

Clients who have the password can create their own tokens for daily use. Token Generation

Back to top

Webhooks

With Tc.gate Webhooks you can subscribe to events and get notified your application when an event happens in Tc.gate. Rather than making an API call when an event happens, Tc.gate webhooks provides this information by doing a POST request to one or more HTTPS endpoints on your server. You can subscribe the events or change the subscription by contacting your Key Account Manager.

Back to top

Webhook URL Requirements

To handle events delivered to your webhook url below requirements must be implemented within your application;

  • Webhook URLs must accept HTTPS connections using TLS v1.2 or higher.
  • Webhook URLs must accept POST requests.
  • Tc.gate will accept any 2XX status code as a successful delivery.

Back to top

Webhook Subscriptions

You can subscribe to what kind of events you want to receive. Below mentioned events are currently available for the webhooks.

OrderAcceptedEvent ORDER

Indicates that order validation is successful.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96530",
   "eventType":"OrderAcceptedEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "orderNumber":"ACME-ORDER-000-000-477-TERM"
   }
}

Back to top

OrderExecutingEvent ORDER

The order execution started.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96528",
   "eventType":"OrderExecutingEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "orderNumber":"ACME-ORDER-000-000-477-TERM"
   }
}

Back to top

OrderChannelInvocationTriggeredEvent ORDER

The channel execution for an order triggered.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96529",
   "eventType":"OrderChannelInvocationTriggeredEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "orderNumber":"ACME-ORDER-000-000-477-TERM",
      "channel":"PRINT",
      "documentNumbers":[
         "DOC1",
         "DOC2"
      ]
   }
}

Back to top

OrderExecutedEvent ORDER

The order has been executed.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96527",
   "eventType":"OrderExecutedEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "orderNumber":"ACME-ORDER-000-000-477-TERM"
   }
}

Back to top

EmailBouncedEvent E-MAIL

The e-mail could not be sent because the recipient's mailbox is full, or recipient's email address or mail server are invalid or nonexistent.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96521",
   "eventType":"EmailBouncedEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "emailId":"XXX",
      "emailAddress":"john@doe.com",
      "error":"Mailbox is full",
      "orderNumber":"ACME-ORDER-000-000-477-TERM",
      "documentNumbers":[
         "DOC1",
         "DOC2"
      ]
   }
}

Back to top

EmailBlockedEvent E-MAIL

The e-mail has been rejected by the recipient's mail server.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96522",
   "eventType":"EmailBlockedEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "emailId":"XXX",
      "emailAddress":"john@doe.com",
      "error":"rejected by the recipient's mail server",
      "orderNumber":"ACME-ORDER-000-000-477-TERM",
      "documentNumbers":[
         "DOC1",
         "DOC2"
      ]
   }
}

Back to top

EmailSentEvent E-MAIL

The e-mail has been sent successfully.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96523",
   "eventType":"EmailSentEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "emailId":"XXX",
      "emailAddress":"john@doe.com",      
      "orderNumber":"ACME-ORDER-000-000-477-TERM",
      "documentNumbers":[
         "DOC1",
         "DOC2"
      ]
   }
}

Back to top

PrintDeliveredEvent PRINT

Defines an event where a tracked print has been delivered.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96525",
   "eventType":"PrintDeliveredEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "printId":"XXXXX",
      "provider":"TRENDCOMMERCE",            
      "trackingId":"XXXXX",
      "documentNumbers":[
         "DOC1",
         "DOC2"
      ]
   }
}

Back to top

PrintNotDeliveredEvent PRINT

Defines an event where a tracked print has not been delivered.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96526",
   "eventType":"PrintNotDeliveredEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "printId":"XXXXX",
      "provider":"TRENDCOMMERCE",            
      "trackingId":"XXXXX",
      "documentNumbers":[
         "DOC1",
         "DOC2"
      ]
   }
}

Back to top

PrintSentEvent PRINT

Defines an event when a print job has been sent.

Request Payload

Below is an example of event request body:

{
   "tenantId":"tripoli",
   "clientId":"ACME",
   "eventId":"96524",
   "eventType":"PrintSentEvent",
   "timestamp":"2022-07-29T21:24:44.3776025Z",
   "metadata":{
      "printId":"XXXXX",
      "jobId":"XXX",      
      "orderNumber":"ACME-ORDER-000-000-477-TERM",
      "shipmentId":"XXXXX",
      "trackingId":"XXXXX",
      "documentNumbers":[
         "DOC1",
         "DOC2"
      ]
   }
}

Back to top

Status codes for Webhooks & Retry Policy

For a successful delivery, we'll accept any 2XX status code. Any other code or message is counted as a failure, which means the retry logic will commence.

If your service (webhook url) has problems handling notifications at any time, we will attempt to re-send failed notifications for 15 minutes.

Back to top

X-Tcgate-Signature Header

Webhook requests include a signature header so that you know the request was sent from Tc.gate. The header name is X-Tcgate-Signature and the value is a SHA-256 encoded hash. Verifing this signature when you receive a request is strongly recommended.

To validate the webhook signature;

  • Concatenate the following string together: TCGATE_SIGNATURE= + request body
  • Create a SHA-256 hash of the resulting string.
  • Compare the hash value to the value of the X-Tcgate-Signature header:
    • If they're equal then this request has passed validation.
    • If these values do not match, then this request may have been tampered with in-transit or someone may be spoofing requests to your endpoint.

Back to top

Best Practices

Events are not guaranteed to be delivered only once. To avoid duplicates if your endpoints receive multiple copies of a single event (by eventId), we recommend that you make your event processing idempotent. For example, you can log processed events, and make sure that your application does not reprocess events that have already been logged.

Back to top

Definitions

Document Status

Status Name Type Source Description
created Document POST Upload Document When the POST request sent for the document and if the pre-validation is done the document status will be marked as created and you will have response as "202 - Created". Then, the validation process runs asyncronously.
accepted Document ASYNC Document Validation Depending on result of the async validation process, the document will be marked as accepted if no findings found.
rejected Document ASYNC Document Validation Depending on result of the async validation process, the document will be marked as rejected if any findings found.
acknowledged PRINT / EMAIL Postal & Email Service Channel is defined and document is in backlog to process.
printing PRINT Postal Service Document is printing.
sent PRINT / EMAIL Postal & Email Service Documet is delivered via the selected channel.
tracked PRINT Postal Service The shipment containing the document had its postal tracking information updated. Only available for documents sent via registered mail.
delivered PRINT Postal Service The shipment containing the document has been delivered successfully.Only available for documents sent via registered mail.
notdelivered PRINT Postal Service The shipment containing the document could not be delivered.Only available for documents sent via registered mail.
bounced EMAIL Email Service Email is bounced.
blocked EMAIL Email Service Email is blocked.

Back to top

Order Status

Status Name Type Source Description
placed Order POST Place Order When the POST request sent to place an order and if the pre-validation is done the order status will be marked as placed and you will have response as "202 - Created". Then, the validation process runs asyncronously.
accepted Order ASYNC Order Validation Depending on result of the async validation process, the document will be marked as accepted if no findings found.
rejected Order ASYNC Order Validation Depending on result of the async validation process, the document will be marked as rejected if any findings found.
scheduled Order ASYNC Order Processing Order will be marked as scheduled if the "scheduleOn" is defined.
executing Order ASYNC Order Processing Order is processig via selected channel.
executed Order ASYNC Order Processing All documents linked to the order are processed.

Back to top

Frequently Asked Questions

  1. Does each document have to be uploaded separately?
  • Yes, each document have to be uploaded separately.
  1. What can I do when I have sent order/document which needs to be updated?
  • For document, there is no update functionality but if the document is not linked with an order it's possible to send DELETE request and POST again.
  • For order, if the order configured as "scheduled" then it's possible to change the scheduleOn with PATCH request or DELETE and send POST request again.
  • For any other cases when you have to update or delete any order or document please contact with support.
  1. Is there a method where we can upload a document and a order at the same time?
  • No, first the document needs to be uploaded then you can place an order.
  1. Which are the different status of an order or a document?
  1. How can we track if the document is sent? or how do we see if an email bounced and therefore the reason?
  • For email, you can see the status of the document via GET request. If the status is "bounced" or "blocked" then you can see the reason via GET request.
  • For print, you can see the status of the document via GET request. If the status is "sent" then you can see the tracking id via GET request.
  1. When do we have to provide the addressLines?

Postal address is for the print channel. It is required when you want to send document with following settings;

{
...
   "settings":{
      "print":{
         "coversheet":true
          ...
      }
   }
...
}

or

{
...
   "settings":{
      "print":{
         "bundling":true
          ....
      }
   }
...
}

or

If the document contains more than 80 pages (parcels).

  1. What happens when we upload a document?
  • When you upload a document, your data goes through a series of async validation processes. After these processes are completed your document reach a status. Ref: Document Status.
  1. What happens when we place an order?
  • When you place an order, your data goes through a series of validation processes, scheduling (if it is configured) and executing events.
    • Step 1: Your POST request will be validated synchronously (e.g: json schema and the request body).
      • If your request isn't validated successfully against the valid schema definitions the response is HTTP status code "400 Bad Request".
      • If the request is valid, Tc.gate will send back HTTP response "201 Created". And it means the order is placed and ready for the next steps.
    • Step 2: Asynchronously validation process runs immediately after the order is placed. The order status will be changed with the result of validations.
      • Note: To track the order status, you must sent a GET request with your "order number".
      • If the validations are failed, your order status will be "rejected".
      • If the validations are successfull, your order status will be "accepted" and it's ready for channel execution.
    • Step 3: Your order will be executed with the channel you have selected. You can see the order status definitions in Order Status table.
  1. What happens using the api-sandbox? Difference to the api-test?
Base Url Environment Scope Description
https://api-sandbox.tcgate.ch Sandbox Development (Tripoli) This is for integration and connectivity testing. The lifetime of the documents /orders is 10 minutes. It will simulate the feedback status.
https://api-test.tcgate.ch Test Test/Integration (Athens) It's for production-ready tests. E-Mails won't be send actually, if the given e-mail addresses are not whitelisted. Print will be processed if requested.
https://api.tcgate.ch Production Production (Olympus)
  1. What about handling special characters?
  • It is possible to use non-ASCII Unicode characters.
  1. Is there any example code of implementation?
  • Yes, please ask the customer support.
  1. Do you have file size limitations of uploading a document?
  • Sending over the e-mail channel the file size limit is 7mb and for the print channel the file size limit is 10mb.
  1. What is the recommended standard to send the PDF?
  • PDF profile (highly recommended): preferably PDF/X-1a (no transparencies, no layers); PDF/A-2b; PDF/X-4 etc.
  • Fonts: embedded or converted to paths
  • Image resolution: 300 dpi
  • Color profile (recommendation): ICC ISO Coates v2 300% or CMYK PSO coated v3
  • Format: A4 (210 x 297 mm / portrait)
  • Note: If the fonts are not embedded, our service attempts do this automatically (no guarantee regarding layout shifts).

Back to top

Documents

Upload Document

You can upload a new document with the following URL:

POST /documents

The request should be in multipart/form-data format with a boundary between the document in binary format(application/pdf) and the document metadata(application/json).

Authorizations:
Bearer
header Parameters
Operation-ID
string

An optional unique string used to identify the operation. If provided, the id must be unique among all operations.

Request Body schema: multipart/form-data
document
required
string <binary>

Upload document with a PDF file.

required
object (CreateDocumentRequest)

The additional information consumed by the data of documents.

type
required
string non-empty

Examples: "TERM" "STANDARD" "AHVUVG"
Type of the document.

required
object (CreateDocumentRequestSettings)

Containing one or several channels with specific settings.

object (CreateDocumentRequestPrintSettings)

Settings for print channel.

bundlingId
string or null [ 0 .. 36 ]

Default: null
Example: "RECIPIENT-123-456"
Bundling id of the document when bundling. Documents with the same bundling id are bundled into one shipment. Documents without a bundling id are bundled by shipping address instead.

bundlingIndex
integer or null <int32>

Default: Maximum Integer Value
Examples: 1 2 3
Position of the document in its bundle when bundling. Documents without a bundling index come last.

object (CreateDocumentRequestPrintSettingsShippingAddress)

Containing the address lines for a postal delivery.

object (CreateDocumentRequestPrintSettingsPages)

Represents the page information about the document.

object (CreateDocumentRequestEmailSettings)

Settings for email channel.

to
required
Array of strings

Represents the email address(es) to which the email will be sent. Can either be a single address or a list of addresses.

Examples:

  • Single: 

    {
  "to": "single_recipient@provider.ch"
}

  • Multiple: 

    {
  "to": [
      "recipient1@provider.ch",
      "recipient2@provider.ch"
  ]
}
cc
Array of strings or null

Email address(es), to which the email will be sent to as a carbon copy. Can either be a single address or a list of addresses.

Examples:

  • Single: 

    {
  "cc": "single_recipient@provider.ch"
}

  • Multiple: 

    {
  "cc": [
      "recipient3@provider.ch",
      "recipient4@provider.ch"
  ]
}
bcc
Array of strings or null

Email address(es), to which the email will be sent to as a blind carbon copy. Can either be a single address or a list of addresses.

Examples:

  • Single: 

    {
  "bcc": "single_recipient@provider.ch"
}

  • Multiple: 

    {
  "bcc": [
      "recipient5@provider.ch",
      "recipient6@provider.ch"
  ]
}
object or null

The additional information consumed by the data of documents.

clientReference
string or null

Default: null
Example: "REF-123-456-789"
Optional client reference for the document, e.g. contract number or client id.

Responses

Request samples 

{
  "type": "TERM",
  "clientReference": "REF-123-456-789",
  "settings": {
    "print": {
      "bundlingId": "RECIPIENT-123-456",
      "bundlingIndex": 1,
      "shipping": {
        "addressLines": [
          "Bob Smith",
          "Zypressenstrasse 15",
          "8080 Zurich"
        ],
        "countryCode": "CH"
      },
      "pages": {
        "type": "White",
        "dmcPosition": "bottom",
        "duplex": true,
        "punch": true,
        "folding": true,
        "pageDefinitions": [{
            "number": 2,
            "type": "ESR",
            "plex": "front"
          },
          {
    "number": 3,
            "plex": "front"
          }
        ]
      }
    },
    "email": {
    "to": [
        "bob.smith@work.ch"
      ]
    }
  }
}

Response samples

Content type
application/json
{ }

List/Query Documents

Returns the collection of documents matching the specified OData queryOptions (provided as query string parameters $filter etc.).

You can list documents with the following URL:

GET /documents

You can also query the list using OData query options:

GET /documents?$filter={filter}&$orderby={orderby}&$top={top}&$skip={skip}

Request Query Parameters

Name Type Required Default Options/Examples Description
$filter string no null e.g. type eq 'TERM' and year(created) eq 2022 Only return documents matching the specified filter criteria.
$orderby string no null e.g. number desc Order the returned documents by the specified properties.
$top int no 100 e.g. 20 Return at most the specified number of documents.
$skip int no 0 e.g. 100 Skip the specified number of documents and do not include them in the result.

The $filter and $orderby options may use any of the following document properties:

Name Type Filter Example
number string e.g. startswith(number, 'CUST-DOC-000-002')
type string e.g. type eq 'TERM'
status string e.g. status eq 'bounced'
channel string e.g. channel eq 'email'
clientReference string e.g. contains(clientReference, 'REF-123')
linkedOrderNumber string e.g. linkedOrderNumber eq 'CUST-ORDER-000-000-326-TERM'
created datetime e.g. created gt 2022-01-01T00:00:00Z or year(created) eq 2022
Authorizations:
Bearer
query Parameters
$filter
string

Filters the results using OData syntax.

$orderby
string

Orders the results using OData syntax.

$skip
string

Indicates the number of results to skip.

$top
string

Indicates the number of results to return.

Responses

Response samples

Content type
application/json
{}

List Registered Mail Documents

You can list documents that were sent as registered mail in the last 7 days with the following URL:

GET /documents/registered

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{}

List Bounced Email Documents

You can list documents that were sent as email and bounced(i.e.were rejected by the recipient) in the last 7 days with the following URL:

GET /documents/bounced

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{}

Get Document

You can get a document with the following URL:

GET /documents/{documentNumber}

Response Body Events

Channel Type Description
print acknowledged The document is being processed for printing.
print printing The document is printing.
print sent The shipment containing the document has been sent to the postal mail provider.The event metadata may contain tracking information for registered mail.
print tracked The shipment containing the document had its postal tracking information updated. Only available for documents sent via registered mail.
print delivered The shipment containing the document has been delivered successfully.Only available for documents sent via registered mail.
print notdelivered The shipment containing the document could not be delivered.Only available for documents sent via registered mail.
email acknowledged The document is being processed for emailing.
email rejected The document failed to be processed for emailing.The event metadata may contain additional information.
email sent The email containing the document has been sent to the email provider.
email blocked The email containing the document was rejected by the email provider. The event metadata may contain additional information.
email bounced The email containing the document could not be delivered.The event metadata may contain additional information.
Authorizations:
Bearer
path Parameters
documentNumber
required
string

The number of the document. e.g. "TRENDCOMMERCE-DOC-000-000-300-TERM"

Responses

Response samples

Content type
application/json
{
  • "number": "CUST-DOC-000-000-001-TERM",
  • "type": "TERM",
  • "status": "sent",
  • "channel": "print",
  • "clientReference": "REF-123-456-789",
  • "events": [
    ],
  • "linkedOrderNumber": "CUST-ORDER-000-000-326-TERM",
  • "linkedOrderUrl": "https://api.tcgate.ch/orders/CUST-ORDER-000-000-326-TERM",
  • "settings": {
    },
  • "pdf": {
    },
  • "created": "2024-01-08T08:23:46.6271501Z",
  • "lastUpdated": "2024-01-08T08:23:46.6271506Z"
}

Delete Document

You can delete an existing document with the following URL:

DELETE /documents/{documentNumber}

Authorizations:
Bearer
path Parameters
documentNumber
required
string

The number of the document. e.g. "TRENDCOMMERCE-DOC-000-000-300-TERM"

header Parameters
Operation-ID
string

An optional unique string used to identify the operation. If provided, the id must be unique among all operations.

Responses

Response samples

Content type
application/json
{}

Download Document

You can download a document PDF with the following URL:

GET /documents/{documentNumber}/pdf

Authorizations:
Bearer
path Parameters
documentNumber
required
string

The number of the document. e.g. "TRENDCOMMERCE-DOC-000-000-300-TERM"

Responses

Response samples

Content type
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Error detail.",
  "instance": "00-0badd479a3011b4db451c16f5c8f7fda-eb0e72a4ec6e7c40-00"
}

Orders

Place Order

You can place an order with the following URL:

POST /orders

Authorizations:
Bearer
header Parameters
Operation-ID
string

An optional unique string used to identify the operation. If provided, the id must be unique among all operations.

Request Body schema:
required
experience
required
string non-empty

Enum: "PRINT" "EMAIL" "X-CHANNEL-EMAIL-PRINT"
Processing experience.

sla
required
string non-empty

Examples: "DAILY" "MONTHLY" "TERM" "MIXDOCUMENT"
Service level agreement.

scheduleOn
string or null

Default: null
Example: "2012-04-23"
The order is retained up to and including that date.

documents
required
Array of strings

Example: "TRENDCOMMERCE-DOC-000-000-300-TERM"
The linked documents (URLs -or- IDs).

required
object (CreateOrderRequestSettings)

Containing one or several channels with specific settings.

object (CreateOrderRequestEmailSettings)

Containing "template" and "from" data.

from
string or null

Default: null
Example: "noreply@tcgate.ch"
Sender email address.

template
string or null

Default: null
Example: "test-01-en"
Email template to use.

object or null

Additional metadata for the email.

property name*
additional property
string or null
object (CreateOrderRequestPrintSettings)

Containing "bundling", "coversheet", "shipping", and "supplements" data.

bundling
boolean or null

Default: false
Enum: true false
Bundles documents with identical bundling ids/addresses into one shipment.

coversheet
boolean or null

Default: false
Enum: true false
Coversheet for each document.

supplements
Array of strings or null

Default: null
Example: "["report-1"]"
The supplements to add to the printing.

object (CreateOrderRequestPrintShipping)

Represents the shipping information for print order.

method
string or null

The shipping method to use. Default: "B2"

ID Description
A A-Mail Standard letter (A-Post Priority)
B1 B-Post Standard single (B-Post Einzelversand)
B2 B2 Bulk Mail (B-Post Massenversand)
AP Recorded Post (A-Post-Plus). Requires an additional franking licence.
R Registered Post. Requires an additional franking licence.
object (CreateOrderRequestDataMatrixCode)

Represents the shipping data matrix information for print order.

clientReference
string or null

Default: null
Example: "TERM-2021-EOY"
Optional client reference for the order, e.g. internal order id.

Responses

Request samples

Content type
{
  • "experience": "X-CHANNEL-EMAIL-PRINT",
  • "sla": "DAILY",
  • "scheduleOn": "2023-08-01",
  • "documents": [
    ],
  • "settings": {
    },
  • "clientReference": "DAILY-2021-EOY"
}

Response samples

Content type
application/json
{}

List/Query Orders

Returns the collection of orders matching the specified OData queryOptions (provided as query string parameters $filter etc.).

You can list orders with the following URL:

GET /orders

You can also query the list using OData query options:

GET /orders?$filter={filter}&$orderby={orderby}&$top={top}&$skip={skip}

Request Query Parameters

Name Type Required Default Options/Examples Description
$filter string no null e.g. type eq 'TERM' and year(created) eq 2022 Only return orders matching the specified filter criteria.
$orderby string no null e.g. number desc Order the returned orders by the specified properties.
$top int no 100 e.g. 20 Return at most the specified number of orders.
$skip int no 0 e.g. 100 Skip the specified number of orders and do not include them in the result.

The $filter and $orderby options may use any of the following document properties:

Name Type Filter Example
number string e.g. startswith(number, 'CUST-DOC-000-002')
sla string e.g. sla eq 'TERM'
experience string e.g. experience eq 'X-CHANNEL-EMAIL-PRINT'
status string e.g. status eq 'executing'
scheduleOn datetime e.g. scheduleOn lt 2022-06-01T00:00:00Z or scheduleOn eq null
clientReference string e.g. contains(clientReference, 'EOY')
created datetime e.g. created gt 2022-01-01T00:00:00Z or year(created) eq 2022
Authorizations:
Bearer
query Parameters
$filter
string

Filters the results using OData syntax.

$orderby
string

Orders the results using OData syntax.

$skip
string

Indicates the number of results to skip.

$top
string

Indicates the number of results to return.

Responses

Response samples

Content type
application/json
{}

Get Order

You can get an order with the following URL:

GET /orders/{orderNumber}

Response Body Events

Channel Type Description
print processed The order has been processed via the print channel for the documents indicated.
email processed The order has been processed via the email channel for the documents indicated.
Authorizations:
Bearer
path Parameters
orderNumber
required
string

The number of the order. e.g. "TRENDCOMMERCE-ORDER-000-000-300-TERM"

Responses

Response samples

Content type
application/json
{
  • "number": "CUST-ORDER-000-000-001-TERM",
  • "experience": "PRINT",
  • "sla": "TERM",
  • "status": "executing",
  • "clientReference": "TERM-2021-EOY",
  • "events": [
    ],
  • "documents": [
    ],
  • "documentsUrl": "https://api.tcgate.ch/orders/CUST-ORDER-000-000-001-TERM/documents",
  • "settings": {
    },
  • "scheduleOn": "2022-08-01",
  • "created": "2024-01-08T08:23:46.6719595Z",
  • "lastUpdated": "2024-01-08T08:23:46.67196Z"
}

Patch Order

You can patch an order with the following URL:

PATCH /orders/{orderNumber}

Below is example of an order rescheduling request body:

{
    "scheduleOn": "2021-09-21T12:05:00.511Z"
}
Authorizations:
Bearer
path Parameters
orderNumber
required
string

The number of the order

header Parameters
Operation-ID
string

An optional unique string used to identify the operation. If provided, the id must be unique among all operations.

Request Body schema:
scheduleOn
string or null

Responses

Request samples

Content type
{
  • "scheduleOn": "2021-09-21T12:05:00.511Z"
}

Response samples

Content type
application/json
{}

Delete Order

You can delete an existing order with the following URL:

DELETE /orders/{orderNumber}

Authorizations:
Bearer
path Parameters
orderNumber
required
string

The number of the order. e.g. "TRENDCOMMERCE-ORDER-000-000-300-TERM"

header Parameters
Operation-ID
string

An optional unique string used to identify the operation. If provided, the id must be unique among all operations.

Responses

Response samples

Content type
application/json
{}

Get Order Documents

Returns the collection of documents for the order with the specified order number.

You can get the collection of documents for the order with the following URL:

GET /orders/{orderNumber}/documents

Authorizations:
Bearer
path Parameters
orderNumber
required
string

The number of the order. e.g. "TRENDCOMMERCE-ORDER-000-000-300-TERM"

Responses

Response samples

Content type
application/json
{}

Token

Generate Token

This API endpoint is used to generate a JSON Web Token (JWT) for the clients that have provided the correct client id, secret, and tenant.

POST /token/generateToken


Below is example of generating token request body:

{
    "ClientId": "ABC123",
    "Secret": "Ab!c12dD34",
    "Tenant": "Tripoli"
}
Authorizations:
Bearer
header Parameters
Operation-ID
string

An optional unique string used to identify the operation. If provided, the id must be unique among all operations.

Request Body schema: multipart/form-data
clientId
required
string^[a-zA-Z0-9]{1,6}$

Example: "MyClientId"
The unique identifier for the client.

Secret
required
string <password>

Example: "Ab!c12dD34"
The client's secret used for authentication. This parameter is case-sensitive and should not be exposed publicly.

Tenant
required
string

Example: "Tripoli"
You should create the token according to the environment you want to use.

Responses

Response samples

Content type
application/json
{
  • "clientId": "ABC123",
  • "bearerToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQiOiAiQUJDMTIzIiwidGVuYW50IjoiVGVuYW50MSIsInJvbGUiOiAiQWRtaW5pc3RyYXRvciIsImVudiI6ICJEZXZlbG9wbWVudCIsImlhdCI6MTY0OTg3MzEyNSwiZXhwIjoxNjUwMTMzMzI1LCJpc3MiOiAidGMiLCJhdWQiOiAiYXBpIn0._1n8QTpYfsn9EqM04db2DukvL8_3BhJECwHBE1kiPF4",
  • "validTo": "2024-01-08T08:23:46.6856892Z"
}