{ "openapi": "3.1.0", "info": { "title": "API de Agentclic para profesionales", "version": "1.0.0", "description": "Conecta tu cuenta de Agentclic con otras herramientas. Cada llamada correcta consume créditos (por defecto, 0.02). Límite: 60 llamadas por minuto y token." }, "servers": [ { "url": "https://agentclic.com/api/public/pro/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token personal (ack_live_…) creado en Ajustes › API." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } } } } }, "paths": { "/me": { "get": { "operationId": "token-actual", "summary": "Token actual y saldo", "description": "Comprueba que el token funciona y consulta el saldo de créditos.\n\nDevuelve el nombre del token, sus permisos, el cliente al que está limitado (si lo está) y el saldo de créditos de la cuenta.\n\nSirve para probar la conexión desde n8n, Make o Zapier antes de montar el resto del flujo.", "tags": [ "Token" ], "parameters": [], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "example": { "token": { "name": "n8n leads", "scopes": [ "contacts:write" ], "clientId": null }, "credits": { "balance": 482.5 } } } } }, "401": { "description": "UNAUTHORIZED: Falta el token o no es válido. TOKEN_REVOKED: El token se ha revocado. TOKEN_EXPIRED: El token ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_CREDITS: No quedan créditos en la cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "PLAN_REQUIRED: La cuenta no tiene el plan Agentes ilimitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Más de 60 llamadas por minuto con el mismo token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/clients": { "get": { "operationId": "listar-clientes", "summary": "Listar clientes", "description": "Tus clientes, para saber el id de cada uno.\n\nDevuelve los clientes de tu cuenta, del más reciente al más antiguo. Si el token está limitado a un cliente, solo devuelve ese.\n\nEl id de cada cliente es el que se usa en las rutas de Contactos.", "tags": [ "Clientes" ], "parameters": [], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "example": { "items": [ { "id": "3f1c2a8e-5b7d-4e19-9a62-0c4d8b7e1f20", "name": "Laura Gómez", "company": "Clínica Sol", "sector": "Clínica dental", "createdAt": "2026-10-01T09:00:00.000Z" } ] } } } }, "401": { "description": "UNAUTHORIZED: Falta el token o no es válido. TOKEN_REVOKED: El token se ha revocado. TOKEN_EXPIRED: El token ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_CREDITS: No quedan créditos en la cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "PLAN_REQUIRED: La cuenta no tiene el plan Agentes ilimitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Más de 60 llamadas por minuto con el mismo token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/clients/{clientId}/contacts": { "get": { "operationId": "listar-contactos", "summary": "Listar contactos", "description": "Contactos del CRM de un cliente, con los mismos filtros que el panel.\n\nDevuelve los contactos por páginas: primero los que tienen actividad más reciente y después el resto por fecha de alta, igual que la lista del panel.\n\nPara pedir la página siguiente, envía el valor de nextCursor en cursor. total solo viene en la primera página.", "tags": [ "Contactos" ], "x-required-scope": "contacts:read", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Id del cliente (ver «Listar clientes»).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Contactos por página, de 1 a 100. Por defecto, 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Valor de nextCursor de la página anterior.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Busca en nombre, email y teléfono.", "schema": { "type": "string" } }, { "name": "stages", "in": "query", "required": false, "description": "Ids de etapa separados por comas. «none» = sin etapa.", "schema": { "type": "string" } }, { "name": "channels", "in": "query", "required": false, "description": "Orígenes separados por comas (widget, whatsapp, instagram, telegram, meta_lead, api, manual…).", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Alta desde esta fecha (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Alta hasta esta fecha (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "example": { "items": [ { "id": "8a2e4c61-1d3b-4f7a-b9e0-5c6d7e8f9a01", "name": "Lucía Martín", "email": "lucia@example.com", "phone": "+34600112233", "company": "Clínica Sol", "notes": "Viene del formulario de la web", "source": "api", "channel": "api", "stageId": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601", "tags": [], "conversationId": null, "lastContactAt": null, "createdAt": "2026-11-03T10:15:00.000Z", "updatedAt": "2026-11-03T10:15:00.000Z" } ], "nextCursor": null, "total": 1 } } } }, "401": { "description": "UNAUTHORIZED: Falta el token o no es válido. TOKEN_REVOKED: El token se ha revocado. TOKEN_EXPIRED: El token ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_CREDITS: No quedan créditos en la cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "PLAN_REQUIRED: La cuenta no tiene el plan Agentes ilimitados. FORBIDDEN_SCOPE: El token no tiene el permiso necesario.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: El cliente no existe, no es tuyo o el token está limitado a otro cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Algún parámetro no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Más de 60 llamadas por minuto con el mismo token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "crear-contacto", "summary": "Crear contacto", "description": "Da de alta un contacto en el CRM de un cliente (por ejemplo, un lead que llega a n8n).\n\nCrea el contacto igual que el botón «Nuevo contacto» del panel, con el origen «API» para que puedas filtrarlo en Contactos.\n\nHace falta al menos un nombre, un email o un teléfono. Si el email o el teléfono ya los tiene otro contacto de ese CRM, responde 409 con el id del contacto existente y no se cobra la llamada: puedes usarlo para actualizarlo con PATCH.\n\nLa etapa y los campos personalizados tienen que ser del CRM de ese cliente. Si algo no es válido, no se crea nada.", "tags": [ "Contactos" ], "x-required-scope": "contacts:write", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Id del cliente.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Correcto", "content": { "application/json": { "example": { "contact": { "id": "8a2e4c61-1d3b-4f7a-b9e0-5c6d7e8f9a01", "name": "Lucía Martín", "email": "lucia@example.com", "phone": "+34600112233", "company": "Clínica Sol", "notes": "Viene del formulario de la web", "source": "api", "channel": "api", "stageId": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601", "tags": [], "conversationId": null, "lastContactAt": null, "createdAt": "2026-11-03T10:15:00.000Z", "updatedAt": "2026-11-03T10:15:00.000Z", "customFields": [ { "fieldId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "value": "Implantes" } ], "origins": [] } } } } }, "401": { "description": "UNAUTHORIZED: Falta el token o no es válido. TOKEN_REVOKED: El token se ha revocado. TOKEN_EXPIRED: El token ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_CREDITS: No quedan créditos en la cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "PLAN_REQUIRED: La cuenta no tiene el plan Agentes ilimitados. FORBIDDEN_SCOPE: El token no tiene el permiso necesario.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: El cliente no existe, no es tuyo o el token está limitado a otro cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "CONTACT_EXISTS: Ya hay un contacto con ese email o teléfono (details.contactId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Falta nombre, email o teléfono, o algún dato no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Más de 60 llamadas por minuto con el mismo token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Nombre (hasta 160 caracteres)." }, "email": { "type": "string", "description": "Email. Se guarda en minúsculas." }, "phone": { "type": "string", "description": "Teléfono. Se normaliza igual que en el panel (p. ej. «600 11 22 33» y «600112233» son el mismo)." }, "company": { "type": "string", "description": "Empresa." }, "notes": { "type": "string", "description": "Notas (hasta 2.000 caracteres)." }, "stageId": { "type": "string", "format": "uuid", "nullable": true, "description": "Etapa del CRM del cliente (ver «Opciones del CRM»)." }, "customFields": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "Campos personalizados: { idDelCampo: valor }. Un valor vacío o null borra el dato." } } }, "example": { "name": "Lucía Martín", "email": "lucia@example.com", "phone": "600 11 22 33", "company": "Clínica Sol", "notes": "Viene del formulario de la web", "stageId": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601", "customFields": { "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f": "Implantes" } } } } } } }, "/clients/{clientId}/contacts/{id}": { "get": { "operationId": "ver-contacto", "summary": "Ver contacto", "description": "Ficha completa de un contacto, con campos personalizados y origen de Meta.\n\nDevuelve el contacto con sus campos personalizados y, si llegó por un anuncio de Meta, su campaña, conjunto, anuncio y formulario.", "tags": [ "Contactos" ], "x-required-scope": "contacts:read", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Id del cliente.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Id del contacto.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "example": { "contact": { "id": "8a2e4c61-1d3b-4f7a-b9e0-5c6d7e8f9a01", "name": "Lucía Martín", "email": "lucia@example.com", "phone": "+34600112233", "company": "Clínica Sol", "notes": "Viene del formulario de la web", "source": "api", "channel": "api", "stageId": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601", "tags": [], "conversationId": null, "lastContactAt": null, "createdAt": "2026-11-03T10:15:00.000Z", "updatedAt": "2026-11-03T10:15:00.000Z", "customFields": [ { "fieldId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "value": "Implantes" } ], "origins": [] } } } } }, "401": { "description": "UNAUTHORIZED: Falta el token o no es válido. TOKEN_REVOKED: El token se ha revocado. TOKEN_EXPIRED: El token ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_CREDITS: No quedan créditos en la cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "PLAN_REQUIRED: La cuenta no tiene el plan Agentes ilimitados. FORBIDDEN_SCOPE: El token no tiene el permiso necesario.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: El cliente no existe, no es tuyo o el token está limitado a otro cliente. NOT_FOUND: El contacto no existe en ese CRM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Más de 60 llamadas por minuto con el mismo token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "actualizar-contacto", "summary": "Actualizar contacto", "description": "Cambia los datos, la etapa o los campos personalizados de un contacto.\n\nSolo se cambian los campos que envíes. Un texto vacío o null borra ese dato.\n\nNo puede quedar sin nombre, email y teléfono a la vez. Si el email o el teléfono nuevos los tiene otro contacto, responde 409 y no cambia nada.", "tags": [ "Contactos" ], "x-required-scope": "contacts:write", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Id del cliente.", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Id del contacto.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "example": { "contact": { "id": "8a2e4c61-1d3b-4f7a-b9e0-5c6d7e8f9a01", "name": "Lucía Martín", "email": "lucia@example.com", "phone": "+34600112233", "company": "Clínica Sol", "notes": "Pidió cita para el jueves", "source": "api", "channel": "api", "stageId": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601", "tags": [], "conversationId": null, "lastContactAt": null, "createdAt": "2026-11-03T10:15:00.000Z", "updatedAt": "2026-11-03T10:15:00.000Z", "customFields": [ { "fieldId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "value": "Implantes" } ], "origins": [] } } } } }, "401": { "description": "UNAUTHORIZED: Falta el token o no es válido. TOKEN_REVOKED: El token se ha revocado. TOKEN_EXPIRED: El token ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_CREDITS: No quedan créditos en la cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "PLAN_REQUIRED: La cuenta no tiene el plan Agentes ilimitados. FORBIDDEN_SCOPE: El token no tiene el permiso necesario.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: El cliente no existe, no es tuyo o el token está limitado a otro cliente. NOT_FOUND: El contacto no existe en ese CRM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "CONTACT_EXISTS: El email o el teléfono nuevos ya los tiene otro contacto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Algún dato no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Más de 60 llamadas por minuto con el mismo token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Nombre (hasta 160 caracteres)." }, "email": { "type": "string", "description": "Email. Se guarda en minúsculas." }, "phone": { "type": "string", "description": "Teléfono. Se normaliza igual que en el panel (p. ej. «600 11 22 33» y «600112233» son el mismo)." }, "company": { "type": "string", "description": "Empresa." }, "notes": { "type": "string", "description": "Notas (hasta 2.000 caracteres)." }, "stageId": { "type": "string", "format": "uuid", "nullable": true, "description": "Etapa del CRM del cliente (ver «Opciones del CRM»)." }, "customFields": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "Campos personalizados: { idDelCampo: valor }. Un valor vacío o null borra el dato." } } }, "example": { "stageId": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601", "notes": "Pidió cita para el jueves" } } } } } }, "/clients/{clientId}/contacts/options": { "get": { "operationId": "opciones-crm", "summary": "Opciones del CRM", "description": "Etapas, campos personalizados y orígenes del CRM de un cliente.\n\nDevuelve los ids de las etapas y de los campos personalizados que necesitas para crear o actualizar contactos, y los orígenes que ya hay en el CRM.", "tags": [ "Contactos" ], "x-required-scope": "contacts:read", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "Id del cliente.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "example": { "stages": [ { "id": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601", "name": "Nuevo", "color": "#8B5CF6", "position": 0, "isDefault": true } ], "fieldGroups": [], "fields": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "groupId": null, "name": "Tratamiento", "type": "text", "position": 0 } ], "channels": [ "api", "manual", "whatsapp" ] } } } }, "401": { "description": "UNAUTHORIZED: Falta el token o no es válido. TOKEN_REVOKED: El token se ha revocado. TOKEN_EXPIRED: El token ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "NO_CREDITS: No quedan créditos en la cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "PLAN_REQUIRED: La cuenta no tiene el plan Agentes ilimitados. FORBIDDEN_SCOPE: El token no tiene el permiso necesario.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: El cliente no existe, no es tuyo o el token está limitado a otro cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Más de 60 llamadas por minuto con el mismo token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }