Especificaciones exactas para que los desarrolladores del cliente expongan sus endpoints de consulta y escritura hacia Atom y Meta de forma segura y eficiente.
🏗️ Panorama de arquitectura
En un Flow conectado, Atom actúa como un proxy. Tú (el cliente) solo publicas endpoints HTTP de negocio; Atom hace el resto.
Meta envía el webhook cifrado a Atom.
Atom descifra, valida la firma, aplica protección SSRF y llama a la API del cliente.
La API del cliente responde en JSON (en menos de 8 segundos).
Atom traduce y entrega la pantalla poblada a Meta.
🛑 Requisitos estrictos de las APIs del cliente
Antes de iniciar la construcción, valida que tus APIs cumplan este checklist:
HTTPS con TLS válido: No se admiten certificados autofirmados.
Respuesta ultra-rápida: Menos de 8 segundos bajo carga real (Meta corta a los 10s, Atom reserva 2s).
URL pública: Nada de localhost o IPs privadas. Atom bloquea peticiones de metadatos de nube por seguridad (SSRF).
JSON Estable: Mismos campos y rutas siempre.
Idempotencia en GET: Atom reintenta peticiones en errores 429/502/503/504.
📦 Contratos de Petición y Respuesta
Lo que Atom envía (Placeholders soportados)
Puedes insertar variables en la URL, headers o body:
Placeholder | Qué trae |
{companyId} / {clientId} | IDs internos de Atom de empresa y cliente. |
{flowId} / {screenId} | Identificadores de Meta del flow y pantalla. |
{predefined_field.X} | Un campo nativo del CRM (ej. correo). |
{data.ruta} | Un dato capturado previamente en el flow. |
(Si un placeholder no se resuelve, la operación falla. Márcalos como opcionales si pueden faltar).
Lo que tu API devuelve
Tu respuesta se mapea a los componentes del flow:
Listas (Dropdown/Opciones): Debes devolver pares { "id": "123", "title": "Nombre" }. El ID se guarda, el Title se muestra.
Un destino o varios (Mode): Puedes llenar un solo campo (Single) o repartir un JSON complejo en varios campos (Outputs).
Datos ocultos (persistData): Conserva datos sin mostrarlos para usarlos en el write-back final.
🛡️ Autenticación y Fallbacks
Autenticación soportada: Bearer (Token estático en header) o SEND (Atom llama primero a tu endpoint de login para obtener token).
Manejo de fallos (Policy): Define operaciones como required: true (falla y detiene todo) o required: false (usa un fallback o valor de respaldo).
⚠️ Atención al Throttling de Meta: Meta monitorea tu API. Si detecta tasa de error >5%, latencia p90 > 1s, o disponibilidad < 90%, bloqueará o restringirá (throttle) tu Flow automáticamente.
¡Construye integraciones a prueba de balas! 🚀
Al respetar los tiempos de respuesta, devolver los formatos JSON esperados y utilizar certificados válidos, garantizas que la capa técnica sea invisible para el usuario y 100% confiable para el negocio. ✅