Partner API Reference
Endpoints públicos para integrar o backend do partner. Todas as chamadas usam a mesma base; a operação é selecionada por route.
Arquivos para importação
Monte uma chamada
Escolha uma rota e gere um cURL com placeholders.
Criar ou atualizar cliente
Cria o cliente final ou atualiza dados usando um ID externo estável.
Request
{
"route": "upsert-partner-customer",
"external_customer_id": "cliente_56790",
"customer_name": "Clínica Mais Vida",
"customer_email": "contato@maisvida.com",
"customer_phone": "5511999999999",
"metadata": { "plano": "pro", "origem": "saas" }
}Resposta resumida
{
"ok": true,
"customer_id": "UUID_DO_CLIENTE",
"external_customer_id": "cliente_56790",
"status": "active"
}Idempotência funcional: reutilize o mesmo external_customer_id para atualizar o mesmo cliente.
Criar instância
Cria a linha do cliente e pode gerar a sessão de conexão no mesmo request.
Request
{
"route": "create-customer-instance",
"external_customer_id": "cliente_56790",
"instance_key": "cliente_56790-whatsapp-principal",
"instance_name": "Atendimento principal",
"create_connect_session": true,
"return_url": "https://app.seusistema.com/integracoes/whatsapp",
"cancel_url": "https://app.seusistema.com/integracoes/whatsapp",
"success_url": "https://partner-connect.hookcloud.app/connect/success",
"error_url": "https://partner-connect.hookcloud.app/connect/error"
}Resposta resumida
{
"ok": true,
"instance_id": "UUID_DA_INSTANCIA",
"connect_session_id": "UUID_DA_SESSAO",
"connect_url": "https://partner-connect.hookcloud.app/connect?token=..."
}instance_name é opcional e interno; o nome oficial vem em verified_name.
Gerar connect ou reconnect
Gera uma sessão curta para conectar ou reconectar uma instância existente.
Request
{
"route": "create-connect-session",
"instance_id": "UUID_DA_INSTANCIA",
"mode": "reconnect",
"return_url": "https://app.seusistema.com/integracoes/whatsapp",
"cancel_url": "https://app.seusistema.com/integracoes/whatsapp",
"success_url": "https://partner-connect.hookcloud.app/connect/success",
"error_url": "https://partner-connect.hookcloud.app/connect/error"
}mode pode ser connect ou reconnect. Abra connect_url no navegador do cliente final.
Consultar instância
Retorna status, número, nome verificado, IDs Meta, callback e links úteis.
Query parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
instance_id | UUID | ID retornado ao criar a instância |
instance_key | string | Chave legível da linha |
phone_number_id | string | ID do número na Meta |
Resposta resumida
{
"ok": true,
"instance_id": "UUID_DA_INSTANCIA",
"instance_key": "cliente_56790-whatsapp-principal",
"status": "connected",
"verified_name": "Clínica Mais Vida",
"display_phone_number": "+55 11 99999-9999",
"quality_rating": "GREEN",
"meta_business_id": "BUSINESS_ID",
"waba_id": "WABA_ID",
"phone_number_id": "PHONE_NUMBER_ID",
"remote_callback_status": "active",
"whatsapp_manager_url": "https://business.facebook.com/wa/manage/phone-numbers/..."
}Envie apenas um identificador. A forma oficial é ?route=get-partner-instance&instance_id=....
Atualizar dados oficiais da Meta
Atualiza nome verificado, número, qualidade e status do nome.
Request
{
"route": "refresh-partner-instance-meta",
"instance_id": "UUID_DA_INSTANCIA"
}Atualizar nome interno
Altera somente o apelido interno da instância.
Request
{
"route": "update-partner-instance-label",
"instance_id": "UUID_DA_INSTANCIA",
"instance_name": "Atendimento unidade centro"
}Obter credencial de envio Meta
Retorna o token Meta e a URL de envio da instância para uso exclusivo no backend.
Request
{
"route": "reveal-partner-instance-meta-token",
"phone_number_id": "PHONE_NUMBER_ID"
}Resposta resumida
{
"ok": true,
"meta_access_token": "EAAB...",
"graph_version": "v25.0",
"phone_number_id": "PHONE_NUMBER_ID",
"send_message_url": "https://graph.facebook.com/v25.0/PHONE_NUMBER_ID/messages"
}Nunca exponha esse token no frontend ou ao cliente final.
Inativar instância
Remove o callback remoto antes de liberar a linha e o slot operacional.
Request
{
"route": "deactivate-partner-instance",
"instance_id": "UUID_DA_INSTANCIA",
"reason": "Cliente cancelou esta linha"
}Se a remoção remota falhar, a API não finge sucesso. Trate conflitos e tente novamente após corrigir a credencial.
Inativar cliente
Inativa o cliente final e trata todas as instâncias vinculadas.
Request
{
"route": "deactivate-partner-customer",
"external_customer_id": "cliente_56790",
"reason": "Cliente cancelou a assinatura"
}Reativar cliente
Reativa o cadastro comercial. Gere reconnect quando os números precisarem de nova autorização.
Request
{
"route": "reactivate-partner-customer",
"external_customer_id": "cliente_56790",
"reason": "Cliente voltou para o SaaS"
}Validar webhook
Testa HTTPS e o desafio da Meta sem alterar as instâncias.
Request
{
"route": "validate-partner-webhook-endpoint",
"webhook_url": "https://api.seusistema.com/webhooks/whatsapp"
}O endpoint deve responder ao GET da Meta devolvendo o hub.challenge exato.
Alterar webhook do partner
Troca o endpoint único e inicia a migração dos números ativos na Meta.
Request
{
"route": "update-partner-webhook-endpoint",
"webhook_url": "https://api.seusistema.com/webhooks/whatsapp",
"reason": "Migração do domínio de produção"
}Resposta resumida
{
"ok": true,
"migration_id": "UUID_DA_MIGRACAO",
"status": "pending",
"total_instances": 12
}Consultar migração de webhook
Acompanha quantas instâncias foram atualizadas, falharam ou aguardam.
Query parameters
| Parâmetro | Descrição |
|---|---|
migration_id | UUID opcional; sem ele retorna a migração mais recente |
Reprocessar falhas do webhook
Tenta novamente apenas as instâncias que falharam.
Request
{
"route": "retry-partner-webhook-migration",
"migration_id": "UUID_DA_MIGRACAO"
}Listar templates
Consulta o catálogo HookCloud em cache, sem consumir GET da Graph API.
Query parameters
| Parâmetro | Descrição |
|---|---|
instance_id / waba_id | Escopo do catálogo |
status | Ex.: APPROVED |
sendable_only | true para templates disponíveis |
search | Nome ou ID |
page/page_size | Paginação; máximo 200 |
Resposta resumida
{
"ok": true,
"source": "hookcloud_cache",
"items": [
{
"template_id": "123456789",
"template_name": "confirmacao_agendamento",
"template_language": "pt_BR",
"template_status": "APPROVED",
"quality_status": "GREEN",
"category": "UTILITY",
"sendable": true,
"components": [],
"parameter_schema": { "total_parameters": 2, "parameters": [] }
}
]
}Consultar template
Retorna componentes, parâmetros, status, qualidade, categoria e sendable.
Query parameters
| Parâmetro | Descrição |
|---|---|
template_id | ID oficial |
template_name + language | Alternativa por nome/idioma |
instance_id ou waba_id | Escopo |
Atualizar catálogo
Enfileira uma reconciliação controlada com a Graph API.
Request
{
"route": "refresh-partner-meta-templates",
"instance_id": "UUID_DA_INSTANCIA"
}Resposta resumida
{
"ok": true,
"accepted": true,
"sync_job_id": "UUID_DO_JOB",
"sync_status": "pending",
"next_allowed_at": "2026-07-21T12:05:00Z"
}Não chame em cada carregamento. A listagem normal já usa cache e webhooks de mudança.
Consultar sincronização de templates
Retorna queued, processing, completed ou failed.
Query parameters
| Parâmetro | Descrição |
|---|---|
instance_id / waba_id | Escopo da sincronização |
Reportar status de mensagem
Permite consolidar sent, delivered, read, failed e deleted na Saúde de Entregas.
Request
{
"route": "report-partner-message-status",
"phone_number_id": "PHONE_NUMBER_ID",
"message_id": "wamid.xxxxx",
"status": "delivered",
"template_name": "confirmacao_agendamento",
"campaign_id": "campanha_456",
"occurred_at": "2026-07-21T12:00:00Z"
}Reportar falha de entrega
Registra falhas normalizadas, inclusive sem waMID usando client_message_id.
Request
{
"route": "report-partner-message-delivery-failure",
"phone_number_id": "PHONE_NUMBER_ID",
"message_id": "wamid.xxxxx",
"client_message_id": "msg_local_123",
"template_name": "campanha_marketing",
"campaign_id": "campanha_456",
"error_code": 131049,
"error_title": "This message was not delivered to maintain a healthy ecosystem engagement",
"error_message": "Detalhe retornado pela Meta",
"recipient_hash": "HMAC_SHA256_HEX_COM_64_CARACTERES",
"occurred_at": "2026-07-21T12:00:00Z"
}Não envie conteúdo, nome ou telefone em texto puro. Use recipient_hash.
Consultar saúde de entregas
Retorna taxa de falha, 131049, 131042, top erros, templates e alertas.
Query parameters
| Parâmetro | Descrição |
|---|---|
window_hours | Janela de análise, ex.: 24 |
Pesquisar eventos de entrega
Busca paginada por status, erro, template, campanha, cliente ou instância.
Query parameters
| Filtro | Exemplo |
|---|---|
status | failed |
error_code | 131049 |
template_name | campanha_marketing |
campaign_id | campanha_456 |
date_from/date_to | ISO 8601 |
page/page_size | 1 / 50 |