# Integracao Kommo

Esta integracao backend depende de configuracao no proprio Kommo e de credenciais salvas por workspace na tela `Integrations`.

## O que esta implementado

- `POST /integrations/kommo/:workspaceKey/webhook`
  - rota legada ainda suportada
- `POST /webhook/kommo?workspaceKey=<workspace-slug>`
  - endpoint publico canonico para webhooks gerais do Kommo
  - cria ou atualiza um `lead Kommo` local ainda nao vinculado
- `POST /integrations/kommo/:workspaceKey/salesbot/messages`
  - rota legada ainda suportada
- `POST /webhook/kommo/salesbot/messages?workspaceKey=<workspace-slug>`
  - endpoint publico canonico para `widget_request` do Salesbot
  - grava a mensagem inbound no historico do lead e armazena o `return_url` da execucao atual
- `GET /integrations/kommo/leads?status=unlinked`
  - lista leads Kommo locais para a tela inicial
- `POST /integrations/kommo/settings`
  - salva subdominio, access token, webhook secret e salesbot secret key do Kommo para o workspace
- `POST /integrations/kommo/leads/:leadRecordId/link-client`
  - vincula manualmente um cliente existente ao lead Kommo
  - cria a conversa do repositório para o cliente e faz backfill das mensagens recebidas antes do vinculo
- `POST /repository/messages`
  - se a conversa estiver vinculada ao Kommo via Salesbot, envia a resposta de volta pelo `return_url`
  - registra auditoria de falha, agenda retry controlado e persiste o estado da entrega outbound

## Modelo atual

- `lead Kommo` nao cria mais `client + case` automaticamente.
- O lead entra primeiro em uma fila local de leads pendentes.
- Um mesmo cliente pode ser vinculado a varios leads diferentes do Kommo.
- Depois do vinculo manual, a conversa passa a existir no repositório do cliente e as mensagens antigas do lead sao reaproveitadas.
- A tela inicial mostra um alerta com a quantidade de leads Kommo ainda nao vinculados.
- Falhas de `return_url` agora sao rastreadas em `kommo_outbound_deliveries`.
- O envio outbound usa timeout, retries imediatos curtos e retries agendados para falhas transitorias.
- O dashboard inicial tenta processar retries vencidos e mostra conversas Kommo com entrega em retry ou falha definitiva.

## O que precisa ser configurado no Kommo

1. Criar uma `Private integration`.
2. Gerar um `long-lived token` ou usar OAuth para chamadas no CRM API.
3. Guardar a `Secret key` da integracao e salvar as credenciais do workspace na tela `Integrations`.
4. Subir um widget com `salesbot_designer`.
5. No Salesbot, criar um passo `widget_request` apontando para:
   - `POST /webhook/kommo/salesbot/messages?workspaceKey=<workspace-slug>`
6. No `widget_request`, enviar pelo menos:
   - `lead`
   - `message`
   - idealmente `chatId`, `talkId`, `contactId`, `senderName`
7. Opcionalmente, configurar webhooks gerais para:
   - lead criado
   - nota/mensagem recebida
   - URL sugerida: `POST /webhook/kommo?workspaceKey=<workspace-slug>`

## Importante

- Webhook geral do Kommo resolve entrada de dados, mas nao envia resposta de volta ao mesmo canal.
- Para responder em um canal ja conectado no Kommo, esta implementacao usa o fluxo documentado de `Salesbot + widget_request`.
- Se um lead ainda nao estiver vinculado a um cliente, a mensagem fica no historico local do lead e nao entra no repositório principal ate o vinculo manual.
- Se quiser usar `Chats API` diretamente, isso exige uma integracao de canal proprio com assinatura `X-Signature` e fluxo separado.
- O `return_url` do Salesbot continua a execucao do bot atual. Enquanto ele nao for chamado, esse bot fica pendente para a entidade.
- Se o `return_url` responder com erro transitório, a mensagem continua salva no nosso repositório com status `kommo_retry_scheduled`.
- Se o retry esgotar o limite configurado ou receber erro nao retentavel, a mensagem fica com status `kommo_delivery_failed` e a conversa aparece na home como incidente operacional.

## Variaveis de ambiente

As credenciais sensiveis do Kommo nao precisam mais ficar no `.env`. Elas sao salvas por workspace, com criptografia, pela tela `Integrations`.

- `KOMMO_RETURN_URL_TIMEOUT_MS`
- `KOMMO_RETURN_URL_MAX_ATTEMPTS`
- `KOMMO_RETURN_URL_IMMEDIATE_ATTEMPTS`
- `KOMMO_DEFAULT_CASE_TYPE_CODE`
- `KOMMO_DEFAULT_CASE_SUBTYPE_CODE`
- `KOMMO_DEFAULT_CASE_STATUS_CODE`
- `KOMMO_DEFAULT_CASE_PRIORITY_CODE`