AgendaPro/platform/crm/API.md

Referencia de la API de Bucéfalo CRM

Host base: https://services.leadconnectorhq.com · Autenticación: Authorization: Bearer <token privado de subcuenta>.

Este documento es la referencia de endpoints. Los hallazgos empíricos —lo que se ha ejercido contra la subcuenta real y con qué resultado— viven en HALLAZGOS.md, y mandan sobre lo que diga aquí: la documentación oficial de esta API está incompleta o desactualizada en varios puntos concretos, todos marcados abajo.

Cada entrada lleva su origen: [DOC] de la especificación OpenAPI pública del proveedor · [MEDIDO] ejercido contra la subcuenta real de este proyecto · [INFERENCIA] deducción no verificada, que no debe usarse como base para escribir código sin comprobarla antes.

---

La cabecera Version: donde más chocan la documentación y la realidad

Familia	Según la documentación	Lo que funciona [MEDIDO]
/contacts/	2021-07-28	2021-07-28 ✅
/locations/	2021-07-28	2021-07-28 ✅
/conversations/	2021-04-15	2021-07-28 ⚠
/calendars/	2021-04-15	v3 ⚠
/opportunities/	2021-07-28	2021-07-28 ✅

client.ts la elige sola por el prefijo de la ruta. No la cambies «para alinearla con la documentación»: con estos valores se ejercieron los 3 210 contactos, los 3 213 hilos y los 7 calendarios. Equivocarla es un 400.

---

Tres convenciones de paginación distintas en la misma API

Confundirlas devuelve listas incompletas sin ningún error, que es la peor forma de fallar.

Qué se pagina	Cómo	Detalle
Contactos	searchAfter	El cursor sale del último elemento del array, no de la raíz de la respuesta. Con page se topa un techo de profundidad antes de los 3 200
Conversaciones	startAfterDate	El valor de ordenación del último hilo de la página
Mensajes	lastMessageId + nextPage	El id del último mensaje, y un booleano que dice si hay más

---

A · Contactos

GET /contacts/{contactId}

Scope contacts.readonly. Devuelve el contacto envuelto en contact. [MEDIDO] El 404 existe aunque la documentación no lo liste. [MEDIDO] attributionSource trae sessionSource y adId poblados, que el esquema oficial no declara. mapAtribucion() es más fiel que el esquema.

POST /contacts/search

Scope contacts.readonly. El esquema del cuerpo NO está documentado: el $ref del OpenAPI apunta a un objeto vacío. Todo lo que sabemos es medido:

{ "locationId": "…", "pageLimit": 100, "searchAfter": [1724900000000, "seD4Pf…"] }

[MEDIDO] 3 210 contactos en ~22 s, idempotente. [INFERENCIA] 100 es probablemente el máximo de pageLimit; no está escrito en ningún sitio. [MEDIDO] El buscador descarta utmCampaign y conserva campaign. Al dar de alta hay que mandar los dos.

Filtrar por id, teléfono o correo dentro de este buscador no está documentado en ninguna parte. Lo que funciona: por id → GET /contacts/{id}; por teléfono o correo → GET /contacts/?query=.

GET /contacts/

Marcado DEPRECADO por la propia documentación. limit máximo 100, default 20. Útil solo para búsquedas puntuales de 1-5 resultados, que es como lo usa buscarPorIdentificador.

Trampa de forma: aquí la atribución se llama attributions (array); en GET /contacts/{id} se llama attributionSource (objeto). Misma información, dos formas.

POST /contacts/

Scope contacts.write. [MEDIDO] locationId va en el cuerpo del POST y rompe el PUT con 422 property locationId should not exist. [MEDIDO] Un duplicado responde 400 con meta.contactId: es idempotencia regalada por el servidor, y mejor que un upsert, cuya rama de actualización descarta la atribución. [MEDIDO] La atribución solo se escribe en el alta; un PUT posterior devuelve 200 sin guardar nada.

---

B · Conversaciones y mensajes

GET /conversations/search

Scope conversations.readonly. Filtros documentados: locationId (obligatorio), contactId, id, assignedTo, followers, mentions, query, sort, sortBy, status, lastMessageType (43 valores), lastMessageDirection, lastMessageAction, startDate/endDate (epoch ms), startAfterDate, limit.

GET /conversations/{conversationId}

[MEDIDO] Devuelve los campos en la raíz, sin envoltorio. [MEDIDO, hallazgo 38] NO devuelve el nombre del contacto ni un canal reconocible — eso solo viene del buscador. Sincronizar un hilo por su id degradaba el nombre a «Sin nombre»; ver syncConversations.ts, que ya no deja que un dato pobre pise a uno bueno. Trampa de forma: aquí type es un número; en el buscador es la cadena TYPE_PHONE.

GET /conversations/{conversationId}/messages

Scope conversations/message.readonly — distinto de conversations.readonly. Tener uno no da el otro. [MEDIDO] La respuesta viene anidada dos niveles: { messages: { messages: [...], lastMessageId, nextPage } }.

GET /conversations/messages/{id}

[MEDIDO] Funciona y devuelve el mensaje en la raíz. El parámetro de ruta no está declarado en la especificación — es un fallo de la documentación, no de la API.

POST /conversations/messages

Scope conversations/message.write. Tipos: SMS, RCS, Email, WhatsApp, IG, FB, Custom, Live_Chat, TIKTOK. [CONTRADICCIÓN] La documentación marca subType y status como obligatorios. enviarCorreo() no manda ninguno y responde 200. Manda lo medido; no los añadas «por cumplir el esquema» sin un sondeo, porque cualquier clave inesperada es 422. [MEDIDO] La respuesta es Email queued successfully: acuse de encolado, no de entrega. Y al releer el hilo, el status del mensaje propio viene null (hallazgo 23). No se puede afirmar que llegó.

---

C · Calendarios, citas y servicios

GET /calendars/

Scope calendars.readonly, Version: v3. [MEDIDO] 7 calendarios en la subcuenta, uno Servicio Spa (LXZIuRPYa3uCPlUlsqY7).

GET /calendars/events

Scope calendars/events.readonly. [MEDIDO, hallazgo 28] Exige uno de calendarId, userId o groupId; sin ellos es 422 Either of userId, calendarId or groupId is required. No existe «todas las citas de la subcuenta»: hay que iterar los calendarios. Asimetría de formato: la entrada (startTime/endTime del query) va en milisegundos epoch; la salida viene en ISO con desplazamiento (2026-12-28T14:00:00-06:00).

GET /calendars/events/appointments/{eventId}

[MEDIDO, hallazgo 43] Sigue devolviendo la cita después de borrarla — es un borrado lógico. Para comprobar si una cita existe, lista el rango del calendario; por id da un falso positivo.

POST /calendars/events/appointments

Scope calendars/events.write — [MEDIDO, hallazgo 33] el token lo tiene. Obligatorios: calendarId, locationId, contactId, startTime. startTime/endTime en ISO con desplazamiento, no en epoch — al revés que el filtro de arriba. Palancas que este proyecto usa a propósito:

• toNotify: false — la plataforma ya avisó a la clienta; que el CRM no lo haga otra vez.
• ignoreFreeSlotValidation: true — AgendaMax es la fuente de verdad del horario y su base ya impide el solape.

[MEDIDO, hallazgo 42] Verificado de punta a punta: creada, releída con la hora de pared idéntica a la escrita, y borrada.

PUT /calendars/events/appointments/{eventId}

No admite locationId ni contactId. Misma trampa que en contactos: no recicles el cuerpo del alta.

DELETE /calendars/events/{eventId}

[MEDIDO] Existe y el token lo tiene. Borrado lógico (ver hallazgo 43).

Servicios: GET/POST /calendars/services/catalog

Scopes calendars.readonly / calendars.write — [MEDIDO, hallazgo 34] el token lo tiene. Un «servicio» es una prestación vendible con duración, precio, categoría, personal y variaciones: literalmente el modelo de un spa.

[MEDIDO, hallazgos 6 y 32] El catálogo de esta subcuenta está VACÍO. Por eso la duración y el precio viven en la plataforma y «sincronizar servicios» solo puede significar publicar.

Obligatorios: locationId, name, slug, staff[] con al menos un miembro (como [{ id: "…" }], no como ["…"]).

[MEDIDO, hallazgos 44-45] La primera publicación en una subcuenta sin catálogo falla con 400 No default service category found for this location — y ese mismo intento hace que el CRM cree la categoría por defecto. El reintento entra sin cambiar nada. publicarServicio reintenta una vez y solo ante ese mensaje.

GET /calendars/service-categories

[MEDIDO, hallazgo 46] Esta es la ruta correcta. /calendars/services/categories cae en el comodín /{serviceId} y devuelve 404 Please provide a valid service ID, que se lee como «no existe el recurso» cuando en realidad significa «no existe la ruta».

DELETE /calendars/services/catalog/{serviceId}

[MEDIDO] Existe y el token lo tiene.

---

D · Subcuentas

GET /locations/{locationId}

Scope locations.readonly. Un token privado de subcuenta basta; no hace falta token de agencia.

[MEDIDO] settings trae una quinta clave que la documentación no declara:

"contactUniqueIdentifiers": ["email", "phone"]

No es un detalle: es la cadena de identidad que el CRM aplica para deduplicar, y la justificación de que la del proyecto (id → teléfono → correo) coincida con la suya en vez de pelearse con ella.

allowDuplicateOpportunity: false es la causa del 400 OPPORTUNITY_NO_DUPLICATE, y es un interruptor de la interfaz, no un límite duro.

Cómo validar que un token corresponde a una subcuenta

No hay endpoint de introspección de token. El método correcto, y el que usa PUT /api/admin/businesses/:id/crm, es leer GET /locations/{locationId} con ese token y comparar location.id con el esperado — identidad contra identidad, no un 200 genérico.

[MEDIDO] El 401 de esta API es ambiguo: significa a la vez «token caducado», «al token le falta el scope» y (probablemente) «el token es de otra subcuenta». Por eso el mensaje de error de la consola nombra las tres posibilidades en vez de afirmar una.

---

E · Límites de tasa

[MEDIDO, hallazgo 37] Cabeceras reales de la subcuenta:

Cabecera	Valor observado
x-ratelimit-max	100
x-ratelimit-interval-milliseconds	10000
x-ratelimit-limit-daily	200000
x-ratelimit-remaining	va bajando en la ventana
x-ratelimit-daily-remaining	199970

O sea 1 petición cada 100 ms, no cada 650 como asumía el cliente originalmente. client.ts lee esas cabeceras en cada respuesta y ajusta el intervalo con un 50 % de margen; el 650 ms queda solo como respaldo para la primera petición de un token, antes de haber visto ninguna cabecera.

La cuota es por aplicación y por subcuenta: añadir cuentas no reparte el límite, cada una tiene el suyo. Por eso el estrangulador es por token y no global.

---

F · Scopes

contacts.readonly              contacts.write
conversations.readonly         conversations.write
conversations/message.readonly conversations/message.write
calendars.readonly             calendars.write
calendars/events.readonly      calendars/events.write
calendars/groups.readonly      calendars/groups.write
locations.readonly             locations.write
locations/customFields.*       locations/customValues.*       locations/tags.*

Dos parejas que se confunden fácil y dan 401 donde no se espera: conversations.readonly no incluye conversations/message.readonly, y calendars.readonly no incluye calendars/events.readonly.

[MEDIDO] Estado del token de esta subcuenta, al 2026-08-29:

Scope	Estado
contactos, conversaciones, mensajes, subcuenta	✔
calendars/events.write	✔ (hallazgo 33)
calendars.write	✔ (hallazgo 34)
usuarios	✔ hoy — daba 401 cuando se midió por primera vez (hallazgos 14 → 35)
crear pipelines	✖ 401 The token is not authorized for this scope

Un permiso medido una vez no queda medido para siempre. El de usuarios cambió entre dos mediciones porque alguien tocó el token. Conviene comprobar los permisos al vincular una subcuenta y volver a hacerlo cuando algo falle con 401, en vez de fiarse de una tabla escrita en el pasado.

---

Lo que NO está documentado y no debe inventarse

1. El esquema del cuerpo de POST /contacts/search: filtros, operadores y campos filtrables. El OpenAPI lo declara como objeto vacío.
2. El máximo real de pageLimit.
3. El valor del techo de profundidad al paginar por número de página. Que existe está medido; cuánto es, no.
4. El cuerpo de la respuesta 429 y la política de reintento recomendada.
5. Si los tokens privados tienen cuota distinta de las aplicaciones de marketplace.
6. Un endpoint de introspección de token.
7. El código exacto que devuelve un token de otra subcuenta. Se infiere 401; comprobarlo exige un segundo token y este proyecto solo tiene uno.

---

Webhooks

Exigen OAuth. Un token privado de subcuenta no puede suscribirse, así que la entrada de datos es por sondeo: los botones de sincronización y POST /api/crm/sync/:entidad/:id. Si algún día se quiere tiempo real, hay que pasar por OAuth, y eso es un entregable propio.