# Cruzar os dados do Virtuazzachat

Base: https://crm-api.virtuazza.com/crm-readonly

Autenticação: `Authorization: Bearer <CHAVE_INDIVIDUAL>`. Use uma variável de ambiente no seu cliente; não coloque a chave no código ou na URL pública do Swagger. Todos os exemplos abaixo usam IDs fictícios.

## Operações

| Operação | account_id |
| --- | ---: |
| Little Duck | 7 |
| Eco Flame Garden | 11 |
| Sofá na Caixa | 12 |
| GrowTech | 14 |
| Afiliados | 17 |

## Fluxo para análise comercial

1. `GET /api/v1/profile` retorna as contas disponíveis.
2. `GET /api/v1/accounts/12/kanban/funnels` retorna os funis cadastrados para consulta e suas etapas. Os dados de cada funil são lidos ao vivo. `meta.catalog_updated_at` informa quando os IDs foram cadastrados. Funis criados depois precisam entrar no catálogo ou ser consultados diretamente por ID. Isso evita a criação automática feita pela listagem nativa em contas vazias.
3. `GET /api/v1/accounts/12/kanban/funnels/101/deals?view=list&page=0` retorna até 50 oportunidades. Incremente `page` enquanto `meta.has_more=true`. Filtros: `stage_id`, `assignee_id`, `filter=active|won|lost|all`, `q`, `next_action` e `timezone`.
4. Para cada negócio, consulte o contato, os produtos negociados, as conversas vinculadas, o responsável e a etapa pelos IDs retornados. `custom_fields` contém os campos do negócio; `custom_attributes` contém os campos do contato ou da conversa.
5. Para o contexto de acompanhamento, use as rotas de tarefas, movimentações, estatísticas e anexos da oportunidade.
6. Para consolidar resultados por período, use `deal_metrics/summary`, `by_stage` e `by_period` com `since` e `until` em YYYY-MM-DD. As métricas usam a data de criação da oportunidade; elas não são um relatório por data de pagamento.

## Chaves de relacionamento

| Chave | Relacionamento |
| --- | --- |
| account_id | Operação. Inclua na chave de integração para separar as cinco marcas. |
| deal.id | Oportunidade. |
| deal.contact_id | Contato da oportunidade. |
| deal.kanban_funnel_id / kanban_stage_id | Funil e etapa comercial. |
| deal.assignee_id | Responsável. Consulte o catálogo de agentes da conta. |
| deal.deal_products[].product_id | Produto do CRM e valor negociado. |
| deal.conversations[].id | ID interno da conversa, usado nos lookups Kanban. |
| deal.conversations[].display_id | Número exibido no CRM, usado para ler conversa e mensagens. |

Não compare IDs de contatos entre operações para identificar a mesma pessoa. Use telefone normalizado, e-mail e outras evidências do cadastro, mantendo casos ambíguos separados. `null` em valor ou data significa dado não informado.

## Exemplo de consulta

```bash
curl --get 'https://crm-api.virtuazza.com/crm-readonly/api/v1/accounts/12/kanban/funnels/101/deals' \
  --header "Authorization: Bearer $VIRTUAZZA_CRM_KEY" \
  --data-urlencode 'view=list' \
  --data-urlencode 'page=0' \
  --data-urlencode 'filter=active' \
  --data-urlencode 'q=contato@example.test'
```

## Paginação

- Oportunidades, tarefas e movimentações: página inicial **0**, até 50 itens. Não existe o limite de 20 páginas nessas novas listagens.
- Contatos, conversas recentes e buscas: páginas **1 a 20**, preservando o contrato anterior.
- Conversas de um contato: copie os dois campos de `meta.next_cursor`, `before_activity_at` e `before_id`, para a próxima requisição.
- Mensagens: use o ID da mensagem mais antiga em `before`.
- Anexos de uma oportunidade: use `next_before_id` como `before_id`.
- Métricas: até 366 dias por requisição. Faça consultas sequenciais e respeite HTTP 429.

## MCP

Endpoint: https://crm-api.virtuazza.com/mcp. Autenticação Bearer com a mesma chave. A credencial ampliada tem 38 ferramentas; `tools/list` mostra a permissão efetiva de cada credencial. O pacote Desktop 1.3.0 consulta esse mesmo catálogo, preservando o acesso das chaves anteriores.

Exemplo de pedido à IA: “Compare as oportunidades ativas da Sofá e da Little Duck por responsável e etapa. Mostre os contatos em comum que você conseguir confirmar, os valores informados e as tarefas vencidas. Cite conta, oportunidade e conversa; sinalize os dados ausentes.”

## Escopo

Somente consulta das cinco operações. Não há criação, edição, exclusão, envio de mensagens, exportação em lote ou acesso direto a lojas/financeiro. Produtos, valores e recibos de pagamento são apenas os já registrados no CRM. A documentação geral histórica não muda a permissão da chave. Nenhum acesso de administrador foi concedido ao Tamura.