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

# Introducción a la API

> Todo lo que necesitás saber antes de hacer tu primera request a la API de Waspy.

## Bienvenido a la API de Waspy

La API de Waspy te permite enviar mensajes de WhatsApp, gestionar contactos, consultar conversaciones y operar tu cuenta de forma programática. Está pensada para integradores que necesitan conectar Waspy con su CRM, ERP, ecommerce u otro sistema.

### ¿Qué podés hacer con la API?

* Enviar mensajes de texto, multimedia y templates por WhatsApp
* Crear y actualizar contactos
* Consultar y gestionar conversaciones
* Listar y consultar templates aprobados por Meta
* Obtener información de tu cuenta, canales y uso del plan

### ¿Para quién es esta documentación?

Para desarrolladores o equipos técnicos que necesitan integrar Waspy con otros sistemas. Asumimos familiaridad básica con REST APIs, JSON y autenticación con tokens.

***

## Base URL

Todas las requests van a:

```
https://api.waspytech.com/api/v2
```

La API actual es **v2**. Los endpoints de v1 siguen funcionando pero no reciben nuevas funcionalidades.

***

## Autenticación

Todas las requests requieren un header `Authorization` con un token Bearer. Podés usar una **API key** (recomendado para integraciones) o un **JWT** (para sesiones de usuario).

```bash theme={null}
curl https://api.waspytech.com/api/v2/account \
  -H "Authorization: Bearer wspy_tu_api_key_aqui"
```

Las API keys se crean desde el panel de Waspy en **Configuración → API Keys**. El formato es `wspy_` seguido de un token seguro.

<Info>
  La API key se muestra una sola vez al crearla. Guardala en un lugar seguro.
</Info>

Más detalles en [Autenticación](/authentication).

***

## Formato de respuesta

Todas las respuestas siguen el mismo formato.

### Respuesta exitosa (recurso individual)

```json theme={null}
{
  "data": {
    "id": "uuid",
    "phoneNumber": "+5491126032641",
    "name": "María García"
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### Respuesta exitosa (lista)

```json theme={null}
{
  "data": [
    { "id": "uuid", "name": "María García" },
    { "id": "uuid", "name": "Carlos López" }
  ],
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "page": 1,
    "pageSize": 20,
    "total": 142
  }
}
```

### Respuesta de error

```json theme={null}
{
  "error": {
    "code": "CONTACT_NOT_FOUND",
    "message": "El contacto no existe o fue eliminado.",
    "status": 404
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

Todas las respuestas incluyen un `requestId` en `meta`. Usalo para soporte técnico si necesitás reportar un problema.

***

## Paginación

La API usa dos modelos de paginación según el recurso:

| Modelo           | Recursos                 | Parámetros         |
| ---------------- | ------------------------ | ------------------ |
| **Page-based**   | Contactos, Templates     | `page`, `pageSize` |
| **Cursor-based** | Conversaciones, Mensajes | `cursor`, `limit`  |

Más detalles en [Paginación](/pagination).

***

## Rate limits

La API permite **120 requests por minuto** por cuenta. Cada respuesta incluye headers con el estado del límite:

| Header                  | Descripción                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Máximo de requests por ventana            |
| `X-RateLimit-Remaining` | Requests restantes                        |
| `X-RateLimit-Reset`     | Segundos hasta que se reinicia la ventana |

Si superás el límite, recibís un `429 RATE_LIMITED` con un header `Retry-After`.

Más detalles en [Rate limits](/rate-limits).

***

## Errores

Los errores siempre devuelven un objeto con `code`, `message` y `status`. Los códigos más comunes:

| Código                   | Status | Significado                                |
| ------------------------ | ------ | ------------------------------------------ |
| `VALIDATION_ERROR`       | 400    | Request con datos inválidos                |
| `MISSING_REQUIRED_FIELD` | 400    | Falta un campo obligatorio                 |
| `CONTACT_NOT_FOUND`      | 404    | El contacto no existe                      |
| `SERVICE_WINDOW_EXPIRED` | 403    | La ventana de 24hs expiró, usá un template |
| `RATE_LIMITED`           | 429    | Superaste el límite de requests            |
| `INTERNAL_ERROR`         | 500    | Error interno                              |

Lista completa en [Errores](/errors).

***

## Waspy y Meta (WhatsApp)

Waspy usa la **API oficial de WhatsApp Business (Cloud API)** de Meta. Esto tiene implicaciones importantes:

* **Waspy cobra** por el uso de la plataforma (plan mensual con límites de conversaciones, agentes y plantillas).
* **Meta cobra** por cada conversación de WhatsApp. Este costo va directo de Meta al cliente. Waspy no agrega markups ni costos ocultos sobre los mensajes.
* Los **templates** deben estar aprobados por Meta para poder usarse.
* Los mensajes no-template solo se pueden enviar dentro de la **ventana de servicio de 24 horas** desde el último mensaje del contacto.

Más detalles en [Meta vs Waspy](/concepts/meta-vs-waspy) y [Ventana de servicio](/concepts/service-window).

***

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Enviá tu primer mensaje en 5 minutos.
  </Card>

  <Card title="Autenticación" icon="key" href="/authentication">
    Creá tu API key y configurá permisos.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explorá todos los endpoints disponibles.
  </Card>

  <Card title="Guías" icon="book" href="/guides/send-first-message">
    Casos de uso paso a paso.
  </Card>
</CardGroup>