> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onflay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listings (Listados)

> Los listings son la abstracción central de Onflay para cualquier cosa que quieras vender: productos digitales, servicios o suscripciones.

## ¿Qué es un listing?

Un **listing** representa cualquier producto o servicio que un creador quiere monetizar. Onflay usa una abstracción genérica de listing que soporta múltiples tipos de comercio desde un mismo modelo de datos.

Piensa en un listing como la "ficha de producto" de tu tienda. Puede ser:

* Un e-book descargable
* Una sesión de consultoría
* Una membresía mensual
* Un curso online
* Acceso a una comunidad

## Tipos de listing

<CardGroup cols={1}>
  <Card title="DIGITAL" icon="download" color="#6366f1">
    **Producto digital de una sola compra.** El comprador recibe acceso o descarga inmediata después del pago. Ejemplos: ebooks, plantillas, fotos, música.
  </Card>

  <Card title="SERVICE" icon="handshake" color="#8b5cf6">
    **Servicio de una sola compra.** El creador provee el servicio manualmente después del pago. Ejemplos: consultoría, diseño, auditoría.
  </Card>

  <Card title="SUBSCRIPTION" icon="arrows-rotate" color="#a78bfa">
    **Suscripción recurrente.** El comprador paga periódicamente para mantener el acceso. Ejemplos: membresías, acceso a contenido premium.
  </Card>
</CardGroup>

## Ciclo de vida de un listing

Cada listing pasa por tres estados:

```
DRAFT → ACTIVE → ARCHIVED
```

| Estado     | Descripción                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `DRAFT`    | En preparación. No visible públicamente ni disponible para compra.                 |
| `ACTIVE`   | Publicado y disponible para compra. Aparece en búsquedas públicas.                 |
| `ARCHIVED` | Desactivado. No se puede comprar pero los compradores anteriores mantienen acceso. |

<Warning>
  Solo los listings en estado `ACTIVE` aparecen en el endpoint público `GET /v1/listings`. Los listings en `DRAFT` solo son visibles para el creador propietario.
</Warning>

## Estructura de un listing

```json theme={"dark"}
{
  "id": "lst_01HXYZ...",
  "creatorId": "crt_01HABC...",
  "type": "DIGITAL",
  "title": "Mi E-Book de Marketing",
  "description": "Guía completa para crecer en redes sociales",
  "slug": "ebook-marketing-2025",
  "priceInCents": 2900,
  "currency": "usd",
  "status": "ACTIVE",
  "metadata": {
    "downloadUrl": "https://...",
    "fileFormat": "PDF",
    "pageCount": 120
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-20T08:15:00Z"
}
```

### Campos principales

<ParamField path="id" type="string">
  Identificador único del listing. Prefijo `lst_`.
</ParamField>

<ParamField path="type" type="enum" required>
  Tipo de listing. Valores: `DIGITAL`, `SERVICE`, `SUBSCRIPTION`.
</ParamField>

<ParamField path="slug" type="string" required>
  URL amigable y única para el listing. Solo letras minúsculas, números y guiones.
</ParamField>

<ParamField path="priceInCents" type="integer" required>
  Precio en centavos de la moneda indicada. Por ejemplo, `2900` = \$29.00 USD.
</ParamField>

<ParamField path="currency" type="string" required>
  Código ISO 4217 de la moneda. Por ejemplo: `usd`, `eur`, `mxn`.
</ParamField>

<ParamField path="metadata" type="object">
  Datos adicionales específicos del tipo de listing. El esquema varía según el tipo.
</ParamField>

## El campo `metadata` por tipo

### DIGITAL

```json theme={"dark"}
{
  "metadata": {
    "downloadUrl": "https://cdn.onflay.com/files/...",
    "fileFormat": "PDF",
    "fileSize": 2048576,
    "previewUrl": "https://..."
  }
}
```

### SERVICE

```json theme={"dark"}
{
  "metadata": {
    "durationMinutes": 60,
    "deliveryDays": 3,
    "revisions": 2,
    "calendarUrl": "https://calendly.com/..."
  }
}
```

### SUBSCRIPTION

```json theme={"dark"}
{
  "metadata": {
    "interval": "month",
    "intervalCount": 1,
    "trialDays": 7,
    "features": ["Acceso completo", "Soporte prioritario"]
  }
}
```

## Operaciones disponibles

| Operación          | Endpoint                    | Autenticación     |
| ------------------ | --------------------------- | ----------------- |
| Crear listing      | `POST /v1/listings`         | JWT (Creador)     |
| Mis listings       | `GET /v1/listings/mine`     | JWT (Creador)     |
| Ver listing propio | `GET /v1/listings/mine/:id` | JWT (Creador)     |
| Listar públicos    | `GET /v1/listings`          | Público           |
| Ver por slug       | `GET /v1/listings/:slug`    | Público           |
| Actualizar         | `PATCH /v1/listings/:id`    | JWT (Propietario) |
| Archivar           | `DELETE /v1/listings/:id`   | JWT (Propietario) |

<Tip>
  El endpoint `GET /v1/listings/:slug` es el que deberías usar para mostrar la página pública de un producto en tu sitio web. Solo devuelve listings `ACTIVE`.
</Tip>

## Slugs únicos

El `slug` es el identificador público de tu listing en la URL. Debe ser:

* Único en toda la plataforma
* Solo letras minúsculas, números y guiones (`-`)
* Entre 3 y 100 caracteres

Ejemplos válidos: `ebook-marketing-2025`, `consultoria-seo`, `membresia-premium-v2`

<Info>
  Si intentas crear un listing con un slug ya existente, recibirás un error `409 Conflict`.
</Info>