# 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 mas completa para acceso a la venta es la **Capa de Acceso Inteligente (SAL)**; para el arranque mas rapido, la mayoria de las plataformas empiezan con la **URL estatica smart publish con one-time token**.

{% 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 %}

Con la Capa de Acceso Inteligente, tu plataforma llama a un endpoint de alta prioridad con una lista de tickets y el identificador del usuario. menta tech responde, para cada ticket, 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 tres modelos para el Acceso a la venta:

- **Opcion 1** Capa de Acceso Inteligente
- **Opcion 2** URL estatica smart publish con one-time token (recomendado)
- **Opcion 3** 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=3 %}
| Modelo | Descripcion | Cuando tiene sentido | Beneficios | Limitaciones |
|--------|-------------|----------------------|-----------|--------------|
| Capa de Acceso Inteligente | Tu backend llama al endpoint SAL de venta con los tickets 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 | Requiere integrar la llamada a SAL y conectar las respuestas con tu UI |
| URL estatica smart publish con one-time token (recomendado) | En cada clic, tu backend pide una URL de smart publish con un one-time token embebido y redirige al usuario | Quieres un unico punto de entrada con experiencia autenticada y una integracion minima | Una sola llamada API por clic, el usuario llega ya autenticado, menta lo enruta automaticamente al mejor destino | No hay estado ni acciones por ticket en tu UI de *Mis tickets* |
| URL estatica de entrada a reventa | Un unico enlace fijo "Vender tickets" envia a los usuarios a la pagina de entrada a reventa en menta tech | Necesitas la integracion minima absoluta o un piloto rapido | Esfuerzo de implementacion muy bajo, sin cambios de backend | No hay estado ni acciones por ticket en tu UI de *Mis tickets*, el usuario debe autenticarse en menta tech |
{% /table %}

___

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

## Capa de Acceso Inteligente

### Concepto

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

Para cada ticket 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`                   |

### Request

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
}
```

### 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 (estados mixtos)                   |

### El campo `sync`

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 para el usuario actual.
2. Llamar al endpoint SAL de venta con los tickets y el email del usuario.
3. Para cada ticket 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.
{% /tab %}

{% tab label="URL estatica smart publish" %}

## URL estatica smart publish con one-time token (recomendado)

### Concepto

**Smart Publish** es un unico punto de entrada estatico a la reventa: colocas un solo call-to-action "Vender tickets" en tu plataforma (por ejemplo en tu seccion de *Mis tickets*) y menta se encarga del resto.

En cada clic, tu backend pide una URL de smart publish nueva para el usuario y lo redirige a ella. La URL devuelta lleva embebido un **one-time token** (token de un solo uso), por lo que el usuario llega ya autenticado — sin login ni pasos extra — y menta lo enruta automaticamente al mejor destino segun su inventario de reventa:

- El wizard de publicacion, cuando tiene tickets elegibles para reventa
- La vista de gestion de publicaciones, cuando ya tiene publicaciones activas
- El hub de tickets de un show, o un selector de shows cuando tiene inventario en varios shows
- Un estado vacio, cuando no tiene nada para revender

Si el usuario todavia no existe en menta, se crea automaticamente.

**Flujo tipico:**

1. Anades un boton o elemento de menu "Vender tickets" en tu UI.
2. En cada clic, tu backend llama al endpoint de Smart Publish con el email del usuario.
3. Rediriges al usuario a la URL devuelta — llega autenticado y menta lo enruta automaticamente.

### Endpoint

```
GET https://api.mentatech.io/v1/marketplace/smartPublish
```

**Headers:**

| Header          | Requerido | Descripcion                          |
|-----------------|-----------|--------------------------------------|
| Authorization   | Si        | Tu API key                           |

**Parametros de query:**

| Parametro | Requerido | Descripcion                                                              |
|-----------|-----------|---------------------------------------------------------------------------|
| email     | Si        | Email del usuario que quiere revender sus tickets                        |
| lang      | Opcional  | Idioma de la interfaz de smart publish (por ejemplo `es`, `en`, `pt`)    |
| eventId   | Opcional  | ID del evento **en tu sistema** (deep link). Redirige al usuario directo a ese evento en lugar de rutear por todo su inventario |
| showId    | Opcional  | ID del show **en tu sistema**. Solo es valido junto a `eventId` — enviar `showId` solo devuelve `400` |

**Ejemplo de respuesta:**

```json
{
  "status": 200,
  "data": {
    "url": "https://sell-ticket.mentatickets.com/es/smart-publish?ticketSellerId=2&oneTimeToken=..."
  },
  "errors": null
}
```

{% callout type="warning" title="La URL es de un solo uso" %}
El one-time token embebido se consume cuando la URL se abre. Pide una URL nueva en cada clic y nunca la cachees ni la embebas de forma estatica en tu UI.
{% /callout %}

### Deep link a un evento o show

Envia `eventId` (y opcionalmente `showId`) para saltear el ruteo por inventario y llevar al usuario directo a un evento o show especifico — por ejemplo, desde un boton "Vender tickets" en la pagina de ese evento en tu plataforma:

```
GET https://api.mentatech.io/v1/marketplace/smartPublish?email=jane@example.com&eventId=EV123&showId=SH456
```

Ambos IDs son los **externos** de tu sistema, exactamente como los envias en la sincronizacion de tickets. Reglas:

- Recomendamos enviar el par `eventId` + `showId`: los IDs de show pueden repetirse entre eventos, y el par identifica al show sin ambiguedad.
- Si envias solo `eventId` y el evento tiene un unico show, el usuario cae directo a ese show, sin importar como se llamen los IDs. Si tus eventos tienen varios shows, envia ambos campos — con `eventId` solo no adivinamos el show.
- Si el deep link no matchea nada accionable para el usuario (evento inexistente, o sin tickets ni publicaciones ahi), aterriza en el estado vacio — nunca en el selector de shows ni en una pagina rota. El boton de actualizar del estado vacio conserva el deep link y vuelve a resolver.
- Sin `eventId` ni `showId` el comportamiento es el de siempre: menta rutea segun todo el inventario del usuario (show unico, selector de shows o estado vacio).

Consulta la documentacion completa del endpoint en la <a href='https://connect.mentatech.io/es/api/get-marketplace-smartPublish' target="_blank">API Reference: Get Smart Publish URL</a>.

### Cuando tiene sentido este modelo

Usa la URL estatica smart publish con one-time token cuando:

- Quieres el camino mas rapido para salir a produccion con reventa.
- Puedes identificar el email del usuario al momento del clic.
- No necesitas estados ni acciones por ticket en tu propia UI de *Mis tickets*.
- Quieres que menta decida automaticamente la mejor experiencia para cada usuario.

### Beneficios

- Una sola llamada API por clic — sin integracion por ticket.
- El usuario llega autenticado (sin friccion de login) gracias al one-time token.
- menta enruta a cada usuario automaticamente al mejor destino.
- Los usuarios se crean automaticamente en menta si todavia no existen.

### Limitaciones

- No hay estado ni acciones por ticket en tu propia UI de *Mis tickets*.
- La URL debe generarse en cada clic desde tu backend (no puede ser un link hardcodeado).
{% /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: una URL fija que siempre apunta a la pagina de entrada a reventa de menta tech.

Hoy esa pagina de entrada es **Smart Publish** — la misma experiencia descripta en la pestana *URL estatica smart publish*: una vez autenticado, menta enruta al usuario al mejor destino segun su inventario de reventa (wizard de publicacion, gestion de publicaciones, hub de tickets o estado vacio).

La diferencia con la variante con one-time token es la autenticacion: con una URL totalmente estatica no hay token embebido, por lo que menta autentica al usuario con tu modelo de autenticacion elegido cuando llega.

**Flujo tipico:**

1. Anades un boton o elemento de menu "Vender tickets" en tu UI.
2. Ese boton apunta a la URL estatica de entrada a reventa proporcionada por menta tech.
3. menta tech autentica al usuario usando tu modelo de autenticacion elegido.
4. menta enruta al usuario al mejor destino segun su inventario de reventa (Smart Publish).

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.

{% callout type="info" title="Prefiere la variante con one-time token" %}
Si tu backend puede identificar el email del usuario al momento del clic, usa la **URL estatica smart publish con one-time token**: el mismo punto de entrada unico, pero el usuario llega ya autenticado. Consulta la <a href='https://connect.mentatech.io/es/api/get-marketplace-smartPublish' target="_blank">API Reference: Get Smart Publish URL</a>.
{% /callout %}

### Cuando tiene sentido este modelo

Utiliza una URL estatica de reventa cuando:

- Quieres la integracion mas pequena posible para empezar a probar reventa.
- No puedes generar la URL por usuario desde tu backend (si puedes, prefiere la variante con one-time token).
- No necesitas acciones de reventa a nivel ticket en tu propia UI de *Mis tickets*.
- Estas ejecutando un piloto mientras planeas una futura migracion a la variante con one-time token o 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 debe autenticarse en menta tech antes de continuar (no hay token embebido).
- 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 %}