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
Meta	`verified_name`	Meta	Nome oficial aprovado/exibido

Slot comercial x instância operacional

Slot comercial

Conta clientes finais ativos. Um cliente com vários números continua consumindo um único slot.

used_slots = clientes ativos distintos

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

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