# Conecta tus sistemas con la API de ioZen

Con la API de ioZen tus sistemas leen tus Intake Bots, envíos, contactos, casos y registros, y le mandan envíos a un bot. Crea una clave, elige sus permisos y haz tu primera llamada.

La API de ioZen sirve para que tus propios sistemas hablen con ioZen. Por ejemplo, una clínica puede leer cada noche los envíos de su Intake Bot de citas, o un taller mecánico puede mandar a su bot las respuestas de un formulario que ya tiene en su sitio.

> **Antes de empezar:** Necesitas el plan Pro y ser propietario o admin del espacio de trabajo.

## 1. Crea una clave

En el menú lateral, ve a «Integraciones» y abre la pestaña «Claves API». Toca **«Crear Clave de API»**.

![La pestaña de claves de API, antes de crear la primera.](https://iozen.ai/docs/shots/es/api-keys-desktop.webp)

En «Nombre», escribe algo que te diga dónde la usas, como "Sistema de citas". En «Permisos», marca solo lo que esa clave necesita. Toca **«Crear Clave de API»**.

## 2. Copia la clave

ioZen te muestra «Tu Clave de API». Empieza con `iozen_live_`. Cópiala ahora y guárdala en un lugar seguro: no podrás verla de nuevo, porque ioZen guarda solo un hash de ella.

Cada clave da acceso a un solo espacio de trabajo: el que la creó.

## 3. Haz tu primera llamada

Manda la clave en el encabezado `Authorization`, después de `Bearer`. Esta llamada lista tus Intake Bots y necesita el permiso «Leer Intake Bots»:

```bash
curl https://app.iozen.ai/api/v1/intake-bots \
  -H "Authorization: Bearer iozen_live_TU_CLAVE"
```

La respuesta llega así:

```json
{
  "success": true,
  "data": {
    "intake_bots": [],
    "pagination": { "has_more": false, "next_cursor": null }
  }
}
```

Si algo falla, llega `"success": false` con un `error` que trae su `code` y su `message`.

## Los permisos

| Permiso | Qué permite |
|---|---|
| «Leer Intake Bots» | Listar tus Intake Bots y ver cada uno. |
| «Escribir Intake Bots» | Crear envíos en un Intake Bot, por ejemplo con las respuestas de tu propio formulario. |
| «Leer Envíos» | Listar los envíos de un Intake Bot y ver cada uno. |
| «Leer Contactos» | Listar tus contactos y ver cada uno. |
| «Leer Casos» | Listar tus Process Boards y sus casos. |
| «Leer Registros» | Listar tus tablas y sus registros. |
| «Gestionar Webhooks» | Crear, editar, eliminar y probar [webhooks](https://iozen.ai/es/docs/webhooks-de-iozen), ver sus entregas y reenviarlas. |
| «Enviar WhatsApp» | Abrir una conversación de WhatsApp con una plantilla aprobada y ver el estado de un mensaje. Necesita el plan Business y un número conectado: [Conecta WhatsApp](https://iozen.ai/es/docs/conecta-whatsapp). |

Si una clave llama a algo sin el permiso, la API responde 403.

## Límites de uso

Cada clave tiene un límite de llamadas por minuto que depende de tu plan. Cada respuesta trae `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset` para que sepas cuánto te queda. Si pasas el límite, la API responde 429 con `Retry-After`: los segundos que debes esperar.

## Reintenta sin duplicar con Idempotency-Key

Si tu sistema reintenta un `POST`, un `PATCH` o un `PUT`, manda el encabezado `Idempotency-Key` con un valor único, como un UUID. Si repites la llamada con la misma clave y el mismo cuerpo dentro de 24 horas, ioZen te devuelve la respuesta guardada sin hacer el cambio dos veces, y la marca con `X-Idempotent-Replayed: true`. Con la misma clave y otro cuerpo, la API responde 409.

Para abrir una conversación de WhatsApp, `Idempotency-Key` es obligatorio.

## Revoca una clave

Si una clave se filtró o ya no la usas, abre su menú y toca «Revocar». En el teléfono, el botón está en la tarjeta de la clave. Confirma con **«Revocar Clave»**. Las aplicaciones que la usan pierden el acceso al instante.

## La referencia completa

Todas las llamadas, con sus parámetros y ejemplos, están en la referencia de [app.iozen.ai/docs/api-reference](https://app.iozen.ai/docs/api-reference). Está solo en inglés. El enlace «Ver documentación de API», en la pestaña «Claves API», abre la misma documentación.

## Preguntas frecuentes

### ¿Qué plan necesito para usar la API?

Pro o superior. Cuántas claves puedes tener depende de tu plan; lo ves en Precios.

### ¿Puedo volver a ver una clave?

No. ioZen la muestra una sola vez y guarda solo un hash. Si la pierdes, revócala y crea otra.

### ¿Cuántas llamadas puedo hacer?

Cada clave tiene un límite por minuto que depende de tu plan. Si lo pasas, la API responde 429 y te dice en el encabezado Retry-After cuántos segundos esperar.

### ¿La referencia de la API está en español?

No. La referencia está solo en inglés, en app.iozen.ai/docs.