La API REST

La API REST es la superficie programática de casi todo lo que guarda una cuenta de AppBO: los contactos y sus campos personalizados, las conversaciones y los mensajes, las oportunidades y los pipelines, los calendarios y las citas, los formularios y sus envíos, los flujos de trabajo y la estructura de subcuentas que usa una agencia para mantener separados a sus clientes. De un lado de la conexión está tu propio código. Un servicio de backend, un proceso nocturno, una app móvil, una herramienta interna de administración o un pipeline de datos. Del otro lado está una sola cuenta, o un conjunto de cuentas autorizadas juntas bajo una misma instalación de app a nivel de agencia.

Recurres a la API cuando el comportamiento que necesitas no se puede expresar como un paso de un flujo de trabajo ni con un conector nativo. Casos típicos: tu sistema de registro principal es un sistema externo y AppBO tiene que reflejarlo; necesitas cargar miles de registros históricos; quieres el historial de conversaciones dentro de tu propia consola de soporte; necesitas calcular algo (una puntuación, una verificación de elegibilidad, un nivel de precio) en tu propio código y escribir el resultado de vuelta en el contacto para que las automatizaciones de BO puedan ramificarse con base en él.

La API también es la base de todas las demás integraciones de esta biblioteca. Las plataformas de automatización, los webhooks salientes y el código personalizado insertado terminan llamando a los mismos endpoints con los mismos tokens y los mismos límites, así que los hábitos de autenticación y manejo de errores que formes aquí se trasladan directamente. Trata la referencia publicada de la API como la fuente de verdad para las rutas exactas, los nombres de campos y los identificadores de alcance, y trata esta guía como la forma del trabajo, no como un sustituto de esa referencia.

1. Decide primero el alcance del impacto. Una integración con una sola subcuenta se autoriza contra esa cuenta; una integración a nivel de agencia se autoriza una vez y después actúa en todas las cuentas a las que se le dio acceso. Producen tokens distintos y requisitos de alcance distintos, y convertir una en la otra después es doloroso.
2. Registra una aplicación en el área para desarrolladores de la plataforma. Ponle un nombre que tu equipo reconozca en una auditoría y anota el identificador de cliente y el secreto de cliente que emite.
3. Elige el modelo de autenticación. Prefiere el flujo de app con OAuth, que entrega un token de acceso renovable vinculado a una cuenta con nombre. Usa una clave de larga duración a nivel de cuenta solo donde la plataforma la ofrezca y tu caso de uso de verdad no pueda completar un intercambio en el navegador.
4. Selecciona los alcances. Pide el conjunto más reducido que cubra tus llamadas: alcances de solo lectura donde solo lees. Copia los identificadores exactos de los alcances de la referencia de la API en lugar de adivinarlos; un alcance mal escrito falla en el momento de la autorización, y uno demasiado amplio es un riesgo permanente.
5. Guarda el secreto de cliente en un gestor de secretos o en una variable de entorno del servidor. Nunca lo incluyas en JavaScript del navegador, en el binario de una app móvil ni en un repositorio.
6. Completa el intercambio de autorización: envía al usuario a la URL de autorización de la plataforma con tu id de cliente, los alcances que pides y la URI de redirección; recibe el código de corta duración en tu endpoint de redirección; cámbialo del lado del servidor por un token de acceso y un token de renovación.
7. Registra lo que llegó junto con los tokens. El identificador de la cuenta o de la ubicación, los alcances otorgados y el vencimiento. Tu código siempre debe saber en nombre de qué cuenta habla un token.
8. Configura los encabezados que necesita cada solicitud: el encabezado Authorization de tipo bearer, un encabezado Accept de JSON y el encabezado de versión de la API que indica la referencia. Omitir el encabezado de versión es una causa común de respuestas que se ven sutilmente mal.
9. Haz una llamada de lectura de bajo riesgo para comprobar que la credencial funciona: trae un solo contacto o lista los calendarios de la cuenta. Un 401 aquí significa que el token o el encabezado están mal; un 403 significa que el token es válido pero falta el alcance.
10. Confirma que el identificador de cuenta de la respuesta coincida con la cuenta que querías tocar. En configuraciones con varias cuentas, esta revisión atrapa el peor tipo de error antes de que escriba algo.
11. Implementa la renovación antes del vencimiento, no después de una falla. Renueva con un temporizador y un margen, y usa un bloqueo para que los procesos que corren en paralelo no compitan entre sí ni invaliden el token de renovación de los demás.
12. Agrega reintentos con espera exponencial y variación aleatoria para las respuestas 429 y 5xx, y registra el identificador de solicitud que devuelve la plataforma para que las conversaciones con soporte tengan algo concreto de donde partir.
13. Reemplaza el sondeo periódico por webhooks salientes siempre que exista un evento para lo que estás vigilando. Consultar listas de contactos cada poco tiempo es la forma más rápida de agotar tu presupuesto de uso.
14. Verifica de principio a fin: crea un contacto desechable por la API, confirma que aparezca en la interfaz de AppBO con los campos que definiste, confirma que se disparó cualquier flujo de trabajo que esperabas y después bórralo.
15. Pasa la credencial a producción con monitoreo. Configura alertas para 401 sostenidos (token roto), 429 sostenidos (estás por encima del presupuesto) y para las fallas de renovación: esas pasan en silencio hasta que algo visible para el usuario se rompe.

De tu sistema a la plataforma

• Contactos: nombre, email, teléfono, dirección, etiquetas, responsable asignado y valores de los campos personalizados definidos en la cuenta.
• Oportunidades: pipeline, etapa, valor monetario, estado y contacto asociado.
• Contenido de conversaciones: mensajes salientes en los canales que cubren tus alcances, además de notas y tareas asociadas a un contacto.
• Citas: calendario, usuario asignado, inicio y fin, y contacto asistente.
• Entrada a flujos de trabajo: agregar un contacto a un flujo de trabajo o activar un disparador entrante que un flujo está escuchando.

De la plataforma a tu sistema

• Los registros de contactos y los valores de sus campos personalizados, que se pueden obtener uno por uno o en páginas filtradas.
• Los hilos de conversación y el cuerpo de los mensajes, con marcas de tiempo y dirección.
• El estado de las oportunidades y los pipelines, para reportes fuera de la plataforma.
• Los envíos de formularios y encuestas, incluidos los datos (payload) de los campos tal como se enviaron.
• Las definiciones de calendarios, la disponibilidad y las citas reservadas.
• Los usuarios y los metadatos de la cuenta, para relacionar responsables entre sistemas.

Lo que no se mueve

• Los elementos creados en los editores. El diseño de las páginas de funnels y sitios, el diseño de las plantillas de email y el estilo de los formularios se crean en la plataforma y no se pueden editar de forma útil como datos de la API.
• El plan, la suscripción y el estado de facturación de la propia cuenta.
• Los datos de cualquier cuenta a la que no se le dio acceso a tu token. No hay lectura implícita entre cuentas.
• Las analíticas agregadas y los resúmenes de los paneles: puedes leer los registros de base y calcular los tuyos, pero los reportes ya armados no son un recurso de la API.
• Los archivos binarios como JSON en línea. Los archivos en general se mueven por sus propios endpoints de carga o de medios; revisa en la referencia el mecanismo vigente antes de suponer que un campo acepta base64.

Escenario: una app externa de onboarding es dueña del registro del cliente, y AppBO tiene que reflejar a cada cliente nuevo para que pueda correr la automatización de seguimiento.

1. Un cliente completa el onboarding en tu propia app. Tu backend escribe el registro en tu base de datos y pone en cola un trabajo de sincronización.
2. El proceso toma el trabajo y le pide a tu almacén de tokens un token de acceso vigente para la cuenta de destino. Al token guardado le quedan once minutos, dentro del margen de renovación, así que el proceso primero lo renueva y guarda el nuevo par.
3. El proceso busca en la plataforma un contacto existente por email, para que un onboarding repetido no cree un segundo registro.
4. No hay coincidencias, así que el proceso hace una llamada para crear el contacto con nombre, email, teléfono, el origen del onboarding y dos campos personalizados: el identificador interno de la cuenta y el nombre del nivel del plan.
5. La plataforma responde 201 con el identificador del contacto nuevo. El proceso escribe ese identificador de vuelta en su propia fila del cliente, y se convierte en la clave de unión para cada actualización posterior.
6. El proceso hace una segunda llamada para agregar el contacto al flujo de trabajo de onboarding.
7. Dentro de la plataforma se dispara el flujo de trabajo: envía el email de bienvenida, espera y después manda un SMS si el email no se abrió.
8. Tres días después, el cliente sube de plan. Tu app pone en cola un trabajo de actualización que esta vez ya tiene el identificador del contacto y hace una actualización directa en lugar de una búsqueda: cambia el campo personalizado del nivel del plan al valor nuevo.
9. Un flujo de trabajo en la plataforma está escuchando cambios en ese campo personalizado y mueve la oportunidad del contacto a la etapa Plan mejorado.
10. Un webhook saliente en el cambio de etapa envía un aviso de vuelta a tu app, que registra que el reflejo está consistente. El ciclo se cierra sin que ninguno de los dos lados haga sondeos.

Límites de uso

La API aplica tanto un límite de ráfaga como una cuota de ventana más larga, y superar cualquiera de los dos devuelve 429. Revisa las cifras vigentes publicadas en la referencia de la API en lugar de fijar en el código un número sacado de un blog, y lee los encabezados de límite de uso en las respuestas reales. Son la vista confiable de tu presupuesto restante. Diseña pensando en el presupuesto: agrupa en lotes donde el endpoint lo permita, guarda en caché los metadatos de la cuenta que casi no cambian y prefiere los webhooks al sondeo.

Reintentos e idempotencia

Supón que no hay eliminación automática de solicitudes duplicadas, a menos que la referencia documente un mecanismo de idempotencia para el endpoint que estás llamando. Una llamada de creación que vence por tiempo bien pudo haber funcionado, así que un reintento a ciegas es como terminas con contactos duplicados. El patrón seguro es buscar y luego crear, o guardar tu propio identificador externo en un campo personalizado y buscarlo antes de escribir. Reintenta solo con 429 y 5xx; un 4xx distinto de 429 va a fallar igual para siempre.

Trampas en el mapeo de campos

Los campos personalizados se referencian por identificador, no por la etiqueta que ves en la interfaz, y cambiarle el nombre a un campo en la interfaz no cambia su identificador. Trae las definiciones de campos de la cuenta al iniciar y asigna por identificador. Cuidado con la conversión de tipos: un campo desplegable rechaza un valor que no esté entre sus opciones, las fechas piden el formato que indica la referencia y los teléfonos conviene enviarlos en E.164 para que tanto la eliminación de duplicados como la mensajería funcionen bien.

Duplicados

Las cuentas difieren en qué tan agresivamente fusionan por email o teléfono. No dependas de que la plataforma elimine duplicados por ti. Elige una sola clave, hazla cumplir de tu lado y guarda el identificador de contacto de la plataforma en el momento en que lo recibes.

Pruebas frente a producción

Haz las pruebas contra una subcuenta de prueba dedicada y no contra una de producción, y mantén credenciales separadas por entorno. El riesgo es que una cuenta de prueba con flujos de trabajo activos y un número de teléfono conectado va a enviar mensajes reales a cualquier número que hayas escrito en tus datos de prueba.

Vencimiento de la autenticación

Los tokens de acceso duran poco, y los tokens de renovación se pueden revocar cuando un usuario desconecta la app, cambia su contraseña o se elimina la instalación. Trata una falla de renovación como un evento de reautorización que necesita a una persona, no como un error pasajero para reintentar para siempre, y configura una alerta, porque si no la integración simplemente se queda callada.

Lo que suele fallar

• Un encabezado de versión de la API faltante o desactualizado que cambia la forma de la respuesta después de una actualización de la plataforma.
• Un alcance que nunca se pidió y que aparece como 403 solo en el único endpoint que llamas pocas veces.
• Procesos en paralelo que compiten por renovar un token e invalidan el par.
• Una paginación que se supone estable mientras se escriben registros debajo del cursor.
• Código escrito para una subcuenta que supone, sin decirlo, que todas las cuentas tienen los mismos campos personalizados.