> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.transcy.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Transcy and App Partner Integration APIs

## Table of contents

[I. Overview](#2-i-overview)
[II. Diagram Overview & Integration Flow](#2-ii-diagram-overview-integration-flow)
[III. Authorization Token & Resource Key Format](#2-iii-authorization-token-resource-key-format)
[1. Token](#3-1-token)
[2. Resource Key Format](#3-2-resource-key-format)
[IV. API & Webhook by 3rd-Party App consumed by Transcy](#2-iv-api-webhook-by-3rd-party-app-consumed-by-transcy)
[1. API Get Resource Data](#3-1-api-get-resource-data)
[2. Webhook: Update Translation](#3-2-webhook-update-translation)
[3. Webhook: App Uninstall](#3-3-webhook-app-uninstall)
[V. APIs Provided by Transcy](#2-v-apis-provided-by-transcy)
[1. Get Translations](#3-1-get-translations)
[2. Check Installation Status](#3-2-check-installation-status)
[3. Get Published Languages](#3-3-get-published-languages)
[4. Webhook: Status Integration](#3-4-webhook-status-integration)
[VI. Contact](#2-vi-contact)

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

## II. Diagram Overview & Integration Flow
![Interaction flow between Transcy and a third-party app during integration](https://storage.crisp.chat/users/helpdesk/website/-/3/5/1/b/351b76ece3eb1400/transcy-3rd-app-integration-fl_ikddlv.png)
*Overview Interaction Flow between Transcy x 3rd-Party App with integration*

| See full diagram [here](https://firegroup.atlassian.net/wiki/external/YmRiMzYwODhhOWJiNDhmMGJmNTA5YTM2NzM4MDg4NWQ)
 

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

1. User enables integration from both apps.
2. Third-Party App sends an integration request to Transcy.
3. Transcy confirms the integration status via webhook.
4. Third-Party App exposes resources for Transcy to fetch.
5. Transcy translated the resources from the original languages to all destination languages.
6. Third-Party App retrieves translations and available languages from Transcy.
7. Any Updates and uninstall events are communicated through webhooks.
 
## III. Authorization Token & Resource Key Format

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

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

## IV. API & Webhook by 3rd-Party App consumed by Transcy

### 1. 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](#3-2-resource-key-format)

### 2. 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
```

### 3. 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
```

## V. APIs Provided by Transcy

### 1. 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"
  }
]
```

### 2. 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
}
```

### 3. 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"]
}]
```

### 4. 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
```

## VI. Contact

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