> ## 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 usar la API

> Convenciones compartidas de autenticación, identificadores, paginación, errores y entrega de mensajes.

## URL base y autenticación

Todas las rutas de la referencia son relativas a:

```text theme={null}
https://platform-api.visitoai.com/m2m/v1
```

Envía `Authorization: Bearer <API_KEY>` en cada solicitud. La clave pertenece a un solo negocio y requiere los permisos indicados por cada endpoint. Los permisos de escritura no implican lectura. Consulta [autenticación](https://docs.visitoai.com/es/api-docs/authentication.md) y [permisos](https://docs.visitoai.com/es/api-docs/permissions.md) para crear y limitar el acceso.

## Identificadores y estado actual

Usa los identificadores devueltos por Visito. Por ejemplo, el `id` de un canal es distinto de los identificadores de teléfono, página o WABA del proveedor. No cambies de negocio añadiendo un ID de tenant a la solicitud: la credencial establece ese límite.

Cuando un endpoint requiera una versión o fecha de actualización, obtén el valor con una lectura reciente. Ante un conflicto `409`, vuelve a consultar el recurso y reconcilia los cambios antes de guardar.

## Paginación

Consulta los parámetros y la respuesta de cada endpoint. En las listas con cursor, usa el `nextCursor` devuelto como el siguiente `cursor`, conserva los filtros y continúa mientras `hasMore` sea verdadero. Los límites y campos pueden variar según el recurso.

## Envíos y reintentos

Los endpoints de envío que requieren `Idempotency-Key` deben recibir una clave estable para la misma operación. Al reintentar, conserva exactamente la misma clave y el mismo cuerpo. Usa otra clave si cambia el destinatario o el contenido.

Un `202 Accepted` indica que el trabajo fue aceptado y quedó en cola. Guarda los identificadores devueltos y usa los [endpoints de estado de entrega](https://docs.visitoai.com/es/api-reference/messaging/overview) para consultar el resultado. Consulta los requisitos de cada operación antes de reintentar una escritura: no todas son idempotentes.

## Errores

Las respuestas de error incluyen un código estructurado y un mensaje:

```json theme={null}
{
  "error": {
    "code": "M2M_AUTH_INSUFFICIENT_SCOPE",
    "message": "M2M credential does not have required scope."
  }
}
```

`error.details` es opcional. Puede incluir permisos faltantes o `retryAfterSeconds`.

| Estado | Qué revisar |
| - | - |
| `400` | Parámetros, cuerpo y encabezados requeridos. |
| `401` / `403` | La credencial y los permisos del endpoint. |
| `404` | El ID y el negocio al que pertenece el recurso. |
| `409` | El estado actual, las versiones y el contrato de reintento. |
| `429` | El límite alcanzado; respeta `retryAfterSeconds` si está presente. |
| `5xx` | La falla temporal; reconcilia cualquier escritura aceptada antes de reintentar. |

Para lecturas con fallas temporales, usa espera exponencial y variación aleatoria. Evita reintentar automáticamente errores de validación, permisos o conflictos. Cada página de endpoint documenta sus respuestas específicas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.