# contacts.stats

Saúde da base, canais de entrada e vendas dos contatos. Números do recorte (`filter` e `q` iguais aos de `contacts.list`), só com os contatos que o membro vê e fora da lixeira. Percentuais de 0 a 100.

`temperature`: média (null sem cálculo), faixa da média pelos cortes da conta, `computed` (contatos com temperatura) e contagem por faixa (`pct` sobre os calculados). `score`: idem por tier, com `enabled` da conta.

`channels`: contatos por origem (`key` = `origin_kind`: `ad`, `organic`, `manual`, `import`, `integration`, `instagram`, `form`, `api`; `pct` sobre o total), do maior para o menor.

`origins`: contatos por origem · sub-origem (`kind` = `origin_kind`; `detail` = campanha do anúncio para `ad`, senão `origin_detail`; null = sem sub-origem), `pct` sobre o total, do maior para o menor. `visits.identified`: contatos com visita identificada (sempre 0: o Atomiks não rastreia páginas).

`sales` (vendas não canceladas dos contatos do recorte): `totalSales` (compras), `avgPurchasesPerContact` (compras ÷ contatos), `ltvCents` (receita ÷ contatos) e `ticketCents` (receita ÷ compras), em centavos.

- Endpoint: `POST https://app.atomiks.com.br/api/v1/contacts.stats` (corpo JSON)
- Quem pode chamar: membro da conta
- Escopo da chave: `contacts:read`
- Grava dados: não
- Pela chave de API: sim
- Ferramenta MCP: `contacts_stats`
- Ficha em JSON: `https://app.atomiks.com.br/api/v1/openapi.json` (operationId `contacts.stats`)

## Entrada

| Campo | Tipo | Obrigatório | Nota |
|---|---|---|---|
| `filter` | object[] | não |  |
| `q` | string | não |  |

<details><summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "filter": {
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 64
          },
          "order": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000
          },
          "field": {
            "type": "string",
            "maxLength": 60
          },
          "operator": {
            "type": "string",
            "maxLength": 30
          },
          "negation": {
            "default": false,
            "type": "boolean"
          },
          "parentId": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 64
              },
              {
                "type": "null"
              }
            ]
          },
          "valueString": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 4000
              },
              {
                "type": "null"
              }
            ]
          },
          "valueNumber": {
            "type": [
              "number",
              "null"
            ]
          },
          "valueDate": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 40
              },
              {
                "type": "null"
              }
            ]
          },
          "valueBool": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "valueUuid": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "field",
          "operator"
        ],
        "additionalProperties": false
      }
    },
    "q": {
      "type": "string",
      "maxLength": 100
    }
  }
}
```

</details>

## Exemplo

```bash
curl -X POST https://app.atomiks.com.br/api/v1/contacts.stats \
  -H "Authorization: Bearer $ATOMIKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter":[{"field":"tag","operator":"in","negation":false,"valueUuid":"00000000-0000-0000-0000-000000000000"}]}'
```

CLI:

```bash
node cli/atomiks.mjs contacts.stats --json '{"filter":[{"field":"tag","operator":"in","negation":false,"valueUuid":"00000000-0000-0000-0000-000000000000"}]}'
```

MCP: ferramenta `contacts_stats` com a mesma entrada.

## Saída

Sucesso: `{"data": ...}` com o formato abaixo.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "total": {
      "type": "number"
    },
    "temperature": {
      "type": "object",
      "properties": {
        "avg": {
          "type": [
            "number",
            "null"
          ]
        },
        "band": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "cold",
                "warm",
                "hot"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "computed": {
          "type": "number"
        },
        "bands": {
          "type": "object",
          "properties": {
            "hot": {
              "type": "object",
              "properties": {
                "count": {
                  "type": "number"
                },
                "pct": {
                  "type": "number"
                }
              },
              "required": [
                "count",
                "pct"
              ],
              "additionalProperties": false
            },
            "warm": {
              "type": "object",
              "properties": {
                "count": {
                  "type": "number"
                },
                "pct": {
                  "type": "number"
                }
              },
              "required": [
                "count",
                "pct"
              ],
              "additionalProperties": false
            },
            "cold": {
              "type": "object",
              "properties": {
                "count": {
                  "type": "number"
                },
                "pct": {
                  "type": "number"
                }
              },
              "required": [
                "count",
                "pct"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "hot",
            "warm",
            "cold"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "avg",
        "band",
        "computed",
        "bands"
      ],
      "additionalProperties": false
    },
    "score": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "avg": {
          "type": [
            "number",
            "null"
          ]
        },
        "tiers": {
          "type": "object",
          "properties": {
            "high": {
              "type": "object",
              "properties": {
                "count": {
                  "type": "number"
                },
                "pct": {
                  "type": "number"
                }
              },
              "required": [
                "count",
                "pct"
              ],
              "additionalProperties": false
            },
            "medium": {
              "type": "object",
              "properties": {
                "count": {
                  "type": "number"
                },
                "pct": {
                  "type": "number"
                }
              },
              "required": [
                "count",
                "pct"
              ],
              "additionalProperties": false
            },
            "low": {
              "type": "object",
              "properties": {
                "count": {
                  "type": "number"
                },
                "pct": {
                  "type": "number"
                }
              },
              "required": [
                "count",
                "pct"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "high",
            "medium",
            "low"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "enabled",
        "avg",
        "tiers"
      ],
      "additionalProperties": false
    },
    "channels": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "number"
          },
          "pct": {
            "type": "number"
          }
        },
        "required": [
          "key",
          "label",
          "count",
          "pct"
        ],
        "additionalProperties": false
      }
    },
    "origins": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string"
          },
          "detail": {
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "number"
          },
          "pct": {
            "type": "number"
          }
        },
        "required": [
          "kind",
          "detail",
          "label",
          "count",
          "pct"
        ],
        "additionalProperties": false
      }
    },
    "visits": {
      "type": "object",
      "properties": {
        "identified": {
          "type": "number"
        }
      },
      "required": [
        "identified"
      ],
      "additionalProperties": false
    },
    "sales": {
      "type": "object",
      "properties": {
        "totalSales": {
          "type": "number"
        },
        "avgPurchasesPerContact": {
          "type": "number"
        },
        "ltvCents": {
          "type": "number"
        },
        "ticketCents": {
          "type": "number"
        }
      },
      "required": [
        "totalSales",
        "avgPurchasesPerContact",
        "ltvCents",
        "ticketCents"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "total",
    "temperature",
    "score",
    "channels",
    "origins",
    "visits",
    "sales"
  ],
  "additionalProperties": false
}
```

## Erros

`{"error": {"code", "message", "requestId"}}`. Códigos: `invalid_input` (400), `unauthorized` (401), `forbidden` / `account_pending` / `scope_missing` (403), `not_found` (404), `limit_reached` (409), `internal` (500).