{
  "openapi": "3.0.3",
  "info": {
    "title": "CopDigital API",
    "version": "2026-10-24",
    "description": "Edición documental; ejemplos ficticios, no resultados de producción. Las operaciones financieras afectan saldo real."
  },
  "servers": [
    {
      "url": "https://back.copdigital.co"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/api/auth/token": {
      "post": {
        "operationId": "auth",
        "summary": "Obtener token",
        "description": "Emite un token para los permisos habilitados de tu cuenta.\nObtener token: Solicita al administrador de CopDigital la habilitación API, los módulos y, si aplica, las IP de salida autorizadas. No hay un endpoint de refresh documentado: al vencer el token, autentícate nuevamente. No solicites un token por cada operación.",
        "tags": [
          "Acceso"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "auth_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "token_type": "Bearer",
                        "access_token": "TU_TOKEN",
                        "expires_in": 86400,
                        "scopes": [
                          "gen_hys",
                          "payments"
                        ],
                        "user": {
                          "id": 123,
                          "usuario": "integrador_demo",
                          "tipo": "distribuidor"
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "auth_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_INVALID_CREDENTIALS",
                      "message": "Credenciales API incorrectas.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "usuario": {
                        "type": "string",
                        "description": "Usuario de la cuenta con acceso API habilitado."
                      },
                      "password": {
                        "type": "string",
                        "description": "Contraseña de esa cuenta."
                      }
                    },
                    "required": [
                      "usuario",
                      "password"
                    ]
                  }
                ]
              },
              "examples": {
                "auth": {
                  "summary": "Obtener token",
                  "value": {
                    "usuario": "TU_USUARIO",
                    "password": "TU_CLAVE"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/dashboard_state": {
      "get": {
        "operationId": "balance",
        "summary": "Consultar saldo",
        "description": "Consulta el saldo y las ganancias de la cuenta autenticada.\nPermiso: gen_hys.\nConsultar saldo: El ejemplo muestra únicamente los campos útiles para consultar saldo; pueden existir otros campos de interfaz.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "balance_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "balances": {
                          "saldo": 50000,
                          "gana_cl": 0,
                          "gana_multip": 1000,
                          "mx_bl": 0,
                          "mx_gl": 0
                        },
                        "user": {
                          "id": 123,
                          "usuario": "integrador_demo",
                          "apodo": "Demo",
                          "tipo": "distribuidor",
                          "moneda": "COP"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "balance_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/modules_state": {
      "get": {
        "operationId": "modules",
        "summary": "Consultar módulos",
        "description": "Lista los módulos habilitados para tu cuenta.\nPermiso: gen_hys.\nConsultar módulos: ",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "modules_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "rows": [
                          {
                            "module_key": "multimedia",
                            "label": "Multimedia",
                            "description": "Servicios multimedia",
                            "is_enabled": 1
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "modules_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/movi": {
      "post": {
        "operationId": "movements",
        "summary": "Consultar movimientos",
        "description": "Consulta movimientos de saldo y, opcionalmente, multiproducto en un único historial.\nPermiso: gen_hys.\nConsultar movimientos: No hay parámetros de paginación en este contrato. Usa rangos de fecha acotados. Sin unificado, data incluye module, action, sEcho, iTotalRecords, iTotalDisplayRecords y aaData; las filas contienen id, pago, mensaje y fecha.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "movements_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "action": "movi",
                        "timezone": "America/Bogota",
                        "iTotalRecords": 0,
                        "iTotalDisplayRecords": 0,
                        "aaData": []
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "movements_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "unificado": {
                        "type": "boolean",
                        "description": "true incluye multiproducto y normaliza fechas a hora Colombia."
                      },
                      "fecha1": {
                        "type": "string",
                        "description": "Fecha inicial, YYYY-MM-DD. Obligatoria junto con la otra fecha; ambas obligatorias con unificado=true."
                      },
                      "fecha2": {
                        "type": "string",
                        "description": "Fecha final, YYYY-MM-DD. Obligatoria junto con la otra fecha; ambas obligatorias con unificado=true."
                      }
                    }
                  }
                ]
              },
              "examples": {
                "movements": {
                  "summary": "Consultar movimientos",
                  "value": {
                    "unificado": true,
                    "fecha1": "2026-10-01",
                    "fecha2": "2026-10-13"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pantalla/catalog": {
      "get": {
        "operationId": "pantalla_catalog",
        "summary": "Pantallas: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nPantallas: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pantalla-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pantalla_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Pantallas",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pantalla-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pantalla/summary": {
      "get": {
        "operationId": "pantalla_summary",
        "summary": "Pantallas: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nPantallas: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pantalla-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pantalla_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Pantallas",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pantalla-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pantalla/purchase": {
      "post": {
        "operationId": "pantalla_purchase",
        "summary": "Pantallas: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nPantallas: comprar: Pantallas compra una unidad; no envíes quantity. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pantalla-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pantalla_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pantalla-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id"
                    ]
                  }
                ]
              },
              "examples": {
                "pantalla-purchase": {
                  "summary": "Pantallas: comprar",
                  "value": {
                    "product_id": 123,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/cuenta/catalog": {
      "get": {
        "operationId": "cuenta_catalog",
        "summary": "Cuentas: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nCuentas: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "cuenta-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "cuenta_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Cuentas",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "cuenta-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/cuenta/summary": {
      "get": {
        "operationId": "cuenta_summary",
        "summary": "Cuentas: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nCuentas: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "cuenta-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "cuenta_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Cuentas",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "cuenta-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/cuenta/purchase": {
      "post": {
        "operationId": "cuenta_purchase",
        "summary": "Cuentas: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nCuentas: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "cuenta-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "cuenta_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "cuenta-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "cuenta-purchase": {
                  "summary": "Cuentas: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/digital1/catalog": {
      "get": {
        "operationId": "digital1_catalog",
        "summary": "TV digital: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nTV digital: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "digital1-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "digital1_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "TV digital",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "digital1-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/digital1/summary": {
      "get": {
        "operationId": "digital1_summary",
        "summary": "TV digital: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nTV digital: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "digital1-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "digital1_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "TV digital",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "digital1-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/digital1/purchase": {
      "post": {
        "operationId": "digital1_purchase",
        "summary": "TV digital: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nTV digital: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "digital1-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "digital1_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "digital1-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "digital1-purchase": {
                  "summary": "TV digital: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/videojug/catalog": {
      "get": {
        "operationId": "videojug_catalog",
        "summary": "Videojuegos: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nVideojuegos: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "videojug-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "videojug_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Videojuegos",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "videojug-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/videojug/summary": {
      "get": {
        "operationId": "videojug_summary",
        "summary": "Videojuegos: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nVideojuegos: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "videojug-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "videojug_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Videojuegos",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "videojug-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/videojug/purchase": {
      "post": {
        "operationId": "videojug_purchase",
        "summary": "Videojuegos: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nVideojuegos: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "videojug-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "videojug_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "videojug-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "videojug-purchase": {
                  "summary": "Videojuegos: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/tools/catalog": {
      "get": {
        "operationId": "tools_catalog",
        "summary": "Herramientas: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nHerramientas: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "tools-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "tools_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Herramientas",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "tools-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/tools/summary": {
      "get": {
        "operationId": "tools_summary",
        "summary": "Herramientas: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nHerramientas: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "tools-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "tools_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Herramientas",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "tools-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/tools/purchase": {
      "post": {
        "operationId": "tools_purchase",
        "summary": "Herramientas: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nHerramientas: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "tools-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "tools_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "tools-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "tools-purchase": {
                  "summary": "Herramientas: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/paneles/catalog": {
      "get": {
        "operationId": "paneles_catalog",
        "summary": "Paneles: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nPaneles: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "paneles-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "paneles_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Paneles",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "paneles-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/paneles/summary": {
      "get": {
        "operationId": "paneles_summary",
        "summary": "Paneles: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nPaneles: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "paneles-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "paneles_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Paneles",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "paneles-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/paneles/purchase": {
      "post": {
        "operationId": "paneles_purchase",
        "summary": "Paneles: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nPaneles: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "paneles-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "paneles_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "paneles-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "paneles-purchase": {
                  "summary": "Paneles: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/music/catalog": {
      "get": {
        "operationId": "music_catalog",
        "summary": "Música: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nMúsica: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "music-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "music_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Música",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "music-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/music/summary": {
      "get": {
        "operationId": "music_summary",
        "summary": "Música: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nMúsica: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "music-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "music_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Música",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "music-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/music/purchase": {
      "post": {
        "operationId": "music_purchase",
        "summary": "Música: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nMúsica: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "music-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "music_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "music-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "music-purchase": {
                  "summary": "Música: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pass/catalog": {
      "get": {
        "operationId": "pass_catalog",
        "summary": "Suscripciones gamer: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nSuscripciones gamer: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pass-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pass_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Suscripciones gamer",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pass-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pass/summary": {
      "get": {
        "operationId": "pass_summary",
        "summary": "Suscripciones gamer: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nSuscripciones gamer: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pass-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pass_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Suscripciones gamer",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pass-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pass/purchase": {
      "post": {
        "operationId": "pass_purchase",
        "summary": "Suscripciones gamer: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nSuscripciones gamer: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pass-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pass_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pass-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "pass-purchase": {
                  "summary": "Suscripciones gamer: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/membre/catalog": {
      "get": {
        "operationId": "membre_catalog",
        "summary": "Membresías: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nMembresías: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "membre-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "membre_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Membresías",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "membre-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/membre/summary": {
      "get": {
        "operationId": "membre_summary",
        "summary": "Membresías: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nMembresías: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "membre-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "membre_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Membresías",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "membre-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/membre/purchase": {
      "post": {
        "operationId": "membre_purchase",
        "summary": "Membresías: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nMembresías: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "membre-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "membre_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "membre-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "membre-purchase": {
                  "summary": "Membresías: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pin/catalog": {
      "get": {
        "operationId": "pin_catalog",
        "summary": "Pines multimedia: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nPines multimedia: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pin-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pin_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Pines multimedia",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pin-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pin/summary": {
      "get": {
        "operationId": "pin_summary",
        "summary": "Pines multimedia: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nPines multimedia: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pin-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pin_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Pines multimedia",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pin-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/pin/purchase": {
      "post": {
        "operationId": "pin_purchase",
        "summary": "Pines multimedia: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nPines multimedia: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pin-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "pin_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pin-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "pin-purchase": {
                  "summary": "Pines multimedia: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/lic-soft/catalog": {
      "get": {
        "operationId": "lic_soft_catalog",
        "summary": "Licencias de software: catálogo",
        "description": "Consulta productos, precio asignado y disponibilidad.\nPermiso: gen_hys.\nLicencias de software: catálogo: El stock puede cambiar entre consulta y compra. No uses IDs ni precios fijos de los ejemplos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "lic-soft-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "lic_soft_catalog",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Licencias de software",
                            "items": [
                              {
                                "id": 123,
                                "nombre": "Producto de ejemplo",
                                "precio": 10000,
                                "available_count": 2,
                                "sold_out": false
                              }
                            ]
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "lic-soft-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/lic-soft/summary": {
      "get": {
        "operationId": "lic_soft_summary",
        "summary": "Licencias de software: resumen",
        "description": "Resume el catálogo por sección.\nPermiso: gen_hys.\nLicencias de software: resumen: ",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "lic-soft-summary_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "lic_soft_summary",
                        "saldo": 50000,
                        "moneda": "COP",
                        "total_items": 1,
                        "sections": [
                          {
                            "id": "seccion-ejemplo",
                            "label": "Licencias de software",
                            "count": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "lic-soft-summary_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/lic-soft/purchase": {
      "post": {
        "operationId": "lic_soft_purchase",
        "summary": "Licencias de software: comprar",
        "description": "Compra un producto disponible del catálogo de esta familia.\nPermiso: gen_hys.\nLicencias de software: comprar: La entrega puede contener varias unidades. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte. Conserva los datos de entrega de forma privada; no los registres en logs públicos.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "lic-soft-purchase_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "lic_soft_purchase",
                        "purchase": {
                          "cant": 1,
                          "correo": "cuenta@example.com",
                          "contrase": "CLAVE_DE_EJEMPLO",
                          "pantallas": "1",
                          "perfil": "1",
                          "pin": "",
                          "fecha": "2026-11-13",
                          "url": "",
                          "cliente": "Cliente de ejemplo",
                          "tipo": "tipo-del-catalogo",
                          "ticket_structure": "credentials",
                          "total": 10000,
                          "saldo_restante": 40000
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "lic-soft-purchase_0": {
                    "value": {
                      "ok": false,
                      "error": "INSUFFICIENT_BALANCE",
                      "message": "Saldo insuficiente.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "product_id": {
                        "type": "integer",
                        "description": "ID del catálogo de esta familia; mayor que cero."
                      },
                      "quantity": {
                        "type": "integer",
                        "description": "Cantidad positiva; sujeta a stock y saldo."
                      },
                      "cliente": {
                        "type": "string",
                        "description": "Etiqueta del cliente final."
                      }
                    },
                    "required": [
                      "product_id",
                      "quantity"
                    ]
                  }
                ]
              },
              "examples": {
                "lic-soft-purchase": {
                  "summary": "Licencias de software: comprar",
                  "value": {
                    "product_id": 123,
                    "quantity": 1,
                    "cliente": "Cliente de ejemplo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/loadear": {
      "post": {
        "operationId": "renew_search",
        "summary": "Buscar cuentas renovables",
        "description": "Consulta tus cuentas para preparar una renovación.\nPermiso: gen_hys.\nBuscar cuentas renovables: No uses el HTML de accion como contrato de negocio.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "renew-search_0": {
                    "value": {
                      "sEcho": 1,
                      "iTotalRecords": 0,
                      "iTotalDisplayRecords": 0,
                      "aaData": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "renew-search_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "busca": {
                        "type": "string",
                        "description": "Texto de búsqueda."
                      },
                      "mode": {
                        "type": "string",
                        "description": "Modo de consulta; omitir para el comportamiento habitual."
                      }
                    }
                  }
                ]
              },
              "examples": {
                "renew-search": {
                  "summary": "Buscar cuentas renovables",
                  "value": {
                    "busca": "cuenta@example.com"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/renova": {
      "post": {
        "operationId": "renew",
        "summary": "Renovar cuenta",
        "description": "Solicita renovación de una venta propia elegible.\nPermiso: gen_hys.\nRenovar cuenta: Solo se permite renovar entre 1 y 15 días antes de vencer, sujeto a elegibilidad. Un HTTP 200 con estado distinto de 1 no es éxito. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.",
        "tags": [
          "Multimedia"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "renew_0": {
                    "value": {
                      "estado": 1,
                      "correo": "cuenta@example.com",
                      "vence": "2026-11-13",
                      "tipo": "netflix",
                      "pantallas": "1",
                      "name": "Plan de ejemplo",
                      "valor": 10000,
                      "valor_fmt": "10.000 COP",
                      "saldo_anterior": 50000,
                      "saldo_nuevo": 40000
                    }
                  },
                  "renew_1": {
                    "value": {
                      "estado": 3,
                      "message": "Su saldo es insuficiente por favor recargue su cuenta."
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "crreo": {
                        "type": "string",
                        "description": "correo de loadear."
                      },
                      "idc": {
                        "type": "integer",
                        "description": "idc de loadear."
                      },
                      "pr": {
                        "type": "string",
                        "description": "perfil de loadear."
                      },
                      "vg": {
                        "type": "integer",
                        "description": "fecha_vence de loadear; días, no una fecha ISO."
                      },
                      "tip": {
                        "type": "string",
                        "description": "tipo de loadear."
                      },
                      "pantll2": {
                        "type": "string",
                        "description": "pantallas de loadear."
                      }
                    },
                    "required": [
                      "crreo",
                      "idc",
                      "vg",
                      "tip"
                    ]
                  }
                ]
              },
              "examples": {
                "renew": {
                  "summary": "Renovar cuenta",
                  "value": {
                    "crreo": "cuenta@example.com",
                    "idc": 123,
                    "pr": "1",
                    "vg": 5,
                    "tip": "netflix",
                    "pantll2": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/enlace-disney/products": {
      "get": {
        "operationId": "disney_products",
        "summary": "Consultar planes Disney",
        "description": "Consulta el catálogo y tus referencias pendientes.\nPermiso: gen_hys.\nConsultar planes Disney: No hay campos count ni trace_id garantizados en esta respuesta. Un catálogo vacío no confirma disponibilidad comercial.",
        "tags": [
          "Disney"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "disney-products_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "products": [
                          {
                            "id": 1,
                            "name": "Plan Disney de ejemplo",
                            "description": "Plan mensual de ejemplo",
                            "price": 19900
                          }
                        ],
                        "pending_references": []
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "disney-products_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/enlace-disney/buy": {
      "post": {
        "operationId": "disney_buy",
        "summary": "Comprar enlace Disney",
        "description": "Compra el plan al precio del catálogo. El saldo se descuenta al registrar la orden.\nPermiso: gen_hys.\nComprar enlace Disney: HTTP 202 con result=pending NO es un rechazo ni una devolución. Consulta la misma referencia. Repetir una referencia propia ya registrada consulta o devuelve su resultado: no inicia otra compra. Nunca cambies la referencia para resolver un timeout. Una referencia cerrada como rejected no vuelve a ejecutarse. No hay devolución automática por fallo de conexión.",
        "tags": [
          "Disney"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "disney-buy_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "result": "success",
                        "reference": "2026101300000001",
                        "link": "https://example.com/activar/ENLACE_DE_EJEMPLO",
                        "activation_url": "https://example.com/activar/ENLACE_DE_EJEMPLO",
                        "provider_id": "entrega-ejemplo",
                        "product": {
                          "id": 1,
                          "name": "Plan Disney de ejemplo",
                          "description": "Plan mensual de ejemplo",
                          "price": 19900
                        },
                        "movement_id": 123,
                        "ganancia": 0,
                        "saldo_actual": 30100
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "disney-buy_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "result": "pending",
                        "reference": "2026101300000001",
                        "message": "Confirmación pendiente. Usa Consultar estado; no repitas la compra."
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "disney-buy_0": {
                    "value": {
                      "ok": false,
                      "message": "Referencia inválida."
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "data": {
                        "type": "object",
                        "properties": {
                          "reference": {
                            "type": "string",
                            "description": "Referencia numérica única de 6 a 16 dígitos. Guárdala antes de enviar."
                          },
                          "productId": {
                            "type": "integer",
                            "description": "ID vigente del catálogo."
                          },
                          "customerName": {
                            "type": "string",
                            "description": "Nombre no vacío, máximo 160 bytes."
                          },
                          "email": {
                            "type": "string",
                            "description": "Correo válido, máximo 254 bytes."
                          },
                          "expectedPrice": {
                            "type": "number",
                            "description": "Precio mostrado; si cambió, devuelve 409 sin iniciar esa compra."
                          }
                        },
                        "required": [
                          "reference",
                          "productId",
                          "customerName",
                          "email"
                        ]
                      }
                    },
                    "required": [
                      "data"
                    ]
                  }
                ]
              },
              "examples": {
                "disney-buy": {
                  "summary": "Comprar enlace Disney",
                  "value": {
                    "data": {
                      "reference": "2026101300000001",
                      "productId": 1,
                      "customerName": "Cliente de ejemplo",
                      "email": "cliente@example.com",
                      "expectedPrice": 19900
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/enlace-disney/status": {
      "post": {
        "operationId": "disney_status",
        "summary": "Consultar compra Disney",
        "description": "Consulta una referencia propia y completa localmente la compra si se confirma la entrega.\nPermiso: gen_hys.\nConsultar compra Disney: No se envía data.id. El cuerpo y los campos de éxito coinciden con buy. HTTP 404 significa que la referencia no se encontró para tu cuenta; no confirma el resultado de una compra ajena.",
        "tags": [
          "Disney"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "disney-status_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "result": "success",
                        "reference": "2026101300000001",
                        "link": "https://example.com/activar/ENLACE_DE_EJEMPLO",
                        "activation_url": "https://example.com/activar/ENLACE_DE_EJEMPLO",
                        "provider_id": "entrega-ejemplo",
                        "product": {
                          "id": 1,
                          "name": "Plan Disney de ejemplo",
                          "description": "Plan mensual de ejemplo",
                          "price": 19900
                        },
                        "movement_id": 123,
                        "ganancia": 0,
                        "saldo_actual": 30100
                      }
                    }
                  },
                  "disney-status_1": {
                    "value": {
                      "ok": true,
                      "data": {
                        "result": "rejected",
                        "reference": "2026101300000001",
                        "message": "Compra cerrada. Consulta tus movimientos."
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "disney-status_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "result": "pending",
                        "reference": "2026101300000001",
                        "message": "Confirmación pendiente. Usa Consultar estado; no repitas la compra."
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "disney-status_0": {
                    "value": {
                      "ok": false,
                      "message": "Referencia no encontrada para tu usuario."
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "data": {
                        "type": "object",
                        "properties": {
                          "reference": {
                            "type": "string",
                            "description": "La misma referencia numérica enviada en buy."
                          }
                        },
                        "required": [
                          "reference"
                        ]
                      }
                    },
                    "required": [
                      "data"
                    ]
                  }
                ]
              },
              "examples": {
                "disney-status": {
                  "summary": "Consultar compra Disney",
                  "value": {
                    "data": {
                      "reference": "2026101300000001"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/solicite/verycode": {
      "post": {
        "operationId": "verycode",
        "summary": "Solicitar código o enlace",
        "description": "Obtiene el código o enlace de una cuenta vendida a tu usuario.\nPermiso: gen_hys.\nSolicitar código o enlace: No permite leer correos de otros clientes. No publica una lista de dominios internos. HTTP 403 EMAIL_NOT_FOUND o CODE_NOT_FOUND no significa credenciales API incorrectas. No hagas consultas continuas: solicita primero el código en el servicio y luego consulta.",
        "tags": [
          "Códigos y soporte"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "verycode_0": {
                    "value": {
                      "ok": true,
                      "code": "CODE_OK",
                      "message": "Codigo encontrado.",
                      "data": {
                        "code": "1234",
                        "date": "2026-10-13 10:30:00"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "verycode_0": {
                    "value": {
                      "ok": false,
                      "code": "EMAIL_NOT_OWNED",
                      "message": "Este correo no esta asociado a su cuenta.",
                      "data": []
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "email": {
                        "type": "string",
                        "description": "Correo asociado a una venta propia."
                      },
                      "tipo": {
                        "type": "string",
                        "description": "Tipo de cuenta exacto de la venta."
                      },
                      "caso": {
                        "type": "string",
                        "description": "Caso compatible de la tabla inferior."
                      }
                    },
                    "required": [
                      "email",
                      "tipo",
                      "caso"
                    ]
                  }
                ]
              },
              "examples": {
                "verycode": {
                  "summary": "Solicitar código o enlace",
                  "value": {
                    "email": "cuenta@example.com",
                    "tipo": "netflix",
                    "caso": "ininet"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/report": {
      "post": {
        "operationId": "report_create",
        "summary": "Reportar un fallo",
        "description": "Registra un fallo de una venta propia elegible.\nPermiso: gen_hys.\nReportar un fallo: Para seguimiento usa report_history y report_thread. El ejemplo usa JSON sin archivo. La ruta también acepta multipart/form-data con evidencia_cap; no establezcas manualmente su boundary. 409 NOT_ALLOWED significa que no hay una venta elegible o que ya está reportada.",
        "tags": [
          "Códigos y soporte"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "report-create_0": {
                    "value": {
                      "ok": true,
                      "success": true,
                      "code": "REPORTED",
                      "message": "Fallo reportado correctamente.",
                      "data": {
                        "module": "gen_hys",
                        "action": "report",
                        "correo": "cuenta@example.com",
                        "idc": "123",
                        "evidencia": ""
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "report-create_0": {
                    "value": {
                      "ok": false,
                      "error": "NOT_ALLOWED",
                      "message": "No existe venta elegible o ya reportada.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "correo": {
                        "type": "string",
                        "description": "Correo de la venta."
                      },
                      "tipo": {
                        "type": "string",
                        "description": "Tipo exacto de la venta."
                      },
                      "perfiles": {
                        "type": "string",
                        "description": "Perfil de la venta; no vacío."
                      },
                      "pantallas": {
                        "type": "string",
                        "description": "Pantallas de la venta; no vacío."
                      },
                      "mensaje": {
                        "type": "string",
                        "description": "Descripción del problema."
                      },
                      "idc": {
                        "type": "string",
                        "description": "Identificador de la cuenta, si está disponible."
                      }
                    },
                    "required": [
                      "correo",
                      "tipo",
                      "perfiles",
                      "pantallas",
                      "mensaje"
                    ]
                  }
                ]
              },
              "examples": {
                "report-create": {
                  "summary": "Reportar un fallo",
                  "value": {
                    "correo": "cuenta@example.com",
                    "tipo": "netflix",
                    "perfiles": "1",
                    "pantallas": "1",
                    "mensaje": "No permite iniciar sesión.",
                    "idc": "123"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/report_history": {
      "post": {
        "operationId": "report_history",
        "summary": "Consultar reportes",
        "description": "Consulta los reportes de fallos de tus ventas.\nPermiso: gen_hys.\nConsultar reportes: Conserva correo, tipo, perfiles y pantallas para consultar el hilo.",
        "tags": [
          "Códigos y soporte"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "report-history_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "report_history",
                        "count": 0,
                        "items": []
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "report-history_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {}
                  }
                ]
              },
              "examples": {
                "report-history": {
                  "summary": "Consultar reportes",
                  "value": {}
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/report_thread": {
      "post": {
        "operationId": "report_thread",
        "summary": "Consultar hilo de reporte",
        "description": "Consulta los mensajes de una combinación de cuenta, tipo y perfil.\nPermiso: gen_hys.\nConsultar hilo de reporte: Aunque solo correo es obligatorio, envía los cuatro valores del reporte para encontrar el hilo correcto.",
        "tags": [
          "Códigos y soporte"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "report-thread_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "report_thread",
                        "count": 0,
                        "items": []
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "report-thread_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "correo": {
                        "type": "string",
                        "description": "Correo de tu venta."
                      },
                      "tipo": {
                        "type": "string",
                        "description": "Tipo exacto del reporte."
                      },
                      "perfiles": {
                        "type": "string",
                        "description": "Perfil exacto; vacío si no aplica."
                      },
                      "pantallas": {
                        "type": "string",
                        "description": "Valor exacto del reporte; vacío si no aplica."
                      }
                    },
                    "required": [
                      "correo"
                    ]
                  }
                ]
              },
              "examples": {
                "report-thread": {
                  "summary": "Consultar hilo de reporte",
                  "value": {
                    "correo": "cuenta@example.com",
                    "tipo": "netflix",
                    "perfiles": "1",
                    "pantallas": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/recargas": {
      "post": {
        "operationId": "recharge",
        "summary": "Realizar recarga",
        "description": "Envía una recarga al número indicado.\nPermiso: gen_hys.\nRealizar recarga: Operadores: cl (Claro), mo (Movistar), ti (Tigo), et (ETB), vi (Virgin), ex (Éxito), bf (Buenofon), wm (WOM), fm (Flash Mobile), di (DirecTV). La habilitación depende de la cuenta. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nPermiso: gen_hys.\nConsultar paquetes: Los códigos disponibles dependen del servicio habilitado. Usa el catálogo, no los valores ilustrativos.\nOperadores: pc = Claro; pm = Movistar; pi = Tigo; ep = ETB; vp = Virgin; pe = Éxito; bp = Buenofon; pw = WOM. Consultar disponibilidad en el catálogo.\nPermiso: gen_hys.\nComprar paquete: El importe se obtiene del catálogo; no se fija enviando valor. Consulta el comprobante desde list_multip y list_multip_ticket para recuperar la entrega. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nOperadores: pc = Claro; pm = Movistar; pi = Tigo; ep = ETB; vp = Virgin; pe = Éxito; bp = Buenofon; pw = WOM. Consultar disponibilidad en el catálogo.\nPermiso: gen_hys.\nConsultar pines: Los códigos disponibles dependen del servicio habilitado. Usa el catálogo, no los valores ilustrativos.\nOperadores: nx = Netflix; vx = Vix; dz = Deezer; xb = Xbox; pt = PlayStation; ws = Win+; dg = DirecTV Go; ra = Razer Gold; of = Office; ff = Free Fire; iu = IMVU; ka = Kaspersky; hg = HotGo; ro = Roblox. Consultar disponibilidad en el catálogo.\nPermiso: gen_hys.\nComprar pin: El importe se obtiene del catálogo; no se fija enviando valor. Consulta el comprobante desde list_multip y list_multip_ticket para recuperar la entrega. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nOperadores: nx = Netflix; vx = Vix; dz = Deezer; xb = Xbox; pt = PlayStation; ws = Win+; dg = DirecTV Go; ra = Razer Gold; of = Office; ff = Free Fire; iu = IMVU; ka = Kaspersky; hg = HotGo; ro = Roblox. Consultar disponibilidad en el catálogo.\nPermiso: gen_hys.\nRecargar apuesta deportiva: Betplay no utiliza este flujo; consulta la solicitud de Especiales. Documento y teléfono son campos distintos. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nOperadores: lk = Luckia; rb = Rushbet; bj = Ya Juego; sm = Sportium; bs = Betsson; bw = BWin. Consultar disponibilidad en el catálogo.\nPermiso: gen_hys.\nPreconsultar EPM: Esta consulta no compra ni entrega un pin. El ejemplo omite los campos variables de la preconsulta.\nLa respuesta comercial de la preconsulta no tiene un esquema normalizado en esta ruta. Este ejemplo muestra solo la envoltura garantizada; no confirma que exista un pin ni que se haya realizado una compra.\nPermiso: gen_hys.\nComprar pin EPM: En la consulta se envían numContador y cantiVenta; en la compra, contador y valor. Conserva el pin y el comprobante de forma privada. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nPermiso: gen_hys.\nConsultar convenios de facturas: Consulta la factura antes de pagar. No uses un identificador fijo de ejemplo.\nPermiso: gen_hys.\nConsultar convenios por código de barras: Consulta la factura antes de pagar. No uses un identificador fijo de ejemplo.\nPermiso: gen_hys.\nPreconsultar factura: Con opc=1 no envíes extConvenio y ballean simultáneamente. Conserva el resultado completo. Paga únicamente si devuelve una preconsulta válida y un importe confirmado. El adaptador no normaliza el identificador ni el importe de la preconsulta a un esquema único. Si no puedes obtenerlos, no intentes el pago; solicita a soporte el contrato del convenio. El ejemplo muestra solo el campo garantizado.\nLos campos comerciales dependen del convenio. El ejemplo muestra solo la envoltura garantizada, no una factura lista para pagar. No hay un nombre único garantizado para el identificador de preconsulta o el importe.\nINTEGRACION CONDICIONADA: Validar el convenio antes de integrar: la preconsulta no normaliza identificador e importe y existe una diferencia en la clasificación del operador entre los canales. No automatizar el pago sin confirmar estos datos con soporte.\nPermiso: gen_hys.\nPagar factura: No enviar el código del convenio como idPre cuando se requiere preconsulta. No confirmar un pago únicamente porque la preconsulta fue exitosa. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nINTEGRACION CONDICIONADA: Validar el convenio antes de integrar: la preconsulta no normaliza identificador e importe y existe una diferencia en la clasificación del operador entre los canales. No automatizar el pago sin confirmar estos datos con soporte.\nPermiso: gen_hys.\nConsultar convenios de revistas: Selecciona un convenio del catálogo vigente.\nPermiso: gen_hys.\nPreconsultar revista: Usa amount para el pago; si es cero o no se confirma la factura, no continúes.\nPermiso: gen_hys.\nPagar revista: La consulta usa phone e idConv; el pago usa celular e idCon. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nPermiso: gen_hys.\nRetirar de billetera: Retira de la billetera del cliente. No confundir con una recarga a esa billetera. Requiere servicio de corresponsal habilitado. La disponibilidad del operador se valida al procesar. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nPermiso: gen_hys.\nDepositar a Movii: Requiere verificación documental de corresponsal y servicio habilitado. Deposita al celular indicado y descuenta saldo. No es el flujo de Nequi especial. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nPermiso: gen_hys.\nRetirar por ACH: Es un retiro con autorización, no una transferencia libre a una cuenta bancaria. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.\nPermiso: gen_hys.\nConsultar llave Bre-B: Requiere identidad verificada y depósitos habilitados. Esta consulta no descuenta saldo. La consulta vence en 10 minutos. Confirma destinatario, importe y costo antes del envío. Los importes del ejemplo no son tarifas fijas.\nPermiso: gen_hys.\nEnviar depósito Bre-B: HTTP 200 y ok=true no confirman entrega: comprueba estado. El saldo se descuenta al registrar el envío. No reenvíes una operación pendiente. Consulta zonabreb usando gatewayDepositToken. Repetir el mismo resolveId con la misma llave, opción y monto devuelve el estado sin otro envío; un resolveId nuevo NO protege contra duplicidad. Máximo dos depósitos registrados por día, usuario y llave; pueden existir límites adicionales. RECHAZADO confirmado incluye devolución del descuento total. Un timeout no confirma rechazo.\nPermiso: gen_hys.\nConsultar paquetes Venezuela: Esta ficha cubre la consulta. La compra de estos productos requiere confirmar la correspondencia del catálogo de venta; no se anuncia como un flujo de compra validado.\nINTEGRACION CONDICIONADA: Solo consulta de catálogo. La correspondencia con la operación de compra no está validada.",
        "tags": [
          "Multiproducto"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "recharge_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "recargas",
                        "flow": "recarga",
                        "idtrans": "DEMO_20261013_001",
                        "provider_status": 200,
                        "provider": {
                          "idtrans": "DEMO_20261013_001",
                          "estado": "00",
                          "respuesta": "Transaccion exitosa",
                          "date": "2026-10-13 10:30:00",
                          "valor": 5000,
                          "producto": "Recarga claro",
                          "telefono": "3000000000",
                          "operador": "cl"
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "paquetes_list_1": {
                    "value": {
                      "ok": true,
                      "data": {
                        "operador": "pc",
                        "count": 1,
                        "rows": [
                          {
                            "practi_code": 123,
                            "product_desc": "Paquete de ejemplo",
                            "sell": 10000
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "paquete_2": {
                    "value": {
                      "ok": true,
                      "data": {
                        "idtrans": "DEMO_20261013_002",
                        "estado": "00",
                        "respuesta": "Transaccion exitosa",
                        "date": "2026-10-13 10:30:00"
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "pines_list_3": {
                    "value": {
                      "ok": true,
                      "data": {
                        "operador": "nx",
                        "count": 1,
                        "rows": [
                          {
                            "practi_code": "123",
                            "product_desc": "Pin de ejemplo",
                            "sell": 10000
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "pines_4": {
                    "value": {
                      "ok": true,
                      "data": {
                        "idtrans": "DEMO_20261013_002",
                        "estado": "00",
                        "respuesta": "Transaccion exitosa",
                        "date": "2026-10-13 10:30:00"
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "sports_5": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "recargas",
                        "flow": "apuesta",
                        "idtrans": "DEMO_APUESTA_001",
                        "provider": {
                          "estado": "00",
                          "respuesta": "Transaccion exitosa"
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "epm-query_6": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "recargas",
                        "flow": "epm_preconsulta",
                        "provider": {
                          "date": "2026-10-13 10:30:00 AM"
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "epm-buy_7": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "recargas",
                        "flow": "epm_compra",
                        "provider": {
                          "idtrans": "DEMO_EPM_001",
                          "respuesta": "Transaccion Exitosa!",
                          "date": "2026-10-13 10:30:00",
                          "info": {
                            "Pin:": "PIN_DE_EJEMPLO",
                            "Cantidad Kwh": "",
                            "Estrato": "",
                            "Subsidio": "",
                            "Contribucion": "",
                            "Otros Cobros": "",
                            "Valor Aplicar Deuda": "",
                            "Saldo Pendiente": "",
                            "Valor Tasa Aseo": "",
                            "Saldo Tasa Aseo": ""
                          }
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "facturas_convenio_consulta_8": {
                    "value": {
                      "ok": true,
                      "data": {
                        "busqueda": "",
                        "count": 1,
                        "rows": [
                          {
                            "id": "123",
                            "nombre": "Convenio de ejemplo",
                            "opt": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "facturas_barcode_convenio_consulta_9": {
                    "value": {
                      "ok": true,
                      "data": {
                        "busqueda": "",
                        "count": 1,
                        "rows": [
                          {
                            "id": "123",
                            "nombre": "Convenio de ejemplo",
                            "opt": 1
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "invoice-query_10": {
                    "value": {
                      "ok": true,
                      "data": {
                        "date": "2026-10-13 10:30:00 AM"
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "invoice-pay_11": {
                    "value": {
                      "ok": true,
                      "data": {
                        "idtrans": "DEMO_FACTURA_001",
                        "estado": "00",
                        "respuesta": "Transaccion exitosa",
                        "date": "2026-10-13 10:30:00",
                        "valor": 20000,
                        "idPre": "ID_DE_PRECONSULTA",
                        "operador": "fc",
                        "info": {
                          "Referencia": "REFERENCIA_DE_FACTURA",
                          "Codigo Convenio": "123",
                          "Nombre Convenio": "Convenio de ejemplo",
                          "LINEA DE ATENCION AL CLIENTE": ""
                        }
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "magazine-list_12": {
                    "value": {
                      "ok": true,
                      "data": {
                        "count": 1,
                        "rows": [
                          {
                            "id": 123,
                            "name": "Revista de ejemplo",
                            "nombre": "Revista de ejemplo",
                            "image": "https://example.com/revista.png",
                            "city": "Colombia"
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "magazine-query_13": {
                    "value": {
                      "ok": true,
                      "data": {
                        "idConv": "123",
                        "reference": "123456",
                        "referencia": "123456",
                        "amount": 20000
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "magazine-pay_14": {
                    "value": {
                      "ok": true,
                      "data": {
                        "idtrans": "DEMO_REVISTA_001",
                        "estado": "00",
                        "respuesta": "Transaccion exitosa",
                        "date": "2026-10-13 10:30:00",
                        "reference": "123456",
                        "amount": 20000,
                        "producto": "Pago de revistas 123456"
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "wallet-withdraw_15": {
                    "value": {
                      "ok": true,
                      "data": {
                        "idtrans": "DEMO_RETIRO_001",
                        "estado": "00",
                        "respuesta": "Transaccion exitosa",
                        "date": "2026-10-13 10:30:00",
                        "valor": 20000,
                        "telefono": "3000000000",
                        "operador": "tpr",
                        "codigoauth": "AUTORIZACION_EJEMPLO"
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "wallet-deposit_16": {
                    "value": {
                      "ok": true,
                      "data": {
                        "idtrans": "DEMO_MOVII_001",
                        "estado": "00",
                        "respuesta": "Transaccion exitosa",
                        "date": "2026-10-13 10:30:00",
                        "valor": 20000,
                        "telefono": "3000000000",
                        "operador": "mm",
                        "codigoauth": "AUTORIZACION_EJEMPLO"
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "ach-withdraw_17": {
                    "value": {
                      "ok": true,
                      "data": {
                        "idtrans": "DEMO_ACH_001",
                        "estado": "00",
                        "respuesta": "Transaccion exitosa",
                        "date": "2026-10-13 10:30:00",
                        "valor": 20000,
                        "cuenta": "0000000001",
                        "documento": "1000000000",
                        "banco": 1,
                        "codigoauth": "AUTORIZACION_EJEMPLO"
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "breb-resolve_18": {
                    "value": {
                      "ok": true,
                      "data": {
                        "provider": {
                          "resolved": true,
                          "cashinEnabled": true,
                          "disperser": "proveedor1",
                          "resolveId": "000000000000000000000000000000000000000000000001",
                          "keyData": {
                            "keyValue": "3000000000",
                            "accountHolderName": "Destinatario de ejemplo",
                            "bankName": "Entidad de ejemplo"
                          },
                          "cashinCost": 500,
                          "cashinMaxAmount": 100000
                        }
                      }
                    }
                  },
                  "breb-deposit_19": {
                    "value": {
                      "ok": true,
                      "data": {
                        "provider": {
                          "gatewayDepositToken": "000000000000000000000000000000000000000000000001",
                          "disperser": "proveedor1",
                          "recipientLabel": "Destinatario de ejemplo",
                          "estado": "PENDIENTE",
                          "respuesta": "Solicitud registrada. Consulta en Zona Bre-B; no repitas el envio.",
                          "manualVerificationRequired": true,
                          "transactionId": "REF_BREB_EJEMPLO",
                          "amount": 20000,
                          "cost": 500,
                          "totalDebit": 20500,
                          "date": "2026-10-13 10:30:00"
                        }
                      }
                    }
                  },
                  "breb-deposit_20": {
                    "value": {
                      "ok": true,
                      "data": {
                        "provider": {
                          "gatewayDepositToken": "000000000000000000000000000000000000000000000001",
                          "disperser": "proveedor1",
                          "recipientLabel": "Destinatario de ejemplo",
                          "estado": "ACCP",
                          "respuesta": "Deposito confirmado",
                          "manualVerificationRequired": false,
                          "transactionId": "REF_BREB_EJEMPLO",
                          "amount": 20000,
                          "cost": 500,
                          "totalDebit": 20500,
                          "date": "2026-10-13 10:30:00"
                        }
                      }
                    }
                  },
                  "breb-deposit_21": {
                    "value": {
                      "ok": true,
                      "data": {
                        "provider": {
                          "gatewayDepositToken": "000000000000000000000000000000000000000000000001",
                          "disperser": "proveedor1",
                          "recipientLabel": "Destinatario de ejemplo",
                          "estado": "RECHAZADO",
                          "respuesta": "Rechazado y saldo devuelto",
                          "manualVerificationRequired": false,
                          "transactionId": "REF_BREB_EJEMPLO",
                          "amount": 20000,
                          "cost": 500,
                          "totalDebit": 20500,
                          "date": "2026-10-13 10:30:00"
                        }
                      }
                    }
                  },
                  "venezuela-catalog_22": {
                    "value": {
                      "ok": true,
                      "data": {
                        "operador": "dtvn",
                        "count": 1,
                        "rows": [
                          {
                            "id": 123,
                            "name": "Paquete de ejemplo",
                            "nombre": "Paquete de ejemplo",
                            "price": 10000,
                            "sell": 10000,
                            "cost": 10000,
                            "product_desc": "Paquete de ejemplo",
                            "practi_code": 123
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "recharge_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "paquetes_list_1": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "paquete_2": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "pines_list_3": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "pines_4": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "sports_5": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "epm-query_6": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "epm-buy_7": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "facturas_convenio_consulta_8": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "facturas_barcode_convenio_consulta_9": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "invoice-query_10": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "invoice-pay_11": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "magazine-list_12": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "magazine-query_13": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "magazine-pay_14": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "wallet-withdraw_15": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "wallet-deposit_16": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "ach-withdraw_17": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  },
                  "venezuela-catalog_18": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-deposit_0": {
                    "value": {
                      "ok": false,
                      "error": "BREB_GATEWAY_ERROR",
                      "message": "No se envio el deposito. Saldo insuficiente."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-resolve_0": {
                    "value": {
                      "ok": false,
                      "error": "BREB_GATEWAY_ERROR",
                      "message": "Selecciona dispersor y llave validos."
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "recarga.",
                        "enum": [
                          "recarga"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Número de 7 a 15 dígitos; conservar ceros iniciales."
                      },
                      "operador": {
                        "type": "string",
                        "description": "Código del servicio."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "valor": {
                        "type": "number",
                        "description": "Monto positivo en COP."
                      },
                      "opc": {
                        "type": "integer",
                        "description": "Usar 1 para el flujo documentado; omitir equivale a 1."
                      },
                      "originCash": {
                        "type": "string",
                        "description": "Identificador de origen, predeterminado 0."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "operador",
                      "idtrans",
                      "valor"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "paquetes_list.",
                        "enum": [
                          "paquetes_list"
                        ]
                      },
                      "operador": {
                        "type": "string",
                        "description": "Código del operador habilitado."
                      },
                      "force_refresh": {
                        "type": "boolean",
                        "description": "Solicita refrescar el catálogo. No usar en cada consulta."
                      }
                    },
                    "required": [
                      "flow",
                      "operador"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "paquete.",
                        "enum": [
                          "paquete"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Número de 7 a 15 dígitos; conservar ceros iniciales."
                      },
                      "operador": {
                        "type": "string",
                        "description": "Código del servicio."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "paquete": {
                        "type": "integer",
                        "description": "practi_code del catálogo; positivo."
                      },
                      "force_refresh": {
                        "type": "boolean",
                        "description": "Refrescar catálogo antes de validar el producto."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "operador",
                      "idtrans",
                      "paquete"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "pines_list.",
                        "enum": [
                          "pines_list"
                        ]
                      },
                      "operador": {
                        "type": "string",
                        "description": "Código del operador habilitado."
                      },
                      "force_refresh": {
                        "type": "boolean",
                        "description": "Solicita refrescar el catálogo. No usar en cada consulta."
                      }
                    },
                    "required": [
                      "flow",
                      "operador"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "pines.",
                        "enum": [
                          "pines"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Número de 7 a 15 dígitos; conservar ceros iniciales."
                      },
                      "operador": {
                        "type": "string",
                        "description": "Código del servicio."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "paquete": {
                        "type": "integer",
                        "description": "practi_code del catálogo; positivo."
                      },
                      "email": {
                        "type": "string",
                        "description": "Correo del destinatario; obligatorio para los pines que lo requieren."
                      },
                      "force_refresh": {
                        "type": "boolean",
                        "description": "Refrescar catálogo antes de validar el producto."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "operador",
                      "idtrans",
                      "paquete"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "apuesta.",
                        "enum": [
                          "apuesta"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Documento del cliente: de 7 a 15 dígitos; no es su teléfono."
                      },
                      "telefono": {
                        "type": "string",
                        "description": "Teléfono del cliente: de 7 a 15 dígitos."
                      },
                      "operador": {
                        "type": "string",
                        "description": "lk Luckia, rb Rushbet, bj Ya Juego, sm Sportium, bs Betsson o bw BWin."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "valor": {
                        "type": "number",
                        "description": "Monto mínimo 2000 COP."
                      },
                      "name": {
                        "type": "string",
                        "description": "Obligatorio para Luckia."
                      },
                      "opc": {
                        "type": "integer",
                        "description": "Usar 1."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "telefono",
                      "operador",
                      "idtrans",
                      "valor"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "epm_preconsulta.",
                        "enum": [
                          "epm_preconsulta"
                        ]
                      },
                      "numContador": {
                        "type": "string",
                        "description": "Número de contador, solo dígitos; conservar ceros iniciales."
                      },
                      "cantiVenta": {
                        "type": "number",
                        "description": "Valor positivo en COP."
                      }
                    },
                    "required": [
                      "flow",
                      "numContador",
                      "cantiVenta"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "epm_compra.",
                        "enum": [
                          "epm_compra"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Celular de 7 a 15 dígitos."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "contador": {
                        "type": "string",
                        "description": "El mismo contador preconsultado, conservando ceros iniciales."
                      },
                      "valor": {
                        "type": "number",
                        "description": "Valor positivo en COP."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "idtrans",
                      "contador",
                      "valor"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "facturas_convenio_consulta.",
                        "enum": [
                          "facturas_convenio_consulta"
                        ]
                      },
                      "busqueda": {
                        "type": "string",
                        "description": "Texto para filtrar convenios."
                      },
                      "force_refresh": {
                        "type": "boolean",
                        "description": "Refrescar el catálogo; no enviar en cada consulta."
                      }
                    },
                    "required": [
                      "flow"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "facturas_barcode_convenio_consulta.",
                        "enum": [
                          "facturas_barcode_convenio_consulta"
                        ]
                      },
                      "busqueda": {
                        "type": "string",
                        "description": "Texto para filtrar convenios."
                      },
                      "force_refresh": {
                        "type": "boolean",
                        "description": "Refrescar el catálogo; no enviar en cada consulta."
                      }
                    },
                    "required": [
                      "flow"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "facturas_consulta.",
                        "enum": [
                          "facturas_consulta"
                        ]
                      },
                      "opc": {
                        "type": "integer",
                        "description": "Modalidad del convenio: 1 o 2."
                      },
                      "idConv": {
                        "type": "string",
                        "description": "Identificador del convenio; obligatorio si no envías ballean."
                      },
                      "extConvenio": {
                        "type": "string",
                        "description": "Referencia de la factura para consulta sin código de barras."
                      },
                      "ballean": {
                        "type": "string",
                        "description": "Código de barras completo, conservando ceros iniciales."
                      }
                    },
                    "required": [
                      "flow",
                      "opc"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "facturas_pago.",
                        "enum": [
                          "facturas_pago"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Celular de 7 a 15 dígitos."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "idPre": {
                        "type": "string",
                        "description": "Identificador de una preconsulta válida."
                      },
                      "valor": {
                        "type": "number",
                        "description": "Importe positivo confirmado en la preconsulta."
                      },
                      "opc": {
                        "type": "integer",
                        "description": "Misma modalidad de consulta: 1 o 2."
                      },
                      "operador": {
                        "type": "integer",
                        "description": "Con opc=1: 0 para convenio general, 1 para gas/energía. Usar la clasificación del convenio, no inferirla del nombre."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "idtrans",
                      "idPre",
                      "valor",
                      "opc",
                      "operador"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "revistas_convenio.",
                        "enum": [
                          "revistas_convenio"
                        ]
                      }
                    },
                    "required": [
                      "flow"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "revistas_consulta.",
                        "enum": [
                          "revistas_consulta"
                        ]
                      },
                      "idConv": {
                        "type": "string",
                        "description": "ID del convenio seleccionado."
                      },
                      "referencia": {
                        "type": "integer",
                        "description": "Referencia numérica positiva de la cuenta o factura del cliente."
                      },
                      "phone": {
                        "type": "string",
                        "description": "Teléfono del cliente, solo dígitos."
                      }
                    },
                    "required": [
                      "flow",
                      "idConv",
                      "referencia",
                      "phone"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "revistas_pago.",
                        "enum": [
                          "revistas_pago"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Celular de 7 a 15 dígitos."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "idCon": {
                        "type": "integer",
                        "description": "ID positivo del convenio; corresponde a idConv de la consulta."
                      },
                      "reference": {
                        "type": "string",
                        "description": "reference de la preconsulta."
                      },
                      "valor": {
                        "type": "number",
                        "description": "amount positivo de la preconsulta."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "idtrans",
                      "idCon",
                      "reference",
                      "valor"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "wallet_cashout.",
                        "enum": [
                          "wallet_cashout"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Celular de 7 a 15 dígitos."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "operador": {
                        "type": "string",
                        "description": "gr RedGage, tpr Tpaga, to TOP o clr Claro Pay."
                      },
                      "valor": {
                        "type": "number",
                        "description": "Importe positivo en COP."
                      },
                      "tokenr": {
                        "type": "string",
                        "description": "Código de retiro del cliente; conservar ceros iniciales."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "idtrans",
                      "operador",
                      "valor",
                      "tokenr"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "wallet_cashin.",
                        "enum": [
                          "wallet_cashin"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Celular de 7 a 15 dígitos."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "operador": {
                        "type": "string",
                        "description": "mm: Movii. No usar códigos de otras billeteras en este flujo."
                      },
                      "valor": {
                        "type": "number",
                        "description": "Importe positivo en COP."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "idtrans",
                      "operador",
                      "valor"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "ach.",
                        "enum": [
                          "ach"
                        ]
                      },
                      "celular": {
                        "type": "string",
                        "description": "Celular de 7 a 15 dígitos."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "athBanco": {
                        "type": "integer",
                        "description": "Banco: 1 Bogotá, 2 Popular, 3 Occidente, 4 AV Villas, 5 Agrario, 6 Davibank, 7 Caja Social."
                      },
                      "athNuCuenta": {
                        "type": "string",
                        "description": "Número de cuenta; conservar ceros iniciales."
                      },
                      "athIdentificacion": {
                        "type": "string",
                        "description": "Documento del titular."
                      },
                      "tokenr": {
                        "type": "string",
                        "description": "Código de autorización del retiro."
                      },
                      "valor": {
                        "type": "number",
                        "description": "Importe positivo en COP."
                      }
                    },
                    "required": [
                      "flow",
                      "celular",
                      "idtrans",
                      "athBanco",
                      "athNuCuenta",
                      "athIdentificacion",
                      "tokenr",
                      "valor"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "breb_key_resolve.",
                        "enum": [
                          "breb_key_resolve"
                        ]
                      },
                      "disperser": {
                        "type": "string",
                        "description": "Código público: proveedor1 o proveedor3. proveedor2 no está disponible para depósitos."
                      },
                      "keyValue": {
                        "type": "string",
                        "description": "Llave del destinatario, entre 3 y 180 bytes."
                      }
                    },
                    "required": [
                      "flow",
                      "disperser",
                      "keyValue"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "breb_key_cashin.",
                        "enum": [
                          "breb_key_cashin"
                        ]
                      },
                      "disperser": {
                        "type": "string",
                        "description": "Código público: proveedor1 o proveedor3. proveedor2 no está disponible para depósitos."
                      },
                      "keyValue": {
                        "type": "string",
                        "description": "Llave del destinatario, entre 3 y 180 bytes."
                      },
                      "resolveId": {
                        "type": "string",
                        "description": "resolveId recibido al consultar esa misma llave."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única de 6 a 64 caracteres: letras, números, guion o guion bajo."
                      },
                      "valor": {
                        "type": "integer",
                        "description": "COP entero: mínimo 10000 y máximo cashinMaxAmount."
                      },
                      "note": {
                        "type": "string",
                        "description": "Concepto; se limita a 120 bytes."
                      }
                    },
                    "required": [
                      "flow",
                      "disperser",
                      "keyValue",
                      "resolveId",
                      "idtrans",
                      "valor"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "flow": {
                        "type": "string",
                        "description": "venquetes_list.",
                        "enum": [
                          "venquetes_list"
                        ]
                      },
                      "operador": {
                        "type": "string",
                        "description": "dtvn Digitel, movn Movistar, mvn Movilnet o stv SimpleTV."
                      },
                      "force_refresh": {
                        "type": "boolean",
                        "description": "Refrescar catálogo; no usar en cada solicitud."
                      }
                    },
                    "required": [
                      "flow",
                      "operador"
                    ]
                  }
                ]
              },
              "examples": {
                "recharge": {
                  "summary": "Realizar recarga",
                  "value": {
                    "flow": "recarga",
                    "celular": "3000000000",
                    "operador": "cl",
                    "idtrans": "DEMO_20261013_001",
                    "valor": 5000,
                    "opc": 1
                  }
                },
                "paquetes_list": {
                  "summary": "Consultar paquetes",
                  "value": {
                    "flow": "paquetes_list",
                    "operador": "pc"
                  }
                },
                "paquete": {
                  "summary": "Comprar paquete",
                  "value": {
                    "flow": "paquete",
                    "celular": "3000000000",
                    "operador": "pc",
                    "idtrans": "DEMO_20261013_002",
                    "paquete": 123
                  }
                },
                "pines_list": {
                  "summary": "Consultar pines",
                  "value": {
                    "flow": "pines_list",
                    "operador": "nx"
                  }
                },
                "pines": {
                  "summary": "Comprar pin",
                  "value": {
                    "flow": "pines",
                    "celular": "3000000000",
                    "operador": "nx",
                    "idtrans": "DEMO_20261013_002",
                    "paquete": 123,
                    "email": "cliente@example.com"
                  }
                },
                "sports": {
                  "summary": "Recargar apuesta deportiva",
                  "value": {
                    "flow": "apuesta",
                    "celular": "1000000000",
                    "telefono": "3000000000",
                    "operador": "lk",
                    "idtrans": "DEMO_APUESTA_001",
                    "valor": 5000,
                    "name": "Cliente de ejemplo",
                    "opc": 1
                  }
                },
                "epm-query": {
                  "summary": "Preconsultar EPM",
                  "value": {
                    "flow": "epm_preconsulta",
                    "numContador": "00000000001",
                    "cantiVenta": 20000
                  }
                },
                "epm-buy": {
                  "summary": "Comprar pin EPM",
                  "value": {
                    "flow": "epm_compra",
                    "celular": "3000000000",
                    "idtrans": "DEMO_EPM_001",
                    "contador": "00000000001",
                    "valor": 20000
                  }
                },
                "facturas_convenio_consulta": {
                  "summary": "Consultar convenios de facturas",
                  "value": {
                    "flow": "facturas_convenio_consulta",
                    "busqueda": ""
                  }
                },
                "facturas_barcode_convenio_consulta": {
                  "summary": "Consultar convenios por código de barras",
                  "value": {
                    "flow": "facturas_barcode_convenio_consulta",
                    "busqueda": ""
                  }
                },
                "invoice-query": {
                  "summary": "Preconsultar factura",
                  "value": {
                    "flow": "facturas_consulta",
                    "opc": 1,
                    "idConv": "ID_DEL_CONVENIO",
                    "extConvenio": "REFERENCIA_DE_FACTURA"
                  }
                },
                "invoice-pay": {
                  "summary": "Pagar factura",
                  "value": {
                    "flow": "facturas_pago",
                    "celular": "3000000000",
                    "idtrans": "DEMO_FACTURA_001",
                    "idPre": "ID_DE_PRECONSULTA",
                    "valor": 20000,
                    "opc": 1,
                    "operador": 0
                  }
                },
                "magazine-list": {
                  "summary": "Consultar convenios de revistas",
                  "value": {
                    "flow": "revistas_convenio"
                  }
                },
                "magazine-query": {
                  "summary": "Preconsultar revista",
                  "value": {
                    "flow": "revistas_consulta",
                    "idConv": "123",
                    "referencia": 123456,
                    "phone": "3000000000"
                  }
                },
                "magazine-pay": {
                  "summary": "Pagar revista",
                  "value": {
                    "flow": "revistas_pago",
                    "celular": "3000000000",
                    "idtrans": "DEMO_REVISTA_001",
                    "idCon": 123,
                    "reference": "123456",
                    "valor": 20000
                  }
                },
                "wallet-withdraw": {
                  "summary": "Retirar de billetera",
                  "value": {
                    "flow": "wallet_cashout",
                    "celular": "3000000000",
                    "idtrans": "DEMO_RETIRO_001",
                    "operador": "tpr",
                    "valor": 20000,
                    "tokenr": "000000"
                  }
                },
                "wallet-deposit": {
                  "summary": "Depositar a Movii",
                  "value": {
                    "flow": "wallet_cashin",
                    "celular": "3000000000",
                    "idtrans": "DEMO_MOVII_001",
                    "operador": "mm",
                    "valor": 20000
                  }
                },
                "ach-withdraw": {
                  "summary": "Retirar por ACH",
                  "value": {
                    "flow": "ach",
                    "celular": "3000000000",
                    "idtrans": "DEMO_ACH_001",
                    "athBanco": 1,
                    "athNuCuenta": "0000000001",
                    "athIdentificacion": "1000000000",
                    "tokenr": "000000",
                    "valor": 20000
                  }
                },
                "breb-resolve": {
                  "summary": "Consultar llave Bre-B",
                  "value": {
                    "flow": "breb_key_resolve",
                    "disperser": "proveedor1",
                    "keyValue": "3000000000"
                  }
                },
                "breb-deposit": {
                  "summary": "Enviar depósito Bre-B",
                  "value": {
                    "flow": "breb_key_cashin",
                    "disperser": "proveedor1",
                    "keyValue": "3000000000",
                    "resolveId": "000000000000000000000000000000000000000000000001",
                    "idtrans": "DEMO_BREB_001",
                    "valor": 20000,
                    "note": "Transferencia Bre-B"
                  }
                },
                "venezuela-catalog": {
                  "summary": "Consultar paquetes Venezuela",
                  "value": {
                    "flow": "venquetes_list",
                    "operador": "dtvn"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/cr-freefire/catalog": {
      "get": {
        "operationId": "freefire_catalog",
        "summary": "Freefire ID: catalogo",
        "description": "Recarga directa al ID del jugador; no entrega un codigo PIN. Consulta paquetes y hasta 30 ordenes propias recientes.\nPermiso: gen_hys.\nFreefire ID: catalogo: Requiere Bearer con permiso gen_hys, cuenta COP, modulo recargas_general y servicio habilitados. Cuerpos JSON directos, sin envolver en data. Solo una unidad por compra. Los paquetes agotados se omiten. La disponibilidad y el precio pueden cambiar: quote y buy vuelven a verificarlos. No enviar precios ni porcentajes en las solicitudes: los calcula CopDigital.",
        "tags": [
          "Multiproducto"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "freefire-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "enabled": true,
                        "packages": [
                          {
                            "id": 272,
                            "product_id": 29,
                            "name": "Free Fire - Latam 110 Diamond",
                            "usd": "0.869000",
                            "fields": [
                              "userid"
                            ],
                            "requires_validation": true,
                            "rate_cop": 3130,
                            "cop": "2719.970"
                          }
                        ],
                        "orders": []
                      }
                    }
                  },
                  "freefire-catalog_1": {
                    "value": {
                      "ok": true,
                      "data": {
                        "enabled": false,
                        "packages": [],
                        "orders": []
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "freefire-catalog_0": {
                    "value": {
                      "ok": false,
                      "message": "No se pudo completar la solicitud. Revisa ID, disponibilidad y saldo. Si ya confirmaste, consulta la misma referencia; no repitas la compra.",
                      "error": "CRFF_UNCONFIRMED"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/cr-freefire/quote": {
      "post": {
        "operationId": "freefire_quote",
        "summary": "Freefire ID: validar y cotizar",
        "description": "Valida los datos requeridos y genera una cotizacion con referencia propia del sistema; no descuenta saldo.\nPermiso: gen_hys.\nFreefire ID: validar y cotizar: Requiere Bearer con permiso gen_hys, cuenta COP, modulo recargas_general y servicio habilitados. Cuerpos JSON directos, sin envolver en data. Solo una unidad por compra. La cotizacion vence a los 5 minutos de su creacion. Muestra jugador, paquete y precio COP antes de pedir confirmacion al cliente. Guarda data.reference y asociala a tu venta local. Cada nueva cotizacion crea otra referencia; no cotices de nuevo para resolver una compra pendiente. Sin requires_validation, nick puede ser una cadena vacia. No inventes ni confirmes un nick no recibido.",
        "tags": [
          "Multiproducto"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "freefire-quote_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "reference": "ff_0123456789abcdef0123456789abcdef",
                        "state": "quoted",
                        "name": "Free Fire - Latam 110 Diamond",
                        "userid": "123456789",
                        "nick": "JugadorDemo",
                        "usd": "0.869000",
                        "rate_cop": "3130.000000",
                        "cop": "2719.970",
                        "refunded": false
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "freefire-quote_0": {
                    "value": {
                      "ok": false,
                      "message": "No se pudo completar la solicitud. Revisa ID, disponibilidad y saldo. Si ya confirmaste, consulta la misma referencia; no repitas la compra.",
                      "error": "CRFF_UNCONFIRMED"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "package_id": {
                        "type": "integer",
                        "description": "ID vigente de paquete."
                      },
                      "userid": {
                        "type": "string",
                        "description": "ID numerico del jugador de 1 a 64 caracteres. Conservar como texto."
                      },
                      "zone": {
                        "type": "string",
                        "description": "Obligatorio si fields incluye zone; de 1 a 64 caracteres alfanumericos, guion o guion bajo."
                      }
                    },
                    "required": [
                      "package_id",
                      "userid"
                    ]
                  }
                ]
              },
              "examples": {
                "freefire-quote": {
                  "summary": "Freefire ID: validar y cotizar",
                  "value": {
                    "package_id": 272,
                    "userid": "123456789"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/cr-freefire/buy": {
      "post": {
        "operationId": "freefire_buy",
        "summary": "Freefire ID: comprar",
        "description": "Confirma una cotizacion propia vigente. Primero descuenta saldo; luego solicita la recarga y devuelve su estado registrado.\nPermiso: gen_hys.\nFreefire ID: comprar: Requiere Bearer con permiso gen_hys, cuenta COP, modulo recargas_general y servicio habilitados. Cuerpos JSON directos, sin envolver en data. Solo una unidad por compra. HTTP 200 y ok=true NO confirman entrega: solo state=completed la confirma. pending tampoco es un rechazo. Se conserva el precio cotizado durante su vigencia; un cambio en el costo del paquete puede impedir comprar y exigir una nueva cotizacion antes de cualquier envio. Si una referencia ya salio de quoted, buy devuelve su estado registrado sin generar otra compra. Aun asi, ante timeout o error consulta status: no repitas compras automaticamente ni cambies la referencia. No hay quantity ni reparto de ganancias en este flujo. El movimiento de saldo registra el descuento; no sustituye la confirmacion de entrega. Estas ordenes no se consultan en list_multip ni list_multip_ticket: usa status y catalog.orders. Construye el comprobante con sus campos.",
        "tags": [
          "Multiproducto"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "freefire-buy_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "reference": "ff_0123456789abcdef0123456789abcdef",
                        "state": "pending",
                        "name": "Free Fire - Latam 110 Diamond",
                        "userid": "123456789",
                        "nick": "JugadorDemo",
                        "usd": "0.869000",
                        "rate_cop": "3130.000000",
                        "cop": "2719.970",
                        "refunded": false
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "freefire-buy_0": {
                    "value": {
                      "ok": false,
                      "message": "No se pudo completar la solicitud. Revisa ID, disponibilidad y saldo. Si ya confirmaste, consulta la misma referencia; no repitas la compra.",
                      "error": "CRFF_UNCONFIRMED"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "reference": {
                        "type": "string",
                        "description": "Referencia exacta recibida en quote; no generar una nueva ni usar idtrans."
                      }
                    },
                    "required": [
                      "reference"
                    ]
                  }
                ]
              },
              "examples": {
                "freefire-buy": {
                  "summary": "Freefire ID: comprar",
                  "value": {
                    "reference": "ff_0123456789abcdef0123456789abcdef"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/cr-freefire/status": {
      "post": {
        "operationId": "freefire_status",
        "summary": "Freefire ID: consultar entrega",
        "description": "Consulta una referencia propia y actualiza su estado cuando se confirma el resultado.\nPermiso: gen_hys.\nFreefire ID: consultar entrega: Requiere Bearer con permiso gen_hys, cuenta COP, modulo recargas_general y servicio habilitados. Cuerpos JSON directos, sin envolver en data. Solo una unidad por compra. Programa la consulta desde tu servidor cada 30 segundos mientras siga pending. Consultas mas frecuentes pueden devolver el estado almacenado sin volver a verificar. No hay webhook al integrador en este flujo ni seguimiento automatico garantizado sin consultas: tu integracion debe consultar status. completed confirma entrega. review requiere soporte; puede corresponder a entrega parcial o fallida y NO confirma devolucion de saldo. No realices otra compra para compensarla. rejected con refunded=true: venta rechazada y reintegro confirmado. Deten las consultas. Se devuelve el monto COP originalmente descontado, sin recalcular tasa ni precio; queda un movimiento con saldo anterior y nuevo. rejected con refunded=false: consulta status con la misma referencia cada 30 segundos para confirmar el reintegro. Ante errores conserva la referencia y contacta soporte si persisten. No repitas buy ni generes otra referencia para resolver este caso. Si descontaste saldo a tu propio cliente, gestiona su devolucion en tu sistema una sola vez por reference al confirmar rejected y refunded=true. CopDigital reintegra tu cuenta de integrador, no el saldo interno de tus clientes. No cambian rutas, autenticacion ni campos de solicitud. Actualiza tu manejo de estados para reconocer rejected y el booleano refunded; un campo ausente no confirma reintegro. Si status devuelve quoted, esa cotizacion aun no tiene compra registrada; no se ha descontado saldo por ella. El limite de 5 minutos sigue aplicando a buy. Ante 409 o fallo de red conserva la referencia y consulta; un error no demuestra que no se desconto saldo. Consulta movimientos para conciliar y contacta soporte si persiste. Los errores funcionales se agrupan en 409 CRFF_UNCONFIRMED; acceso puede fallar con 401/403, moneda no COP con 422, metodo incorrecto con 405. No hay trace_id garantizado en estas cuatro rutas.",
        "tags": [
          "Multiproducto"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "freefire-status_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "reference": "ff_0123456789abcdef0123456789abcdef",
                        "state": "completed",
                        "name": "Free Fire - Latam 110 Diamond",
                        "userid": "123456789",
                        "nick": "JugadorDemo",
                        "usd": "0.869000",
                        "rate_cop": "3130.000000",
                        "cop": "2719.970",
                        "refunded": false
                      }
                    }
                  },
                  "freefire-status_1": {
                    "value": {
                      "ok": true,
                      "data": {
                        "reference": "ff_0123456789abcdef0123456789abcdef",
                        "state": "quoted",
                        "name": "Free Fire - Latam 110 Diamond",
                        "userid": "123456789",
                        "nick": "JugadorDemo",
                        "usd": "0.869000",
                        "rate_cop": "3130.000000",
                        "cop": "2719.970",
                        "refunded": false
                      }
                    }
                  },
                  "freefire-status_2": {
                    "value": {
                      "ok": true,
                      "data": {
                        "reference": "ff_0123456789abcdef0123456789abcdef",
                        "state": "pending",
                        "name": "Free Fire - Latam 110 Diamond",
                        "userid": "123456789",
                        "nick": "JugadorDemo",
                        "usd": "0.869000",
                        "rate_cop": "3130.000000",
                        "cop": "2719.970",
                        "refunded": false
                      }
                    }
                  },
                  "freefire-status_3": {
                    "value": {
                      "ok": true,
                      "data": {
                        "reference": "ff_0123456789abcdef0123456789abcdef",
                        "state": "review",
                        "name": "Free Fire - Latam 110 Diamond",
                        "userid": "123456789",
                        "nick": "JugadorDemo",
                        "usd": "0.869000",
                        "rate_cop": "3130.000000",
                        "cop": "2719.970",
                        "refunded": false
                      }
                    }
                  },
                  "freefire-status_4": {
                    "value": {
                      "ok": true,
                      "data": {
                        "reference": "ff_0123456789abcdef0123456789abcdef",
                        "state": "rejected",
                        "name": "Free Fire - Latam 110 Diamond",
                        "userid": "123456789",
                        "nick": "JugadorDemo",
                        "usd": "0.869000",
                        "rate_cop": "3130.000000",
                        "cop": "2719.970",
                        "refunded": false
                      }
                    }
                  },
                  "freefire-status_5": {
                    "value": {
                      "ok": true,
                      "data": {
                        "reference": "ff_0123456789abcdef0123456789abcdef",
                        "state": "rejected",
                        "name": "Free Fire - Latam 110 Diamond",
                        "userid": "123456789",
                        "nick": "JugadorDemo",
                        "usd": "0.869000",
                        "rate_cop": "3130.000000",
                        "cop": "2719.970",
                        "refunded": true
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "freefire-status_0": {
                    "value": {
                      "ok": false,
                      "message": "No se pudo completar la solicitud. Revisa ID, disponibilidad y saldo. Si ya confirmaste, consulta la misma referencia; no repitas la compra.",
                      "error": "CRFF_UNCONFIRMED"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "reference": {
                        "type": "string",
                        "description": "Misma referencia guardada al cotizar y comprar."
                      }
                    },
                    "required": [
                      "reference"
                    ]
                  }
                ]
              },
              "examples": {
                "freefire-status": {
                  "summary": "Freefire ID: consultar entrega",
                  "value": {
                    "reference": "ff_0123456789abcdef0123456789abcdef"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/zonabreb": {
      "post": {
        "operationId": "breb_history",
        "summary": "Consultar depósitos Bre-B",
        "description": "Lista depósitos propios y permite actualizar uno pendiente.\nPermiso: gen_hys.\nConsultar depósitos Bre-B: Sin token se consulta el historial registrado, no se fuerza una actualización. Espera al menos 30 segundos entre actualizaciones del mismo depósito pendiente. No uses status_retry_after=0 para consultar continuamente. Incluye la fecha de envío en el rango: actualizar por token no evita el filtro de fechas. Un arreglo vacío no demuestra rechazo ni devolución.",
        "tags": [
          "Multiproducto"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-history_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "count": 1,
                        "rows": [
                          {
                            "gatewayDepositToken": "000000000000000000000000000000000000000000000001",
                            "tipo": "En proceso",
                            "monto": -20500,
                            "estado": "PENDIENTE",
                            "fecha": "2026-10-13 10:30:00",
                            "referencia": "REF_BREB_EJEMPLO",
                            "llave": "3000000000",
                            "can_refresh_status": true,
                            "status_retry_after": 0,
                            "detail": {
                              "Dispersor": "proveedor1",
                              "Llave": "3000000000",
                              "Recibe": "Destinatario de ejemplo",
                              "Valor enviado": 20000,
                              "Comision": 500,
                              "Total descontado": 20500
                            }
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-history_0": {
                    "value": {
                      "ok": false,
                      "error": "BREB_GATEWAY_ERROR",
                      "message": "Espera 30 segundos entre consultas."
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "fecha1": {
                        "type": "string",
                        "description": "Desde YYYY-MM-DD; hoy en Colombia si se omite."
                      },
                      "fecha2": {
                        "type": "string",
                        "description": "Hasta YYYY-MM-DD; hoy en Colombia si se omite."
                      },
                      "gatewayDepositToken": {
                        "type": "string",
                        "description": "Token del depósito que se desea actualizar antes de listar."
                      }
                    }
                  }
                ]
              },
              "examples": {
                "breb-history": {
                  "summary": "Consultar depósitos Bre-B",
                  "value": {
                    "fecha1": "2026-10-01",
                    "fecha2": "2026-10-13",
                    "gatewayDepositToken": "000000000000000000000000000000000000000000000001"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/list_multip": {
      "post": {
        "operationId": "multiproduct_sales",
        "summary": "Consultar ventas multiproducto",
        "description": "Lista los movimientos propios del rango solicitado.\nPermiso: gen_hys.\nConsultar ventas multiproducto: No interpreta automáticamente una compra ausente como rechazada. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.",
        "tags": [
          "Multiproducto"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "multiproduct-sales_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "list_multip",
                        "count": 0,
                        "rows": []
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "multiproduct-sales_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "fecha1": {
                        "type": "string",
                        "description": "Fecha inicial, YYYY-MM-DD."
                      },
                      "fecha2": {
                        "type": "string",
                        "description": "Fecha final, YYYY-MM-DD."
                      }
                    },
                    "required": [
                      "fecha1",
                      "fecha2"
                    ]
                  }
                ]
              },
              "examples": {
                "multiproduct-sales": {
                  "summary": "Consultar ventas multiproducto",
                  "value": {
                    "fecha1": "2026-10-01",
                    "fecha2": "2026-10-13"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/list_multip_ticket": {
      "post": {
        "operationId": "multiproduct_ticket",
        "summary": "Consultar comprobante",
        "description": "Obtiene el comprobante de una venta propia.\nPermiso: gen_hys.\nConsultar comprobante: Puede responder 404 NOT_FOUND o 409 TICKET_NOT_AVAILABLE. No envíes idTransaction como id.",
        "tags": [
          "Multiproducto"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "multiproduct-ticket_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "id": 123,
                        "title": "Comprobante CopDigital",
                        "fields": [],
                        "text_lines": []
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "multiproduct-ticket_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "data.rows[].id del historial; mayor que cero."
                      }
                    },
                    "required": [
                      "id"
                    ]
                  }
                ]
              },
              "examples": {
                "multiproduct-ticket": {
                  "summary": "Consultar comprobante",
                  "value": {
                    "id": 123
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/esp/catalog": {
      "get": {
        "operationId": "special_catalog",
        "summary": "Consultar especiales",
        "description": "Consulta servicios, paquetes y horario disponible.\nPermiso: gen_hys.\nConsultar especiales: Consulta los límites y paquetes antes de solicitar. La disponibilidad puede cambiar.",
        "tags": [
          "Especiales"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "special-catalog_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "services": [],
                        "configured": true,
                        "schedule": {
                          "open": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "special-catalog_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/esp/req": {
      "post": {
        "operationId": "special_request",
        "summary": "Solicitar recarga o retiro especial",
        "description": "Registra una solicitud especial para su procesamiento.\nPermiso: gen_hys.\nSolicitar recarga o retiro especial: Respuesta de éxito en la raíz. Algunas validaciones responden texto en lugar de JSON: conserva el código HTTP y trata el cuerpo como texto si no se puede decodificar. Retiro Nequi se registra pendiente sin descuento inicial; consulta esp/resp para su resolución. Betplay: operador=Betplay, enviar celular, identidad y telefono, valor y descript; no enviar withdrawal_code. Su disponibilidad está sujeta al horario del servicio. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.",
        "tags": [
          "Especiales"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "special-request_0": {
                    "value": {
                      "idtrans": "DEMO_ESPECIAL_001",
                      "estado": "00",
                      "respuesta": "Pendiente de confirmacion. No se desconto saldo.",
                      "date": "2026-10-13 10:30:00"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "special-request_0": {
                    "value": {
                      "ok": false,
                      "message": "Ingresa un monto entre $10.000 y $1.000.000 COP, un celular Nequi valido y, para retiros, el codigo de 6 digitos."
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "source": {
                        "type": "string",
                        "description": "especiales para Nequi y los servicios del catálogo; omitir en el flujo Betplay."
                      },
                      "operador": {
                        "type": "string",
                        "description": "RecargaNequi, RetiroNequi o servicio habilitado del catálogo. Betplay usa el flujo indicado abajo."
                      },
                      "celular": {
                        "type": "string",
                        "description": "Celular Nequi de 10 dígitos que comienza por 3; en Betplay identifica al cliente."
                      },
                      "identidad": {
                        "type": "string",
                        "description": "Identificación; para Nequi enviar el mismo celular."
                      },
                      "idtrans": {
                        "type": "string",
                        "description": "Referencia única no vacía."
                      },
                      "descript": {
                        "type": "string",
                        "description": "Descripción de la solicitud."
                      },
                      "valor": {
                        "type": "number",
                        "description": "Para Nequi, COP entero entre 10000 y 1000000; otros servicios según catálogo."
                      },
                      "withdrawal_code": {
                        "type": "string",
                        "description": "Obligatorio en RetiroNequi: 6 dígitos, conservando ceros iniciales."
                      },
                      "telefono": {
                        "type": "string",
                        "description": "Obligatorio en Betplay sin source=especiales: 10 dígitos."
                      },
                      "adicional": {
                        "type": "string",
                        "description": "Información adicional, cuando el servicio la admite."
                      }
                    },
                    "required": [
                      "operador",
                      "celular",
                      "identidad",
                      "idtrans",
                      "descript",
                      "valor"
                    ]
                  }
                ]
              },
              "examples": {
                "special-request": {
                  "summary": "Solicitar recarga o retiro especial",
                  "value": {
                    "source": "especiales",
                    "operador": "RetiroNequi",
                    "celular": "3000000000",
                    "identidad": "3000000000",
                    "idtrans": "DEMO_ESPECIAL_001",
                    "descript": "Retiro Nequi",
                    "valor": 20000,
                    "withdrawal_code": "000000"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/esp/resp": {
      "post": {
        "operationId": "special_history",
        "summary": "Consultar solicitudes especiales",
        "description": "Lista tus solicitudes y respuestas de especiales.\nPermiso: gen_hys.\nConsultar solicitudes especiales: La lista está en aaData, en la raíz. No hay paginación por parámetros.",
        "tags": [
          "Especiales"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "special-history_0": {
                    "value": {
                      "sEcho": 1,
                      "iTotalRecords": 0,
                      "iTotalDisplayRecords": 0,
                      "aaData": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "special-history_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {}
                  }
                ]
              },
              "examples": {
                "special-history": {
                  "summary": "Consultar solicitudes especiales",
                  "value": {}
                }
              }
            }
          }
        }
      }
    },
    "/v2/nq/apipes": {
      "post": {
        "operationId": "pse",
        "summary": "Generar pago PSE",
        "description": "Genera un enlace de pago por el importe solicitado.\nPermiso: payments.\nGenerar pago PSE: Requiere método habilitado y verificación de la cuenta. Consulta el pago con verifypay: Terp=PSE y data=reference. No confundas reference con provider_reference. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pse_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "provider": "pse",
                        "title": "PSE",
                        "link": "https://example.com/pagar/REFERENCIA",
                        "reference": "REF_EJEMPLO",
                        "provider_reference": "REF_ADICIONAL",
                        "return_mode": "internal"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "pse_0": {
                    "value": {
                      "ok": false,
                      "error": "INVALID_AMOUNT",
                      "message": "Digite un valor valido.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "valor": {
                        "type": "string",
                        "description": "Monto en COP, solo dígitos, sin separadores."
                      },
                      "mail": {
                        "type": "string",
                        "description": "Correo válido si se envía."
                      },
                      "description": {
                        "type": "string",
                        "description": "Descripción de hasta 120 caracteres."
                      },
                      "redirectUrl": {
                        "type": "string",
                        "description": "URL de retorno. Omitir para usar el retorno del servicio."
                      }
                    },
                    "required": [
                      "valor"
                    ]
                  }
                ]
              },
              "examples": {
                "pse": {
                  "summary": "Generar pago PSE",
                  "value": {
                    "valor": "20000",
                    "mail": "cliente@example.com"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/nq/apicop": {
      "post": {
        "operationId": "qr_generate",
        "summary": "Generar QR COP",
        "description": "Genera un QR de pago sin importe en la solicitud.\nPermiso: payments.\nGenerar QR COP: También admite GET. La respuesta normal está en la raíz, no en data. Los plazos del ejemplo son ilustrativos. Generar un QR no confirma un pago. Guarda sid para verificar y no generes otro por un timeout.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "qr-generate_0": {
                    "value": {
                      "ok": true,
                      "provider": "qr",
                      "title": "QR Multibanca",
                      "expired": false,
                      "sid": "REF_EJEMPLO",
                      "reference": "REF_EJEMPLO",
                      "total": 300,
                      "created_at": 1791900000,
                      "expire_at": 1791900300,
                      "remaining": 300,
                      "image_b64": "IMAGEN_QR_DEVUELTA",
                      "disclaimer": "",
                      "helper": "",
                      "return_mode": "internal"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "qr-generate_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "sid": {
                        "type": "string",
                        "description": "Referencia existente para solicitar su imagen; omitir al generar."
                      }
                    }
                  }
                ]
              },
              "examples": {
                "qr-generate": {
                  "summary": "Generar QR COP",
                  "value": {}
                }
              }
            }
          }
        }
      }
    },
    "/v2/nq/verify_qr": {
      "post": {
        "operationId": "qr_verify",
        "summary": "Verificar QR COP",
        "description": "Consulta el pago y aplica el saldo si está confirmado.\nPermiso: payments.\nVerificar QR COP: QR COP admite también GET con hash en query. Tiene un límite de 5 intentos de verificación; 429 VERIFY_LIMIT_REACHED no se resuelve reintentando en bucle. No es un webhook: el integrador consulta el estado.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "qr-verify_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "pending",
                        "reference": "REF_EJEMPLO",
                        "message": "Aun no se refleja un pago para este QR."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "qr-verify_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "sid": {
                        "type": "string",
                        "description": "Referencia del QR generado. También acepta data como alias."
                      }
                    },
                    "required": [
                      "sid"
                    ]
                  }
                ]
              },
              "examples": {
                "qr-verify": {
                  "summary": "Verificar QR COP",
                  "value": {
                    "sid": "REF_EJEMPLO"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/nq/cancel_qr": {
      "post": {
        "operationId": "qr_cancel",
        "summary": "Cancelar QR COP",
        "description": "Cierra un QR propio que aún no tiene pago aplicado.\nPermiso: payments.\nCancelar QR COP: Cancelar un QR no es una devolución de una compra. No permite cancelar un pago ya aplicado.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "qr-cancel_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "cancelled",
                        "reference": "REF_EJEMPLO"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "qr-cancel_0": {
                    "value": {
                      "ok": false,
                      "error": "PAYMENT_ALREADY_APPLIED",
                      "message": "Este QR ya tiene pago confirmado y no se puede rechazar.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "sid": {
                        "type": "string",
                        "description": "Referencia del QR. También acepta data como alias."
                      }
                    },
                    "required": [
                      "sid"
                    ]
                  }
                ]
              },
              "examples": {
                "qr-cancel": {
                  "summary": "Cancelar QR COP",
                  "value": {
                    "sid": "REF_EJEMPLO"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/breb/generate/qr": {
      "post": {
        "operationId": "breb_qr",
        "summary": "Generar QR Bre-B",
        "description": "Genera un QR de pago por el importe indicado.\nPermiso: payments.\nGenerar QR Bre-B: Cada QR es de un solo uso. Consulta reference con verify_qr. El valor de image del ejemplo es un marcador, no una imagen válida. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-qr_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "provider": "qr_breb",
                        "title": "QR Bre-B",
                        "image": "IMAGEN_QR_DEVUELTA",
                        "reference": "REF_EJEMPLO",
                        "provider_reference": "REF_ADICIONAL",
                        "return_mode": "internal"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-qr_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "valor": {
                        "type": "number",
                        "description": "Monto mayor que cero; máximo 50.000.000 COP."
                      }
                    },
                    "required": [
                      "valor"
                    ]
                  }
                ]
              },
              "examples": {
                "breb-qr": {
                  "summary": "Generar QR Bre-B",
                  "value": {
                    "valor": 20000
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/breb/verify_qr": {
      "post": {
        "operationId": "breb_verify",
        "summary": "Verificar QR Bre-B",
        "description": "Consulta el pago y aplica el saldo si está confirmado.\nPermiso: payments.\nVerificar QR Bre-B: Un rechazo puede responder 409 PAYMENT_REJECTED. No es un webhook: el integrador consulta el estado.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-verify_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "pending",
                        "reference": "REF_EJEMPLO",
                        "message": "Aun no se refleja una transaccion para este QR-B."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-verify_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "sid": {
                        "type": "string",
                        "description": "Referencia del QR generado. También acepta data como alias."
                      }
                    },
                    "required": [
                      "sid"
                    ]
                  }
                ]
              },
              "examples": {
                "breb-verify": {
                  "summary": "Verificar QR Bre-B",
                  "value": {
                    "sid": "REF_EJEMPLO"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/breb/cancel_qr": {
      "post": {
        "operationId": "breb_cancel",
        "summary": "Cancelar QR Bre-B",
        "description": "Cierra un QR propio que aún no tiene pago aplicado.\nPermiso: payments.\nCancelar QR Bre-B: Cancelar un QR no es una devolución de una compra. No permite cancelar un pago ya aplicado.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-cancel_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "status": "cancelled",
                        "reference": "REF_EJEMPLO"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "breb-cancel_0": {
                    "value": {
                      "ok": false,
                      "error": "PAYMENT_ALREADY_APPLIED",
                      "message": "Este QR ya tiene pago confirmado y no se puede rechazar.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "sid": {
                        "type": "string",
                        "description": "Referencia del QR. También acepta data como alias."
                      }
                    },
                    "required": [
                      "sid"
                    ]
                  }
                ]
              },
              "examples": {
                "breb-cancel": {
                  "summary": "Cancelar QR Bre-B",
                  "value": {
                    "sid": "REF_EJEMPLO"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/prix/generate/link": {
      "post": {
        "operationId": "prix",
        "summary": "Generar pago Prix",
        "description": "Genera el enlace de pago Prix.\nPermiso: payments.\nGenerar pago Prix: Verifica con POST /gen_hys/verifypay, Terp=PRIX y data=reference. No reenvíes una operación de compra por un timeout o un 5xx. Consulta su referencia o historial; si el resultado sigue sin confirmarse, contacta a soporte.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "prix_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "provider": "prix",
                        "title": "Prix",
                        "link": "https://example.com/pagar/REFERENCIA",
                        "reference": "REF_EJEMPLO",
                        "provider_reference": "REF_ADICIONAL",
                        "return_mode": "internal"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "prix_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "valor": {
                        "type": "string",
                        "description": "COP sin separadores; mínimo 20000."
                      },
                      "logoBase64": {
                        "type": "string",
                        "description": "Logo opcional en base64."
                      }
                    },
                    "required": [
                      "valor"
                    ]
                  }
                ]
              },
              "examples": {
                "prix": {
                  "summary": "Generar pago Prix",
                  "value": {
                    "valor": "20000"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/prix_status": {
      "post": {
        "operationId": "prix_status",
        "summary": "Consultar estado registrado de Prix",
        "description": "Devuelve el último estado registrado; no sustituye una verificación del pago.\nPermiso: gen_hys.\nConsultar estado registrado de Prix: Para actualizar y verificar, usa verifypay con Terp=PRIX.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "prix-status_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "prix_status",
                        "reference": "REF_EJEMPLO",
                        "provider_reference": "REF_ADICIONAL",
                        "status": "pending",
                        "status_raw": "pending",
                        "expected_amount": 20000,
                        "paid_amount": 0,
                        "cost": 0,
                        "created_at": "2026-10-13 10:30:00",
                        "paid_at": ""
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "prix-status_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "reference": {
                        "type": "string",
                        "description": "Referencia de generación. Obligatoria si no envías provider_reference."
                      },
                      "provider_reference": {
                        "type": "string",
                        "description": "Referencia adicional; alternativa a reference."
                      }
                    }
                  }
                ]
              },
              "examples": {
                "prix-status": {
                  "summary": "Consultar estado registrado de Prix",
                  "value": {
                    "reference": "REF_EJEMPLO"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/verifypay": {
      "post": {
        "operationId": "verify_payment",
        "summary": "Verificar pago",
        "description": "Verifica una referencia propia y devuelve el resultado de aplicación del pago.\nPermiso: gen_hys.\nVerificar pago: Esta ruta requiere scope gen_hys, aunque la generación en /v2/ requiere payments. Solicita ambos si vas a utilizar este flujo. Los estados y errores de pendiente varían por medio; un 409 no siempre es un rechazo definitivo.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "verify-payment_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "verifypay",
                        "terp": "PSE",
                        "status": "applied",
                        "amount": 20000,
                        "cost": 0,
                        "credit": 20000
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "verify-payment_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "Terp": {
                        "type": "string",
                        "description": "Para generación actualmente documentada: PSE, QR, QR_BREB, o PRIX."
                      },
                      "data": {
                        "type": "string",
                        "description": "reference recibida al generar el pago."
                      }
                    },
                    "required": [
                      "Terp",
                      "data"
                    ]
                  }
                ]
              },
              "examples": {
                "verify-payment": {
                  "summary": "Verificar pago",
                  "value": {
                    "Terp": "PSE",
                    "data": "REF_EJEMPLO"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gen_hys/consultpay": {
      "post": {
        "operationId": "payments_list",
        "summary": "Consultar pagos por fecha",
        "description": "Consulta el historial propio de un medio de pago.\nPermiso: gen_hys.\nConsultar pagos por fecha: Consulta el estado para confirmar el pago; no interpretes un retorno de navegador como confirmación. Para verificar, conserva la reference original de generación.",
        "tags": [
          "Pagos"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "payments-list_0": {
                    "value": {
                      "ok": true,
                      "data": {
                        "module": "gen_hys",
                        "action": "consultpay",
                        "count": 1,
                        "rows": [
                          {
                            "#": 1,
                            "id": 123,
                            "referencia": "REF_EJEMPLO",
                            "monto": 20000,
                            "estado": "PAGADO",
                            "tipo": "PSE",
                            "fechaemision": "2026-10-13 10:30:00"
                          }
                        ]
                      },
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Resultado según el estado de negocio. Ejemplos ilustrativos; pueden omitirse campos adicionales.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "examples": {
                  "payments-list_0": {
                    "value": {
                      "ok": false,
                      "error": "AUTH_API_INVALID",
                      "message": "Bearer token invalido o sin permisos API.",
                      "trace_id": "ejemplo-traza"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "fecha1": {
                        "type": "string",
                        "description": "Fecha inicial, YYYY-MM-DD."
                      },
                      "fecha2": {
                        "type": "string",
                        "description": "Fecha final, YYYY-MM-DD."
                      },
                      "Terp": {
                        "type": "string",
                        "description": "PSE, QR, QR_BREB, o PRIX para los medios documentados."
                      }
                    },
                    "required": [
                      "fecha1",
                      "fecha2",
                      "Terp"
                    ]
                  }
                ]
              },
              "examples": {
                "payments-list": {
                  "summary": "Consultar pagos por fecha",
                  "value": {
                    "fecha1": "2026-10-01",
                    "fecha2": "2026-10-13",
                    "Terp": "PSE"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
