Articles on: Integration

Overview

This document outlines the integration process between Transcy and third-party applications. It covers authentication, key formatting rules, required APIs, and webhook flows for seamless data exchange and translation management.

By following this guide, third-party apps can securely exchange data with Transcy, ensure translation consistency, and maintain synchronization of integration status through webhooks.

Diagram Overview & Integration Flow

Overview Interaction Flow between Transcy x 3rd-Party App with integration

See full diagram here

The integration between a User, a Third-Party App, and Transcy follows this sequence:

User enables integration from both apps.
Third-Party App sends an integration request to Transcy.
Transcy confirms the integration status via webhook.
Third-Party App exposes resources for Transcy to fetch.
Transcy translated the resources from the original languages to all destination languages.
Third-Party App retrieves translations and available languages from Transcy.
Any Updates and uninstall events are communicated through webhooks.

Authorization Token & Resource Key Format

Token

Transcy provides each third-party app with a secret key.

The third-party app uses this key to generate tokens for secure interaction with Transcy.

Please contact your partnership manager for the configuration environment, including the Secret Key, End-Point, and sandbox settings.

Token Payload Example

{
  "shop_id": "bigInt",
  "app_name": "transcy/bogos"
}

If the token originates from Transcy, the app_name value will be transcy.
For other apps, replace accordingly.

Resource Key Format

Keys must follow a hierarchical, dot-notation structure to ensure proper grouping in menus.

Keys must contain at least one dot (.).
Items with the same prefix will be grouped together.

Example

om_navigation.side_menu.item1
om_navigation.side_menu.item2
om_navigation.side_menu.item3
om_block.text_paragraph1_content

These keys will be displayed in Transcy Interface as:

OneMobile

om_navigation
- side_menu.item1
- side_menu.item2
- side_menu.item3
om_block
- text_paragraph1_content

Naming Convention Recommendation for Resource Key

The end-user will see only the Resource Key in the manage translation panel of Transcy. Therefore, clearly naming the resource key enhances user experience and prevents confusion about which content/key corresponds to the correct phrase for translation.

DO:

Ensure the resource key is meaningful and understandable.
Indicate which part of the app or section the resource key belongs to.
Group resource keys by function, feature, page, or section of the app.

DON'T:

Use multiple resource keys at the same level with identical content.
Create meaningless resource keys (e.g., key1, key2, key3).
Include too many resource keys at the same level without grouping.
Include settings or configurations in the content, as this can lead to misconfiguration of your app

API & Webhook by 3rd-Party App consumed by Transcy

API Get Resource Data

Description: Transcy retrieves resources from third-party apps, allowing users to manage its translations.
Method: GET
Endpoint: {third_app_url}/api/transcy/resources
Headers:

{
  "Authorization": "token"
}

Response:

{
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}

Reference Resource Key Format in Section Resource Key Format

Webhook: Update Translation

The third-party app can push updates to Transcy to refresh default values or status in the Transcy management dashboard.

Method: POST
Endpoint: {transcy_url}/api/integration/webhook/update
Parameters:

{
  "locale": "string"
}

Response Example:

true

Webhook: App Uninstall

The third-party app must notify Transcy when the store uninstalls the app.

Method: POST
Endpoint: {transcy_url}/api/integration/webhook/status
Payload:

{
  "type": "uninstalled"
}

Response Example:

true

APIs Provided by Transcy

Get Translations

Retrieve translations after Transcy has processed them.

If a resource is not yet translated, the default value will be returned.

Method: POST
Endpoint: {transcy_url}/api/integration/translations
Parameters:

{
  "locale": "string"
}

Response Example:

[
  {
    "key": "key1",
    "translation": "value1"
  },
  {
    "key": "key2",
    "translation": "value2"
  }
]

Check Installation Status

Verify whether a store is still using Transcy.

If not, the third-party app may load translations directly.

Method: GET
Endpoint: {transcy_url}/api/integration/install-status
Response Example:

{
  "id": "string",
  "shopify_domain": "string",
  "app_plan": "string",
  "app_status": "string" // 0 = uninstalled, 1 = installed
}

Get Published Languages

Retrieve the list of published languages of Merchant Store available in Transcy.

Method: GET
Endpoint: {transcy_url}/api/integration/languages
Response Example:

{
  "default": "string",
  "codes": ["en", "fr", "de"]
}]

Webhook: Status Integration

Description: Transcy sends webhooks to notify the third-party app about integration status changes such as enable, disable, uninstall, or translation updates.
Method: POST
Endpoint: {third_app_url}/api/transcy/webhook/status
Headers:

{
  "token": "token"
}

Payload Example:

{
  "type": "uninstalled | reinstalled | enable_integrate | disable_integrate | updated_language | translation_updated"
}

Response:

true

Contact

For more information, please contact your partnership contact point, any update document or added API will be updated here.

Updated on: 24/03/2026

Was this article helpful?

Thank you!

Transcy and App Partner Integration APIs

Table of contents