🧪 Simulating a Location-Based Purchase with Dummy Products

This guide explains how to test in a simulated way your implementation of the dynamic flow of location-based dummy products using CSQ’s API suite. This simulation mimics real-world selection logic based on geography and product catalog, providing developers with a reliable test structure for integration and error handling.

🔁 General Overview

Location-based products follow a dynamic path composed of chained GET calls, each one revealing the next step (nextPath, nextField). This approach guarantees that your integration remains resilient to product complexity changes or future updates to the API structure.

🧠 Remember you can use the Get Labels method to have a preview of all the possible steps any dynamic flow might have.

This dummy sequence is geographically contextualized and, in the case of this dummy flow, it specifically follows:

Country Selection

Category Selection

State Selection

Municipality Selection

Product Listing

Create Cart (always mandatory)

Purchase (alwaysmandatory)

The only optional step skipped in this dummy flows is Get Deliver Locations, but have mind it could play a role in real life products. This is why it is mandatory to follow the flow through the nextPath field from each response..

⚠️ Important Notice – Dynamic Flow Logic
The location-based product flow follows a dynamic GET sequence, where each response includes a nextPath indicating the next endpoint to call. This path-driven logic means the number of steps required before reaching GET /products can vary depending on the specific product configuration.
🧭 In real scenarios, some products may involve:
Additional intermediate steps, such as districts, sectors, or delivery points
Or fewer steps, skipping certain fields entirely
✅ To ensure compatibility across all products, never hardcode assumptions about the number of steps. Instead:
Always follow the nextPath provided in each API response
Continue iterating until you reach the product listing endpoint

📍 Dynamic GET Sequence in this dummy scenario

The full sequence of dynamic GET requests for location-based dummy products, is designed to simulate geographical product selection before cart creation and purchase.

Each call returns a nextPath, guiding the client to the next step. Dummy responses are predictable and reusable for developer tests — especially with fixed values such as categoryId = 8,countryId = 192, stateId = 473, and municipalityId = 499.

Let’s walk through the GET flow in simple terms, with full example responses and developer tips ✅.

🌍 Step 1 – Get Countries

Response Example:

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

✅ What to Store:

countryId = 192 → Required for Create Cart

Follow the nextPath shown above.

🧭 Next Call:

🛍️ Step 2 – Get Categories

Response Example:

[
  {
    "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": 2,
    "name": "COMBO",
    "nextPath": "/physical-products/states/{{terminalId}}/2/192",
    "nextField": "stateId"
  },
  {
    "categoryId": 8,
    "name": "DUMMY",
    "nextPath": "/physical-products/states/{{terminalId}}/8/192",
    "nextField": "stateId"
  }
]

✅ Use:

categoryId = 8 ("DUMMY") → needed for dummy flow.

Follow its nextPath to load states.

🧭 Next Call:

⚠️ Important Warning – Dummy Flow Safety
When testing the location-based product flow, it is mandatory to use category 8 ("DUMMY"). This category is specifically designed for simulation and safe testing.
🚫 Using any other category (e.g. "PHONE", "MODEM", "COMBO") may result in:
Access to real products
Actual charges to your account
Irreversible transactions affecting end users
✅ Always ensure:
categoryId = 8 is selected when building the dummy test flow.
🔒 For internal QA and developer environments, hardcode categoryId = 8 when applicable or validate programmatically before sending requests to cart and purchase endpoints.
This practice protects your team, your customers, and your integration from accidental costs or data exposure.

🏞️ Step 3 – Get States

Response Example (shortened):

[
  {
    "stateId": 472, "name": "Pinar del Río", "nextPath": "/physical-products/municipalities/{{terminalId}}/8/472", "nextField": "municipalityId"
  },
  {
    "stateId": 473, "name": "La Habana", "nextPath": "/physical-products/municipalities/{{terminalId}}/8/473", "nextField": "municipalityId"
  },
  {
    "stateId": 474, "name": "Artemisa", "nextPath": "/physical-products/municipalities/{{terminalId}}/8/474", "nextField": "municipalityId"
  }
  // ...
]

✅ what to store:

stateId = 473 ("La Habana") → required for cart creation

🧭 Next Call:

🏘️ Step 4 – Get Municipalities

Response Example (shortened):

[
  {
    "municipalityId": 499, "name": "Centro Habana", "nextPath": "/physical-products/products/{{terminalId}}/8/499", "nextField": "productId"
  },
  {
    "municipalityId": 512, "name": "Habana Vieja", "nextPath": "/physical-products/products/{{terminalId}}/8/512", "nextField": "productId"
  },
  {
    "municipalityId": 513, "name": "Diez de Octubre", "nextPath": "/physical-products/products/{{terminalId}}/8/513", "nextField": "productId"
  }
  // ...
]

✅ what to store:

municipalityId = 499 ("Centro Habana") → required for cart creation

🧭 Next Call:

📦 Step 5 – Get Products

Response Example:

[
  {
    "productPriceX100": 100,
    "productId": 846,
    "operatorId": 9988,
    "name": "Arroz 1kg",
    "description": "Paquete de arroz de 1 kilogramo",
    "imageUrl": "https://static.csqworld.com/flags/CU.png"
  },
  {
    "productPriceX100": 100,
    "productId": 847,
    "operatorId": 9988,
    "name": "Aceite 1L",
    "description": "Botella de aceite de 1 litro",
    "imageUrl": "https://static.csqworld.com/flags/CU.png"
  }
]

✅ What to store:

productId = 846 ("Arroz 1kg") -> required as a parameter in the body of create cart step.

operatorId = 9988 → required as a parameter in the Create Cart and Purchase steps.

📌 Summary of Dummy Test Values (Stable)

Field	Dummy Value
`countryId`	`192` → Cuba
`categoryId`	`8` → Dummy
`stateId`	`473` → La Habana
`municipalityId`	`499` → Centro Habana

✅ These are fixed values you can hardcode for dummy testing.
The only variable is the actual product (productId and operatorId), which may change.

⚠️ Important Reminder — Follow nextPath Always

In real product flows, the number of GET steps may increase or decrease depending on configuration.
That’s why you should always:

Read the nextPath from each response

Don’t skip or guess the next call

Continue until you reach GET /products

🛒 Step 6: Create Cart

Example Body Payload:

{
  "productId": 846,
  "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"
}

Expected Response

{
    "resultMessage": "Cart created successfully",
    "resultCode": 0,
    "cartId": 440, // ⚠️ Note: The "cartId" value will change every time a new cart is created.
    "productPriceX100": 100,
    "amountToSendX100": 600,
    "deliveryPriceX100": 500
}

✅ What to store:

cartId -> required as a parameter in the body of purchase step.

amountToSendx100 → required as a parameter in the body of purchase step.

🧠 Developer Tips:

Always ensure consistency between location fields (stateId, municipalityId, countryId) used across steps.

You must always call Create Cart before Purchase.

deliveryPriceX100 is included in the cart response but handled internally.

💳 Step 7: Purchase

Payload Example:

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

✅ This call finalizes the transaction and returns confirmation:

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

🧠 Use supplierreference and suppliertoken for reconciliation or audit tracking.

⚠️ Stable Values in Dummy Flow

In the location-based dummy flow, the following values are considered fixed and always available for testing purposes:

Field	Dummy Value
`countryId`	`192` → Cuba
`categoryId`	`8` → Dummy (most relevant!!)
`stateId`	`473` → La Habana
`municipalityId`	`499` → Centro Habana

These locations are preconfigured in the simulation environment and can be reliably used across dummy test scenarios. Even if product options (productId) may change over time, this location path will consistently return valid data to reach the product listing step.

✅ Tip: If you're building automated tests or frontends for this flow, you can hardcode this location chain for dummy simulations while keeping productId dynamic.

Location-based products simulation

🧪 Simulating a Location-Based Purchase with Dummy Products#

🔁 General Overview#

📍 Dynamic GET Sequence in this dummy scenario#

🌍 Step 1 – Get Countries#

🛍️ Step 2 – Get Categories#

🏞️ Step 3 – Get States#

🏘️ Step 4 – Get Municipalities#

📦 Step 5 – Get Products#

📌 Summary of Dummy Test Values (Stable)#

🛒 Step 6: Create Cart#

💳 Step 7: Purchase#

⚠️ Stable Values in Dummy Flow#

🧪 Simulating a Location-Based Purchase with Dummy Products

🔁 General Overview

📍 Dynamic GET Sequence in this dummy scenario

🌍 Step 1 – Get Countries

🛍️ Step 2 – Get Categories

🏞️ Step 3 – Get States

🏘️ Step 4 – Get Municipalities

📦 Step 5 – Get Products

📌 Summary of Dummy Test Values (Stable)

🛒 Step 6: Create Cart

💳 Step 7: Purchase

⚠️ Stable Values in Dummy Flow