Atlas · API de integración v1

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.

Base
https://atlas.atharix.com/api/integration/v1/
Autenticación
X-API-Key: <clave>
Formato
JSON · UTF-8 · barras finales
Esquema OpenAPI
Referencia completa
Primera llamada
curl https://atlas.atharix.com/api/integration/v1/leads/?limit=5 \
  -H "X-API-Key: atlas_zvHSHQ…"
Entender

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.

Empezar

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.

GET me/
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.

POST leads/bulk/ con dry_run
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ó.

Usar

Reglas comunes a toda la API

ReglaCó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.
IdempotenciaPor 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 parcialSolo 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ónPor 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éfonosE.164 (+34600111222). Si mandas country o default_country (ISO-2), Atlas normaliza los nacionales. Sin país y sin prefijo, 400.
EsquemasGET 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ímitesPor 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 haceCrear 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 seguimiento
  • leads.createCrear leads (una fila o lote)
  • leads.updateEtapa, etiquetas, notas, origen, baja
  • leads.convertConvertir un lead en cliente
  • activities.createActividades (también LinkedIn) y tareas
  • pipelines.manageEtapas del embudo
  • conversations.readLo que el lead habló por chat o WhatsApp
  • webhooks.manageAvisar a una URL cuando entra un lead

Cuentas y cartera

  • accounts.readLeer cuentas y sus personas
  • accounts.syncCrear y editar cuentas y contactos
  • invoices.read / invoices.syncFacturas
  • receivables.readAntigüedad de saldos, deudores
  • receivables.syncRegistrar cobros
  • contacts.create · events.createCaptura desde landings y tiendas

Configurar el agente

  • bots.readVer agentes, su lienzo y su prompt
  • bots.writeConfigurarlos (no crear ni borrar)
  • bots.createCrear agentes: cuentan contra los del plan
  • bots.simulateProbar en el simulador sin efectos
  • knowledge.read / knowledge.writeFAQ y documentos
  • queues.read / queues.writeColas y equipo
  • custom_fields.* · tag_rules.*Campos y reglas de etiquetado
  • forms.read / forms.writeFormularios web y sus envíos
  • catalog.* · branches.* · channels.*Catálogo, sedes y números de WhatsApp
  • cases.readCasos que abren los agentes: motivo y resumen
  • privacy.readRegistro de enmascarado de la IA

Beat Hub (pedidos y reservas)

  • hub.read / hub.writeCuentas, equipo, embudo, captura
  • orders.read / orders.writePedidos
  • bookings.read / bookings.writeDisponibilidad y reservas
  • working_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.

AjustePanelAPI
Identidad, tono, directivas, repregunta, cola de casosSimple › Identidad / ConversaciónPATCH config/
Carriles, conocimiento por carril, actividades, derivación, términos, verificación, acceso reservado, cierre, datos que pide, decisiones, pasos de ProcesoDiseñador (lienzo)PUT flow/
Capacidades (Pedidos, Citas, Cotización, Entrega…), catálogo, sedesCajas del lienzo / Conocimiento / Configuracióncapabilities/, 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 bienvenidaSimple › Identidad / Reglas / PersonasPATCH 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 turnoNoPATCH 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 arribaNoSí (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 cobroSíNo, a propósito

Errores: qué significa cada uno y qué hacer

CódigoQué pasóQué hacer
401Invalid 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.
403API key missing required scope: leads.updateFalta 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.
404Contact not found for this business.El recurso no es de este negocio o no existe. Crea o sincroniza primero.
405Método no permitidoCasi siempre POST accounts/: las cuentas van por accounts/bulk/.
429Demasiadas peticionesEspera lo que diga Retry-After. Agrupa en lotes en vez de llamar fila a fila.
Conectar

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 personaQué deja hacer
ConsultarLeer leads, conversaciones, casos, cuentas, cartera, agentes y conocimiento. No cambia nada.
Trabajar leads y cuentasCrear y mover leads, actividades y tareas, convertir, cargar cuentas.
Configurar agentesConfiguració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 nuevosbots.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)

  1. 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.
  2. 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.
  3. 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?».
  4. Si prefieres una clave en vez de iniciar sesión (uso compartido, sin persona detrás), añade X-API-Key en Request headers si tu organización tiene esa sección; si no, usa Claude Code.
Las 67 acciones (⚠ = pide confirmación)
# 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í.

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.

Procedimiento del agente
  1. Identifícate antes de actuar. GET me/. Anota tus scopes. No intentes una ruta cuyo ámbito no tienes: un 403 no se rodea, se le pide a la persona.
  2. 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.
  3. 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.
  4. 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 sin dry_run con el mismo cuerpo.
  5. Un lead, una cuenta o una tarea nunca son tuyos. owner_email y assignee_email son personas de GET team/. Si no te dicen quién, no mandes dueño: Atlas lo reparte.
  6. Pagina con el cursor tal cual hasta has_more: false. No calcules páginas ni totales.
  7. Respeta Retry-After y agrupa en lotes. Fila a fila es la forma más rápida de llegar al 429.
  8. 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».
docs/llms.txt
# 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 vezGuá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ónCrea la nueva, cámbiala en el conector, comprueba en el Dashboard que las llamadas llegan con la nueva, revoca la vieja.
Mínimo privilegioUn usuario de servicio por asistente, con los ámbitos de lo que hace. Para un asistente de solo consulta, solo *.read.
Caducidad e IPsPon caducidad a toda clave que viva fuera de tu infraestructura. La lista de IPs vale para servidores tuyos; no para conectores en la nube.
RegistroCada petición queda en Agentes externos › Dashboard: usuario de servicio, ruta, resultado y qué leads, cuentas o actividades tocó.
Datos personalesLo 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 APIBorrar bots, conectar números de WhatsApp, cambiar el dueño de un lead con dueño, entrar al panel. Eso queda para personas.