# Prompt para integrar seu sistema à HookCloud Partner

Copie o bloco abaixo para sua ferramenta de IA e anexe `GUIA-IMPLEMENTACAO.md`. Substitua os campos entre colchetes pelo contexto do seu projeto. Não cole chaves, tokens, senhas, links privados de conexão nem dados de clientes. Este prompt pode ser usado como texto em qualquer assistente; editar arquivos e executar testes depende dos recursos disponíveis nessa ferramenta.

---

Quero integrar meu sistema à HookCloud Partner. Leia o guia anexado antes de implementar. Use a documentação atual da HookCloud e as referências oficiais da Meta para confirmar contratos que não estejam detalhados no guia.

## Meu contexto

- Nome do produto: [NOME DO MEU SISTEMA]
- Tipo: [CRM / chatbot / central de atendimento / disparos / automação / combinação]
- Stack de frontend: [FRAMEWORK OU AINDA NÃO DEFINIDO]
- Stack de backend: [LINGUAGEM, FRAMEWORK E HOSPEDAGEM]
- Banco de dados e fila: [TECNOLOGIAS OU AINDA NÃO DEFINIDAS]
- Autenticação e isolamento entre clientes: [COMO FUNCIONA HOJE]
- Recursos existentes a preservar: [LISTA]
- Primeiro fluxo que quero entregar: [RESULTADO DESEJADO]
- Ambientes disponíveis: [DESENVOLVIMENTO / HOMOLOGAÇÃO / PRODUÇÃO]
- Recursos autorizados nesta etapa: [ALTERAÇÕES LOCAIS, PUBLICAÇÃO, TESTES EXTERNOS ETC.]
- Meus clientes já possuem cadastros ou números no Partner: [SIM / NÃO / A CONFERIR]
- Onde vou configurar os segredos: [GERENCIADOR DE SEGREDOS OU VARIÁVEIS DO BACKEND; SEM VALORES]

## Como trabalhar

1. Confira o projeto atual antes de editar. Preserve fluxos, alterações e dados existentes. Se não tiver acesso ao código, entregue uma implementação adaptada à stack e explique onde cada parte deve ser inserida.
2. Identifique os requisitos que já existem, o que precisa mudar e eventuais dependências externas. Avance nas partes independentes e pergunte apenas por decisões que realmente bloqueiem a implementação.
3. Separe três responsabilidades:
   - **HookCloud Partner:** cadastro de clientes, instâncias, sessões Connect, estado da conexão, desligamento, credenciais autorizadas e eventos de gestão.
   - **Meta Graph API:** envio de mensagens, arquivos, criação/edição/exclusão de templates e recursos Meta explicitamente documentados.
   - **Meu sistema:** login, isolamento de clientes, conversas, histórico, bot/IA, filas, campanhas, consentimento, permissões e interface.
4. Não invente endpoints HookCloud como `/send-message`, `/create-template` ou rotas com o nome dos exemplos `meta-*`. Os exemplos `meta-*` da documentação são chamadas diretas à Graph. Não copie URLs de aplicações demonstrativas.
5. Configure credenciais somente no servidor. Peça que eu as insira no gerenciador de segredos, sem expô-las no chat. Não entregue Partner API Key, token Meta ou segredo HMAC ao navegador.
6. Faça o onboarding respeitar o estado real: acesso do parceiro após o checkout confirmado, cadastro obrigatório no Portal, webhook global com GET validado **e salvo**, POST autenticado e permissões adequadas. Não tente preencher CPF/CNPJ do proprietário pela API de clientes.
7. Antes de criar registros, veja se já existem. Importe e reconcilie inventário pelo ID do parceiro, ID/identificador externo do cliente e `instance_id`, mantendo os IDs locais e o histórico. Nunca identifique propriedade apenas por nome ou telefone.
8. Para novo cliente e novo número, prefira `upsert-partner-customer` e depois `create-customer-instance`. A rota combinada `create-partner-instance` é uma alternativa; não chame as duas para o mesmo número. Guarde a `instance_key` gerada pela HookCloud.
9. Abra o `connect_url` retornado pela HookCloud. Fechar a janela da Meta ou voltar ao meu sistema não prova conclusão. Confirme pelo evento autenticado e pelo GET da instância. Reconexão e link expirado reutilizam a instância existente.
10. Implemente recepção durável, deduplicação e ordenação de eventos. A assinatura Meta e a assinatura HookCloud são diferentes. O token do desafio GET não autentica POST. Se o mecanismo de autenticação POST ainda não estiver provisionado para minha integração, trate isso como pré-requisito explícito; não aceite eventos sem validação.
11. Para atendimento, respeite a janela de 24 horas baseada em mensagem recebida real. Fora dela, use template aprovado. FEP é benefício de cobrança condicionado e independente; não use “7 dias” como autorização universal para texto livre.
12. Preserve BSUID completo e seu escopo empresarial. Nos envios use `recipient` para BSUID ou `to` para telefone, sem ambos. `user_id` vem do webhook e username não é destinatário.
13. Implemente fila e registro de tentativa antes dos envios. Um timeout após POST não autoriza reenviar cegamente. Revalide instância, geração da conexão, permissão, janela, opt-in e template antes de cada envio efetivo.
14. Use os estados de saúde da HookCloud sem transformar pendência de pagamento, nome em análise, RED ou erro técnico em banimento. Mostre data, fonte, estado desconhecido e uma explicação clara para cada erro.
15. Priorize webhooks e cache. Não faça GET contínuo à Meta nem uma consulta Graph a cada abertura de card. Use paginação, limites de concorrência, recuo com variação aleatória e circuitos de pausa em falhas recorrentes.
16. Não envie mensagens reais, crie campanhas, exclua templates, desconecte números ou altere cobrança fora da autorização que eu fornecer. Prepare testes locais e deixe testes externos claramente separados. Uma autorização anterior válida pode ser reutilizada dentro do mesmo escopo.

## Entrega que espero

- Implementação funcional e arquivos alterados, com instruções de configuração sem segredos.
- Mapeamento das rotas HookCloud e Graph utilizadas e dos escopos necessários.
- Modelo de dados com propriedade dos registros, idempotência, histórico e geração da conexão.
- Recepção GET/POST, conversas reais, estados de entrega e recursos compatíveis com meu tipo de sistema.
- Casos de teste executados e resultados, diferenciando testes simulados de evidência real.
- Limitações e pendências concretas, sem afirmar entrega, aprovação Meta, reconexão ou desligamento sem confirmação.
- Passos de publicação e operação, dentro da autorização desta etapa.

Comece examinando o projeto e apresentando as decisões essenciais; depois implemente o que já estiver autorizado.

---

O arquivo `hookcloud-partner/SKILL.md` é um complemento opcional para ferramentas que reconhecem esse formato. Ele não é necessário para usar este prompt nem garante descoberta automática em todas as ferramentas.