URL base y autenticación
Todas las rutas de la referencia son relativas 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 y permisos para crear y limitar el acceso.
Identificadores y estado actual
Usa los identificadores devueltos por Visito. Por ejemplo, elid 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 elnextCursor 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 requierenIdempotency-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 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:error.details es opcional. Puede incluir permisos faltantes o retryAfterSeconds.
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.