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

# Cómo autenticar solicitudes a la API M2M de Visito

> Crea credenciales M2M, asigna scopes mínimos y autentica solicitudes de servidor a la API de Visito con bearer tokens e idempotencia.

La API para desarrolladores de Visito usa credenciales machine-to-machine. Cada clave pertenece a un tenant e incluye scopes explícitos que controlan las acciones permitidas.

<Warning>
  Las credenciales M2M son secretos. Guárdalas únicamente en variables de entorno de servidor o en un gestor de secretos. Nunca las incluyas en código frontend, móvil o incrustado.
</Warning>

## Crear una clave de API

1. Abre el dashboard de Visito.
2. Ve a **Build → API Keys**.
3. Selecciona **Create new API Key**.
4. Usa un nombre claro, como `Sincronización PMS` o `Automatización CRM`.
5. Selecciona únicamente los scopes necesarios.
6. Copia la clave de inmediato y guárdala de forma segura.

## Encabezado de autorización

Envía la credencial como bearer token:

```http theme={null}
Authorization: Bearer visito_m2m_...
```

## Scopes disponibles

| Scope                      | Permite                                        |
| -------------------------- | ---------------------------------------------- |
| `channels:read`            | Consultar canales y sus identificadores        |
| `conversations:read`       | Listar conversaciones y consultar su detalle   |
| `conversations:write`      | Enviar respuestas en conversaciones existentes |
| `tools:read`               | Consultar herramientas personalizadas de IA    |
| `tools:write`              | Crear, actualizar y eliminar herramientas      |
| `tools:execute`            | Probar la ejecución de herramientas            |
| `tools:logs:read`          | Consultar registros de ejecución               |
| `whatsapp_templates:read`  | Consultar plantillas de WhatsApp               |
| `whatsapp_templates:write` | Crear plantillas para revisión de Meta         |
| `whatsapp_templates:send`  | Enviar plantillas aprobadas                    |

## Ejemplo

```bash theme={null}
curl https://api.visitoai.com/m2m/v1/channels \
  -H "Authorization: Bearer $VISITO_M2M_API_KEY" \
  -H "Accept: application/json"
```

## Idempotencia

Los endpoints de envío requieren el encabezado `Idempotency-Key`. Usa un valor estable de tu sistema, como un identificador de reserva, pago o ejecución de workflow.

```http theme={null}
Idempotency-Key: confirmacion-reserva-2423265220870
```

Si repites una solicitud con la misma clave y el mismo cuerpo, Visito devuelve la operación original en lugar de crear un envío duplicado.

## Política de reintentos

* Reintenta solicitudes `GET` después de respuestas transitorias `429`, `502` o `503`, con espera exponencial y jitter.
* Reintenta un envío únicamente con el mismo cuerpo y la misma `Idempotency-Key`.
* No reintentes automáticamente respuestas `400`, `401`, `403`, `404` o `409`.
* Si una respuesta `429` incluye `error.details.retryAfterSeconds`, espera al menos ese tiempo.

Usa una nueva clave de idempotencia cuando cambien el destinatario, la plantilla, la conversación o el contenido del mensaje.