Cadastro e organização dos clientes

Modelo de dados

Listar clientes

Use a listagem paginada para sincronizar telas, pesquisar cadastros e acompanhar slots.

curl --request GET \
  --url 'https://api.hookcloud.app/functions/v1/swift-worker?route=list-partner-customers&page=1&page_size=50&status=active&search=clinica' \
  --header 'apikey: SUA_PUBLISHABLE_KEY' \
  --header 'Authorization: Bearer hc_partner_live_SUA_CHAVE'

Filtros: search, status, include_merged, include_erased, page e page_size.

Consultar um cliente

curl --request GET \
  --url 'https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-customer&customer_id=UUID_DO_CLIENTE' \
  --header 'apikey: SUA_PUBLISHABLE_KEY' \
  --header 'Authorization: Bearer hc_partner_live_SUA_CHAVE'

Também é possível usar external_customer_id. O retorno inclui instâncias, slot comercial, histórico recente e estado de risco Meta.

Editar nome, e-mail e telefone

A atualização usa PATCH. Envie expected_updated_at para impedir que uma edição antiga sobrescreva uma alteração mais recente.

curl --request PATCH \
  --url 'https://api.hookcloud.app/functions/v1/swift-worker?route=update-partner-customer' \
  --header 'apikey: SUA_PUBLISHABLE_KEY' \
  --header 'Authorization: Bearer hc_partner_live_SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: UUID_GERADO_PELO_SEU_BACKEND' \
  --data '{
    "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"
  }'

Histórico de alterações

GET https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-customer-history&customer_id=UUID&page=1&page_size=50

O histórico registra origem, ator, campos alterados, valores anteriores/novos, motivo, merge e movimentação de instâncias.

Mesclar cadastros duplicados

O cliente de origem é arquivado e suas instâncias passam para o cliente principal. Tokens, callbacks, números e instance_key não são modificados.

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

Mover uma instância

Use para corrigir uma linha vinculada ao cliente errado. A operação altera somente partner_customer_id.

{
  "route": "move-partner-instance-to-customer",
  "instance_id": "UUID_DA_INSTANCIA",
  "target_customer_id": "UUID_DO_CLIENTE_CORRETO",
  "reason": "Número vinculado ao cliente incorreto"
}

Idempotência sem complicação

Em operações estruturais, envie um UUID no header Idempotency-Key. Se o seu backend repetir a mesma requisição depois de um timeout, a HookCloud devolve o resultado anterior sem executar tudo novamente.

Idempotency-Key: 6c10a60e-9b19-4f23-9be8-8b928af88e26

Não reutilize a mesma chave com outro payload; isso retorna 409 idempotency_key_reused.

Inativar não é apagar

O lifecycle normal deve usar deactivate-partner-customer e reactivate-partner-customer. A inativação remove callbacks, libera slots e preserva o histórico. Eliminação de dados pessoais é uma operação administrativa restrita à HookCloud.

Eventos para sincronizar seu sistema

• hookcloud.partner.customer.updated
• hookcloud.partner.customer.merged
• hookcloud.partner.instance.moved
• hookcloud.partner.customer.erasure_started
• hookcloud.partner.customer.erased
• hookcloud.partner.customer.erasure_failed

Os eventos usam o mesmo endpoint e a mesma assinatura HMAC descritos em Webhooks.