# API

La API te permite trabajar con los bots de Watbot desde tu propio código: buscar y crear contactos, enviarles mensajes, cambiar variables y etiquetas, recargar saldos y gestionar listas. Por ejemplo, el CRM de tu sitio web puede pasar un lead al bot, y un sistema de pagos puede otorgar bonos después de una compra.

La API está disponible para el propietario de la cuenta con el plan Pro. Cada solicitud se ejecuta en nombre del propietario de la clave y con sus permisos.

## Clave de API

La clave se obtiene en tu perfil, en la pestaña «API»: consulta [Clave de API](https://support.watbot.org/es/account/profile#clave-de-api). La clave da acceso completo a la cuenta: guárdala en tu servidor y nunca la pongas en el código de páginas web ni de apps para teléfono.

Pasa la clave en el encabezado `Authorization`:

```
Authorization: Bearer YOUR_API_KEY
```

Si no puedes definir un encabezado, pasa la clave en el parámetro `api_token`, en la URL o en el cuerpo de la solicitud. El encabezado es más seguro: las URL con parámetros quedan en los registros del servidor.

El botón «Regenerar» del perfil reemplaza la clave, y la anterior deja de funcionar de inmediato. La clave también se restablece cuando cambias o restableces la contraseña; después obtén una nueva. Para comprobar una clave, llama a [getMe](https://support.watbot.org/es/api/account#getme): devuelve la cuenta a la que pertenece la clave.

## Solicitudes

Todos los métodos están en:

```
https://watbot.org/es/api/v1/methodName
```

- La mayoría de los métodos aceptan tanto `GET` como `POST`; en cada método se indica cuáles. Llama con `POST` a los métodos que modifican datos.
- Los parámetros de `POST` se envían como JSON (`Content-Type: application/json`) o como campos de formulario; los de `GET`, en la URL.
- Las respuestas son JSON en UTF-8.

> [!IMPORTANT]
> Envía el encabezado `Accept: application/json` en cada solicitud. Sin él, los errores de validación llegan como una redirección en lugar de una respuesta JSON `422`, y tu código no podrá procesarlos.

Ejemplo: los contactos de un bot.

```bash title="Solicitud"
curl -X POST "https://watbot.org/es/api/v1/getContacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345}'
```

El ID del bot (`bot_id`) es el número que aparece en la dirección del bot en el panel: `/bots/12345/…`.

## Límites

- **Frecuencia**: 120 solicitudes por minuto por cuenta, sumando todos los métodos.
- Por encima del límite, la API responde con `429`. El encabezado `Retry-After` indica cuántos segundos esperar; `X-RateLimit-Remaining` muestra cuántas solicitudes quedan en el minuto actual.

## Errores

Una respuesta correcta tiene el código `200` o `201`. Errores:

| Código | Cuándo | Respuesta |
|---|---|---|
| `401` | No hay clave, la clave es incorrecta o se regeneró | `{"error": "unauthorized"}` |
| `402` | El propietario de la clave no tiene el plan Pro | `{"error": "…", "code": "pro_required"}` |
| `403` | Sin acceso al bot o al objeto; la cuenta está bloqueada | `{"error": "…"}` |
| `404` | No se encontró el bot, el contacto o el registro | `{"error": "…"}` o `{"message": "…"}` |
| `410` | El método se desactivó (un método obsoleto después de su fecha de retirada) | `{"error": "…", "code": "method_removed"}` |
| `422` | Los parámetros no pasaron la validación | `{"message": "…", "errors": {"field": ["…"]}}` |
| `429` | Demasiadas solicitudes | `{"message": "Too Many Attempts."}` |

Un error `422` enumera en `errors` cada campo con sus motivos:

```json
{
  "message": "The contact id field is required.",
  "errors": {
    "contact_id": ["The contact id field is required."]
  }
}
```

Los textos de error pueden cambiar: en tu código, guíate por el código de estado y por los campos `code` y `errors`.

Hasta que se desactiva, un método obsoleto funciona como antes, pero cada respuesta lleva el encabezado `Deprecation: true` y un encabezado `Sunset` con la fecha de desactivación. Compruébalos en tu código para pasar a tiempo al método que lo reemplaza.