Saltar al contenido principal
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.
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.

​
Crear una clave de API

  1. Abre el dashboard de Visito.
  2. Abre Desarrolladores → Claves de API.
  3. Selecciona Create new API Key.
  4. Usa un nombre claro, como Sincronización de pedidos 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:

​
Scopes disponibles

​
Ejemplo

​
Idempotencia

Los endpoints de envío requieren el encabezado Idempotency-Key. Usa un valor estable de tu sistema, como un identificador de pedido, pago o ejecución de workflow.
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.

​
Permisos adicionales

  • conversations:assignment:read
  • conversations:assignment:write
  • conversations:handoffs:write
  • conversations:policy:write
  • crm:sales:read
  • crm:sales:write
  • knowledge:read
  • knowledge:write
  • messages:read
  • properties:read
  • reporting:read
  • webhooks:read
  • webhooks:write
Los permisos de escritura no incluyen lectura. Las suscripciones requieren también el permiso de lectura del recurso. Las claves existentes no cambian. ops:handoffs:create no autoriza la API de Ops independiente.

​
Permisos de gestión de acciones

Estos permisos son independientes. La configuración no concede ejecución ni diagnósticos. Las API keys y autorizaciones existentes no cambian; refrescar un token no agrega permisos. Detalles de migración.

​
Permisos de configuración de IA para clientes

  • ai_settings:read: personalidad/campos de runtime, límite de fotos y política de derivación actuales.
  • ai_settings:write: actualizaciones con versión de esa configuración existente.
Requieren consentimiento explícito; no implican trazas, parámetros/inspección de Actions, control de canales ni mensajes programados. Las conexiones existentes no cambian. Consulta configuración de IA.

​
Permisos separados para conexión y gestión de canales

channels:read lee canales e intentos de conexión. channels:write conserva únicamente la operación existente de respuestas automáticas con versión. El nuevo channels:connect:write crea enlaces temporales que completa una persona; channels:manage:write gestiona activación/configuración, desconexiones solicitadas y mantenimiento compatible. Se verifica al administrador vigente. API keys y autorizaciones OAuth existentes conservan sus permisos exactos. Otorga permisos adicionales explícitamente, sin ampliar credenciales antiguas. Consulta contrato y recuperación.

​
Tickets y escalaciones

tickets:read permite descubrir ambos tipos; tickets:write gestiona tickets generales. conversations:handoffs:create inicia escalaciones; su gestión conserva conversations:handoffs:write y su asignación conversations:assignment:write. Los permisos de contexto y envío siguen separados. Las claves y concesiones OAuth anteriores mantienen sus permisos exactos. Concede el acceso nuevo de forma explícita. Consulta contrato y flujo de agentes.

​
El acceso a comercio es explícito

Las claves API y autorizaciones OAuth conservan sus permisos. Solicita explícitamente los permisos nuevos junto con lectura de ventas. Leer/escribir tickets no autoriza modificar compras. El Agente integrado conserva sus aprobaciones y se audita la identidad de la credencial/autorización. Consulta la matriz completa de Tickets y escalaciones, el flujo MCP y los comandos de Comercio con sourceVersion.