Introducción a la API #

La API REST de Your AI Connector le permite crear su propia integración sobre su cuenta. Puede crear y buscar contactos, gestionar campañas, preguntas frecuentes, tareas y citas, enviar mensajes, registrar webhooks, leer analíticas y conectar canales de mensajería: todo lo que hace el panel de control, impulsado por código.

Esta es la página central de la documentación de la API. Si está conectando Your AI Connector a una herramienta que ya tiene una integración integrada, es posible que no necesite la API en absoluto. La API es para integraciones personalizadas y automatización a gran escala.

URL base #

Cada solicitud se dirige a la misma dirección web base, y todas las rutas en estos documentos son relativas a ella:

https://api.youraiconnector.com/v1

Por lo tanto, el endpoint de campañas es https://api.youraiconnector.com/v1/campaigns, el endpoint de contactos es https://api.youraiconnector.com/v1/contacts, y así sucesivamente.

Todas las solicitudes deben utilizar una conexión segura (HTTPS). Las solicitudes HTTP simples son rechazadas.

Obtención de una clave de API #

El acceso a la API es una función de pago. Si su plan no la incluye, cada solicitud devolverá un 403 con este cuerpo:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Una vez que el acceso a la API esté habilitado en su plan, genere una clave desde el panel de control. El paso a paso completo se encuentra en Acceso a la API; en resumen: vaya a Configuración → Integraciones → Clave de API para generar o regenerar su clave. La Clave de API es su propia sección dentro de Integraciones, separada de los Webhooks, y solo aparece una vez que el acceso a la API está en su plan. Trate la clave como una contraseña: otorga acceso total a su cuenta.

Autenticación #

Puede enviar su clave de API de cuatro maneras. Todas funcionan en cada endpoint que acepte autenticación mediante clave de API.

Para producción, prefiera una de las formas de encabezado para que su clave nunca termine en un registro del servidor o en el historial del navegador. La forma de parámetro de consulta siempre funciona y es la más sencilla para una prueba puntual.

Consulte Autenticación para obtener un desglose completo de cada método, con ejemplos y orientación sobre cuándo usar cada uno.

Su primera solicitud #

Aquí tiene una llamada completa y funcional que enumera las campañas de su cuenta. Utiliza su clave de API y devuelve primero las campañas más recientes.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

Una respuesta exitosa se ve así:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

Respuestas de éxito y error #

Cada respuesta JSON contiene un indicador success para que pueda ramificar según el mismo sin tener que analizar los códigos de estado.

Una respuesta exitosa es success: true más los datos para ese endpoint (el nombre del campo varía: campaigns, contacts, data, etc.):

{
  "success": true,
  "campaigns": []
}

Una respuesta fallida es success: false con un mensaje error legible por humanos y un error_code numérico que coincide con el estado HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Compruebe siempre success (o el estado HTTP) antes de leer los datos. Consulte Errores y paginación para ver la tabla completa de códigos de estado y cómo paginar a través de grandes conjuntos de resultados.

Límites de tasa #

Las solicitudes autenticadas están limitadas a 300 solicitudes por minuto por clave de API. También existe un límite más amplio de 1200 solicitudes por minuto por cuenta, contando cada solicitud autenticada realizada para esa cuenta.

Si supera cualquiera de los límites, recibirá una respuesta 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Espere y vuelva a intentarlo después de una breve pausa. También puede consultar su uso actual en cualquier momento con GET https://api.youraiconnector.com/v1/api-keys/usage, que devuelve cuántas solicitudes ha utilizado en la ventana actual y cuándo se restablece; esto es útil para crear una limitación en el lado del cliente. Consulte Claves de API.

Guías de recursos #

Los grupos de recursos a continuación tienen cada uno su propia guía con las rutas exactas, los campos de solicitud y las formas de respuesta.

Agentes, puntos de entrada y difusiones #

Los Agentes de IA, los Puntos de entrada y las Difusiones se encuentran en la especificación OpenAPI publicada, por lo que puede explorar sus campos exactos y ejecutar solicitudes en vivo contra ellos en el explorador de API. Cada uno tiene su propia guía: Agentes de IA, Puntos de entrada y Difusiones.

Leer esta documentación en Markdown #

Cada página de esta documentación tiene un gemelo en Markdown sin formato: tome la dirección de la página y añada /index.md al final. Por lo tanto, esta página también está disponible en https://docs.youraiconnector.com/api/getting-started/index.md, y se devuelve como texto sin formato en lugar de como una página web; es útil cuando desea pegar una página en un asistente de IA o incluirla en un script.

Para recorrer todo el conjunto, comience desde https://docs.youraiconnector.com/sitemap.xml, que enumera todas las páginas que publicamos. Tenga en cuenta que la documentación se mantiene deliberadamente fuera de los motores de búsqueda, por lo que obtener estas direcciones directamente es la forma de acceder a ella desde el código.

No existe un punto final de documentación protegido por clave ni una descarga masiva todavía; los gemelos en Markdown y el mapa del sitio son toda la interfaz, y ninguno requiere una clave de API.

Próximos pasos #

• Autenticación — elija el método de autenticación adecuado para su integración.
• Errores y paginación — gestione fallos y navegue por los resultados paginados.
• Acceso a la API — genere su clave y vea ejemplos prácticos.