Deja que tu asistente trabaje dentro de Atlas
Una API con clave para que un bot, un asistente de IA o tu propio sistema lea y escriba en Atlas: leads, cuentas, cartera, conocimiento y la configuración de los agentes. Cada acción queda firmada por quien la hizo.
curl https://atlas.atharix.com/api/integration/v1/leads/?limit=5 \
-H "X-API-Key: atlas_zvHSHQ…"Cómo funciona: una identidad, una clave, unos permisos
Atlas no da claves sueltas. Primero existe un usuario de servicio: un nombre («Beatriz Ventas»), un tipo (agente, integración o sistema) y una persona del equipo que responde por él. De él cuelgan sus claves, cada una con sus ámbitos (permisos). Todo lo que hace la clave queda a nombre del usuario de servicio, en el registro de peticiones y en los propios datos («Creado por Beatriz (agente)»).
Por qué así y no una clave por persona
Porque puedes suspender al agente (sus claves responden 401 hasta que lo reactives), revocarlo para siempre o quitarle un permiso y que todas sus claves lo pierdan al instante. Y porque lo que firmó sigue a su nombre, aunque ya no exista. Un asistente nunca es dueño de nada: el dueño de un lead o una cuenta es siempre una persona del equipo.
Empieza en 5 minutos
Crea el usuario de servicio
En el panel: Agentes externos › Usuarios de servicio › Nuevo. Ponle nombre, tipo «Agente» y una persona responsable. Marca solo los permisos que va a necesitar; la clave nunca podrá tener más que él.
Crea su clave
Desde la ficha del usuario de servicio: Nueva clave. Se ve una sola vez. Guárdala en el gestor de secretos del bot o en la configuración del conector, nunca en un chat. Puedes ponerle caducidad, lista de IPs y un límite de peticiones por minuto. Hay dos claves activas como máximo: la suya y la de rotación.
Pregunta quién eres
Una llamada sin ámbito que no toca nada y te devuelve el usuario de servicio, el negocio y los ámbitos efectivos de la clave (los suyos recortados por los del usuario de servicio). Es lo primero que debe hacer un agente.
curl https://atlas.atharix.com/api/integration/v1/me/ -H "X-API-Key: $ATLAS_KEY" // 200 { "service_user": {"slug": "beatriz", "display_name": "Beatriz Ventas", "kind": "agent", "status": "active", "owner_email": "diego@…"}, "business": {"id": "b867…", "name": "Atharix Global S.L.U", "country": "ES"}, "api_key": {"label": "Beatriz", "key_prefix": "atlas_zvHSHQ", "expires_at": "2026-11-10T00:00:00Z", "expires_in_days": 24, "rate_limit_per_min": 60, "ip_restricted": false}, "scopes": ["leads.read", "leads.create", "leads.update", "activities.create"], "server_time": "2026-10-17T09:30:00Z" }
Ensaya sin guardar nada
Cualquier carga en lote acepta "dry_run": true: se procesa entera, con las mismas comprobaciones, y responde exactamente lo que pasaría. Luego se deshace. No hay cabecera de sandbox ni entorno de pruebas: el modo de prueba es este.
curl -X POST https://atlas.atharix.com/api/integration/v1/leads/bulk/ \ -H "X-API-Key: $ATLAS_KEY" -H "Content-Type: application/json" \ -d '{"dry_run": true, "leads": [{"external_ref": "fila-17", "first_name": "Ana", "phone": "+34600111222", "source_detail": "GADS-brand-es"}]}' // 200: lo que PASARÍA. Nada guardado. { "created": 1, "updated": 0, "unchanged": 0, "rejected": [], "dry_run": true }
Repite sin dry_run
Mismo cuerpo. Si una fila está mal, vuelve en rejected con su índice y el motivo; las demás entran. Ve a Agentes externos › Dashboard y verás la llamada, quién la hizo y qué lead tocó.
Reglas comunes a toda la API
| Regla | Cómo es |
|---|---|
| Lotes | …/bulk/ recibe una lista (accounts, contacts, leads, activities, tasks) y responde por fila: created, updated, unchanged, deleted, rejected: [{index, reason}]. Una fila mala no tumba el lote. Máximo 1.000 cuentas o 500 del resto por llamada. Una fila sola es un lote de una fila. |
| Idempotencia | Por clave natural, no por cabecera: id (el de Atlas) → external_ref (tu id) → tax_id / email / phone. Repetir la misma carga no duplica: devuelve unchanged. |
| Escritura parcial | Solo cambia lo que mandas. Mandar "" vacía el campo. Las claves de fila que Atlas no conoce vuelven en ignored_fields en vez de perderse. |
| Paginación | Por cursor: {"<recurso>": [...], "next_cursor": "…", "has_more": true}. La siguiente página se pide con ?cursor=<next_cursor>. El cursor es opaco: devuélvelo tal cual. limit de 1 a 500. No hay count total. |
| Teléfonos | E.164 (+34600111222). Si mandas country o default_country (ISO-2), Atlas normaliza los nacionales. Sin país y sin prefijo, 400. |
| Esquemas | GET accounts/schema/, contacts/schema/, leads/schema/, invoices/schema/, receivables/schema/ devuelven los campos que acepta cada carga, incluidos los personalizados del negocio. Léelos antes de cargar: son la verdad del día. |
| Límites | Por clave: el rate_limit_per_min que le pusieron (si lo tiene). Además, rutas de captura 30/min, eventos 20/min, conversión 10/min. Al pasarte, 429 con Retry-After. |
| Lo que la API no hace | Crear o borrar bots (bots.create es un ámbito aparte porque gasta los agentes del plan; borrar es solo del panel), conectar un número de WhatsApp, cambiar el dueño de un lead que ya lo tiene, ni nada que una pantalla no enseñe. |
Permisos (ámbitos)
Cada ruta exige un ámbito. Sin él, 403 con el nombre del que falta. Dáselos al usuario de servicio por lo que va a hacer, no «todos por si acaso». Los de lectura y escritura van separados a propósito: un bot que carga leads no tiene por qué poder reescribir sus notas.
Comercial (leads)
leads.readLeer leads y su seguimientoleads.createCrear leads (una fila o lote)leads.updateEtapa, etiquetas, notas, origen, bajaleads.convertConvertir un lead en clienteactivities.createActividades (también LinkedIn) y tareaspipelines.manageEtapas del embudoconversations.readLo que el lead habló por chat o WhatsAppwebhooks.manageAvisar a una URL cuando entra un lead
Cuentas y cartera
accounts.readLeer cuentas y sus personasaccounts.syncCrear y editar cuentas y contactosinvoices.read/invoices.syncFacturasreceivables.readAntigüedad de saldos, deudoresreceivables.syncRegistrar cobroscontacts.create·events.createCaptura desde landings y tiendas
Configurar el agente
bots.readVer agentes, su lienzo y su promptbots.writeConfigurarlos (no crear ni borrar)bots.createCrear agentes: cuentan contra los del planbots.simulateProbar en el simulador sin efectosknowledge.read/knowledge.writeFAQ y documentosqueues.read/queues.writeColas y equipocustom_fields.*·tag_rules.*Campos y reglas de etiquetadoforms.read/forms.writeFormularios web y sus envíoscatalog.*·branches.*·channels.*Catálogo, sedes y números de WhatsAppcases.readCasos que abren los agentes: motivo y resumenprivacy.readRegistro de enmascarado de la IA
Beat Hub (pedidos y reservas)
hub.read/hub.writeCuentas, equipo, embudo, capturaorders.read/orders.writePedidosbookings.read/bookings.writeDisponibilidad y reservasworking_hours.manageHorarios del equipo
Endpoints
Más de 100 rutas bajo /api/integration/v1/. Aquí las que más se usan; el esquema OpenAPI las trae todas con sus campos (referencia completa). Despliega cada una para ver la regla que muerde si no la sabes.
Leads y seguimiento
GETleads/leads.readListar leads
Filtros: q (o search), stage, tag, source_detail (exacto o con *: GADS-*), updated_since, owner_email. Cursor y limit.
GET leads/?source_detail=GADS-*&updated_since=2026-10-01&limit=100
{ "leads": [{"id": "7e3a…", "stage": "Contactado", "owner": {"email": "diego@…"}, …}],
"next_cursor": "MjAyNi0x…", "has_more": true }POSTleads/leads.createCrear un lead
Una fila. Si ya existe por external_ref, correo o teléfono, devuelve el existente sin duplicar. owner_email solo llena un lead sin dueño; sin él, el lead pasa por el reparto del negocio y el dueño recibe aviso.
POSTleads/bulk/leads.create · leads.updateCargar o editar leads
Hasta 500. dry_run, overwrite (pisar lo que ya tiene valor), id para editar uno concreto. Responde por fila.
PATCHleads/{id}/leads.updateActualizar un lead
Etapa (stage), etiquetas, notas, campos personalizados, contacto, empresa, external_ref, opportunity_value (= el deal abierto). DELETE lo da de baja (soft).
POSTleads/{id}/convert/leads.convertConvertir en cliente
Mismo servicio que el botón del panel. Pide tax_id (RUC/CIF/NIF). Sin dry_run. 10/min.
GETleads/{id}/conversations/conversations.readLeer lo que habló
Conversaciones del lead por chat web y WhatsApp, con sus mensajes. Útil para que el bot comercial llegue con contexto.
POSTactivities/bulk/activities.createRegistrar actividades
Tipos: call, email, meeting, note, whatsapp, linkedin_invite, linkedin_message… Se atan por lead_id o lead_external_ref. tasks/bulk/ programa seguimientos con due_in_days.
GETlead-pipeline/leads.readEmbudo y etapas
Un solo embudo a la vista; el estado del lead es su etapa. POST lead-pipeline/stages/ añade etapas (pipelines.manage).
POSTwebhooks/webhooks.manageAvisar cuando entra un lead
Crea una automatización «Lead creado» que llama a tu URL (solo https públicas, sin redirecciones). Filtra por channels = primer tramo del source_detail (WEB, WA, GADS). POST webhooks/{id}/test/ manda uno de prueba.
Cuentas, contactos y cartera
POSTaccounts/bulk/accounts.syncCrear y editar cuentas
No existe POST accounts/ (405): todo va por el lote. Reconoce por id → external_ref → tax_id. País en billing_country; el tipo de identificación se deduce del país. Hasta 1.000.
GETaccounts/accounts.readBuscar cuentas
q, tax_id, tag, country, updated_since. accounts/sync/close/ cierra una sincronización y marca bajas.
POSTcontacts/bulk/accounts.syncPersonas de cada cuenta
Van después de las cuentas: la API no inventa cuentas. default_country normaliza teléfonos. Campos linkedin y notes. El WhatsApp de la persona va aquí (wa_id), no en la cuenta.
POSTinvoices/bulk/invoices.syncFacturas
El documento. Después, receivables/payments/bulk/ registra cobros y receivables/aging/ y by-account/ dan saldos por antigüedad y deudores.
GETcounts/accounts.readConciliación
Cuánto tiene Atlas de cada cosa, para cuadrarlo contra tu origen tras una carga.
Montar y configurar un agente
Es el mismo serializer y el mismo compilador que usa el Diseñador del panel: lo que se configura ahí se configura aquí.
GETbots/ · bots/{id}/ · bots/modes/bots.readAgentes del negocio
Ficha de cada agente: modo (generative o process), idioma, widget, colecciones, has_flow y la config editable. bots/modes/ dice qué modos permite el negocio y su cupo. Nunca sale el widget_token.
POSTbots/bots.createCrear un agente
{name, mode, default_language, slug, template_slug, dry_run}. Cuenta contra los agentes que incluye el plan, como en el panel: sin hueco, 403 plan_limit_bots (el plan lo cambia una persona en el panel; no se compran agentes sueltos). dry_run responde would_create. La respuesta trae next_steps con las rutas siguientes. Borrar sigue siendo del panel.
PATCHbots/{id}/bots.writeNombre, chat web y ajustes técnicos
Acepta name, default_language, widget_enabled, widget_settings, widget_allowed_domains y los ajustes del bot: is_active (pausar: el agente deja de contestar en todos sus canales, lo avisa en warnings), model_name (solo modelos con tabla de precios: sin ella el freno de coste no frena), temperature (0–2), max_tokens (100–16000), max_cost_per_turn (USD por turno), respect_business_hours, business_hours_message, allowed_contract_types y enabled_tools (solo las 6 de infraestructura; las del lienzo dan 409). Cualquier otra clave da 400 con la ruta correcta.
PATCHbots/{id}/config/bots.writeIdentidad, directivas y ajustes avanzados
Básicos: identity (nombre, empresa, tono, trato, alcance, especialidades, saludo al que vuelve, role_label, name_reply, welcome_menu), directives, format_rules, phases, case_queue_key, clarification. Avanzados (hasta ahora solo por consola): lead_capture (campos que pide, cola según el país, evidencia de cliente, derivación automática al completar datos), followups, postsale, fixed_replies, memory, planner, ui.no_tap_options, guards.purchase_grounding, catalog.category_words, reasoning_effort, hide_team_names, case_team_mode, turn_buffer_enabled, muted_ack_enabled.
Cómo se valida lo que entra: cada clave tiene una lista cerrada de subclaves, tipos, rangos y longitudes; toda cola tiene que existir en GET queues/ y todo campo personalizado en GET custom-fields/; las expresiones regulares se compilan antes de guardarse. Lo desconocido da 400 diciendo qué se acepta. Lo que gobierna el lienzo (carriles, derivación, términos, verificación, cierre, captura) da 409 designer_owned: va por flow/. Los bloques se mezclan por subclave y null borra; los escalares se sustituyen. En modo Proceso solo process, case_queue_key y los cuatro que lee el motor de casos.
PUTbots/{id}/flow/bots.writeEl lienzo entero
{version, nodes, edges, canvas_viewport}. Guardar es publicar: compila al instante y reescribe lo que el lienzo gobierna; la caja que no mandes desaparece. version es un candado: si otro guardó antes, 409 version_conflict. Los ids que no sean de este lienzo se tratan como cajas nuevas y vuelven en id_map. Sirve para los dos modos: cajas por audiencia o pasos del guion de Proceso. GET devuelve el grafo, el informe de compilación y el lint.
// Validar sin guardar: lo mismo, dentro de una transacción que se deshace POST bots/{id}/flow/validate/ → compile_report, node_configs, panel_warnings // Sustituir el lienzo por una plantilla (no se deshace) POST bots/{id}/flow/from-template/ {template_slug, version} GET flow-templates/ → plantillas de lienzo y guiones de proceso GET flow-catalog/ → qué cajas existen, sus subtipos, puertos y config
GETbots/{id}/diagnostics/bots.read¿Quedó bien?
Lee lo que decide el runtime de verdad, no la config: herramientas por carril, guion publicado, colecciones fuera de carril, modo selected roto, colas sin miembros, lienzo que al guardarse desharía arreglos a mano. Cada problema trae severity y how_to_fix. No escribe nada. Llámalo siempre después de flow/.
POSTbots/{id}/simulate/bots.simulateProbar sin efectos
Un turno real del agente (mismo motor, mismo prompt, mismas herramientas) sin que quede nada: ni conversación, ni lead, ni caso, ni aviso, ni WhatsApp. Devuelve respuesta, botones, herramientas pedidas, datos capturados, cola y persona a la que habría ido el caso. session encadena turnos (24 h, 40 turnos). Gasta tokens de IA de verdad; 20 turnos/min por clave. Probar como un cliente real exige accounts.read.
GETbots/{id}/preview-prompt/bots.readEl prompt que verá el modelo
?phase=. Devuelve system_prompt compilado y char_count. Míralo antes de dar por buena una configuración.
PUTbots/{id}/knowledge/bots.writeQué conocimiento usa
{"faqs": {"mode": "all"}, "products": {"mode": "selected", "item_ids": [...]}}. Colecciones: faqs, documents, products, contracts, properties, events, resources, service_areas, activities, promotions. Si el lienzo reparte el conocimiento por carril, avisa en warnings: ahí manda el lienzo.
POSTfaqs/bulk/ · documents/knowledge.writeEl contenido del conocimiento
FAQ en lote (hasta 200, dry_run); documentos por JSON o multipart (.pdf, .docx, .txt, .md hasta 20 MB). Se indexan solos para el RAG. Sin external_ref: reintentar un lote sin id duplica.
POSTcatalog/{colección}/bulk/catalog.writeProductos, eventos, promociones…
Lo que el agente consulta y ofrece: productos y categorías, eventos y aperturas, promociones, áreas de servicio, actividades, contratos, inmuebles. catalog/schema/ da los campos de cada colección; clave natural y dry_run como en el resto; Qdrant se actualiza a juego.
PATCHcapabilities/{tipo}/bots.writeCómo funcionan las cajas de «hacer»
Pedidos (por audiencia), Citas, Cursos, Cotización, Distribuidor, Entrega y sus zonas (capabilities/delivery/zones/); Cobros solo lectura. Son del negocio, no del agente: las comparten todos sus bots. El lienzo vincula los bots al publicar, por eso bots es de solo lectura salvo en Catálogo. GET capabilities/?bot= dice si ese bot tiene la caja.
GETbranches/branches.readSedes
De las sedes cuelgan las colas por sede, las aperturas y la caja «¿A qué sede va?». POST/PATCH con branches.write. Crear una sede cuenta contra las que incluye el plan: sin hueco, 403 plan_limit_branches.
GETqueues/ · team/ · sla-policies/queues.readColas, equipo y SLA
Colas con queues.write (nombre, clave, miembros, SLA, bot, sede, principal por sede). Políticas SLA con queues.write: POST sla-policies/ y PATCH sla-policies/{id}/ (plazos de primera respuesta y resolución, por prioridad, dry_run); los casos ya abiertos conservan sus plazos. El equipo es de solo lectura: team/ es la lista de personas válidas como owner_email.
GETcustom-fields/ · tag-rules/ · forms/*.read / *.writeCampos, reglas y formularios
Campos de lead y de cuenta (que el bot puede pedir), reglas de etiquetado automático y formularios web con su casilla de privacidad (forms/{id}/publish/, submissions/, banner/).
PATCHchannels/whatsapp/{id}/channels.writeQué número contesta qué bot
{"bot": " o null. Conectar, registrar o desactivar el número sigue siendo del panel (OAuth de Meta). Nunca sale el token de Meta.
Entrenar al agente: ver qué falla, corregir, probar y medir
Cada escritura acepta dry_run y responde el cambio exacto (changes con antes y después) sin guardar. Lo que la API cambia de un agente o de una FAQ guarda antes una versión que se puede restaurar.
GETcases/ · cases/{id}/cases.readCasos y su motivo
Los casos que abren los agentes y el equipo: motivo de derivación (reason, p. ej. info_not_found), resumen, cola, persona, agente y plazos. Filtros bot, status (open = todos los abiertos), reason, queue, breached, created_since, q, order=recent. El detalle trae historial, comentarios y CSAT. GET cases/reports/{overview|sla|satisfaction|departments}/ da los números de las pantallas Reportes, SLA y encuesta, con los mismos servicios que el panel.
GETconversations/ · conversations/{id}/conversations.readConversaciones de los agentes
De todos los agentes, nunca las del simulador. Filtros bot, channel, since/until, audience, outcome (handed_off, case_opened, lead_created, idle_closed, open, closed), signal (rag_zero_hits…). Cada mensaje trae su id, herramientas y señales.
GETbots/{id}/knowledge-gaps/ · bots/{id}/metrics/conversations.read · bots.readHuecos y métricas
Huecos: preguntas sin respuesta, casos por «información no documentada», respuestas marcadas mal y temas repetidos. Métricas (range=7d…): conversaciones por canal y carril, derivaciones por motivo, casos, CSAT, coste, latencia y señales de confusión. POST conversations/{id}/messages/{mid}/feedback/ (bots.write) marca una respuesta good/bad con su corrección.
PATCHbots/{id}/verification/ · bots/{id}/lanes/bots.writeVerificación y carriles
Verificación por cédula/RUC en Cliente y VIP (misma validación que el panel). lanes/: qué caja ve cada carril (PUT {version, boxes: {node_id: [carriles]}}, mismo candado de version que el lienzo). GET bots/{id}/audience-rules/ explica cómo se decide el carril y qué herramientas tiene cada uno.
POSTbots/{id}/knowledge/search/bots.read · knowledge.readBuscar como el agente
{query, audience}: lo que recuperaría el agente en ese carril, con puntuación. También GET knowledge/index-status/, POST knowledge/reindex/, GET faqs/duplicates/ y documentos desde una URL pública (source_url en documents/).
POSTbots/{id}/test-suite/bots.simulatePruebas en lote
Casos con la respuesta esperada (contains, not_contains, matches, tools_called, case_opened, queue_key…) en el simulador sin efectos. 8 casos y 12 turnos por llamada, 4 por minuto. compare_with_bot_id corre lo mismo en otro agente, p. ej. su copia (POST bots/{id}/clone/, bots.create, cuenta como un agente más del plan).
GETrevisions/ · revisions/{id}/restore/bots.* · knowledge.*Versiones y vuelta atrás
Versiones previas de agentes y FAQ guardadas por la API, con quién y por qué ruta. Restaurar guarda antes la versión actual (undo_revision_id). Lo cambiado en el panel no deja versión aquí.
GETbusiness-hours/bots.read · queues.readHorario del negocio
El horario que usan los SLA, festivos de los próximos 90 días y si ahora está abierto. Si el negocio marca días como «Solo con cita previa» (p. ej. los sábados), añade appointment_only_days y appointment_summary; esos días no son horario y no mueven los plazos. Solo lectura: se cambia en el panel.
Qué se configura dónde
Comparado con lo que edita el panel, para saber por dónde entra cada ajuste.
| Ajuste | Panel | API |
|---|---|---|
| Identidad, tono, directivas, repregunta, cola de casos | Simple › Identidad / Conversación | PATCH config/ |
| Carriles, conocimiento por carril, actividades, derivación, términos, verificación, acceso reservado, cierre, datos que pide, decisiones, pasos de Proceso | Diseñador (lienzo) | PUT flow/ |
| Capacidades (Pedidos, Citas, Cotización, Entrega…), catálogo, sedes | Cajas del lienzo / Conocimiento / Configuración | capabilities/, catalog/, branches/ |
Pausar/activar, modelo, max_tokens, horario, mensaje fuera de horario, discreción (hide_team_names), quién recibe avisos de casos, menú de bienvenida | Simple › Identidad / Reglas / Personas | PATCH bots/{id}/ y config/ |
Enrutado por país del lead, derivación automática al completar datos, evidencia de cliente, campos que el bot rellena, seguimientos, posventa, respuestas fijas, memoria, reasoning_effort, coste máximo por turno | No | PATCH config/ con validación por clave |
Posición y subtítulo del widget, name_reply, notas de directivas, format_rules, y todos los avanzados de arriba | No | Sí (solo API) |
| Conectar un número de WhatsApp, borrar un bot, rotar token del widget, restablecer plantilla, alta de personas, cambiar el horario del negocio (leerlo sí), cuentas de cobro | Sí | No, a propósito |
Errores: qué significa cada uno y qué hacer
| Código | Qué pasó | Qué hacer |
|---|---|---|
| 401 | Invalid API key. / «El usuario de servicio … está suspendido» | Comprueba la cabecera X-API-Key. Si el texto habla del usuario de servicio, pide al owner que lo reactive: la clave está bien. |
| 403 | API key missing required scope: leads.update | Falta ese ámbito. Añádeselo al usuario de servicio (y a la clave) en el panel. No lo rodees probando otra ruta. |
| 403 | «Esta clave no admite peticiones desde la IP 1.2.3.4» | La clave tiene lista de IPs. Añade esa IP o llama desde una de la lista. Para conectores en la nube (Claude, Grok), quita la lista o pon la del proveedor. |
| 400 | {"phone": "…"} / {"detail": "El cursor no es válido…"} | Dice el campo y el motivo. En lotes, el motivo va por fila en rejected. Lee el schema/ del recurso. |
| 404 | Contact not found for this business. | El recurso no es de este negocio o no existe. Crea o sincroniza primero. |
| 405 | Método no permitido | Casi siempre POST accounts/: las cuentas van por accounts/bulk/. |
| 429 | Demasiadas peticiones | Espera lo que diga Retry-After. Agrupa en lotes en vez de llamar fila a fila. |
Conectar un asistente de IA
Hay dos formas de que un asistente use Atlas. Por conector MCP: Atlas publica en https://atlas.atharix.com/mcp un servidor con 67 acciones agrupadas por tarea («buscar leads», «guardar el lienzo», «probar el agente», «ver qué no supo contestar»…); el asistente las llama solo, ejecuta las de lectura sin preguntar y pide confirmación en las que escriben. La persona se conecta iniciando sesión en Atlas (OAuth), elige negocio y paquetes de permisos, y no copia ninguna clave. Por API directa: le das al asistente la clave y el esquema OpenAPI, y construye él las llamadas; vale para cualquier herramienta.
Qué pasa por debajo cuando alguien pulsa «Conectar»
Cada conexión es un usuario de servicio con una clave interna que nadie ve («Claude · Carlos Jordan»). Hereda todo lo de la API con clave: ámbitos, registro de peticiones, firma «Creado por…», límite por minuto y bloqueo si el negocio está suspendido. Solo puede conectar el owner o un admin del negocio. Se desconecta quitando el conector en Claude, revocando la conexión en el panel o suspendiendo su usuario de servicio en Agentes externos.
| Paquete que marca la persona | Qué deja hacer |
|---|---|
| Consultar | Leer leads, conversaciones, casos, cuentas, cartera, agentes y conocimiento. No cambia nada. |
| Trabajar leads y cuentas | Crear y mover leads, actividades y tareas, convertir, cargar cuentas. |
| Configurar agentes | Configuración y conocimiento de los agentes, lienzo, verificación y carriles, catálogo, colas y SLA, asignar un número de WhatsApp ya conectado, simulador y pruebas en lote. |
| Crear agentes nuevos | bots.create. Gasta los agentes del plan; nunca va marcado por defecto. |
Antes de conectar desde la nube con una clave
Claude y Grok llaman a Atlas desde sus servidores, no desde tu ordenador. Si usas una clave (en vez de iniciar sesión) y tiene lista de IPs permitidas, quítala para esa clave. Crea una clave solo para ese asistente, con los ámbitos justos y caducidad. Asignar un número de WhatsApp ya conectado (channels.write) va en «Configurar agentes»; conectar uno nuevo a Meta sigue en el panel.
Claude (web, escritorio y móvil)
- En Claude, abre Ajustes › Conectores › Añadir conector personalizado. URL:
https://atlas.atharix.com/mcp. En Team/Enterprise lo añade el owner de la organización en Organization settings › Connectors y cada miembro pulsa Conectar. - Pulsa Conectar: se abre Atlas, inicias sesión con tu cuenta de siempre, eliges el negocio y marcas los paquetes de permisos. Vuelves a Claude ya conectado. Hace falta ser owner o admin del negocio.
- Claude descubre las acciones y las muestra en el selector de herramientas del chat. Solo ve las que tu conexión puede usar. Prueba: «¿Qué leads entraron esta semana por Google Ads?».
- Si prefieres una clave en vez de iniciar sesión (uso compartido, sin persona detrás), añade
X-API-Keyen Request headers si tu organización tiene esa sección; si no, usa Claude Code.
# Quién soy atlas_whoami # Leads y cuentas atlas_search_leads · atlas_get_lead · atlas_get_pipeline · atlas_list_team · atlas_search_accounts · atlas_get_receivables atlas_create_lead · atlas_log_activity · atlas_schedule_task (añaden, no pisan) ⚠ atlas_update_lead · ⚠ atlas_convert_lead # Cargas (cuentas, contactos, FAQ…): siempre primero la vista previa atlas_get_import_schema · atlas_preview_import (dry_run) · ⚠ atlas_import_records # Agentes atlas_get_agents · atlas_get_agent_setup · atlas_diagnose_agent · atlas_test_agent (simulador, gasta tokens) · atlas_search_faqs ⚠ atlas_update_agent_config # Montar un agente entero atlas_get_flow_catalog · atlas_get_flow_templates · atlas_get_flow · atlas_validate_flow ⚠ atlas_save_flow (sustituye el lienzo; 409 si cambió la versión) · ⚠ atlas_load_flow_template · ⚠ atlas_create_agent (gasta un agente del plan) atlas_save_branch · atlas_save_queue · atlas_preview_catalog · ⚠ atlas_import_catalog · ⚠ atlas_assign_whatsapp_number # Entrenar un agente: ver qué falla atlas_knowledge_gaps · atlas_agent_metrics · atlas_search_cases · atlas_get_case · atlas_case_reports · atlas_list_agent_conversations · atlas_get_conversation atlas_get_audience_rules · atlas_get_agent_lanes · atlas_get_index_status · atlas_test_retrieval · atlas_find_duplicates · atlas_search_documents atlas_search_catalog · atlas_list_queues · atlas_list_whatsapp_numbers · atlas_get_business_hours · atlas_list_versions # Entrenar un agente: corregir (todas con dry_run) ⚠ atlas_update_agent_settings · ⚠ atlas_set_agent_active · ⚠ atlas_set_widget · ⚠ atlas_set_audience_verification · ⚠ atlas_set_agent_tools ⚠ atlas_set_knowledge_access · ⚠ atlas_upsert_document · ⚠ atlas_delete_faq · atlas_reindex_knowledge · atlas_attach_image_url ⚠ atlas_save_sla_policy · atlas_flag_reply · ⚠ atlas_restore_version · ⚠ atlas_clone_agent (gasta un agente del plan) # Entrenar un agente: probar (gastan tokens) atlas_run_test_suite · atlas_compare_versions
Cada acción es una o dos llamadas internas a /api/integration/v1/ con la misma credencial: no puede hacer nada que la API no deje. atlas_get_agent_setup dice de antemano qué pasos NO puede hacer esta conexión y quién sí.
Grok (app) y la API de xAI
- Crea en Atlas el usuario de servicio «Grok» y su clave.
- En grok.com/connectors: New Connector › Custom. URL:
https://atlas.atharix.com/mcp. Los conectores personalizados van con los planes de pago de Grok. - Grok descubre las herramientas y las ofrece en la conversación. El servidor tiene que ser público: Grok no habla con tu máquina ni con servidores locales.
- Si tu bot usa la API de xAI, pásale el servidor en
tools: funciona con el SDK nativo y con la API Responses compatible con OpenAI (transportes Streaming HTTP y SSE).
{
"model": "grok-4",
"tools": [{
"type": "mcp",
"server_label": "atlas",
"server_url": "https://atlas.atharix.com/mcp",
"headers": { "X-API-Key": "atlas_…" }
}],
"input": "Registra una llamada con Pronobis: quieren demo el jueves."
}En la API de xAI no están soportados hoy require_approval ni connector_id: la confirmación de escrituras la pones tú en tu bot, o limitas la clave a ámbitos de lectura.
Claude Code (terminal)
La forma más rápida de probar hoy, porque Claude Code sí admite cabeceras y puede hablar con un servidor en tu propia máquina.
# Con tu cuenta de Atlas (OAuth): añade y luego inicia sesión con /mcp claude mcp add --transport http atlas https://atlas.atharix.com/mcp > /mcp # O con una clave de usuario de servicio claude mcp add --transport http atlas https://atlas.atharix.com/mcp \ --header "X-API-Key: $ATLAS_KEY" # dentro de Claude Code: > usa atlas_whoami y dime qué permisos tengo
Encima del conector, una skill aporta el método: «montar un bot» o «cargar una cartera» como pasos ordenados que Claude sigue con las acciones del conector. Las skills no dan acceso; lo da el conector. Sin él, una skill con la clave dentro es una clave compartida sin control.
ChatGPT, n8n, Make, Zapier y tu propio código
- ChatGPT (GPT personalizado › Acciones): importa el esquema desde
https://atlas.atharix.com/api/integration/v1/schema/, autenticación «API Key», cabecera personalizadaX-API-Key. - n8n / Make / Zapier: nodo HTTP con la cabecera. Usa los lotes (
…/bulk/) conexternal_refpara que re-ejecutar un flujo no duplique. Para recibir leads en tiempo real, crea un webhook conPOST webhooks/. - Tu código: cualquier cliente HTTP. El esquema OpenAPI genera el cliente tipado en el lenguaje que uses.
import os, requests BASE = "https://atlas.atharix.com/api/integration/v1/" H = {"X-API-Key": os.environ["ATLAS_KEY"]} def leads(**params): while True: r = requests.get(BASE + "leads/", headers=H, params=params, timeout=30); r.raise_for_status() body = r.json(); yield from body["leads"] if not body["has_more"]: break params["cursor"] = body["next_cursor"]
Para agentes: cómo leer esta página y actuar
Si eres un agente de IA al que le han dado una clave de Atlas, este es tu procedimiento. Está pensado para que lo sigas sin pedir nada más a la persona.
- Identifícate antes de actuar.
GET me/. Anota tusscopes. No intentes una ruta cuyo ámbito no tienes: un 403 no se rodea, se le pide a la persona. - Lee el esquema del recurso que vas a cargar (
GET leads/schema/…). Los campos personalizados del negocio solo están ahí. No inventes campos: si no están en el esquema, no existen. - Busca antes de crear.
GET leads/?q=,GET accounts/?tax_id=. Atlas ya evita duplicados por clave natural, pero tú debes saber si vas a crear o a editar para explicárselo a la persona. - Toda escritura masiva, primero en
dry_run. Enseña el resultado (cuántos crea, edita, rechaza y por qué) y pide confirmación. Después repite sindry_runcon el mismo cuerpo. - Un lead, una cuenta o una tarea nunca son tuyos.
owner_emailyassignee_emailson personas deGET team/. Si no te dicen quién, no mandes dueño: Atlas lo reparte. - Pagina con el cursor tal cual hasta
has_more: false. No calcules páginas ni totales. - Respeta
Retry-Aftery agrupa en lotes. Fila a fila es la forma más rápida de llegar al 429. - Cuenta lo que hiciste con las palabras de la persona: «He registrado la llamada con Pronobis y he programado el seguimiento para el jueves», no «POST activities/bulk/ 200».
# Atlas API para agentes > API con clave para leer y escribir en Atlas (ARM: clientes, ventas y agentes de WhatsApp y web). Base https://atlas.atharix.com/api/integration/v1/ · cabecera X-API-Key. ## Empieza aquí - [Quién soy](https://atlas.atharix.com/api/integration/v1/me/): ámbitos reales de la clave - [Esquema OpenAPI](https://atlas.atharix.com/api/integration/v1/schema/): todas las rutas y campos - [Servidor MCP](https://atlas.atharix.com/mcp/): acciones para Claude, Grok y clientes MCP ## Reglas - Lotes en …/bulk/ con dry_run:true para ensayar; idempotencia por id → external_ref → tax_id/email/phone - Cursor opaco: ?cursor=next_cursor hasta has_more:false - Dueños siempre personas de GET team/; un agente nunca es dueño - 403 = falta ámbito: pedirlo, no rodearlo
Recetas
Bot comercial que trabaja la cartera de leads
Ámbitos: leads.read, leads.update, activities.create, conversations.read. Cada mañana: GET leads/?stage=Nuevo&updated_since=ayer → por cada uno GET leads/{id}/conversations/ para llegar con contexto → tras el contacto, POST activities/bulk/ con la llamada y tasks/bulk/ con due_in_days: 3, 7, 14 → PATCH leads/{id}/ con la etapa. Nunca owner_email: el reparto ya lo hizo Atlas.
Montar un agente entero desde fuera
Ámbitos: bots.create, bots.read, bots.write, bots.simulate, knowledge.write, queues.write, custom_fields.write. Orden: colas y campos primero (queues/, custom-fields/) → FAQ y documentos (faqs/bulk/) → POST bots/ con plantilla → GET flow-catalog/ para saber qué cajas existen → POST flow/validate/ hasta que el informe salga limpio → PUT flow/ → PATCH config/ con identidad y directivas → GET diagnostics/ y arregla lo que diga how_to_fix → POST simulate/ con 5 o 6 mensajes típicos → PATCH channels/whatsapp/{id}/ para darle el número. Si alguien tiene el Diseñador abierto, el candado version te avisa con 409 en vez de pisarle.
Recibir cada lead nuevo en tu sistema
Ámbito: webhooks.manage. POST webhooks/ {"url": "https://tu-sistema.com/atlas", "channels": ["WEB","WA","GADS"]} → POST webhooks/{id}/test/ para ver el cuerpo → tu endpoint responde 2xx en menos de 10 s y procesa en segundo plano.
Seguridad y datos
| La clave se ve una vez | Guárdala en un gestor de secretos. Si la pierdes, crea otra y revoca la vieja: por eso hay dos activas por usuario de servicio. |
| Rotación | Crea la nueva, cámbiala en el conector, comprueba en el Dashboard que las llamadas llegan con la nueva, revoca la vieja. |
| Mínimo privilegio | Un usuario de servicio por asistente, con los ámbitos de lo que hace. Para un asistente de solo consulta, solo *.read. |
| Caducidad e IPs | Pon caducidad a toda clave que viva fuera de tu infraestructura. La lista de IPs vale para servidores tuyos; no para conectores en la nube. |
| Registro | Cada petición queda en Agentes externos › Dashboard: usuario de servicio, ruta, resultado y qué leads, cuentas o actividades tocó. |
| Datos personales | Lo que un asistente de IA lee de Atlas pasa por su proveedor (Anthropic, xAI, OpenAI…). Antes de conectar datos de clientes, ese proveedor tiene que figurar como encargado en tu documentación de protección de datos. Atlas enmascara los datos que envía a la IA en los negocios que lo activan (privacy.read enseña el registro). |
| Lo que no se puede hacer por API | Borrar bots, conectar números de WhatsApp, cambiar el dueño de un lead con dueño, entrar al panel. Eso queda para personas. |