API de Páginas do Lead Ads — Páginas do Facebook e Formulários Instantâneos

​

Endpoints

​

Antes de vincular: compartilhamento e posse

1. compartilha a Página com o portfólio empresarial da Pilot Status — o partnerBusinessId que GET /v1/lead-pages devolve — no Meta Business Manager;
2. dá ao usuário do sistema da Pilot Status as tarefas da Página de que ele precisa. candidates[].missingTasks lista o que ainda falta: MODERATE, MANAGE_LEADS, ou PAGE_ACCESS quando a Página nem foi atribuída ao usuário do sistema. Lista vazia significa pronta; null significa que não foi possível consultar a Meta.

​

Credenciais e permissões

• Tokens OAuth/MCP precisam de integrations:manage (ADMIN ou OWNER do workspace) em todos os endpoints, leituras incluídas — ANALYST e AGENT são recusados com 403 PERMISSION_DENIED. Uma chave ps_ clássica não tem papel e passa pelo escopo.
• Escopo: uma chave com escopo de número, ou uma credencial da conta inteira com o header x-whatsapp-number-id, vê e altera só os vínculos daquele número. Uma credencial da conta inteira sem o header vê o workspace todo e indica o número no corpo. Um vínculo num número fora do escopo da credencial responde 403 NUMBER_NOT_IN_GRANT.

​

GET /v1/lead-pages

{
  "linked": [
    {
      "pageLinkId": "cmgpl0001ab12cd34ef56",
      "pageId": "102345678901234",
      "pageName": "MM Design",
      "whatsappNumberId": "num_01HZX...",
      "subscribedAt": "2026-10-06T10:15:00.000Z",
      "subscriptionError": null,
      "linkedAt": "2026-10-06T10:14:58.000Z",
      "leadsCount": 42
    }
  ],
  "candidates": [
    { "pageId": "109876543210987", "pageName": "MM Design Outlet", "missingTasks": ["MANAGE_LEADS"] }
  ],
  "configured": true,
  "partnerBusinessId": "123456789012345",
  "candidatesLookup": "ok",
  "eligibilityBlocker": null
}

​

POST /v1/lead-pages

curl -X POST https://pilotstatus.com.br/v1/lead-pages \
  -H "x-api-key: ps_..." \
  -H "Content-Type: application/json" \
  -d '{ "pageId": "109876543210987", "whatsappNumberId": "num_01HZX..." }'

• pageId é o id numérico da Página do Facebook. whatsappNumberId só pode ficar de fora quando a credencial está vinculada a um número. Qualquer outro campo é recusado com 400 UNKNOWN_FIELDS.
• A posse e as tarefas da Página são conferidas antes de gravar qualquer coisa: 409 PAGE_NOT_ELIGIBLE (com reason quando conhecido; sem ele quando outro workspace já vinculou a Página), 409 PAGE_MISSING_PERMISSION (com missingTasks), 409 PAGE_ALREADY_LINKED (com o pageLinkId existente).
• Com sucesso (201 { "link": { … } }), a Pilot Status se inscreve nos leads da Página e começa a buscar os leads dos últimos 90 dias em segundo plano. Se a Meta recusar a inscrição, o vínculo é criado mesmo assim e subscriptionError diz o motivo.

​

PATCH /v1/lead-pages/{pageLinkId}

​

DELETE /v1/lead-pages/{pageLinkId}

​

POST /v1/lead-pages/{pageLinkId}/resync

{ "started": true, "pageLinkId": "cmgpl0001ab12cd34ef56", "subscribedAt": "2026-10-21T10:02:44.000Z", "subscriptionError": null }

• Uma ressincronização por vínculo a cada 10 minutos. Dentro dessa janela a resposta é 429 RESYNC_COOLDOWN com retryAfterSeconds. Se não for possível conferir a espera, a resposta é 503 RESYNC_UNAVAILABLE, nunca uma ressincronização sem limite.
• A posse é conferida de novo. Uma Página que deixou de ser elegível é marcada no vínculo (subscriptionError) e responde 409 PAGE_NOT_ELIGIBLE com reason.

​

GET /v1/lead-pages/{pageLinkId}/forms

• consentAvailable: false — as caixas do formulário não puderam ser lidas. A lista é desconhecida, não vazia.
• formsTruncated: true — a Página tem mais formulários do que a Pilot Status leu.

​

PUT /v1/lead-pages/{pageLinkId}/forms/{formId}

{
  "consentDisclaimerKey": "whatsapp_optin",
  "autoSendEnabled": true,
  "templateId": null,
  "freeText": "Olá {{nome}}, recebemos seu pedido de orçamento!",
  "variableMap": { "nome": { "source": "field", "key": "full_name" } },
  "formName": "Orçamento — Outubro"
}

​

Erros