Meta Account

O Meta Account é a camada que cuida da sua relação com a Meta antes de qualquer mensagem sair. Ele descobre, espelha e vigia tudo que existe na sua conta Meta Business: as contas de WhatsApp (WABA), os números, os templates, os aplicativos, os usuários de sistema, os catálogos e os webhooks. Você entrega um identificador de negócio e um token; ele devolve o mapa completo e passa a avisar quando algo muda.

Na prática, ele resolve o dia em que o time de atendimento diz que "o WhatsApp parou" e ninguém sabe se o problema é o token que expirou, o webhook que foi apontado para o lugar errado, o número que caiu de qualidade ou o template que a Meta reprovou. Em vez de abrir quatro telas diferentes no painel da Meta e um chamado no fornecedor, você chama GET /businesses/:id/token/health e GET /businesses/:id/sync/drift e tem a resposta.

flowchart LR
  V["Você<br/>businessId + token de system user"] -->|"POST /discover"| BB["meta-account"]
  BB <-->|"Graph API v25.0"| M["Meta<br/>seu Business Manager"]
  BB --> E1["Mapa do portfólio<br/>WABAs · números · templates"]
  BB --> E2["Saúde do token<br/>GET /token/health"]
  BB --> E3["Divergência<br/>GET /sync/drift"]
  BB --> E4["Webhooks unificados<br/>app + WABA"]

Está em beta desde abril de 2026. O código roda no monolito e tem entry point standalone na porta 3028, mas ainda não está publicado nos ambientes de staging e produção — não aparece em infra/TOPOLOGY.md nem em AMBIENTES.md. A cobertura de testes automatizados é um único teste ponta a ponta contra a API real da Meta. Trate como pré-produção e leia a §15 antes de prometer prazo a cliente.

O cenário. Uma empresa decide atender e vender pelo WhatsApp. Contrata um fornecedor, recebe um número funcionando em duas semanas e fica satisfeita. Dois anos depois tem seis números, duas WABAs, quarenta templates e três aplicativos — e não tem ideia de onde nada disso mora, nem de quem é.

flowchart LR
  subgraph BMF["Business Manager do FORNECEDOR"]
    W1["WABA 1"]
    W2["WABA 2"]
    APP["Apps Meta"]
  end
  E["Sua empresa"] -.->|"não tem acesso administrativo"| BMF
  META["Meta"] -->|"fatura o parceiro"| F["Fornecedor"]
  F -->|"refatura você"| E
  W1 --> N1["6 números"]
  W2 --> N2["40 templates"]
  E -->|"quer sair"| SAIDA["Migração precisa ser<br/>INICIADA pelo fornecedor"]

O que trava hoje.

• A conta oficial pode não ser sua. No modelo Solution Partner, a Meta fatura o parceiro, e não você: os clientes trazidos pelo parceiro usam a linha de crédito dele (Solution Partner overview). Você não tem relação financeira direta com a Meta e não vê o custo de origem.
• Sair depende de quem você quer deixar. A migração de WABA entre parceiros é iniciada pelo provedor atual, que precisa marcar a conta e desabilitar a verificação em duas etapas do número (documentação da Meta). O cliente não migra sozinho. Quem está perdendo a conta tem, na prática, um veto operacional.
• Os recursos estão espalhados por telas que não conversam. Business Manager, configurações da WABA, configurações do número, painel do aplicativo. Responder "qual app está inscrito em qual WABA" exige navegar por três lugares e confiar na memória.
• Os webhooks existem em três níveis. Aplicativo, WABA e número. Cada um é configurado em um lugar diferente, com uma regra de herança diferente, e a falha silenciosa é o modo de falha padrão: o evento simplesmente não chega.
• Os erros da Meta não dizem nada. O código 190 com subcódigo 463 significa "seu token de desktop expirou porque tokens desse tipo duram cerca de 60 dias". Ninguém descobre isso lendo a mensagem original.
• O token expira e ninguém percebe. Até o cliente reclamar.

O custo de não resolver. Ele aparece em três frentes, e só uma delas dá algum sinal — tarde.

Custo direto: a indisponibilidade que ninguém detecta

O custo direto é a janela de indisponibilidade que ninguém detecta — se o webhook cai, as mensagens dos seus clientes chegam ao WhatsApp e não chegam ao seu sistema, e o único alarme é a reclamação.

Custo estrutural: quanto mais tempo, mais caro sair

O custo estrutural é maior e mais lento: quanto mais tempo a conta oficial fica no nome de um terceiro, mais caro fica sair, porque a saída depende da cooperação de quem está sendo trocado.

O prazo de 30 de junho de 2027

E há um prazo concreto no horizonte para quem opera no Brasil: a Meta determinou que clientes elegíveis migrem todas as WABAs para faturamento em BRL até 30 de junho de 2027, sob risco de interrupção de serviço (Pricing on the WhatsApp Business Platform, consulta em 2026-08-16). Quem não sabe onde estão as próprias WABAs não consegue cumprir esse prazo.

A conta é do cliente, por construção

O BB não tem Business Manager próprio. A entrada obrigatória de POST /discover é o identificador do seu negócio na Meta e um token gerado por você. Não existe caminho no código em que a Catalisa seja dona da WABA — a §5 e a §14 mostram onde isso está no código.

flowchart LR
  subgraph CLI["Business Manager do CLIENTE"]
    WABA["WABA · números · templates"]
    SU["System user + token"]
  end
  SU -->|"token delegado, revogável"| BB["meta-account<br/>opera em cima"]
  BB -.->|"nunca cria nem possui"| WABA
  CLI -->|"relação de faturamento direta"| META["Meta"]

Descoberta em vez de cadastro

Você não digita a lista de números, WABAs e templates. O DiscoveryService percorre o grafo da Meta e grava tudo, e as chamadas seguintes são idempotentes: rodar de novo atualiza, não duplica.

flowchart LR
  P["POST /discover"] --> D["DiscoveryService"]
  D --> A["WABAs próprias e de cliente"]
  D --> B["Números"]
  D --> C["Templates"]
  D --> E["Apps"]
  D --> F["System users"]
  D --> G["Catálogos"]
  A --> DB[("espelho em meta_account")]
  B --> DB
  C --> DB
  E --> DB
  F --> DB
  G --> DB

A divergência vira dado

O banco é um espelho consultável, e a Meta continua sendo a fonte de verdade. GET /sync/drift compara os dois e devolve campo a campo o que mudou sem você saber.

Erro traduzido com o que fazer

O meta-error-translator mapeia mais de vinte códigos da Meta para erros da plataforma com orientação em texto claro, preservando o objeto original em details.meta para depuração.

Segredo cifrado por organização

O token da Meta e o segredo do aplicativo ficam cifrados em AES-256-GCM no banco, por tenant. Nunca em variável de ambiente compartilhada, nunca de volta na resposta.

Panorama. O acesso à API do WhatsApp passa por um ecossistema de parceiros da Meta, dividido em duas figuras com consequências bem diferentes. O Solution Partner (o que o mercado chama de BSP) tem linha de crédito e pode estendê-la aos clientes que traz; nesse arranjo a Meta fatura o parceiro, e o parceiro fatura o cliente. O Tech Provider não tem linha de crédito: "clients onboarded by Tech Providers must provide their own payment method", e "Meta will then bill these clients for API usage" (Solution Partner overview, consulta em 2026-08-16).

flowchart TD
  META["Meta"]
  META -->|"fatura o parceiro"| SP["Solution Partner (BSP)<br/>tem linha de crédito"]
  SP -->|"refatura o cliente"| C1["Cliente do BSP"]
  META -->|"fatura o cliente direto"| C2["Cliente do Tech Provider"]
  TP["Tech Provider<br/>sem linha de crédito"] -.->|"opera, não fatura"| C2
  META -->|"fatura o cliente direto"| C3["Cliente Catalisa"]
  CAT["meta-account<br/>opera com token delegado"] -.->|"opera, não fatura"| C3

Essa distinção é a raiz econômica do aprisionamento. No modelo BSP, o cliente não tem relação financeira direta com a Meta, não vê o preço de custo, e — quando decide sair — descobre que o procedimento de migração precisa ser iniciado pelo parceiro que ele está deixando. Isso não é conjectura de mercado: está na documentação da própria Meta, citada na §4.

O Meta Account não compete com BSP em conectividade. Ele resolve a camada que quase nenhum deles entrega: a gestão do portfólio Meta como recurso de primeira classe, com o ativo no nome do cliente.

Comparativo montado a partir das documentações públicas dos fornecedores em 2026-08-16. As lacunas marcadas como "não localizada" significam exatamente isso — não encontramos documentação pública, o que não equivale a afirmar que o recurso não exista. Para Take Blip, Zenvia e Gupshup não localizamos declaração pública sobre a propriedade da WABA.

Nossos diferenciais

1. A propriedade do ativo é consequência do código, não do contrato

A entrada de POST /discover é o identificador do negócio do cliente mais um token do cliente. Não existe Business Manager da Catalisa no caminho, não há linha de crédito estendida e não há chamada que crie WABA em nome de terceiro.

Por que é difícil de copiar: um concorrente que já tenha milhares de WABAs no próprio Business Manager não copia isso com uma mudança de produto — teria que migrar a base inteira, com a cooperação de cada cliente.

2. A descoberta substitui o cadastro

Um POST percorre o grafo da Meta — WABAs próprias e de cliente, números, templates, aplicativos, system users, catálogos — e grava o espelho.

Por que é difícil de copiar: não pela chamada em si, mas pelo tratamento — 31 métodos de cliente HTTP, tradução de mais de vinte códigos de erro e reconciliação idempotente com exclusão lógica de quem sumiu.

3. Os três níveis de webhook em um lugar só

A Meta separa assinatura de aplicativo, assinatura de WABA e roteamento por número em contextos distintos, com tokens de autenticação distintos. O BB encapsula as duas formas que existem e expõe status e configuração unificados.

4. O espelho é consultável e a divergência é explícita

Ter os recursos da Meta em Postgres permite consulta, junção e histórico de sincronização — e permite responder "o que mudou lá sem eu saber" sem depender do suporte de ninguém.

Quando escolher o concorrente. Há quatro situações em que a resposta honesta é "não é este BB".

O Meta Account ganha quando o problema é muitos ativos Meta, muitas mãos e a exigência de que a conta oficial seja do cliente — não quando o problema é entregar o primeiro número em uma semana.

Precificação em definição. O Meta Account não tem preço fechado. Ele é uma camada de provisionamento e governança, não um canal de mensagem, e a intenção é que acompanhe a contratação do wpp-business em vez de ser vendido isolado. Não há valor a divulgar, e este documento não estima nenhum.

O que dispara custo.

O custo que não é nosso. O custo de mensagem é da Meta e vai direto para o cliente, porque a conta é do cliente. Desde 1º de julho de 2025 a Meta cobra por mensagem entregue, e não mais por conversa (Pricing on the WhatsApp Business Platform; a página de cobrança por conversa está marcada como substituída). O que isso significa por categoria:

Também são gratuitas as mensagens dentro da janela de ponto de entrada gratuito de 72 horas, aberta quando o usuário chega por anúncio Click to WhatsApp ou por botão de página do Facebook e o negócio responde em 24 horas.

flowchart TD
  MSG["Mensagem entregue"] --> CAT{"Categoria do template"}
  CAT -->|"Service"| FREE["Gratuita<br/>desde 2024-11-01"]
  CAT -->|"Marketing"| PAGA["Sempre cobrada"]
  CAT -->|"Utility"| JAN{"Dentro de janela<br/>de atendimento aberta?"}
  CAT -->|"Authentication"| JAN2{"Dentro de janela?"}
  JAN -->|"sim"| FREE
  JAN -->|"não"| PAGA
  JAN2 -->|"sim"| FREE
  JAN2 -->|"não"| FAIXA["Cobrada, com faixas<br/>de volume a taxas menores"]
  ENTRADA["Ponto de entrada gratuito<br/>Click to WhatsApp ou botão de página"] -->|"resposta em 24h, janela de 72h"| FREE

Comparação de custo — cenário nomeado: operação com 3 números, 1 WABA e 200 mil mensagens de template por mês.

Preços públicos consultados em 2026-08-16: 360dialog (página datada de 14/08/2026), Twilio WhatsApp, Take Blip (sem data visível). Infobip e Gupshup não publicam preço em página aberta. Não reproduzimos tarifa da Meta por país porque a documentação oficial distribui os valores em arquivos anexos, não na página — baixe o rate card vigente antes de qualquer proposta. Todos os números acima são dos fornecedores, não estimativas nossas.

ROI. A conta de guardanapo tem duas linhas e nenhuma delas é licença.

Linha 1 — a indisponibilidade que ninguém detecta

Um webhook desconfigurado não gera erro visível: o envio segue funcionando e só o recebimento para. Se a sua operação depende de resposta do cliente — cobrança, confirmação, atendimento — cada hora nesse estado é conversa perdida. Detecção por reclamação custa dias; GET /webhooks/status custa uma chamada.

Linha 2 — o custo de saída

Enquanto a conta oficial estiver no nome de um fornecedor, trocar de fornecedor exige a cooperação dele, e o poder de negociação na renovação de contrato é dele. Com a conta no seu nome, o custo de saída é revogar um token. Esse é o item de maior valor econômico e o mais difícil de colocar em planilha, porque ele só aparece no dia em que você precisa dele.

As cinco camadas

flowchart TD
  CLI["Cliente HTTP<br/>Bearer JWT emitido pelo IAM"]
  subgraph L1["1 · Borda — Hono app, basePath /meta-account"]
    MW["applyCommonMiddleware<br/>corpo 1 MB · CORS · headers · rate limit"]
    AUTH["authMiddleware + requirePermission + requireOrganization"]
  end
  subgraph L2["2 · Rotas — 14 routers"]
    R["Zod parse + validateUuidParam"]
  end
  subgraph L3["3 · Serviços (12)"]
    S1["DiscoveryService<br/>orquestra o onboarding inteiro"]
    S2["SyncService<br/>fullSync · syncResource · detectDrift"]
    S3["TokenHealthService<br/>introspecção → classificação → evento"]
    S4["WebhookService<br/>níveis de app e WABA + auto-configure"]
    S5["Business · Waba · PhoneNumber · Template · App<br/>SystemUser · Catalog · Product"]
  end
  subgraph L4["4 · Persistência e provedor"]
    REPO["repositories (11, Prisma)<br/>PostgreSQL, schema meta_account<br/>espelho local consultável"]
    PROV["providers/meta-graph<br/>MetaGraphClient — 31 métodos<br/>retry 3x, espera 1s / 2s / 4s<br/>translateMetaError (20+ códigos)"]
  end
  subgraph L5["5 · Externo"]
    META["Meta Graph API v25.0<br/>graph.facebook.com"]
  end
  CLI --> MW --> AUTH --> R
  R --> S1 & S2 & S3 & S4 & S5
  S1 & S2 & S3 & S4 & S5 --> REPO
  S1 & S2 & S3 & S4 & S5 --> PROV
  PROV -->|"HTTPS"| META

Onde cada router é montado

O caminho de uma requisição

sequenceDiagram
  autonumber
  participant C as Cliente
  participant H as Hono + middlewares
  participant R as Router
  participant S as Service
  participant D as Repository Prisma
  participant G as MetaGraphClient
  participant M as Meta Graph API
  C->>H: Bearer JWT
  H->>H: authMiddleware · requirePermission · requireOrganization
  H->>R: contexto com organizationId
  R->>R: Zod parse + validateUuidParam
  R->>S: input validado
  S->>D: findById(id, organizationId)
  D-->>S: registro do espelho
  S->>G: chamada com token decifrado
  G->>M: HTTPS graph.facebook.com/v25.0
  M-->>G: resposta ou erro
  G-->>S: ResultAsync com erro já traduzido
  S->>D: upsertByMetaId + lastSyncAt
  S-->>R: ResultAsync de T ou AppError
  R-->>C: handleResult → JSON

Decisões não óbvias.

O token da Meta mora no banco, cifrado por organização — não em variável de ambiente

É a decisão que torna o BB multi-tenant de verdade: cada organização conecta o próprio Business Manager, e o META_ACCOUNT_CREDENTIAL_MASTER_KEY é apenas a chave de cifragem AES-256-GCM, comum ao serviço.

O trade-off é que a chave mestra vira ativo crítico — vazá-la expõe os tokens de todos os tenants — e por isso ela é validada como 64 caracteres hexadecimais e guardada em SOPS.

O segredo nunca volta na resposta

BusinessService e AppService passam todo retorno por toSafeBusiness/toSafeApp, que removem o campo cifrado e o substituem por hasAccessToken/hasAppSecret booleanos. Um GET no negócio não vaza token nem por acidente de serialização.

Retry só no que adianta repetir

O MetaGraphClient repete três vezes, com espera de 1s, 2s e 4s, apenas quando o erro traduzido é INTERNAL, SERVICE_UNAVAILABLE ou TIMEOUT.

flowchart TD
  CH["Chamada à Graph API"] --> ERR{"Erro traduzido"}
  ERR -->|"INTERNAL · SERVICE_UNAVAILABLE · TIMEOUT"| RT["Repete<br/>1s → 2s → 4s, no máximo 3x"]
  ERR -->|"UNAUTHORIZED · FORBIDDEN · VALIDATION"| STOP["Falha na hora<br/>insistir não melhora e arrisca bloqueio por taxa"]
  RT -->|"esgotou"| STOP
  RT -->|"sucesso"| OK["Resposta"]

Token inválido, permissão faltando e parâmetro errado não são repetidos, porque nenhum deles melhora com insistência — e insistir em erro de autenticação é a receita para ser bloqueado por limite de taxa.

A introspecção de token usa o próprio token como credencial de aplicativo

debugToken(input, input) — a Meta aceita que um token se autovalide, o que evita exigir um token de aplicativo separado só para checar saúde.

Os identificadores das rotas são UUIDs internos, não IDs da Meta

Todas as rotas passam por validateUuidParam. GET /wabas/:id recebe o UUID da linha em meta_wabas, não o identificador numérico da WABA na Meta. Os campos metaAppId e metaWabaId nos corpos de configuração de webhook também são UUIDs internos, apesar do nome sugerir o contrário — é a armadilha de integração mais provável deste BB.

A Meta é a fonte de verdade; o banco é cache consultável

Por isso existe detectDrift: em vez de fingir que o espelho está sempre correto, o BB expõe a diferença. A reconciliação usa upsertByMetaId mais exclusão lógica de quem sumiu do lado da Meta, o que torna discover e sync seguros de repetir.

O nível de webhook por número não existe porque a Meta não o oferece

O enum MetaWebhookLevel tem o valor PHONE_NUMBER, mas não há endpoint correspondente na Meta: os eventos trafegam pela WABA e são distinguidos por metadata.phone_number_id. O roteamento por número é responsabilidade da aplicação consumidora.

Monolito vs. standalone

O app.ts é montado no monolito em src/app.ts e responde em http://localhost:3000/meta-account. O main.ts sobe o mesmo app com Bun.serve na porta 3028 quando DEPLOYMENT_MODE=standalone. Não há diferença de comportamento entre os modos: o BB não chama outros building blocks, só a Graph API. O que muda é que, em standalone, applyCommonMiddleware é a única fonte de limite de corpo, CORS, cabeçalhos de segurança e limite de taxa — no monolito eles também vêm da camada externa.

Glossário

Modelo de dados — schema meta_account no PostgreSQL. 11 modelos.

Todos os modelos com dado da Meta guardam a resposta original em rawMeta (JSON) e o instante da última leitura em lastSyncAt. Todos usam exclusão lógica por deletedAt. Todos são isolados por organizationId, com unicidade composta — por exemplo @@unique([organizationId, metaWabaId]) — de modo que duas organizações podem apontar para o mesmo recurso da Meta sem colidir.

Enumerações

Grafo de recursos

O MetaBusiness é a raiz: um Business Manager por organização conectada. Tudo o mais pendura nele.

erDiagram
  MetaBusiness ||--o{ MetaWaba : "owned ou client"
  MetaBusiness ||--o{ MetaApp : "aplicativos do BM"
  MetaBusiness ||--o{ MetaSystemUser : "origem dos tokens permanentes"
  MetaBusiness ||--o{ MetaCatalog : "catálogos do BM"
  MetaBusiness ||--|| MetaTokenHealth : "um para um"
  MetaBusiness ||--o{ MetaSyncLog : "histórico"
  MetaWaba ||--o{ MetaPhoneNumber : "números"
  MetaWaba ||--o{ MetaTemplateSnapshot : "retratos de template"
  MetaWaba ||--o{ MetaWebhookConfig : "nível WABA"
  MetaApp ||--o{ MetaWebhookConfig : "nível APP"
  MetaCatalog ||--o{ MetaProduct : "produtos"

  MetaBusiness {
    string metaBusinessId "raiz do grafo"
    string accessToken "cifrado AES-256-GCM"
    string verificationStatus
    enum lastSyncStatus
  }
  MetaWaba {
    string metaWabaId
    string ownershipType "owned ou client"
    string businessVerificationStatus
    string accountReviewStatus
    string currency
  }
  MetaPhoneNumber {
    string displayPhoneNumber
    string qualityRating "qualidade"
    string status
    string codeVerificationStatus "verificação"
    string throughputLevel "throughput"
  }
  MetaTemplateSnapshot {
    string metaTemplateId "único por organização, template e idioma"
    string language
    string category
    string status
  }
  MetaApp {
    string metaAppId
    string appSecret "cifrado, necessário para webhook de app"
  }
  MetaSystemUser {
    string metaSystemUserId
    string role "ADMIN ou EMPLOYEE"
  }
  MetaCatalog {
    string metaCatalogId
    int productCount
  }
  MetaProduct {
    string retailerId
    string availability
  }
  MetaWebhookConfig {
    enum level "APP ou WABA"
    string callbackUrl
  }
  MetaTokenHealth {
    enum status
    date expiresAt
  }
  MetaSyncLog {
    string syncType
    enum status
    int durationMs
  }

Máquina de estados da saúde do token

O status não é editado: ele é recalculado do zero a cada POST /token/check (e dentro de POST /discover), a partir da resposta de debugToken. A árvore de decisão é esta:

flowchart TD
  IN["POST /token/check ou POST /discover"] --> DBG["debugToken na Graph API"]
  DBG --> V1{"is_valid"}
  V1 -->|"false"| INVALID["INVALID"]
  V1 -->|"true"| EXP{"expires_at existe e maior que zero"}
  EXP -->|"sim"| QUANDO{"quando expira"}
  QUANDO -->|"já passou"| EXPIRED["EXPIRED"]
  QUANDO -->|"em menos de 7 dias"| SOON["EXPIRING_SOON"]
  QUANDO -->|"em mais de 7 dias"| ESC{"faltam escopos obrigatórios"}
  EXP -->|"não — token sem expiração"| ESC
  ESC -->|"sim"| MISS["MISSING_SCOPES"]
  ESC -->|"não"| OK["VALID"]

E estes são os estados persistidos em MetaTokenHealth.status, com os caminhos que acontecem na prática:

stateDiagram-v2
  state "Nunca verificado — GET /token/health devolve 404" as Ausente
  state "VALID" as V
  state "EXPIRING_SOON — faltam 7 dias ou menos" as ES
  state "EXPIRED" as EX
  state "INVALID — revogado ou inválido na Meta" as IN
  state "MISSING_SCOPES — falta escopo obrigatório" as MS

  [*] --> Ausente
  Ausente --> V: primeira verificação, token íntegro
  Ausente --> MS: primeira verificação, escopo faltando
  Ausente --> IN: primeira verificação, is_valid false
  V --> ES: nova verificação dentro da janela de 7 dias
  V --> EX: nova verificação depois de expiresAt
  V --> IN: token revogado na Meta
  V --> MS: escopo removido do token
  ES --> EX: nova verificação depois da data
  ES --> V: token novo gravado e reverificado
  EX --> V: token novo gravado e reverificado
  IN --> V: token novo gravado e reverificado
  MS --> V: token novo com os escopos exigidos
  note right of V
    INVALID, EXPIRED e EXPIRING_SOON publicam
    meta-account.token.healthChanged.
    Token de system user sem expiração chega
    com expires_at = 0 e nunca vira EXPIRING_SOON.
  end note

Máquina de estados da sincronização

MetaSyncLog.status e MetaBusiness.lastSyncStatus compartilham o enum MetaSyncStatus. Na prática, o código percorre só dois dos quatro valores:

stateDiagram-v2
  state "PENDING — padrão do schema Prisma; nenhum código o grava" as P
  state "IN_PROGRESS — gravado ao criar o log de sincronização" as IP
  state "COMPLETED — grava resourcesFound, resourcesSynced e durationMs" as C
  state "FAILED — declarado no enum; nenhum código o grava hoje" as F

  [*] --> IP: POST /discover, POST /sync ou sync de um tipo só
  P --> IP: só se a linha nascer sem status explícito
  IP --> C: a cadeia ResultAsync termina em ok
  IP --> F: transição prevista, não implementada
  C --> [*]
  F --> [*]

Prefixo: /meta-account. Em monolito, a base é http://localhost:3000. Em standalone, a porta é 3028.

Todas as 36 rotas exigem, sem exceção: authMiddleware (Bearer JWT do IAM), requirePermission e o middleware local requireOrganization — que devolve 403 quando o token não carrega organizationId. Rotas de leitura exigem META_ACCOUNT_READ; rotas que escrevem ou chamam a Meta exigem META_ACCOUNT_MANAGE.

Armadilha central: todo :id, :businessId, :catalogId e :productId é o UUID interno da linha no banco, validado por validateUuidParam. Não é o identificador numérico da Meta. Os campos metaAppId e metaWabaId nos corpos de webhook também são UUIDs internos, apesar do nome.

Descoberta — /meta-account/api/v1/discover

Negócios — /meta-account/api/v1/businesses

WABAs — /meta-account/api/v1/wabas

Números — /meta-account/api/v1/phone-numbers

Templates, aplicativos e system users

Webhooks

Catálogos e produtos

Sincronização e saúde do token

Valores aceitos em :resourceType: wabas, phone_numbers, templates, apps, system_users, catalogs. Qualquer outro devolve 400.

Saúde do serviço

POST /meta-account/api/v1/discover

O ponto de entrada do BB. Valida o token, confere os escopos obrigatórios antes de gravar qualquer coisa, e só então percorre o grafo.

sequenceDiagram
  autonumber
  participant C as Cliente
  participant BB as meta-account
  participant M as Meta Graph API
  participant DB as PostgreSQL
  C->>BB: POST /discover com businessId e accessToken
  BB->>M: debugToken usando o próprio token como credencial
  M-->>BB: is_valid, scopes, expires_at
  alt token inválido ou sem escopo obrigatório
    BB-->>C: 400 VALIDATION com missingScopes e currentScopes
    Note over BB,DB: nada é gravado no banco
  else token aprovado
    BB->>M: getBusinessInfo do businessId
    BB->>DB: upsertByMetaId do negócio, token cifrado, lastSyncStatus IN_PROGRESS
    BB->>DB: upsert de MetaTokenHealth
    BB->>DB: cria MetaSyncLog com status IN_PROGRESS
    par WABAs
      BB->>M: getOwnedWabas + getClientWabas, depois números e templates
    and Aplicativos
      BB->>M: lista os apps do BM
    and System users
      BB->>M: lista os system users do BM
    and Catálogos
      BB->>M: lista os catálogos do BM
    end
    BB->>DB: upserts do espelho
    BB->>DB: MetaSyncLog COMPLETED e lastSyncStatus COMPLETED
    BB->>BB: publica meta-account.business.discovered
    BB-->>C: 201 com o grafo descoberto
  end

Request

{
  "businessId": "1234567890123456",
  "accessToken": "<token de system user do SEU Business Manager>"
}

{
  "businessId": "1234567890123456",
  "accessToken": "<token de system user do SEU Business Manager>"
}

Resposta 201

{
  "data": {
    "business": {
      "id": "3f1c…",
      "metaBusinessId": "1234567890123456",
      "name": "Empresa Exemplo LTDA",
      "verificationStatus": "verified"
    },
    "tokenHealth": {
      "status": "VALID",
      "scopes": ["business_management", "whatsapp_business_management", "..."],
      "missingScopes": [],
      "expiresAt": null
    },
    "wabas": [
      {
        "waba": { "id": "9a2e…", "metaWabaId": "9876543210", "name": "Atendimento", "ownershipType": "owned" },
        "phoneNumbers": [
          { "id": "b71d…", "metaPhoneNumberId": "5544332211", "displayPhoneNumber": "+55 11 90000-0000",
            "qualityRating": "GREEN", "status": "CONNECTED" }
        ],
        "templateCount": 12
      }
    ],
    "apps": [{ "id": "c40a…", "metaAppId": "111222333444", "name": "Integração Exemplo" }],
    "systemUsers": [{ "id": "d55b…", "metaSystemUserId": "555666777", "name": "automacao", "role": "ADMIN" }],
    "catalogs": [{ "id": "e66c…", "metaCatalogId": "888999000", "name": "Catálogo Loja", "productCount": 42 }],
    "syncLog": { "status": "COMPLETED", "resourcesFound": 61, "resourcesSynced": 61, "durationMs": 4312 }
  }
}

{
  "data": {
    "business": {
      "id": "3f1c…",
      "metaBusinessId": "1234567890123456",
      "name": "Empresa Exemplo LTDA",
      "verificationStatus": "verified"
    },
    "tokenHealth": {
      "status": "VALID",
      "scopes": ["business_management", "whatsapp_business_management", "..."],
      "missingScopes": [],
      "expiresAt": null
    },
    "wabas": [
      {
        "waba": { "id": "9a2e…", "metaWabaId": "9876543210", "name": "Atendimento", "ownershipType": "owned" },
        "phoneNumbers": [
          { "id": "b71d…", "metaPhoneNumberId": "5544332211", "displayPhoneNumber": "+55 11 90000-0000",
            "qualityRating": "GREEN", "status": "CONNECTED" }
        ],
        "templateCount": 12
      }
    ],
    "apps": [{ "id": "c40a…", "metaAppId": "111222333444", "name": "Integração Exemplo" }],
    "systemUsers": [{ "id": "d55b…", "metaSystemUserId": "555666777", "name": "automacao", "role": "ADMIN" }],
    "catalogs": [{ "id": "e66c…", "metaCatalogId": "888999000", "name": "Catálogo Loja", "productCount": 42 }],
    "syncLog": { "status": "COMPLETED", "resourcesFound": 61, "resourcesSynced": 61, "durationMs": 4312 }
  }
}

expiresAt: null indica token sem expiração — é o comportamento esperado de um token de system user e o estado desejável.

Erros

É idempotente: chamar de novo com o mesmo businessId atualiza o registro existente, graças ao upsertByMetaId.

GET /meta-account/api/v1/businesses/:businessId/token/health

Lê o último estado gravado — não consulta a Meta. Para reconsultar, use POST .../token/check antes.

Resposta 200

{
  "data": {
    "status": "EXPIRING_SOON",
    "message": "Token is valid but expiring soon.",
    "guidance": "Generate a new system user token in Meta Business Settings > System Users for permanent access.",
    "expiresAt": "2026-08-22T10:00:00.000Z",
    "expiresInDays": 6,
    "scopes": ["business_management", "whatsapp_business_management"],
    "missingScopes": ["whatsapp_business_messaging", "catalog_management"],
    "requiredScopes": ["business_management", "whatsapp_business_management",
                       "whatsapp_business_messaging", "catalog_management"]
  }
}

{
  "data": {
    "status": "EXPIRING_SOON",
    "message": "Token is valid but expiring soon.",
    "guidance": "Generate a new system user token in Meta Business Settings > System Users for permanent access.",
    "expiresAt": "2026-08-22T10:00:00.000Z",
    "expiresInDays": 6,
    "scopes": ["business_management", "whatsapp_business_management"],
    "missingScopes": ["whatsapp_business_messaging", "catalog_management"],
    "requiredScopes": ["business_management", "whatsapp_business_management",
                       "whatsapp_business_messaging", "catalog_management"]
  }
}

missingScopes compara contra os escopos recomendados, não só os obrigatórios. Um token com status: VALID e missingScopes preenchido está funcional — apenas sem acesso a mensageria ou catálogo. requiredScopes na resposta lista, na verdade, o conjunto recomendado completo.

Responde 404 quando nunca houve verificação para esse negócio; rode POST .../token/check primeiro.

POST /meta-account/api/v1/webhooks/app

Assina o webhook no nível do aplicativo. Exige que o appSecret já esteja gravado por PATCH /apps/:id — sem ele, responde 400.

Request

{
  "metaAppId": "c40a1e88-0000-0000-0000-000000000000",
  "callbackUrl": "https://api.suaempresa.com.br/webhooks/whatsapp",
  "verifyToken": "uma-string-de-no-minimo-8-caracteres",
  "objectType": "whatsapp_business_account",
  "fields": ["messages", "message_template_status_update"]
}

{
  "metaAppId": "c40a1e88-0000-0000-0000-000000000000",
  "callbackUrl": "https://api.suaempresa.com.br/webhooks/whatsapp",
  "verifyToken": "uma-string-de-no-minimo-8-caracteres",
  "objectType": "whatsapp_business_account",
  "fields": ["messages", "message_template_status_update"]
}

GET /meta-account/api/v1/businesses/:businessId/sync/drift

Resposta 200

{
  "data": {
    "checkedAt": "2026-08-16T14:03:11.000Z",
    "drifts": [
      { "resourceType": "phone_number", "resourceId": "5544332211",
        "displayName": "+55 11 90000-0000", "field": "qualityRating",
        "localValue": "GREEN", "remoteValue": "YELLOW" }
    ],
    "summary": { "total": 1, "phone_number": 1 }
  }
}

{
  "data": {
    "checkedAt": "2026-08-16T14:03:11.000Z",
    "drifts": [
      { "resourceType": "phone_number", "resourceId": "5544332211",
        "displayName": "+55 11 90000-0000", "field": "qualityRating",
        "localValue": "GREEN", "remoteValue": "YELLOW" }
    ],
    "summary": { "total": 1, "phone_number": 1 }
  }
}

A comparação cobre, hoje, quatro campos: name e businessVerificationStatus na WABA; qualityRating e status no número. E percorre apenas WABAs próprias — as de cliente ficam de fora. Ver §15.

Do zero ao portfólio Meta mapeado. O caminho abaixo usa o monolito local, porque o meta-account ainda não está publicado em staging (§1).

Estes comandos não foram executados na redação deste documento — a etapa 3 em diante exige credenciais reais de um Business Manager, que não entram em documentação. As respostas mostradas refletem os tipos de retorno do código. Credenciais de teste em AMBIENTES.md.

O caminho tem sete etapas, e a segunda delas acontece fora da Catalisa:

sequenceDiagram
  autonumber
  participant V as Você
  participant I as IAM
  participant BM as Seu Business Manager
  participant MA as meta-account
  participant M as Meta Graph API
  V->>I: 1. login, recebe o JWT
  V->>BM: 2. cria system user e gera o token com os escopos
  BM-->>V: token que não expira + ID do negócio
  V->>MA: 3. POST /discover com businessId e token
  MA->>M: percorre o grafo
  MA-->>V: 201 com business, tokenHealth e WABAs
  V->>MA: 4. GET /businesses/:id/graph
  V->>MA: 5. GET /businesses/:id — confirma que o token não vaza
  V->>MA: 6. POST /businesses/:id/token/check

0. Subir a infra e o serviço

docker-compose up -d postgres redis minio
bun run dev

docker-compose up -d postgres redis minio
bun run dev

Espere ver o log do monolito respondendo na porta 3000.

1. Autenticar no IAM

TOKEN=$(curl -s -X POST http://localhost:3000/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

echo "${TOKEN:0:20}…"

TOKEN=$(curl -s -X POST http://localhost:3000/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

echo "${TOKEN:0:20}…"

eyJhbGciOiJIUzI1NiIs…

eyJhbGciOiJIUzI1NiIs…

2. Gerar o token na Meta — feito por você, no seu Business Manager

Esta etapa acontece fora da Catalisa, e é ela que garante que a conta é sua:

1. Em business.facebook.com, abra Configurações do negócio → Usuários → Usuários do sistema.
2. Crie um system user com papel ADMIN (ou use um existente).
3. Atribua a ele os ativos: a WABA, o aplicativo e o catálogo.
4. Clique em Gerar novo token, escolha o aplicativo e marque, no mínimo, business_management e whatsapp_business_management. Some whatsapp_business_messaging e catalog_management se for usar mensageria e catálogo.
5. Copie o token. Anote também o ID do negócio, visível na URL ou em Informações do negócio.

Guarde esse token com SOPS. Ele dá acesso administrativo ao seu Business Manager.

3. Descobrir o portfólio

curl -s -X POST http://localhost:3000/meta-account/api/v1/discover \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "SEU_BUSINESS_ID",
    "accessToken": "SEU_TOKEN_DE_SYSTEM_USER"
  }' | jq '.data | {business, tokenHealth, wabas: (.wabas | length)}'

curl -s -X POST http://localhost:3000/meta-account/api/v1/discover \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "SEU_BUSINESS_ID",
    "accessToken": "SEU_TOKEN_DE_SYSTEM_USER"
  }' | jq '.data | {business, tokenHealth, wabas: (.wabas | length)}'

{
  "business": { "id": "3f1c…", "name": "Empresa Exemplo LTDA", "verificationStatus": "verified" },
  "tokenHealth": { "status": "VALID", "missingScopes": [], "expiresAt": null },
  "wabas": 2
}

{
  "business": { "id": "3f1c…", "name": "Empresa Exemplo LTDA", "verificationStatus": "verified" },
  "tokenHealth": { "status": "VALID", "missingScopes": [], "expiresAt": null },
  "wabas": 2
}

4. Guardar o UUID interno e ver o grafo

BUSINESS_ID=$(curl -s http://localhost:3000/meta-account/api/v1/businesses \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')

curl -s "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/graph" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.business | {name, wabas: [.wabas[].name]}'

BUSINESS_ID=$(curl -s http://localhost:3000/meta-account/api/v1/businesses \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')

curl -s "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/graph" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.business | {name, wabas: [.wabas[].name]}'

{
  "name": "Empresa Exemplo LTDA",
  "wabas": ["Atendimento", "Cobrança"]
}

{
  "name": "Empresa Exemplo LTDA",
  "wabas": ["Atendimento", "Cobrança"]
}

O $BUSINESS_ID guardado aqui é o UUID interno — é ele que todas as rotas seguintes esperam.

5. Confirmar que o token não vaza

curl -s "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID" \
  -H "Authorization: Bearer $TOKEN" | jq '.data | {name, hasAccessToken, accessToken}'

curl -s "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID" \
  -H "Authorization: Bearer $TOKEN" | jq '.data | {name, hasAccessToken, accessToken}'

{ "name": "Empresa Exemplo LTDA", "hasAccessToken": true, "accessToken": null }

{ "name": "Empresa Exemplo LTDA", "hasAccessToken": true, "accessToken": null }

O campo accessToken não existe na resposta — toSafeBusiness o remove. O que sobra é o booleano.

6. Checar a saúde do token

curl -s -X POST "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/token/check" \
  -H "Authorization: Bearer $TOKEN" | jq '.data | {status, expiresAt, missingScopes}'

curl -s -X POST "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/token/check" \
  -H "Authorization: Bearer $TOKEN" | jq '.data | {status, expiresAt, missingScopes}'

{
  "status": "VALID",
  "expiresAt": null,
  "missingScopes": []
}

{
  "status": "VALID",
  "expiresAt": null,
  "missingScopes": []
}

status: "VALID" com expiresAt: null é o estado desejável: token de system user, sem data de validade.

Onboarding completo: do zero ao número apto a enviar

Objetivo. Sair de uma empresa sem nada na Meta e chegar a um número capaz de enviar mensagem, com a conta oficial no nome do cliente.

Este é o fluxo que a §1 promete. As etapas do primeiro bloco acontecem fora do BB, no domínio da Meta, e são justamente as que garantem que a conta é do cliente.

flowchart TD
  subgraph FORA["Fora do BB — no Business Manager do CLIENTE"]
    E1["1. Criar o Business Manager<br/>business.facebook.com"]
    E2["2. Verificação de negócio<br/>destrava 20 números e o tier 2.000"]
    E3["3. Criar app Meta e vincular ao BM<br/>developers.facebook.com"]
    E4["4. Criar WABA e adicionar número<br/>nome de exibição vai para aprovação"]
    E5["5. System user ADMIN, atribuir ativos<br/>WABA, app e catálogo; gerar token que NÃO expira"]
    E1 --> E2 --> E3 --> E4 --> E5
  end
  subgraph BB["No meta-account"]
    E6["6. POST /discover<br/>valida escopos, mapeia e espelha WABAs, números,<br/>templates, apps, system users e catálogos"]
    E7["7. GET /businesses/:id/token/health<br/>status VALID? expiresAt null?"]
    E8["8. Número não verificado?<br/>POST /phone-numbers/:id/request-verification method SMS<br/>POST /phone-numbers/:id/verify code 123456"]
    E9["9. PATCH /apps/:id com appSecret<br/>habilita o webhook de app"]
    E10["10. POST /businesses/:id/webhooks/auto-configure<br/>assina o app e todas as WABAs"]
    E11["11. GET /businesses/:id/webhooks/status<br/>conferir antes de seguir"]
    E6 --> E7 --> E8 --> E9 --> E10 --> E11
  end
  subgraph WPP["No wpp-business"]
    E12["12. POST /wpp-business/api/v1/accounts"]
    E13["13. POST /wpp-business/api/v1/accounts/:id/phone-numbers"]
    E14["Número apto a enviar<br/>começando no tier de 250 destinatários por dia"]
    E12 --> E13 --> E14
  end
  E5 -->|"businessId + accessToken"| E6
  E11 -->|"wabaId + businessId + accessToken<br/>IDs da META, não UUIDs"| E12

Armadilhas.

• As etapas 1 a 5 não são automatizadas por este BB. Não existe Embedded Signup aqui (§15). É trabalho manual do cliente, uma única vez — e é o preço da propriedade da conta.
• Gere o token como system user, não pelo painel do desenvolvedor. O token do painel expira em cerca de 60 dias e produz o erro 190/463 num sábado.
• A callbackUrl do webhook precisa ser pública e com TLS válido. A Meta faz uma requisição real de verificação; URL de exemplo ou certificado inválido faz a assinatura falhar.
• Na etapa 12, o wpp-business espera os identificadores da Meta (wabaId, businessId), não os UUIDs internos do meta-account. Leia-os dos campos metaWabaId e metaBusinessId.
• Portfólio novo começa limitado a 2 números registrados e sobe para 20 com a verificação de negócio, ou ao atingir o limite de 2.000 mensagens.

Conferir e consertar webhook que parou de entregar

Objetivo. Descobrir em qual nível a assinatura sumiu e reaplicá-la sem abrir o painel da Meta.

sequenceDiagram
  autonumber
  participant V as Você
  participant MA as meta-account
  participant M as Meta Graph API
  V->>MA: GET /businesses/:id/webhooks/status
  MA->>M: getAppSubscriptions por app com appSecret gravado
  MA->>M: consulta as assinaturas de cada WABA
  M-->>MA: estado real, por nível
  MA-->>V: levels.app, levels.waba, levels.phoneNumber
  V->>MA: POST /businesses/:id/webhooks/auto-configure
  MA->>M: subscribeAppToWebhooks em cada app com segredo
  MA->>M: subscribeWabaToApp em cada WABA
  M-->>MA: sucesso ou falha, recurso a recurso
  MA-->>V: 200 com results, um item por recurso

Passo 1 — o que a Meta diz que está inscrito, agora.

curl -s "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/webhooks/status" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.levels'

curl -s "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/webhooks/status" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.levels'

{
  "app": [
    { "appId": "111222333444", "appName": "Integração Exemplo", "configured": true,
      "callbackUrl": "https://api.suaempresa.com.br/webhooks/whatsapp",
      "fields": ["messages", "message_template_status_update"], "active": true }
  ],
  "waba": [
    { "wabaId": "9876543210", "wabaName": "Atendimento", "configured": true,
      "overrideCallbackUri": null, "inheritsFromApp": true },
    { "wabaId": "1122334455", "wabaName": "Cobrança", "configured": false,
      "overrideCallbackUri": null, "inheritsFromApp": false }
  ],
  "phoneNumber": []
}

{
  "app": [
    { "appId": "111222333444", "appName": "Integração Exemplo", "configured": true,
      "callbackUrl": "https://api.suaempresa.com.br/webhooks/whatsapp",
      "fields": ["messages", "message_template_status_update"], "active": true }
  ],
  "waba": [
    { "wabaId": "9876543210", "wabaName": "Atendimento", "configured": true,
      "overrideCallbackUri": null, "inheritsFromApp": true },
    { "wabaId": "1122334455", "wabaName": "Cobrança", "configured": false,
      "overrideCallbackUri": null, "inheritsFromApp": false }
  ],
  "phoneNumber": []
}

A WABA com configured: false é a que parou de entregar. phoneNumber volta sempre vazio — a Meta não expõe assinatura por número (§15).

Passo 2 — reaplicar em todos os apps com segredo e todas as WABAs.

curl -s -X POST \
  "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/webhooks/auto-configure" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"callbackBaseUrl":"https://api.suaempresa.com.br/webhooks/whatsapp"}' | jq '.data.results'

curl -s -X POST \
  "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/webhooks/auto-configure" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"callbackBaseUrl":"https://api.suaempresa.com.br/webhooks/whatsapp"}' | jq '.data.results'

A resposta traz um item por recurso, com success e error:

[
  { "resource": "app:111222333444", "success": true },
  { "resource": "waba:9876543210",  "success": true },
  { "resource": "waba:1122334455",  "success": false, "error": "Meta API bad request: …" }
]

[
  { "resource": "app:111222333444", "success": true },
  { "resource": "waba:9876543210",  "success": true },
  { "resource": "waba:1122334455",  "success": false, "error": "Meta API bad request: …" }
]

Armadilhas.

• auto-configure só toca aplicativos com appSecret gravado. Um aplicativo sem segredo é silenciosamente ignorado — rode PATCH /apps/:id antes e confira o hasAppSecret.
• A operação é parcialmente tolerante a falha por desenho: uma WABA que falha não aborta as outras. Sempre leia o array results; um 200 não significa que tudo deu certo.
• Ela usa um conjunto fixo de campos: messages, message_template_status_update, message_template_quality_update e account_update. Se precisar de outros, use POST /webhooks/app com a lista explícita.
• O verifyToken é gerado aleatoriamente a cada chamada. Se o seu endpoint valida um token fixo, use as rotas específicas em vez desta.

Verificar um número novo

Objetivo. Levar um número recém-adicionado à WABA até o estado verificado, sem sair do terminal.

sequenceDiagram
  autonumber
  participant V as Você
  participant MA as meta-account
  participant M as Meta Graph API
  participant T as Telefone
  V->>MA: POST /phone-numbers/:id/request-verification com method SMS
  MA->>MA: resolve número → WABA → negócio e decifra o token
  MA->>M: POST no recurso request_code
  M->>T: envia o código por SMS ou chamada de voz
  MA-->>V: 200 com success true
  T-->>V: código de 4 a 10 caracteres
  V->>MA: POST /phone-numbers/:id/verify com o código
  MA->>M: POST no recurso verify_code
  M-->>MA: success
  MA-->>V: 200 com success true

Passo 1 — pedir o código.

curl -s -X POST \
  "http://localhost:3000/meta-account/api/v1/phone-numbers/$PHONE_UUID/request-verification" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"method":"SMS","language":"pt_BR"}'

curl -s -X POST \
  "http://localhost:3000/meta-account/api/v1/phone-numbers/$PHONE_UUID/request-verification" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"method":"SMS","language":"pt_BR"}'

{ "data": { "success": true } }

{ "data": { "success": true } }

Passo 2 — confirmar o código recebido.

curl -s -X POST "http://localhost:3000/meta-account/api/v1/phone-numbers/$PHONE_UUID/verify" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

curl -s -X POST "http://localhost:3000/meta-account/api/v1/phone-numbers/$PHONE_UUID/verify" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

{ "data": { "success": true } }

{ "data": { "success": true } }

Armadilhas. O $PHONE_UUID é o UUID interno, e o BB resolve sozinho a cadeia número → WABA → negócio para achar o token. O código aceita de 4 a 10 caracteres. Números de teste da Meta se comportam de forma diferente dos reais — valide o fluxo com um número de teste antes de mexer em produção.

Descobrir o que mudou na Meta sem você saber

Objetivo. Comparar o espelho local com a Meta e reconciliar o que estiver diferente.

flowchart LR
  D["GET /sync/drift<br/>compara 4 campos, só WABAs próprias"] --> Q{"Achou divergência?"}
  Q -->|"sim"| S["POST /sync<br/>reconcilia tudo"]
  Q -->|"não"| S2["Não prova que nada mudou<br/>rode o sync mesmo assim"]
  S --> R["created · updated · removed<br/>removed é exclusão lógica"]
  S3["POST /sync/:resourceType<br/>um tipo só"] --> R

Passo 1 — perguntar o que divergiu.

curl -s "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/sync/drift" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.summary, .data.drifts'

curl -s "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/sync/drift" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.summary, .data.drifts'

{ "total": 1, "phone_number": 1 }
[
  { "resourceType": "phone_number", "resourceId": "5544332211",
    "displayName": "+55 11 90000-0000", "field": "qualityRating",
    "localValue": "GREEN", "remoteValue": "YELLOW" }
]

{ "total": 1, "phone_number": 1 }
[
  { "resourceType": "phone_number", "resourceId": "5544332211",
    "displayName": "+55 11 90000-0000", "field": "qualityRating",
    "localValue": "GREEN", "remoteValue": "YELLOW" }
]

Passo 2 — reconciliar tudo.

curl -s -X POST "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/sync" \
  -H "Authorization: Bearer $TOKEN" | jq '.data | {created, updated, removed}'

curl -s -X POST "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/sync" \
  -H "Authorization: Bearer $TOKEN" | jq '.data | {created, updated, removed}'

{ "created": 0, "updated": 7, "removed": 1 }

{ "created": 0, "updated": 7, "removed": 1 }

Passo 3 — ou reconciliar só um tipo.

curl -s -X POST \
  "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/sync/phone_numbers" \
  -H "Authorization: Bearer $TOKEN" | jq '.data'

curl -s -X POST \
  "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/sync/phone_numbers" \
  -H "Authorization: Bearer $TOKEN" | jq '.data'

Armadilhas. drift não é exaustivo — cobre quatro campos e só WABAs próprias (§15). Um relatório vazio não prova que nada mudou. O removed do sync é exclusão lógica: o recurso sai das listagens mas a linha permanece para auditoria. E não há agendamento embutido: chame o sync por cron ou por um job seu.

Rotacionar o token da Meta sem downtime

Objetivo. Trocar a credencial da Meta guardada no BB sem que nenhuma chamada falhe no meio.

sequenceDiagram
  autonumber
  participant V as Você
  participant BM as Business Manager
  participant MA as meta-account
  participant M as Meta Graph API
  V->>BM: gera o token novo, com os mesmos escopos
  V->>MA: PATCH /businesses/:id com accessToken novo
  MA->>MA: cifra e sobrescreve na hora
  MA-->>V: hasAccessToken true
  V->>MA: POST /businesses/:id/token/check
  MA->>M: debugToken com o token novo
  M-->>MA: is_valid e escopos
  MA-->>V: status VALID
  V->>BM: só agora, revogar o token antigo

Passo 1 — gravar o token novo. Gere-o antes no Business Manager.

curl -s -X PATCH "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"accessToken":"NOVO_TOKEN"}' | jq '.data.hasAccessToken'

curl -s -X PATCH "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"accessToken":"NOVO_TOKEN"}' | jq '.data.hasAccessToken'

true

true

Passo 2 — validar antes de revogar o antigo.

curl -s -X POST "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/token/check" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.status'

curl -s -X POST "http://localhost:3000/meta-account/api/v1/businesses/$BUSINESS_ID/token/check" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.status'

"VALID"

"VALID"

Armadilhas. Gere e valide o token novo antes de revogar o antigo — o PATCH sobrescreve na hora, e um token errado só aparece na próxima chamada à Meta. Rode token/check logo em seguida. Se o wpp-business usa uma cópia do mesmo token, atualize-a também: os dois building blocks guardam credenciais independentes.

A relação com o wpp-business, em uma imagem

É a divisão que dá nome ao BB: um cuida da conta, o outro da conversa.

flowchart TD
  subgraph MA["meta-account — a conta é sua e está saudável"]
    MA1["descoberta · espelho · saúde do token<br/>webhooks · divergência"]
  end
  subgraph WB["wpp-business — a conversa acontece"]
    WB1["POST /wpp-business/api/v1/accounts<br/>wabaId, businessId, accessToken, name"]
    WB2["mensagens · templates · campanhas · flows · inbox · catálogo<br/>contatos · automações · pagamentos · analytics"]
    WB1 --> WB2
  end
  MA1 -->|"três valores lidos do espelho<br/>metaWabaId · metaBusinessId · accessToken"| WB1
  WB2 -->|"eventos de domínio"| WE["webhooks-engine<br/>entrega ao sistema cliente"]
  WB2 -->|"eventos de domínio"| AT["audit-trail<br/>quem mexeu no quê"]
  WB2 -->|"eventos de domínio"| CU["customers<br/>quem é a pessoa do outro lado"]

A passagem de bastão, passo a passo

sequenceDiagram
  autonumber
  participant I as IAM
  participant MA as meta-account
  participant OP as Painel ou script de provisionamento
  participant WB as wpp-business
  I-->>OP: JWT com organizationId e permissões
  OP->>MA: POST /discover
  OP->>MA: GET /businesses/:id/graph
  MA-->>OP: metaWabaId, metaBusinessId e o negócio espelhado
  Note over OP: o accessToken NÃO volta pela API<br/>quem provisiona já o tem em mãos
  OP->>WB: POST /accounts com wabaId, businessId, accessToken e name
  WB-->>OP: conta criada, pronta para números e mensagens
  Note over MA,WB: não há chamada de módulo entre os dois<br/>a ponte é operacional

Honestidade sobre o acoplamento

Hoje a passagem de bastão é operacional, não automática: não há código no wpp-business que importe o meta-account, nem chamada de módulo entre os dois. Quem faz a ponte é o painel ou o script de provisionamento, lendo os identificadores de um e escrevendo no outro. Isso é bom para desacoplamento e ruim para conveniência — os dois guardam cópias independentes do token, e rotacionar exige atualizar os dois. Uma etapa de handoff automática é candidata natural de roadmap.

O argumento comercial continua de pé, e é o mesmo da §5: em um BSP, essas duas camadas são a mesma caixa-preta, e é por isso que sair dela custa caro. Aqui elas são separadas de propósito, e a de baixo — a que determina a propriedade do ativo — fica na mão do cliente.

Variáveis de ambiente

A chave mestra é validada no schema de configuração como exatamente 64 caracteres hexadecimais, e getMasterKey() a relê de process.env a cada operação, rejeitando formato inválido. Sem ela, cifrar e decifrar lançam erro — o módulo carrega, mas nenhuma operação com credencial funciona.

Dependências de infraestrutura

Limites e quotas

Catálogo de erros

Antes da tabela, o caminho de triagem — ele resolve a maior parte dos chamados sem abrir o log:

flowchart TD
  E["Chamada falhou"] --> S{"Status HTTP"}
  S -->|"401"| A{"De quem é o token"}
  A -->|"JWT do IAM"| A1["Renove o token no IAM"]
  A -->|"token da Meta"| A2["Leia details.meta.code<br/>190 é família de expiração/revogação"]
  S -->|"403"| B["Falta permissão META_ACCOUNT_*<br/>ou o JWT não traz organizationId"]
  S -->|"404"| C["Você usou o ID da Meta<br/>onde o BB espera o UUID interno"]
  S -->|"400"| D{"O que o corpo diz"}
  D -->|"missingScopes"| D1["Gere token novo com os escopos"]
  D -->|"appSecret"| D2["PATCH /apps/:id antes de assinar webhook"]
  D -->|"resourceType"| D3["Use um dos 6 tipos aceitos"]
  S -->|"500"| F["Falha ao decifrar<br/>confira META_ACCOUNT_CREDENTIAL_MASTER_KEY"]
  S -->|"503"| G["Limite de taxa da Meta<br/>espere e repita"]

Erros da plataforma:

Erros da Meta, já traduzidos por translateMetaError, com o objeto original preservado em details.meta:

Observabilidade

• Eventos de domínio publicados: business.discovered, business.updated, business.deleted, token.healthChanged, sync.completed, webhook.configured, webhook.removed — todos com prefixo meta-account.. As constantes token.expiring, sync.started, sync.failed e sync.driftDetected estão declaradas mas não publicadas por nenhum código hoje (§15).
• MetaSyncLog é a trilha operacional: tipo, status, recursos encontrados e sincronizados, duração em milissegundos. GET /sync/history a expõe. É a primeira coisa a olhar quando alguém diz que "o espelho está errado".
• MetaTokenHealth.lastCheckedAt diz há quanto tempo a saúde não é reavaliada. Um valor antigo significa que ninguém está rodando token/check — o BB não verifica sozinho.
• rawMeta guarda a resposta original da Meta em cada recurso, e details.meta acompanha cada erro traduzido com fbtrace_id. Junto, é o que permite abrir chamado na Meta com evidência.
• GET /meta-account/health responde com o payload padrão de versão. É uma sonda de processo vivo, não verifica banco nem conectividade com a Meta — diferente do /health do IAM.

Isolamento entre tenants

O organizationId vem do claim assinado do JWT e nunca do corpo. Todas as 36 rotas aplicam o requireOrganization local, que devolve 403 quando o claim falta.

Abaixo disso, a garantia é repetida na camada de dados: todo método de repositório recebe organizationId e o inclui na cláusula where — findById(id, organizationId) filtra por { id, organizationId, deletedAt: null }. Não existe caminho de leitura que dispense o filtro.

flowchart TD
  JWT["JWT assinado pelo IAM<br/>claim organizationId"] --> MW["requireOrganization<br/>403 se o claim faltar"]
  MW --> RT["Rota"]
  RT --> SV["Service recebe organizationId"]
  SV --> RP["findById(id, organizationId)"]
  RP --> WH["where id, organizationId, deletedAt null"]
  WH --> PG[("PostgreSQL<br/>@@unique organizationId + metaXxxId")]
  BODY["Corpo da requisição"] -.->|"nunca é fonte de tenant"| SV

As chaves compostas @@unique([organizationId, metaXxxId]) reforçam a separação no schema: duas organizações podem referenciar o mesmo recurso da Meta sem colisão nem vazamento.

Segredos da Meta

O access token do negócio e o app secret são cifrados em AES-256-GCM com vetor de inicialização aleatório de 12 bytes e tag de autenticação, no formato iv:authTag:ciphertext. A chave é a META_ACCOUNT_CREDENTIAL_MASTER_KEY, de 32 bytes, exigida em hexadecimal e validada no formato. O GCM garante que um valor adulterado no banco falhe a decifragem em vez de produzir texto claro corrompido.

Segredo não sai na resposta

flowchart LR
  IN["POST /discover<br/>accessToken em texto claro"] --> ENC["encryptSecret<br/>AES-256-GCM"]
  ENC --> DB[("meta_businesses.accessToken<br/>iv:authTag:ciphertext")]
  DB --> DEC["decryptSecret<br/>só na hora de chamar a Meta"]
  DEC --> M["Meta Graph API"]
  DB --> SAFE["toSafeBusiness / toSafeApp"]
  SAFE --> OUT["Resposta HTTP<br/>hasAccessToken · hasAppSecret"]
  DEC -.->|"nunca vai para log"| LOG["Logs"]

toSafeBusiness e toSafeApp desestruturam e descartam os campos cifrados, devolvendo hasAccessToken e hasAppSecret booleanos. getResourceGraph faz o mesmo descarte antes de serializar o grafo. A decifragem acontece só no momento da chamada à Meta, em variável local, e o valor não é registrado em log.

Superfície do token da Meta

O token gravado costuma ser de system user com papel ADMIN — uma credencial ampla sobre o Business Manager do cliente. Duas consequências operacionais:

Validação antes de gravar

POST /discover introspecta o token e recusa a operação quando faltam escopos obrigatórios, antes de persistir qualquer coisa. Credencial insuficiente não entra no banco.

Exclusão lógica

Todos os modelos usam deletedAt, e todas as consultas filtram por deletedAt: null. O histórico sobrevive à remoção, o que atende retenção e auditoria.

Proteções de borda

applyCommonMiddleware aplica limite de corpo de 1 MB, CORS com política de falha segura, cabeçalhos de segurança e limite de taxa. Isso importa especialmente em standalone, que é o modo de produção: sem esse helper, o app do módulo subiria sem nenhuma dessas proteções.

LGPD

O BB armazena números de telefone de negócio (displayPhoneNumber, verifiedName) e, quando há catálogo, dados de produto. Números de atendimento empresarial não são, em geral, dado pessoal de titular — mas o campo rawMeta guarda a resposta bruta da Meta, e o conteúdo dela é definido pela Meta, não por nós. Antes de operação regulada, revise o que rawMeta está retendo e por quanto tempo. Não há expurgo automatizado — a exclusão é lógica (§15).

Enquadramento com a Meta

Operar com a WABA no Business Manager do cliente mantém a relação de faturamento entre o cliente e a Meta, e mantém a responsabilidade pelas políticas de mensageria com quem é dono da conta. É a configuração mais simples de defender numa auditoria, além de ser a que preserva a portabilidade discutida na §5.

Maturidade

Funcionalidade no schema, ausente no código

Capacidade sem rota HTTP

Cobertura funcional

A Catalisa vira dona da minha conta de WhatsApp?

Não, e o código não permite. A entrada obrigatória do POST /discover é o identificador do seu Business Manager mais um token que você gera dentro dele. Não existe chamada no BB que crie Business Manager ou WABA em nome da Catalisa, e não estendemos linha de crédito da Meta — o que significa que a Meta fatura você diretamente. Se decidir encerrar a relação, revogue o token no painel da Meta: a conta, o número, os templates e o histórico de qualidade continuam onde sempre estiveram.

Por que isso importa tanto? É só formalidade?

Não é. A Meta documenta que a migração de WABA entre parceiros é iniciada pelo provedor atual, que precisa marcar a conta e desabilitar a verificação em duas etapas do número (Migrating a WABA between Multi-Partner Solutions). Quem detém a conta detém um veto operacional sobre a sua saída, e esse poder aparece na mesa na hora de renovar contrato. Com a conta no seu nome, a troca de fornecedor não passa por autorização de ninguém.

Então o meta-account substitui meu BSP?

Não completamente, e é importante ser claro. Ele não envia mensagem — quem faz isso é o wpp-business — e não oferece linha de crédito da Meta. Se você precisa que alguém banque o consumo da Meta por você, o modelo BSP resolve isso e nós não. O que ele substitui é a dependência do painel de terceiro para saber e mudar o estado da sua própria conta Meta.

Qual a diferença entre o meta-account e o wpp-business?

Um cuida da conta, o outro da conversa. O meta-account descobre e vigia os ativos Meta: WABAs, números, templates, apps, system users, catálogos, webhooks e a saúde do token. O wpp-business usa esses ativos para enviar mensagem, rodar campanha, atender no inbox e processar pedido. Na prática, o meta-account produz os três valores — wabaId, businessId e accessToken — que o wpp-business consome ao criar uma conta. Hoje essa passagem é manual: não há chamada automática entre os dois (§12).

Preciso mesmo criar um system user? Não posso usar o token do painel?

Pode, e vai funcionar por cerca de 60 dias. Depois ele expira e você recebe erro 190 subcódigo 463 — normalmente fora do horário comercial. O token de system user pode ser configurado para não expirar, e é o que o POST /system-users/:id/generate-token gera. Vale os dez minutos de configuração.

Por que GET /wabas/:id devolve 404 com o ID que vejo no painel da Meta?

Porque as rotas usam o UUID interno da linha no banco, não o identificador numérico da Meta. É a confusão mais comum deste BB. Liste os recursos por GET /businesses/:id/graph e use o campo id de cada um; o identificador da Meta aparece ao lado, em metaWabaId, metaPhoneNumberId e assim por diante. Os campos metaAppId e metaWabaId dos corpos de webhook também são UUIDs internos, apesar do nome.

O relatório de divergência voltou vazio. Posso confiar que nada mudou?

Não. Ele compara quatro campos e percorre apenas as WABAs próprias — não detecta recurso criado ou removido, nem mudança em template, app ou catálogo (§15). Para uma reconciliação de verdade, rode POST /businesses/:id/sync e compare os contadores de created, updated e removed.

Quantas mensagens meu número pode disparar por dia?

O BB não responde isso hoje: a coluna messagingLimitTier existe no schema e nunca é preenchida (§15). Consulte o painel da Meta. Vale saber que a regra mudou em 7 de outubro de 2025: os limites passaram a ser calculados por business portfolio, e não mais por número, e os degraus atuais são 250, 2.000, 10.000, 100.000 e ilimitado — o antigo degrau de 1.000 deixou de existir (Upcoming changes to messaging limits).

Excluí uma configuração de webhook e os eventos continuam chegando. É bug?

É comportamento atual, e está documentado na §15. O DELETE /webhooks/:id faz exclusão lógica do nosso registro — ele não cancela a assinatura na Meta. Os métodos para isso existem no cliente HTTP mas não estão expostos em rota. Enquanto isso, cancele pelo painel da Meta e confirme com GET /businesses/:id/webhooks/status.

Quanto custa?

A precificação do building block está em definição, e este documento não estima valor (§6). O custo de mensagem é outra conta e não é nossa: ele vai direto da Meta para você, porque a conta é sua. Desde 1º de julho de 2025 a Meta cobra por mensagem entregue, não mais por conversa, e mensagens de service são gratuitas desde novembro de 2024. Baixe o rate card vigente na documentação da Meta antes de montar qualquer projeção — as tarifas por país mudam trimestralmente em 2026.

_{Padrão: PADRAO-DOCUMENTACAO.md · Aprofundamento técnico e roadmap: docs/analysis.md}