Referência

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.

Antes dos endpoints

Como ler esta referência

GET

Use ?route=NOME_DA_ROTA e envie os demais valores na query string. Não envie body.

POST / PATCH

Envie route no JSON ou na query. Use Content-Type: application/json.

Autenticação

Rotas de integração usam Partner API Key. Rotas de preferências/notificações usam o JWT do membro logado no Portal.

Convenção	Regra
Datas	ISO 8601 em UTC, por exemplo `2026-07-24T12:00:00Z`.
Telefones	Prefira E.164 sem espaços: `5511999999999`. O campo cadastral aceita formatação, mas a Graph API espera formato internacional.
Booleanos	Use JSON `true`/`false` ou query `true`/`false`.
IDs	`instance_id` e `customer_id` são UUIDs HookCloud. `external_customer_id` e `instance_key` são strings estáveis do seu SaaS.
Idempotência	Em merge, movimentação e edições críticas, envie `Idempotency-Key` único por operação.
Resposta de erro	`{"error":{"code":"...","message":"...","details":...}}`. Use o HTTP status e `error.code` na lógica do seu backend.

SDKs e coleções

Arquivos para importação

OpenAPI 3.1 ↓Postman Collection ↓Workflow n8n ↓

Gerador

Monte uma chamada

Escolha uma rota e gere um cURL com placeholders.

RotaPartner API Key

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Criar ou atualizar cliente

Cria o cliente final ou atualiza dados usando um ID externo estável.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	upsert-partner-customer	Seleciona a operação.	`upsert-partner-customer`
`external_customer_id`	body	string (1–200)	sim	imutável e único dentro do partner	ID estável do cliente no seu SaaS. Reutilizar o mesmo valor atualiza o mesmo cadastro.	`cliente_56790`
`customer_name`	body	string (2–200)	sim	texto livre	Nome interno usado pelo partner. Não altera o nome verificado pela Meta.	`Clínica Mais Vida`
`customer_email`	body	string/e-mail	não	null ou e-mail válido	Contato cadastral. Pode ser omitido ou enviado como null.	`contato@maisvida.com`
`customer_phone`	body	string (6–40)	não	E.164 recomendado	Contato cadastral; não é o número WhatsApp da instância.	`5511999999999`
`metadata`	body	object JSON	não	{}	Dados próprios do seu SaaS. Não envie segredos ou dados de cartão.	`{"plano":"pro"}`

Erros mais comuns

error.code	HTTP	Quando ocorre
`missing_customer_fields`	400	external_customer_id/customer_name ausentes
`billing_access_restricted`	402/409	novo cliente bloqueado por billing
`customer_upsert_failed`	500	falha de banco

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.

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=list-partner-customers#

Listar clientes

Consulta paginada por nome, e-mail, telefone, External ID e status.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	list-partner-customers	Seleciona a consulta.	`list-partner-customers`
`page`	query	integer	não	padrão 1; mínimo 1	Página atual.	`1`
`page_size`	query	integer	não	padrão 50; 1–200	Quantidade máxima por página.	`50`
`search`	query	string	não	busca parcial	Pesquisa nome, e-mail, telefone e external_customer_id.	`clinica`
`status`	query	string	não	active, inactive, canceled, merged	Filtro exato do status local. Sem o parâmetro, retorna todos os status permitidos.	`active`
`include_merged`	query	boolean	não	false	Inclui cadastros de origem já mesclados.	`true`
`include_erased`	query	boolean	não	false	Inclui registros cujo PII foi eliminado administrativamente.	`false`

Query

page, page_size, search, status, include_merged, include_erased.

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-customer#

Consultar cliente

Use customer_id ou external_customer_id. Retorna instâncias e histórico recente.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	get-partner-customer	Seleciona a consulta.	`get-partner-customer`
`customer_id`	query	UUID	condicional	exatamente um identificador	UUID interno retornado pela HookCloud.	`9b9e...`
`external_customer_id`	query	string	condicional	exatamente um identificador	Alternativa usando o ID estável do seu SaaS.	`cliente_56790`

PATCHhttps://api.hookcloud.app/functions/v1/swift-worker?route=update-partner-customer#

Editar cliente

Altera somente nome, e-mail e telefone.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query ou body	string	sim	update-partner-customer	Seleciona a operação.	`update-partner-customer`
`customer_id`	body	UUID	sim	UUID HookCloud	Cliente a editar.	`UUID_DO_CLIENTE`
`changes.customer_name`	body	string (2–200)	não	texto livre	Novo nome interno.	`Clínica Mais Vida`
`changes.customer_email`	body	string/null	não	e-mail válido ou null	Novo e-mail cadastral.	`contato@maisvida.com`
`changes.customer_phone`	body	string/null	não	6–40 caracteres	Novo telefone cadastral.	`5511999999999`
`expected_updated_at`	body	ISO 8601	recomendado	timestamp da última leitura	Controle de concorrência. Se o cadastro mudou depois desse horário, a API retorna 409.	`2026-07-23T12:00:00Z`
`reason`	body	string até 500	não	texto auditável	Motivo exibido no histórico.	`Correção cadastral`
`Idempotency-Key`	header	string 8–200	não	UUID recomendado	Evita repetir a mesma edição após timeout.	`550e8400-e29b-41d4-a716-446655440000`

Erros mais comuns

error.code	HTTP	Quando ocorre
`immutable_customer_fields`	400	tentativa de alterar identificador/status
`invalid_customer_email`	400	e-mail inválido
`customer_changed_since_last_read`	409	expected_updated_at antigo
`idempotency_key_reused`	409	mesma chave com payload diferente

{
  "customer_id": "UUID_DO_CLIENTE",
  "changes": {
    "customer_name": "Clínica Mais Vida",
    "customer_email": "contato@maisvida.com",
    "customer_phone": "5511999999999"
  },
  "expected_updated_at": "2026-07-23T12:00:00Z",
  "reason": "Correção cadastral"
}

Imutáveis: external_customer_id e instance_key.

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-customer-history#

Histórico do cliente

Retorna alterações, merge e movimentações com paginação.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	get-partner-customer-history	Seleciona a consulta.	`get-partner-customer-history`
`customer_id / external_customer_id`	query	UUID/string	sim	um dos dois	Identifica o cliente.	`UUID_DO_CLIENTE`
`page`	query	integer	não	padrão 1	Página.	`1`
`page_size`	query	integer	não	padrão 50; máximo 200	Itens por página.	`50`

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Mesclar clientes

Move instâncias para o cadastro principal sem desconectar os números.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	merge-partner-customers	Seleciona a operação.	`merge-partner-customers`
`source_customer_id`	body	UUID	sim	cliente duplicado	Cadastro que será arquivado/mesclado.	`UUID_DUPLICADO`
`target_customer_id`	body	UUID	sim	cliente principal	Cadastro que permanecerá ativo e receberá as instâncias.	`UUID_PRINCIPAL`
`reason`	body	string até 500	não	auditável	Motivo da mesclagem.	`Cadastro duplicado`
`Idempotency-Key`	header	string	recomendado	UUID único	Evita aplicar o merge duas vezes.	`UUID_UNICO`

{
  "route": "merge-partner-customers",
  "source_customer_id": "UUID_DUPLICADO",
  "target_customer_id": "UUID_PRINCIPAL",
  "reason": "Cadastro duplicado"
}

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Mover instância para outro cliente

Altera somente o vínculo interno. Instance Key, Meta token e callback não mudam.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	move-partner-instance-to-customer	Seleciona a operação.	`move-partner-instance-to-customer`
`instance_id`	body	UUID	sim	instância existente	Número/instância a mover.	`UUID_DA_INSTANCIA`
`target_customer_id`	body	UUID	sim	cliente ativo do mesmo partner	Novo vínculo interno.	`UUID_CLIENTE_DESTINO`
`reason`	body	string até 500	não	auditável	Motivo da correção.	`Número conectado no cliente errado`
`Idempotency-Key`	header	string	recomendado	UUID único	Evita repetição após timeout.	`UUID_UNICO`

{
  "route": "move-partner-instance-to-customer",
  "instance_id": "UUID_DA_INSTANCIA",
  "target_customer_id": "UUID_DO_CLIENTE",
  "reason": "Vínculo incorreto"
}

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Criar instância

Cria a linha do cliente e pode gerar a sessão de conexão no mesmo request.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	create-customer-instance	Seleciona a operação.	`create-customer-instance`
`partner_customer_id`	body	UUID	condicional	ou external_customer_id	UUID do cliente.	`UUID_DO_CLIENTE`
`external_customer_id`	body	string	condicional	ou partner_customer_id	Alternativa para localizar o cliente.	`cliente_56790`
`instance_key`	body	string	sim	único por partner; imutável	Chave estável da linha no seu sistema. Use letras, números, hífen/underscore.	`cliente_56790-whatsapp-principal`
`instance_name`	body	string	não	gerado automaticamente	Apelido interno; o nome oficial vem da Meta.	`WhatsApp principal`
`create_connect_session`	body	boolean	não	true	Se true, já retorna connect_url.	`true`
`return_url`	body	HTTPS URL	não	URL padrão do partner	Destino ao fechar o Connect Flow.	`https://app.seusistema.com/integracoes`
`cancel_url`	body	HTTPS URL	não	fallback do return_url	Destino se o usuário cancelar.	`https://app.seusistema.com/integracoes`
`success_url / error_url`	body	HTTPS URL	não	telas internas HookCloud	Normalmente deixe a HookCloud usar os padrões do Connect Flow.	`https://partner-connect.hookcloud.app/connect/success`
`metadata`	body	object	não	{}	Metadados próprios sem segredos.	`{"canal":"suporte"}`

Erros mais comuns

error.code	HTTP	Quando ocorre
`customer_not_found`	404	cliente não existe
`customer_inactive`	409	reative o cliente primeiro
`meta_risk_customer_blocked`	409	política de risco bloqueou conexão
`billing_access_restricted`	402/409	assinatura não permite expansão

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.

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Gerar connect ou reconnect

Gera uma sessão curta para conectar ou reconectar uma instância existente.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	create-connect-session	Seleciona a operação.	`create-connect-session`
`instance_id / instance_key`	body	UUID/string	sim	um dos dois	Identifica a instância.	`UUID_DA_INSTANCIA`
`mode`	body	enum	não	connect \| reconnect; padrão connect	Use reconnect quando a instância já teve uma conexão Meta.	`reconnect`
`return_url`	body	HTTPS URL	não	URL padrão do partner	Destino ao concluir/fechar.	`https://app.seusistema.com/integracoes`
`ttl_hours`	body	number	não	limite definido pelo backend	Tempo de validade da sessão.	`2`
`registration_override`	body	boolean	somente admin HookCloud	false	Ignora a guarda local de erro Meta 133016 após validação manual.	`true`

Erros mais comuns

error.code	HTTP	Quando ocorre
`missing_identifier`	400	sem instance_id/instance_key
`partner_customer_inactive`	409	cliente inativo; reative antes
`meta_registration_rate_limited`	429	Meta 133016/cooldown
`instance_not_found`	404	instância inexistente

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.

Embedded Signup oficial

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-instance#

Consultar instância

Retorna status, número, nome verificado, IDs Meta, callback e links úteis.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	get-partner-instance	Seleciona a consulta.	`get-partner-instance`
`instance_id`	query	UUID	condicional	exatamente um identificador	UUID interno. Não use external_customer_id.	`UUID_DA_INSTANCIA`
`instance_key`	query	string	condicional	exatamente um identificador	Chave estável criada pelo partner.	`cliente_56790-whatsapp1`
`phone_number_id`	query	string numérica	condicional	exatamente um identificador	ID técnico da Meta recebido no webhook messages.	`1093754977160703`

Erros mais comuns

error.code	HTTP	Quando ocorre
`invalid_instance_id`	400	instance_id não é UUID
`multiple_identifiers`	400	mais de um identificador
`instance_not_found`	404	não encontrado

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=....

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Atualizar dados oficiais da Meta

Atualiza nome verificado, número, qualidade e status do nome.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	refresh-partner-instance-meta	Seleciona a operação.	`refresh-partner-instance-meta`
`instance_id / instance_key / phone_number_id`	body	UUID/string	sim	um identificador	Instância a consultar na Graph API.	`UUID_DA_INSTANCIA`

Request

{
  "route": "refresh-partner-instance-meta",
  "instance_id": "UUID_DA_INSTANCIA"
}

Phone Numbers oficial

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Atualizar nome interno

Altera somente o apelido interno da instância.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	update-partner-instance-label	Seleciona a operação.	`update-partner-instance-label`
`instance_id`	body	UUID	sim	instância do partner	Instância.	`UUID_DA_INSTANCIA`
`instance_name`	body	string	sim	apelido interno	Não altera verified_name na Meta.	`Atendimento comercial`

Request

{
  "route": "update-partner-instance-label",
  "instance_id": "UUID_DA_INSTANCIA",
  "instance_name": "Atendimento unidade centro"
}

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Obter credencial de envio Meta

Retorna o token Meta e a URL de envio da instância para uso exclusivo no backend.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	reveal-partner-instance-meta-token	Seleciona a operação.	`reveal-partner-instance-meta-token`
`instance_id / instance_key / phone_number_id`	body	UUID/string	sim	um identificador	Instância cuja credencial será revelada.	`UUID_DA_INSTANCIA`

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.

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Inativar instância

Remove o callback remoto antes de liberar a linha e o slot operacional.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	deactivate-partner-instance	Seleciona a operação.	`deactivate-partner-instance`
`instance_id / instance_key`	body	UUID/string	sim	um identificador	Instância a inativar.	`UUID_DA_INSTANCIA`
`reason`	body	string	não	auditável	Motivo da inativação.	`Cliente cancelou esta linha`

Erros mais comuns

error.code	HTTP	Quando ocorre
`remote_callback_removal_failed`	409	callback ativo não pôde ser removido
`meta_send_access_revocation_failed`	409	não foi possível garantir bloqueio de envio
`meta_credential_missing_for_hard_disconnect`	409	credencial necessária ausente

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.

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Inativar cliente

Inativa o cliente final e trata todas as instâncias vinculadas.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	deactivate-partner-customer	Seleciona a operação.	`deactivate-partner-customer`
`partner_customer_id / external_customer_id`	body	UUID/string	sim	um identificador	Cliente a inativar.	`cliente_56790`
`reason`	body	string	não	auditável	Motivo.	`Cliente cancelou assinatura`

Erros mais comuns

error.code	HTTP	Quando ocorre
`customer_not_found`	404	cliente inexistente
`customer_deactivation_partial_failure`	409	uma ou mais instâncias falharam; verifique results

Request

{
  "route": "deactivate-partner-customer",
  "external_customer_id": "cliente_56790",
  "reason": "Cliente cancelou a assinatura"
}

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Reativar cliente

Reativa o cadastro comercial. Gere reconnect quando os números precisarem de nova autorização.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	reactivate-partner-customer	Seleciona a operação.	`reactivate-partner-customer`
`partner_customer_id / external_customer_id`	body	UUID/string	sim	um identificador	Cliente a reativar.	`cliente_56790`
`reason`	body	string	não	auditável	Motivo.	`Cliente retornou ao SaaS`

Erros mais comuns

error.code	HTTP	Quando ocorre
`customer_not_found`	404	cliente inexistente
`customer_merged`	409	cadastro mesclado não pode ser reativado

Request

{
  "route": "reactivate-partner-customer",
  "external_customer_id": "cliente_56790",
  "reason": "Cliente voltou para o SaaS"
}

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Validar webhook

Testa HTTPS e o desafio da Meta sem alterar as instâncias.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	validate-partner-webhook-endpoint	Seleciona a operação.	`validate-partner-webhook-endpoint`
`webhook_url`	body	HTTPS URL	sim	porta 443; sem credenciais na URL	Endpoint público. Localhost, IP privado e redirects são bloqueados.	`https://api.seusistema.com/webhooks/whatsapp`
`meta_verify_token`	body	string	condicional	token atual/gerado	Token que o endpoint usa no desafio GET da Meta.	`hc_meta_verify_...`

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.

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Alterar webhook do partner

Troca o endpoint único e inicia a migração dos números ativos na Meta.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	update-partner-webhook-endpoint	Seleciona a operação.	`update-partner-webhook-endpoint`
`webhook_url`	body	HTTPS URL	sim	validado antes de aplicar	Novo endpoint único do partner.	`https://api.seusistema.com/webhooks/whatsapp`
`meta_verify_token`	body	string	condicional	token da configuração	Deve ser o mesmo configurado no seu endpoint.	`hc_meta_verify_...`
`reason`	body	string	não	auditável	Motivo da troca.	`Migração de domínio`

Erros mais comuns

error.code	HTTP	Quando ocorre
`webhook_validation_failed`	409	challenge/HTTPS falhou
`webhook_url_private_address`	400	localhost/IP privado
`webhook_migration_failed`	500	falha ao enfileirar/aplicar

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
}

Override de callback oficial

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-webhook-migration#

Consultar migração de webhook

Acompanha quantas instâncias foram atualizadas, falharam ou aguardam.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query/body	string	sim	get-partner-webhook-migration	Seleciona a consulta.	`get-partner-webhook-migration`
`migration_id`	query/body	UUID	não	última migração se omitido	Migração específica.	`UUID_DA_MIGRACAO`

Query parameters

Parâmetro	Descrição
`migration_id`	UUID opcional; sem ele retorna a migração mais recente

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Reprocessar falhas do webhook

Tenta novamente apenas as instâncias que falharam.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	retry-partner-webhook-migration	Seleciona a operação.	`retry-partner-webhook-migration`
`migration_id`	body	UUID	sim	migração com falhas	Reprocessa apenas itens falhos/pendentes.	`UUID_DA_MIGRACAO`

Request

{
  "route": "retry-partner-webhook-migration",
  "migration_id": "UUID_DA_MIGRACAO"
}

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=list-partner-meta-templates#

Listar templates

Consulta o catálogo HookCloud em cache, sem consumir GET da Graph API.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	list-partner-meta-templates	Seleciona a consulta.	`list-partner-meta-templates`
`instance_id / instance_key / phone_number_id / waba_id`	query	UUID/string	sim	um escopo	A HookCloud resolve a WABA do catálogo.	`UUID_DA_INSTANCIA`
`status`	query	enum	não	APPROVED, PENDING, REJECTED, PAUSED, DISABLED	Filtro de status oficial.	`APPROVED`
`sendable_only`	query	boolean	não	false	Quando true, retorna somente templates utilizáveis no momento.	`true`
`quality_status`	query	string	não	GREEN, YELLOW, RED, FLAGGED	Filtro de qualidade.	`GREEN`
`category`	query	string	não	MARKETING, UTILITY, AUTHENTICATION	Categoria.	`UTILITY`
`language`	query	string	não	código Meta	Idioma.	`pt_BR`
`search`	query	string	não	nome ou ID	Busca parcial.	`confirmacao`
`page / page_size`	query	integer	não	1 / 50; máximo 100	Paginação.	`1 / 50`

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": [] }
    }
  ]
}

Fetch Message Templates oficial

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-meta-template#

Consultar template

Retorna componentes, parâmetros, status, qualidade, categoria e sendable.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	get-partner-meta-template	Seleciona a consulta.	`get-partner-meta-template`
`template_id`	query	string	condicional	ou name+language	ID oficial da Meta.	`123456789`
`template_name`	query	string	condicional	junto com language	Nome do template.	`confirmacao_agendamento`
`language`	query	string	condicional	junto com template_name	Idioma Meta.	`pt_BR`
`instance_id / waba_id`	query	UUID/string	sim	escopo	Garante que o template pertence ao partner.	`UUID_DA_INSTANCIA`

Query parameters

Parâmetro	Descrição
`template_id`	ID oficial
`template_name` + `language`	Alternativa por nome/idioma
`instance_id` ou `waba_id`	Escopo

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Atualizar catálogo

Enfileira uma reconciliação controlada com a Graph API.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	refresh-partner-meta-templates	Seleciona a operação.	`refresh-partner-meta-templates`
`instance_id / waba_id`	body	UUID/string	sim	um escopo	WABA a reconciliar com a Graph API.	`UUID_DA_INSTANCIA`
`force`	body	boolean	somente admin HookCloud	false	Ignora cooldown após análise.	`true`

Erros mais comuns

error.code	HTTP	Quando ocorre
`template_refresh_rate_limited`	429	cooldown por WABA
`meta_credential_not_found`	409	credencial Meta indisponível

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.

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-meta-template-sync#

Consultar sincronização de templates

Retorna queued, processing, completed ou failed.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	get-partner-meta-template-sync	Seleciona a consulta.	`get-partner-meta-template-sync`
`instance_id / waba_id`	query	UUID/string	sim	um escopo	Consulta o último job.	`UUID_DA_INSTANCIA`

Query parameters

Parâmetro	Descrição
`instance_id` / `waba_id`	Escopo da sincronização

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Reportar status de mensagem

Permite consolidar sent, delivered, read, failed e deleted na Saúde de Entregas.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	report-partner-message-status	Seleciona a operação.	`report-partner-message-status`
`phone_number_id`	body	string	sim	ID Meta da origem	Mapeia a instância/cliente.	`1093754977160703`
`message_id`	body	string	condicional	waMID quando existente	ID retornado pela Meta.	`wamid.xxx`
`client_message_id / request_id`	body	string	condicional	quando não existe waMID	ID local para falhas síncronas.	`msg_local_123`
`status`	body	enum	sim	sent, delivered, read, failed, deleted	Estado recebido no webhook messages/statuses.	`delivered`
`occurred_at`	body	ISO 8601	não	agora	Horário do evento na Meta.	`2026-07-21T12:00:00Z`
`template_id / template_name`	body	string	não	contexto	Template usado.	`campanha_marketing`
`campaign_id`	body	string	não	ID do seu SaaS	Agrupamento da campanha.	`campanha_456`
`recipient_hash`	body	hex 64	não	HMAC-SHA256	Identificador pseudonimizado do destinatário.	`64_HEX`
`error_code / error_title / error_message`	body	integer/string	quando failed	erro Meta	Detalhes normalizados.	`131049`

Erros mais comuns

error.code	HTTP	Quando ocorre
`invalid_delivery_status`	400	status fora do enum
`instance_not_found`	404	phone_number_id não mapeado
`delivery_status_report_failed`	500	falha ao persistir

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"
}

Status webhooks oficiais

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Reportar falha de entrega

Registra falhas normalizadas, inclusive sem waMID usando client_message_id.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	report-partner-message-delivery-failure	Atalho que força status failed.	`report-partner-message-delivery-failure`
`phone_number_id`	body	string	sim	ID Meta	Instância de origem.	`1093754977160703`
`message_id ou client_message_id`	body	string	sim	um dos dois	Identificador da mensagem/tentativa.	`wamid.xxx`
`error_code`	body	integer/string	sim	código Meta	Ex.: 131049 ou 131042.	`131049`
`error_title / error_message / error_details`	body	string	não	texto Meta	Detalhes sem conteúdo da mensagem.	`Healthy ecosystem engagement`
`recipient_hash`	body	hex 64	recomendado	HMAC-SHA256	Não envie telefone em texto puro.	`64_HEX`

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.

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-delivery-health#

Consultar saúde de entregas

Retorna taxa de falha, 131049, 131042, top erros, templates e alertas.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	get-partner-delivery-health	Seleciona a consulta.	`get-partner-delivery-health`
`window_hours`	query	integer	não	padrão 24; 1–2160	Janela de agregação em horas.	`24`
`customer_id / instance_id`	query	UUID	não	escopo opcional	Restringe a um cliente ou instância.	`UUID_DO_CLIENTE`
`alert_status`	query	string	não	padrão open	Filtra alertas retornados.	`open`
`severity / category / error_code`	query	string	não	filtros opcionais	Refina alertas.	`critical`

Query parameters

Parâmetro	Descrição
`window_hours`	Janela de análise, ex.: 24

GEThttps://api.hookcloud.app/functions/v1/swift-worker?route=search-partner-delivery-events#

Pesquisar eventos de entrega

Busca paginada por status, erro, template, campanha, cliente ou instância.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	search-partner-delivery-events	Seleciona a consulta.	`search-partner-delivery-events`
`search`	query	string	não	busca parcial	Busca IDs e textos normalizados.	`campanha_456`
`status`	query	enum	não	sent, delivered, read, failed, deleted	Status final.	`failed`
`error_code`	query	string	não	código Meta	Erro específico.	`131049`
`template_name / campaign_id`	query	string	não	filtro exato/parcial	Contexto da campanha.	`campanha_marketing`
`customer_id / instance_id`	query	UUID	não	escopo	Cliente/instância.	`UUID`
`date_from / date_to`	query	ISO 8601	não	intervalo	Datas inclusive/exclusive conforme backend.	`2026-07-01T00:00:00Z`
`page / page_size / sort`	query	integer/string	não	1 / 50 / desc; máximo 200	Paginação e ordenação.	`1 / 50 / desc`

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

Partner Portal

Notificações e preferências

Estas rotas são destinadas ao frontend autenticado do Partner Portal e usam o JWT do membro. Elas não aceitam a Partner API Key como substituta do usuário.

GEThttps://api.hookcloud.app/functions/v1/swift-worker#

Listar notificações

Retorna o sino unificado com Academy, Meta, templates, saúde de entregas, billing e sistema.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	list-partner-notifications	Seleciona a consulta.	`list-partner-notifications`
`limit`	query	integer	não	padrão 30; 1–100	Itens mais recentes.	`40`
`before`	query	ISO 8601	não	cursor temporal	Paginação para itens anteriores.	`2026-07-24T12:00:00Z`

Exemplo

GET ?route=list-partner-notifications&limit=40

Erros mais comuns

error.code	HTTP	Quando ocorre
`partner_member_required`	401/403	rota exige JWT de membro; não Partner API Key
`notification_list_failed`	500	falha de consulta

GEThttps://api.hookcloud.app/functions/v1/swift-worker#

Consultar preferências

Retorna as categorias habilitadas pelo usuário logado.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	query	string	sim	get-partner-notification-preferences	Seleciona a consulta.	`get-partner-notification-preferences`

Exemplo

GET ?route=get-partner-notification-preferences

PATCHhttps://api.hookcloud.app/functions/v1/swift-worker#

Atualizar preferências

Ativa/desativa categorias e popups para o usuário atual.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	update-partner-notification-preferences	Seleciona a operação.	`update-partner-notification-preferences`
`notify_academy`	body	boolean	não	true	Respostas, aprovações e atualizações da Academy.	`true`
`notify_meta_alerts`	body	boolean	não	true	Alertas oficiais Meta.	`true`
`notify_templates`	body	boolean	não	true	Status/qualidade de templates.	`true`
`notify_delivery_health`	body	boolean	não	true	Falhas e saúde de entregas.	`true`
`notify_billing`	body	boolean	não	true	Falhas, recuperação e faturas.	`true`
`notify_billing_reminders`	body	boolean	não	true	Avisos aproximadamente 24h antes.	`true`
`notify_system`	body	boolean	não	true	Avisos gerais HookCloud.	`true`
`popup_enabled`	body	boolean	não	true	Toast visual; o sino continua disponível.	`false`

Exemplo

{"route":"update-partner-notification-preferences","notify_templates":false,"popup_enabled":true}

Erros mais comuns

error.code	HTTP	Quando ocorre
`partner_member_required`	401/403	rota exige JWT
`notification_preferences_update_failed`	500	falha ao salvar

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Marcar uma notificação como lida

Registra a leitura para o usuário atual.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	mark-partner-notification-read	Seleciona a operação.	`mark-partner-notification-read`
`notification_id`	body	UUID	sim	notificação visível ao usuário	Marca a leitura.	`UUID_DA_NOTIFICACAO`

Exemplo

{"route":"mark-partner-notification-read","notification_id":"UUID"}

POSThttps://api.hookcloud.app/functions/v1/swift-worker#

Marcar todas como lidas

Marca todas as notificações visíveis como lidas.

Parâmetros detalhados

Campo	Local	Tipo	Obrigatório	Valores / padrão	Descrição	Exemplo
`route`	body	string	sim	mark-all-partner-notifications-read	Seleciona a operação.	`mark-all-partner-notifications-read`

Exemplo

{"route":"mark-all-partner-notifications-read"}

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