Management of Serialized Datastrings

Deposit Serialized GS1 using /provider/deposit API

The deposit API has several parameters, but the only required parameter is “gs1s,” which allows you to pass the serialized gs1s (created using the format described earlier). If today’s date is within the campaign start and end dates specified in the master offer file, and the serialized gs1s format is correct, TCB will accept the deposit. You can send up to 15 serialized gs1s per deposit.

To make the API call, you must get the access token from the access and secret keys.

curl -X POST 'https://api.try.thecouponbureau.org/access_token' \
-H 'Content-Type: application/json' \
-H 'x-api-key: ACCESS_KEY' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

With the access token, call the provider deposit API.

curl -X POST 'https://api.try.thecouponbureau.org/provider/deposit' \
-H 'Content-Type: application/json' \
-H 'x-api-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"gs1s":[<Array of serialized gs1s>]}'

When depositing, ensuring that the serialized data strings are unique and non-sequential is essential, as TCB will not accept duplicates and will return an error message accordingly. However, creating unique serialized GS1s can be challenging for providers using the data format. In such cases, the API offers a mode that allows you to shift the responsibility of generating unique serialized GS1s to the TCB layer. By setting the mode as “base_gs1”, you can send the base GS1 instead of the formatted serialized GS1s and let TCB generate unique serialized GS1s using your serialization prefix, and then deposit and return them.

curl -X POST 'https://api.try.thecouponbureau.org/provider/deposit' \
-H 'Content-Type: application/json' \
-H 'x-api-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"gs1s":[<Array of base gs1s>],"mode":"base_gs1"}'

To deposit three serialized GS1s for the base GS1 81120211223344777026, you can pass the same base GS1 three times in the “gs1s” field.

curl -X POST 'https://api.try.thecouponbureau.org/provider/deposit' \
-H 'Content-Type: application/json' \
-H 'x-api-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"gs1s":["81120211223344777026","81120211223344777026","81120211223344777026"],"mode":"base_gs1"}'

Using the “base_gs1” mode simplifies the creation of unique serialized GS1s for the provider but also introduces a new complexity. If a network error causes a timeout in the HTTP API request, the serialized GS1s may have been created in the TCB layer, but the provider may not have received them. Typically, providers receive the serialized GS1s in the response and associate them with a user account. To retrieve the generated serialized GS1s in such a scenario, the “client_txn_id” parameter is used. This is an ID that the provider can create on their side. After the TCB platform generates and deposits serialized GS1s, it associates the “client_txn_id” with the newly generated serialized GS1s. The provider can call the same deposit API with the same “client_txn_id” if a network timeout occurs. If data is associated with the “client_txn_id,” TCB will return it directly without creating a new one. This process makes deposit requests idempotent.

curl -X POST 'https://api.try.thecouponbureau.org/provider/deposit' \
-H 'Content-Type: application/json' \
-H 'x-api-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"gs1s":[<Array of base gs1s>],"mode":"base_gs1","client_txn_id":"xni73-ndi73-lkf937"}'