# Acceso a la venta - Introducción

## Descripcion general

**El acceso a la venta** define como los usuarios entran al flujo de reventa desde tu seccion de *Mis tickets* para publicar o gestionar sus entradas.

La integracion principal para acceso a la venta es la **Capa de Acceso Inteligente (SAL)**.

{% callout type="info" title="Smart Access Layer" %}
La capa de acceso inteligente tambien lo vas a encontrar como Smart Access Layer (SAL) en algunos lugares de la documentacion.
{% /callout %}

Tu plataforma llama a un endpoint de alta prioridad con una lista de tickets (u ordenes) y el identificador del usuario. menta tech responde, para cada ticket u orden, con:

- El estado actual de la reventa (`SELLABLE`, `FOR_SALE`, `SOLD`, `NOT_SELLABLE`)
- Las acciones disponibles como call-to-actions (por ejemplo: vender, editar publicacion, ver detalles)
- Las URLs para ejecutar esas acciones
- Componentes de UI opcionales (por ejemplo: banner de venta)

Tu UI utiliza esta respuesta para decidir que mostrar para cada ticket y a donde enviar al usuario cuando hace clic. La informacion de tickets se consulta bajo demanda mientras el usuario ve sus tickets o inicia una accion de reventa, por lo que menta tech no agrega carga a tus onsales principales.

menta tech admite dos modelos para el Acceso a la venta:

- **Opcion 1** Capa de Acceso Inteligente (recomendado)
- **Opcion 2** URL estatica de entrada a reventa

Las reglas de reventa subyacentes son las mismas. La decision es que tan conectada debe estar tu UI de *Mis tickets* con esas reglas.

## Comparacion de modelos de integracion

{% table highlight-first=true highlight-row=2 %}
| Modelo | Descripcion | Cuando tiene sentido | Beneficios | Limitaciones |
|--------|-------------|----------------------|-----------|--------------|
| Capa de Acceso Inteligente (recomendado) | Tu backend llama al endpoint SAL de venta con tickets u ordenes y la identidad del usuario, y recibe por item el estado y las CTAs | Quieres acciones y estados de reventa nativos dentro de *Mis tickets* | Estado en tiempo real a nivel ticket, acciones contextuales, logica impulsada por reglas de menta tech, soporta flujos a nivel ticket y a nivel orden | Requiere integrar la llamada a SAL y conectar las respuestas con tu UI |
| URL estatica de entrada a reventa | Un unico enlace "Vender tickets" envia a los usuarios a una pagina generica de entrada a reventa en menta tech | Necesitas una integracion minima o un piloto rapido | Esfuerzo de implementacion muy bajo | No hay estado ni acciones por ticket en tu UI de *Mis tickets*, la experiencia se maneja integramente en menta tech |
{% /table %}

___

{% conditionaltabs id="tabs-1765307261094" %}
{% tab label="Capa de Acceso Inteligente" %}

## Capa de Acceso Inteligente (recomendado)

### Concepto

La **Capa de Acceso Inteligente** permite que tu vista de *Mis tickets* le pregunte a menta tech, para cada ticket u orden, que se puede hacer en ese momento y como hacerlo.

Para cada item que envias, menta tech evalua:

- Si el ticket es elegible para reventa, segun las reglas configuradas en el dashboard de menta tech
- Si ya esta publicado o vendido
- Que accion tiene sentido (por ejemplo: publicar en venta, editar publicacion, ver detalles, sin accion)
- Si el vendedor necesita completar su configuracion de datos de pago

El endpoint esta disenado como un camino de alta prioridad capaz de manejar solicitudes grandes de forma eficiente, con el rendimiento necesario para acciones criticas en tiempo real.

### Endpoint

```
POST https://api.mentatech.io/v1/wrapper/accesslayer
```

**Headers:**

| Header          | Requerido | Descripcion                          |
|-----------------|-----------|--------------------------------------|
| Authorization   | Si        | Tu API key                           |
| Content-Type    | Si        | `application/json`                   |

### Modos de request

El SAL de venta soporta dos modos de request. Debes enviar **tickets** **o** **orders** en el body, no ambos.

{% conditionaltabs id="tabs-sell-modes" %}
{% tab label="Modo tickets" %}

#### Modo tickets

Usa este modo cuando tu plataforma trackea tickets individuales. Envias cada `ticketId` y menta devuelve el estado y CTAs por ticket.

**Body del request:**

| Campo                    | Tipo     | Requerido | Descripcion                                         |
|--------------------------|----------|-----------|-----------------------------------------------------|
| user                     | string   | Si        | Email del usuario (el vendedor)                     |
| tickets                  | array    | Si        | Lista de tickets a evaluar                          |
| tickets[].eventId        | string   | Si        | Identificador externo del evento                    |
| tickets[].showId         | string   | Si        | Identificador externo del show                      |
| tickets[].ticketId       | string   | Si        | Identificador externo del ticket                    |
| tickets[].ticketOptionId | string   | Si        | Identificador de categoria de acceso                |
| tickets[].priceTypeId    | string   | Opcional  | Identificador de tipo de precio (cuando aplica)     |

**Ejemplo de request:**

```json
POST /v1/wrapper/accesslayer
Authorization: YOUR_API_KEY

{
  "user": "seller@example.com",
  "tickets": [
    {
      "eventId": "evt-123",
      "showId": "show-456",
      "ticketId": "T001",
      "ticketOptionId": "GA"
    },
    {
      "eventId": "evt-123",
      "showId": "show-456",
      "ticketId": "T002",
      "ticketOptionId": "VIP",
      "priceTypeId": "standard"
    }
  ]
}
```

**Ejemplo de respuesta:**

```json
{
  "data": {
    "user": "seller@example.com",
    "tickets": [
      {
        "status": "SELLABLE",
        "ticketId": "T001",
        "ticketOptionId": "GA",
        "priceTypeId": "",
        "sync": true,
        "callToActions": [
          {
            "key": "SELL",
            "text": "Sell",
            "url": "https://sell-ticket.mentatickets.com/es/publish/65fdc7eb...?ticketSellerId=2&oneTimeToken=...&utm_source=sell&syncPage=true",
            "enabled": true
          }
        ]
      },
      {
        "status": "FOR_SALE",
        "ticketId": "T002",
        "ticketOptionId": "VIP",
        "priceTypeId": "standard",
        "sync": true,
        "callToActions": [
          {
            "key": "P2P",
            "text": "Peer to Peer",
            "url": "https://event.mentatickets.com/es/...?sellerId=...&ticketSellerId=2&utm_source=sell&syncPage=true",
            "enabled": true
          },
          {
            "key": "EDIT",
            "text": "Edit Listing",
            "url": "https://sell-ticket.mentatickets.com/es/list-item/...?listingId=...&ticketSellerId=2&oneTimeToken=...&utm_source=sell&syncPage=true",
            "enabled": true
          }
        ]
      }
    ],
    "components": [
      {
        "type": "banner",
        "class": "sellBanner",
        "sellBanner": {
          "title": "Vende tus entradas",
          "description": "Publica tus tickets en el marketplace",
          "image": "https://cdn.example.com/sell-banner.png",
          "visible": true,
          "colors": {
            "background": "#0A1F44",
            "text": "#FFFFFF"
          },
          "callToAction": {
            "text": "Empezar a vender",
            "url": "https://sell-ticket.mentatickets.com/es/publish/...?ticketSellerId=2&utm_source=sell&syncPage=true",
            "enabled": true
          }
        }
      }
    ]
  },
  "errors": [],
  "status": 200
}
```

{% /tab %}

{% tab label="Modo ordenes" %}

#### Modo ordenes

Usa este modo cuando tu plataforma trackea ordenes (cada orden contiene multiples tickets). Envias cada `orderId` con sus combinaciones de categoria, y menta devuelve un estado y CTA agregado por orden.

**Body del request:**

| Campo                              | Tipo     | Requerido | Descripcion                                         |
|------------------------------------|----------|-----------|-----------------------------------------------------|
| user                               | string   | Si        | Email del usuario (el vendedor)                     |
| orders                             | array    | Si        | Lista de ordenes a evaluar                          |
| orders[].orderId                   | string   | Si        | Identificador externo de la orden                   |
| orders[].eventId                   | string   | Si        | Identificador externo del evento                    |
| orders[].showId                    | string   | Si        | Identificador externo del show                      |
| orders[].combinations              | array    | Si        | Combinaciones de ticket option/price type en la orden |
| orders[].combinations[].ticketOptionId | string | Si    | Identificador de categoria de acceso                |
| orders[].combinations[].priceTypeId    | string | Opcional | Identificador de tipo de precio                   |

**Ejemplo de request:**

```json
POST /v1/wrapper/accesslayer
Authorization: YOUR_API_KEY

{
  "user": "seller@example.com",
  "orders": [
    {
      "orderId": "ORD-001",
      "eventId": "evt-123",
      "showId": "show-456",
      "combinations": [
        { "ticketOptionId": "GA" },
        { "ticketOptionId": "VIP", "priceTypeId": "standard" }
      ]
    }
  ]
}
```

**Ejemplo de respuesta:**

```json
{
  "data": {
    "user": "seller@example.com",
    "orders": [
      {
        "orderId": "ORD-001",
        "status": "SELLABLE",
        "callToActions": [
          {
            "key": "SELL",
            "text": "Sell",
            "url": "https://sell-ticket.mentatickets.com/es/publish/...?ticketSellerId=2&oneTimeToken=...&utm_source=sell&syncPage=true",
            "enabled": true
          }
        ]
      }
    ],
    "components": []
  },
  "errors": [],
  "status": 200
}
```

{% callout type="info" title="Agregacion de estado por orden" %}
Cuando una orden contiene multiples tickets, menta evalua cada ticket individualmente y devuelve un estado agregado para la orden usando esta cascada de decision:

1. Si todos los tickets son `NOT_SELLABLE` → la orden es `NOT_SELLABLE`
2. Si algun ticket es `SELLABLE` y otros ya estan publicados o vendidos → la orden es `SELLABLE` con CTA `MANAGE`
3. Si todos los tickets son `SELLABLE` (ninguno publicado o vendido) → la orden es `SELLABLE` con CTA `SELL`
4. Si todos los tickets publicados/vendidos comparten el mismo grupo y algunos estan publicados → la orden es `FOR_SALE` con CTA `EDIT`
5. Si todos los tickets publicados/vendidos comparten el mismo grupo y todos estan vendidos → la orden es `SOLD` con CTA `DETAILS`
6. Si los tickets publicados/vendidos pertenecen a grupos diferentes → la orden es `FOR_SALE` con CTA `MANAGE`
{% /callout %}

{% /tab %}
{% /conditionaltabs %}

### Referencia de estados

| Estado         | Descripcion                                                           |
|----------------|-----------------------------------------------------------------------|
| `SELLABLE`     | El ticket puede ser publicado en venta. CTA: `SELL`                   |
| `NOT_SELLABLE` | El ticket no puede ser publicado (las reglas no lo permiten)          |
| `FOR_SALE`     | El ticket tiene una publicacion activa. CTAs: `EDIT`, `P2P`           |
| `SOLD`         | El ticket fue vendido a traves del marketplace. CTA: `DETAILS`        |

### Referencia de call-to-actions

| Key                  | Texto                 | Descripcion                                                               |
|----------------------|-----------------------|---------------------------------------------------------------------------|
| `SELL`               | Sell                  | Link para iniciar el flujo de publicacion del ticket                      |
| `EDIT`               | Edit Listing          | Link para editar o ver la publicacion activa                              |
| `DETAILS`            | View Listing Details  | Link para ver detalles de la publicacion vendida                          |
| `P2P`                | Peer to Peer          | Link para compartir la publicacion (link de compra directa)               |
| `PENDING_PAYOUT_INFO`| Pending Payout Info   | El vendedor necesita completar su configuracion de pago (aparece junto a otros CTAs) |
| `MANAGE`             | Manage Tickets        | Link a la pagina de gestion de tickets (modo ordenes, estados mixtos)     |

### El campo `sync` (modo tickets)

En modo tickets, cada ticket en la respuesta incluye un booleano `sync`:

- `sync: true` — el ticket ya esta sincronizado en la base de datos de menta.
- `sync: false` — el ticket aun no esta en la base de datos de menta. La URL del CTA incluye `syncPage=true` para que el frontend dispare la sincronizacion antes de publicar.

{% callout type="info" title="Tickets desconocidos" %}
menta no almacena tu inventario de tickets de forma permanente — los sincroniza bajo demanda cuando un usuario quiere vender. Esto significa que un `ticketId` que envies puede no existir aun en la base de datos de menta.

Cuando un ticket aun no es conocido por menta, el SAL de venta igualmente evalua su posibilidad de venta usando las reglas de reventa configuradas para esa combinacion de evento/show/categoria. Si las reglas permiten la publicacion, la respuesta devuelve `SELLABLE` con `sync: false` y una URL de CTA que dispara la sincronizacion automaticamente. Tu UI no necesita manejar esto de forma diferente — simplemente renderiza el CTA como siempre y menta se encarga del resto.
{% /callout %}

### Componentes

La respuesta incluye un array `components` con elementos de UI opcionales. Actualmente, el SAL de venta devuelve:

**Banner de venta** (`type: "banner"`, `class: "sellBanner"`)

Un banner promocional que incentiva al usuario a vender sus tickets. La visibilidad se controla por las reglas configuradas en el dashboard de menta tech.

| Campo                      | Descripcion                                  |
|----------------------------|----------------------------------------------|
| `sellBanner.title`         | Texto del titulo del banner                  |
| `sellBanner.description`   | Texto de descripcion del banner              |
| `sellBanner.image`         | URL de la imagen del banner                  |
| `sellBanner.visible`       | Si el banner debe ser renderizado            |
| `sellBanner.colors`        | Colores opcionales de fondo y texto          |
| `sellBanner.callToAction`  | CTA con texto, URL, flag enabled y colores   |

### Como usarlo en tu UI

Tu pagina de *Mis tickets* deberia:

1. Resolver la lista de tickets (u ordenes) para el usuario actual.
2. Llamar al endpoint SAL de venta con los items y el email del usuario.
3. Para cada ticket u orden en la respuesta:
   - Usar `status` para mostrar el estado actual (por ejemplo: Disponible para venta, En venta, Vendido).
   - Renderizar cada entrada en `callToActions` como un boton o link accionable, usando `text` como label y `url` como destino.
   - Si `callToActions` esta vacio, no mostrar acciones de reventa para ese item.
4. Si `components` contiene un banner de venta visible, renderizarlo en una ubicacion apropiada.

Como toda la logica de elegibilidad y estados se gestiona mediante reglas en el dashboard de menta tech, cualquier cambio que hagas ahi se refleja automaticamente en las respuestas del SAL, sin cambios de codigo de tu lado.

### Cuando tiene sentido este modelo

Usa la Capa de Acceso Inteligente cuando:

- Quieres que la reventa se sienta totalmente integrada en tu UI de *Mis tickets*.
- Necesitas estados en tiempo real a nivel ticket, como `SELLABLE`, `SOLD`, `FOR_SALE`.
- Quieres controlar desde el dashboard de menta tech en que eventos, shows o categorias esta habilitada la reventa.
- Prefieres no implementar ni mantener reglas de reventa en tu propio codigo.
- Necesitas soportar flujos de venta tanto a nivel ticket como a nivel orden.
{% /tab %}

{% tab label="URL estatica de reventa" %}

## Modelo de URL estatica de entrada a reventa

### Concepto

El modelo de entrada estatica ofrece un unico punto de entrada generico a la reventa desde tu plataforma. En lugar de preguntar a menta tech por cada ticket que mostrar, rediriges a los usuarios a una pagina generica de entrada a reventa.

**Flujo tipico:**

1. Anades un boton o elemento de menu "Vender tickets" en tu UI.
2. Ese boton apunta a una URL estatica de entrada a reventa proporcionada por menta tech.
3. menta tech autentica al usuario usando tu modelo de autenticacion elegido.
4. Dentro de menta tech, el usuario ve sus tickets elegibles y elige cuales publicar.

Tu pagina de *Mis tickets* no muestra acciones ni estados de reventa por ticket. Toda la interaccion de reventa ocurre dentro de la experiencia de menta tech.

### Cuando tiene sentido este modelo

Utiliza una URL estatica de reventa cuando:

- Quieres la integracion mas pequena posible para empezar a probar reventa.
- No necesitas acciones de reventa a nivel ticket en tu propia UI de *Mis tickets*.
- Estas ejecutando un piloto mientras planeas una futura migracion al modelo SAL.

### Beneficios

- Esfuerzo de implementacion muy bajo.
- No se requiere integracion de backend mas alla de enlazar a la URL de entrada a reventa.
- Buen punto de partida para pilotos pequenos o con fuerte limitacion de tiempo.

### Limitaciones

- No hay estado ni acciones por ticket en tu propia UI.
- El usuario siempre entra en un flujo de reventa generico y debe elegir los tickets dentro de menta tech.
- Tu plataforma no refleja las reglas de reventa definidas en el dashboard a nivel de ticket.
{% /tab %}

{% /conditionaltabs %}