Especificações exatas para que os desenvolvedores do cliente exponham seus endpoints de consulta e escrita para Atom e Meta de forma segura e eficiente.
🏗️ Panorama de arquitetura
Em um Flow conectado, Atom atua como um proxy. Você (o cliente) apenas publica endpoints HTTP de negócio; Atom faz o resto.
Meta envia o webhook criptografado a Atom.
Atom descriptografa, valida a assinatura, aplica proteção SSRF e chama a API do cliente.
A API do cliente responde em JSON (em menos de 8 segundos).
Atom traduz e entrega a tela preenchida a Meta.
🛑 Requisitos rigorosos das APIs do cliente
Antes de iniciar a construção, valide que suas APIs cumpram este checklist:
HTTPS com TLS válido: Certificados autoassinados não são permitidos.
Resposta ultra-rápida: Menos de 8 segundos sob carga real (Meta corta aos 10s, Atom reserva 2s).
URL pública: Nada de localhost ou IPs privados. Atom bloqueia requisições de metadados de nuvem por segurança (SSRF).
JSON Estável: Mesmos campos e rotas sempre.
Idempotência em GET: Atom tenta novamente requisições em erros 429/502/503/504.
📦 Contratos de Requisição e Resposta
O que Atom envia (Placeholders suportados)
Você pode inserir variáveis na URL, headers ou body:
Placeholder | O que traz |
{companyId} / {clientId} | IDs internos de Atom de empresa e cliente. |
{flowId} / {screenId} | Identificadores de Meta do flow e tela. |
{predefined_field.X} | Um campo nativo do CRM (ex. email). |
{data.rota} | Um dado capturado previamente no flow. |
(Se um placeholder não se resolver, a operação fala. Marque-os como opcionais se puderem faltar).
O que sua API retorna
Sua resposta é mapeada para os componentes do flow:
Listas (Dropdown/Opções): Você deve retornar pares { "id": "123", "title": "Nome" }. O ID é salvo, o Title é exibido.
Um destino ou vários (Mode): Você pode preencher um único campo (Single) ou distribuir um JSON complexo em vários campos (Outputs).
Dados ocultos (persistData): Conserva dados sem exibi-los para usá-los no write-back final.
🛡️ Autenticação e Fallbacks
Autenticação suportada: Bearer (Token estático no header) ou SEND (Atom chama primeiro seu endpoint de login para obter token).
Tratamento de falhas (Policy): Defina operações como required: true (falha e detém tudo) ou required: false (usa um fallback ou valor de reserva).
⚠️ Atenção ao Throttling de Meta: Meta monitora sua API. Se detectar taxa de erro >5%, latência p90 > 1s, ou disponibilidade < 90%, bloqueará ou restringirá (throttle) seu Flow automaticamente.
Construa integrações à prova de balas! 🚀
Ao respeitar os tempos de resposta, retornar os formatos JSON esperados e utilizar certificados válidos, você garante que a camada técnica seja invisível para o usuário e 100% confiável para o negócio. ✅