🧪 Simulating a Location-Based Purchase with Category-Based Dummy Products

This guide explains how to test your implementation of the location-based product flow using dummy products available within each real category.
These dummy products simulate real purchase flows without affecting production data, enabling developers to safely validate integration and error-handling behavior.

🔁 General Overview

Location-based products follow a dynamic flow made up of chained GET calls, where each response specifies the next step through nextPath and nextField.
This approach allows the flow to adapt automatically to product complexity or API changes without hardcoding paths.

🧠 You can use the Get Labels method to preview all the possible steps that any dynamic flow might have.

The flow typically involves:

Country Selection

Category Selection

Optional Geographic Steps (e.g. state, municipality)

Product Listing

Mandatory Fields

Optional Nationalities

Cart Creation

Purchase

⚠️ Depending on the category, the flow may skip certain location levels.
For example:

COMBO, PHONE, or MODEM categories may include state and municipality steps.

ESIM might skip those and go directly to products.

⚙️ Dynamic Flow Logic

Each step in the flow returns a nextPath — the exact URL for the next call.
This ensures flexibility and prevents assumptions about how many steps exist between country and product.

✅ Always follow the nextPath value returned by the API response.

Do not hardcode the order or number of steps. Some products may:

Include additional layers (districts, delivery points, etc.)

Omit certain layers altogether

Continue calling GET endpoints until the response points to /products, which is the product listing endpoint.

📍 Step 1 – Get Countries

Example Response:

[
  {
    "countryId": 192,
    "name": "Cuba",
    "nextPath": "/physical-products/categories/{{terminalId}}/192",
    "nextField": "categoryId"
  }
]

✅ Store:

countryId = 192 → required later in cart creation.

Follow the nextPath to get categories.

🧭 Next Call:

🛍️ Step 2 – Get Categories

Example Response:

[
    {
        "categoryId": 2,
        "name": "COMBO",
        "nextPath": "/physical-products/states/{{terminalId}}/2/192",
        "nextField": "stateId"
    },
    {
        "categoryId": 4,
        "name": "PHONE",
        "nextPath": "/physical-products/states/{{terminalId}}/4/192",
        "nextField": "stateId"
    },
    {
        "categoryId": 5,
        "name": "MODEM",
        "nextPath": "/physical-products/states/{{terminalId}}/5/192",
        "nextField": "stateId"
    },
    {
        "categoryId": 12,
        "name": "SIM",
        "nextPath": "/physical-products/states/{{terminalId}}/12/192",
        "nextField": "stateId"
    },
    {
        "categoryId": 13,
        "name": "ESIM",
        "nextPath": "/physical-products/products/{{terminalId}}/13/192",
        "nextField": "productId"
    }
]

✅ Use:

Any real category (e.g. COMBO, PHONE, MODEM, SIM, ESIM)

Each one may contain dummy products for testing.

🧭 Next Step:
Follow the nextPath from the selected category — it can lead to states or directly to products, depending on configuration.

⚠️ Important Notice — Safe Testing
All categories now include dedicated dummy products for simulation.
✅ Always choose products explicitly labeled as "Dummy" in the product listing.
These are test-only and will not trigger real charges.
🚫 Avoid selecting real (non-dummy) products unless you intend to perform actual transactions.

🏞️ Example: Flow with a Category That Includes States (e.g. COMBO)

Example Response (shortened):

[
  {
    "stateId": 473,
    "name": "La Habana",
    "nextPath": "/physical-products/municipalities/{{terminalId}}/2/473",
    "nextField": "municipalityId"
  }
]

🧭 Next Call:

🏘️ Example: Get Municipalities

Response Example:

[
  {
    "municipalityId": 499,
    "name": "Centro Habana",
    "nextPath": "/physical-products/products/{{terminalId}}/2/499",
    "nextField": "productId"
  }
]

🧭 Next Call:

📦 Step – Get Products

Response Example:

[
  {
    "productPriceX100": 100,
    "productId": 9001,
    "operatorId": 9988,
    "name": "DUMMY COMBO 1",
    "description": "Simulated product for integration testing",
    "imageUrl": "https://static.csqworld.com/flags/CU.png"
  },
  {
    "productPriceX100": 150,
    "productId": 9002,
    "operatorId": 9988,
    "name": "Real Product – COMBO Plan 1",
    "description": "Actual product with charge",
    "imageUrl": "https://static.csqworld.com/flags/CU.png"
  }
]

✅ Select:

A dummy product, clearly labeled as such ("Dummy Product").

Use its productId and operatorId in the following steps.

📝 Step – Get Fields

This is a mandatory step before creating the cart. After selecting a product, you must call this endpoint to discover the dynamic fields required for that specific categoryId. This allows your UI to build the correct form for the user.

Example Response:

[
  {
    "field": "nationality",
    "type": "select",
    "labels": { "en": "Nationality", "es": "Nacionalidad" },
    "values": ["Colombiana", "Venezolana", "Argentina"],
    "path": "/physical-products/nationalities"
  },
  {
    "field": "beneficiaryName",
    "type": "string",
    "labels": { "en": "Beneficiary Name", "es": "Nombre del Beneficiario" },
    "values": [],
    "path": ""
  }
]

✅ Action:

Use this response to dynamically generate a form for the user.

If a field contains a path (like nationality in the example), it means you must make an additional call to that path to get the list of possible values.

For other fields, use the type and labels to display the appropriate input control.

🧭 Next Call:

If a field has a path, call that endpoint (e.g., Get Nationalities).

Otherwise, proceed to Create Cart after collecting user input.

🛒 Step – Optional: Get Nationalities (Conditional)

This step is only executed if the response from Get Fields included a field with a path pointing to this endpoint. It provides the values for a selection list.

Example Response:

[
  { "id": 1, "name": "Colombia" },
  { "id": 2, "name": "Venezuela" },
  { "id": 3, "name": "Argentina" }
]

✅ Action:

Use the id and name from the response to populate the selection list (e.g., a dropdown) for the corresponding field in your UI.

🧭 Next Call:

After the user has filled all the required fields, you are ready to create the cart.

🛒 Step – Create Cart

Body Example:

{
  "productId": 9001,
  "countryId": 192,
  "stateId": 473,
  "municipalityId": 499,
  "buyerName": "TEST CSQ",
  "buyerSurname": "TEST CSQ",
  "buyerPhone": "123456789",
  "buyerEmail": "test@test.com",
  "buyerDocumentNumber": "98787666",
  "beneficiaryName": "beneficiary",
  "beneficiarySurname": "surname",
  "beneficiaryPhone": "888999111",
  "beneficiaryEmail": "beneficiary@email.com",
  "beneficiaryDocumentNumber": "61827396",
  "beneficiaryDocumentType": "ID_CARD",
  "city": "LA HABANA",
  "address": "PRUEBA"
}

Response Example:

{
  "resultMessage": "Cart created successfully",
  "resultCode": 0,
  "cartId": 440,
  "productPriceX100": 100,
  "amountToSendX100": 600,
  "deliveryPriceX100": 500
}

✅ Store:

cartId → required for purchase.

amountToSendX100 → required for purchase.

💳 Step – Purchase

Body Example:

{
  "amountToSendX100": 600,
  "localDateTime": "2025-07-09T14:06:00",
  "cartId": "440"
}

Response Example:

{
  "rc": 0,
  "items": [
    {
      "finalstatus": 0,
      "resultcode": "10",
      "resultmessage": "Operation completed successfully",
      "supplierreference": "440",
      "suppliertoken": ""
    }
  ]
}

✅ Use:

supplierreference and suppliertoken for reconciliation or audit tracking.

📘 Summary

Field	Description / Example
`countryId`	`192` → Cuba
`categoryId`	Variable (COMBO, PHONE, etc.)
`stateId`	Optional — depends on category
`municipalityId`	Optional — depends on category
`productId`	Dummy product ID (safe for tests)
`operatorId`	Required for cart/purchase

✅ The dummy simulation is now available within each real product category.
Just ensure to pick a dummy-labeled product, and always follow the nextPath chain dynamically.

Location-based products simulation

🧪 Simulating a Location-Based Purchase with Category-Based Dummy Products#

🔁 General Overview#

⚙️ Dynamic Flow Logic#

📍 Step 1 – Get Countries#

🛍️ Step 2 – Get Categories#

🏞️ Example: Flow with a Category That Includes States (e.g. COMBO)#

🏘️ Example: Get Municipalities#

📦 Step – Get Products#

📝 Step – Get Fields#

🛒 Step – Optional: Get Nationalities (Conditional)#

🛒 Step – Create Cart#

💳 Step – Purchase#

📘 Summary#

🧪 Simulating a Location-Based Purchase with Category-Based Dummy Products

🔁 General Overview

⚙️ Dynamic Flow Logic

📍 Step 1 – Get Countries

🛍️ Step 2 – Get Categories

🏞️ Example: Flow with a Category That Includes States (e.g. COMBO)

🏘️ Example: Get Municipalities

📦 Step – Get Products

📝 Step – Get Fields

🛒 Step – Optional: Get Nationalities (Conditional)

🛒 Step – Create Cart

💳 Step – Purchase

📘 Summary