# 識別碼 (Identifier) 和 參考 ID (ReferenceId)

*注意：本頁的代碼應視為偽碼 (pseudocode)。有關詳細資訊和完全正确的範例，請參閱說明文件中描述特定功能的頁面。*

## <mark style="color:blue;">重要事項</mark>

* 存款地址會永久映射至其建立時的識別碼 (`identifier`)
* 傳送至此類地址的交易總會包含識別碼 (`identifier`)
* `referenceId` 在存款請求中是可選的。如果您同時管理存款請求，它可以讓您進一步識別用戶存入的是哪筆存款。
  * 注意：`referenceId` 會在 24 小時後過期。存款仍可存入相關地址，但 `referenceId` 將不會出現在回調中。
    * 您可以在[回調設置](/traditional-chinese/yi-biao-ban/kai-fa-zhe.md#cun-kuan-qing-qiu-you-xiao-qi-xian)中調整此到期時間範圍。
  * 如果您使用相同的識別碼 (`identifier`) 和[網路](/traditional-chinese/jian-jie/shu-yu.md#wang-lu)新增多個 `referenceId`，只要它們尚未過期，就會依序傳回，最舊的先傳回。(除非使用不同的[請求金額](/traditional-chinese/zhi-nan/yao-qiu-de-jinehe-huo-bi-requested-amount-currency.md)）
* 在出款請求中，`referenceId` 為必填欄位，可用於識別單筆付款交易。

強烈建議在使用者和存款地址之間保持一對一的對應關係。

#### <mark style="color:blue;">為什麼？</mark>

* 永久分配的存款地址意味著每次啟動存款（或通過某種演算法從預先產生的池中選擇）時都不必創建新的錢包。為一個識別碼 (identifier) 請求一個存款地址後，您知道該識別碼 (identifier) 和地址是永遠相連的，因此不需要再為該識別碼 (identifier) 請求存款地址。如果您仍想檢查地址，AP 只需在資料庫中查找該錢包，而不是在區塊鏈上創建一個新錢包 - 這可能是一個冗長的過程，因此仍然更有效率。
* 如果您管理的是一組用戶，您會更容易追蹤哪個用戶有哪個地址用於存款（因為只有一個，而且總是同一個）。同樣地，您的用戶只需處理一個地址（或確實是每個網絡一個）用於存款，將存款進入錯誤錢包的任何風險降至最低。

## <mark style="color:blue;">詳細說明</mark>

在文件和程式碼中，您會遇到「識別碼」 (identifier)的概念。識別碼 (identifier) 就是唯一識別存款地址。通常，識別碼 (identifier) 會是 userId 或類似的東西，但如何使用則由您決定。

如果您管理存款請求，您可以將您的存款 ID 傳給 「referenceId」，以進一步識別用戶存入的是哪筆存款。

如果您管理出款請求，您可以直接將您的出款 ID 傳給 「referenceId」，它將在回調中作為參考 ID 「referenceId」 返回。

## <mark style="color:blue;">存款</mark>

### <mark style="color:blue;">建立存款地址</mark>

您最先遇到識別碼 (identifier) 的地方通常是為您的軟體[建立錢包](/traditional-chinese/sdk/han-shi-functions/getdepositaddress.md)（存款地址）時，也許是讓您的某位使用者將資金存入錢包。如果您控制著許多使用者，您很可能會以一些獨特的屬性（例如 ID 或使用者名稱）儲存他們的資料。這可以用來取得存款地址：

```typescript
AkashicPay.getDepositAddress("TRX", "user1");
// -> 'TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb'
```

回調的地址 (上例中為 TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb) 現在永久指定給識別碼 `'user1'`。之後任何相同函式 (function) 的回調都會傳回相同的地址：

```typescript
AkashicPay.getDepositAddress("TRX", "user1");
// -> 'TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb'
```

如果您變更網路或識別碼 (identifier)，自然會得到不同的地址：

```typescript
AkashicPay.getDepositAddress("TRX", "user2");
// -> 'TDkteGBASJSvoHSeAAwej3LAfFLj7zhhaE'

AkashicPay.getDepositAddress("ETH", "user1");
// -> '0x159cA92b12F67E5676d82C238f4906692618A555' (diffrent format on Ethereum)
```

如果您需要將存款對應到您的存款請求，您需要將存款請求 ID 傳給 referenceId

```javascript
AkashicPay.getDepositAddress("TRX", "user2", "order1");
// -> 'TDkteGBASJSvoHSeAAwej3LAfFLj7zhhaE'

AkashicPay.getDepositAddress("ETH", "user1", "order2");
// -> '0x159cA92b12F67E5676d82C238f4906692618A555' (diffrent format on Ethereum)
```

> 請注意，兩次操作均返回相同的地址。目前有兩筆 「訂單」 等待處理，將依建立順序完成。這意味著：首次向錢包存款將觸發回調函式，其中 `"referenceId": "order1"`， 第二次向該地址存款將觸發回調函式，其中`"referenceId": "order2"`此情況假設所有訂單均未過期（預設建立後24小時失效）。

### <mark style="color:blue;">存款回調</mark>

如果我們已經識別為 `user1` 的用戶現在決定向錢包 `TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb` 入金，您將收到一個[回調](/traditional-chinese/hui-diao/cun-kuan-hui-diao-deposit-callback.md)到您在 AkashicPay.com 上設定的 URL。回調物件中會有一個標題為識別碼 (`identifier`) 的欄位，其值為 `user1`。這可以讓您輕鬆地將存款與其所屬的用戶相識別。當然，如果您願意的話，也可以將地址 (TTV...) 儲存在資料庫中，然後用它來代替。

如果您在 getDepositAddress 中傳入 `referenceId`，您也會在回調中收到 `referenceId`。

## <mark style="color:blue;">出款/提款</mark>

### <mark style="color:blue;">處理出款（提款）</mark>

對於[出款/提款](/traditional-chinese/sdk/han-shi-functions/ti-kuan-ti-bi-payout.md)，必須在函式呼叫中包含 `referenceId`。`referenceId` 必須能用來識別該筆付款交易。

```typescript
AkashicPay.payout('tx1', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')

AkashicPay.payout('tx2', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '5', 'TRX', 'USDT')
```

這將在 Tron (TRX) 網絡上啟動一筆從 AkashicPay 到外部錢包 TAzsQ... 的交易，價值為 10 USDT。由於 AkashicPay 的工作方式，提款可能會從許多錢包中的一個發送。因此，不能保證（事實上，不太可能）取款是從用來存款的相同地址發送的，您絕對不應該相信這一點。

但是，基於上述原因，我們強烈建議存款時不要使用此方法。

### <mark style="color:blue;">出款回調</mark>

當使用上述功能觸發提款時，您將再次收到一個[回調](/traditional-chinese/hui-diao/ti-kuan-ti-bi-hui-diao-payout-callback.md)到您在 AkashicPay.com 上設置的 URL。當您收到出款回調時，交易已經被確認，並且可以安全地將款項存入用戶的賬號中。

## <mark style="color:blue;">特殊案例</mark>

### <mark style="color:blue;">付款時沒有 referenceId？</mark>

根據您的使用情況，有些情況下可能不需要包含 `referenceId`。例如，向特殊錢包進行內部交易或進行利潤出款時。一般而言，對於這些與任何使用者無關的出款，`referenceId` 基本上是多餘的。但是，我們仍然要求所有交易都要有`referenceId`，以確保所有交易都能被清楚追蹤。這是由於沒有安全的方法來分開兩個交易，否則在技術上有可能同時發生兩個原本相等的交易。因此，我們鼓勵您使用合理的`referenceId` 記錄所有交易。例如：

```typescript
AkashicPay.payout('INTERNAL_TRANSFER', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')

AkashicPay.payout('PROFIT_PAYOUT', 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM', '1000', 'TRX', 'USDT')
```

當然，任何字串參數 (string-argument) 都是允許的，所以如果您絕對確定不想透過`referenceId`來追蹤交易，您可以直接提供任何隨機字串 (string)，然後馬上忘記它：

**注意！**&#x8ACB;勿使用空字串 (string)！

```typescript
AkashicPay.payout('foo', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')

AkashicPay.payout('NaN', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')
```

### <mark style="color:blue;">多個存款地址？</mark>

當然，沒有什麼可以阻止您在系統中為「user1」提供多個存款地址。也許一個地址會用於特別促銷或其他情況。在這種情況下，您可以簡單地做以下事情：

```typescript
AkashicPay.getDepositAddress("TRX", "user1-normal");
// -> 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM'
AkashicPay.getDepositAddress("TRX", "user1-special");
// -> 'TRMzP9A18iQNvaFn33zkhhnN5exmLWZ5Ad'
```

或許您可以將此儲存於您的使用者，例如：

```
{
    userId: 'user1',
    wallets: [{address: 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM',
            identifier: 'user1-normal'},
             {address: 'TRMzP9A18iQNvaFn33zkhhnN5exmLWZ5Ad',
              identifier: 'user1-special'}]
}
```

像往常一樣，任何存入上述兩個地址的存款現在都會返回各自的識別碼 (identifier)。

這是一個展示如何使用 AkashicPay 的範例。但是，我們建議在用戶和存款地址之間始終保持一對一的映射，以獲得最高的效率和最小的混淆可能性。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akashicpay.com/traditional-chinese/zhi-nan/shi-bie-ma-identifier-referenceid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.