Fundamentos

Conceitos e identificadores

Os erros mais comuns acontecem quando IDs diferentes são tratados como se fossem iguais.

Mapa de entidades

Entidade	Identificador	Quem define	Uso
Partner	`partner_id`	HookCloud	Empresa/SaaS que integra a plataforma
Cliente final	`external_customer_id`	Seu SaaS	ID estável do assinante dentro do seu sistema
Cliente final	`partner_customer_id`	HookCloud	UUID interno retornado pela HookCloud
Instância	`instance_id`	HookCloud	UUID técnico da conexão
Instância	`instance_key`	Seu SaaS	Chave legível e única por linha
Meta	`meta_business_id`	Meta	Business Portfolio
Meta	`meta_waba_id`	Meta	WhatsApp Business Account
Meta	`meta_phone_number_id`	Meta	Número usado nos endpoints Graph
Pessoa no WhatsApp	`user_id / from_user_id`	Meta	BSUID da pessoa no portfólio; enviar como recipient
Identidade entre portfólios inscritos	`parent_user_id`	Meta, se habilitado	Parent BSUID opcional, não presumir disponível
Nome de usuário	`username`	Usuário / Meta	Apresentação; não substitui BSUID
Meta	`verified_name`	Meta	Nome oficial aprovado/exibido

Capacidade contratada e instância operacional

Slot comercial

Conta números conectados ou com reserva ativa. Um cliente com cinco números consome cinco vagas; cadastrar o cliente não consome uma vaga.

used_numbers = números com ocupação/reserva ativa

Instância operacional

Representa um número oficial, seu callback, token, status e lifecycle.

1 instância = 1 phone_number_id

Nome oficial x nome interno

verified_name é atualizado a partir da Meta e deve ser exibido como nome oficial. instance_name é apenas um apelido interno para organização no seu SaaS.

Campo	Pode editar?	Fonte
`verified_name`	Não diretamente	Meta / Phone Number
`instance_name`	Sim	Seu SaaS / HookCloud
`effective_business_name`	Calculado	verified_name com fallback

Callback por número

A HookCloud aplica o endpoint do partner no número conectado. Assim, mensagens e status operacionais chegam diretamente ao sistema do partner, enquanto a HookCloud mantém controles de lifecycle.

Meta→phone_number_id→Webhook do partner

Referências: WABA subscriptions · Override de callback

Estados principais

Campo	Valores comuns	Significado
`status`	pending, connected, paused, canceled, error	Estado da conexão
`remote_callback_status`	active, updating, removed, remove_failed	Estado real do callback na Meta
`slot_state`	counting, released	Estado operacional da linha
`stripe_status`	trialing, active, past_due, unpaid, canceled	Estado financeiro
`billing_access_state`	enabled, restricted, suspended	Permissão comercial

Lifecycle do cliente e da instância

Estado do cliente	Nova instância	Reconnect	Como voltar
active	Permitida	Permitido	—
inactive/canceled/archived	Bloqueada	Bloqueado	`reactivate-partner-customer`
merged	Bloqueada	Bloqueado	Use o cliente de destino
PII erased	Bloqueada	Bloqueado	Crie novo cadastro conforme sua política

Esta página ajudou?Use o Partner Portal para suporte e compartilhe o link desta seção.