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

# Descripción general de la API

> Visión general de la API REST de SalesOS: arquitectura, convenciones, límites de uso y primeros pasos.

# API de SalesOS

La API REST de SalesOS te permite integrar la plataforma con tus sistemas existentes, automatizar procesos y construir aplicaciones personalizadas sobre los datos de ventas.

## URL base

```
https://api.play2sell.com/v1
```

## Características principales

<CardGroup cols={2}>
  <Card title="REST" icon="server">
    API RESTful con endpoints intuitivos que siguen las convenciones estándar HTTP.
  </Card>

  <Card title="JSON" icon="brackets-curly">
    Todas las solicitudes y respuestas usan formato JSON.
  </Card>

  <Card title="OAuth/JWT" icon="key">
    Autenticación segura basada en tokens JWT.
  </Card>

  <Card title="Paginación" icon="arrows-left-right">
    Respuestas paginadas para manejar grandes volúmenes de datos de forma eficiente.
  </Card>
</CardGroup>

## Convenciones

### Métodos HTTP

| Método   | Uso                                         |
| -------- | ------------------------------------------- |
| `GET`    | Consultar recursos                          |
| `POST`   | Crear nuevos recursos                       |
| `PUT`    | Actualizar un recurso completo              |
| `PATCH`  | Actualizar campos específicos de un recurso |
| `DELETE` | Eliminar un recurso                         |

### Códigos de respuesta

| Código | Significado                                  |
| ------ | -------------------------------------------- |
| `200`  | Solicitud exitosa                            |
| `201`  | Recurso creado exitosamente                  |
| `400`  | Solicitud inválida (datos incorrectos)       |
| `401`  | No autenticado (token inválido o expirado)   |
| `403`  | No autorizado (permisos insuficientes)       |
| `404`  | Recurso no encontrado                        |
| `429`  | Límite de solicitudes alcanzado (rate limit) |
| `500`  | Error interno del servidor                   |

### Formato de error

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El campo 'email' es requerido",
    "details": [
      {
        "field": "email",
        "message": "Este campo no puede estar vacío"
      }
    ]
  }
}
```

## Paginación

Las listas usan paginación basada en cursor:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}
```

Parámetros de paginación: `?page=1&per_page=20`

## Límites de uso (Rate Limiting)

| Plan           | Límite                   |
| -------------- | ------------------------ |
| **Starter**    | 100 solicitudes/minuto   |
| **Business**   | 500 solicitudes/minuto   |
| **Enterprise** | 2,000 solicitudes/minuto |

Los headers de respuesta incluyen información sobre tu uso:

```
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1709251200
```

<Warning>
  Si alcanzas el límite de solicitudes, recibirás un error `429`. Espera hasta que el contador se reinicie o considera optimizar tus llamadas.
</Warning>

## Primeros pasos

<Steps>
  <Step title="Obtén tus credenciales">
    Consulta la guía de [autenticación](/es/api/authentication) para obtener tus tokens de acceso.
  </Step>

  <Step title="Haz tu primera llamada">
    Prueba con una solicitud simple como listar tus leads:

    ```bash theme={null}
    curl -H "Authorization: Bearer TU_TOKEN" \
      https://api.play2sell.com/v1/leads
    ```
  </Step>

  <Step title="Explora los endpoints">
    Revisa la documentación de cada endpoint para conocer todos los recursos disponibles.
  </Step>
</Steps>

## Endpoints disponibles

<CardGroup cols={2}>
  <Card title="Leads" icon="user-group" href="/es/api/endpoints/leads">
    CRUD de leads, búsqueda y filtrado.
  </Card>

  <Card title="Ventas" icon="handshake" href="/es/api/endpoints/sales">
    Oportunidades, pipeline y actividades.
  </Card>

  <Card title="Usuarios" icon="users" href="/es/api/endpoints/users">
    Gestión de usuarios y equipos.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/es/api/endpoints/webhooks">
    Recibe notificaciones de eventos en tiempo real.
  </Card>
</CardGroup>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Autenticación" icon="key" href="/es/api/authentication">
    Configura la autenticación para la API.
  </Card>

  <Card title="Integraciones" icon="plug" href="/es/api/integrations/n8n">
    Conecta SalesOS con tus herramientas.
  </Card>
</CardGroup>