# Relatórios

> Volume, tempo de resposta, equipe, caixas, IA e créditos.

Os relatórios são só de leitura e usam o escopo `relatorios:ler`. Dão os mesmos números da tela Relatórios, no fuso da sua organização, e nunca mostram valores em dinheiro: o uso de IA vem só em créditos.

- `de` e `ate` (AAAA-MM-DD): o período, de até 366 dias. Sem eles, valem os últimos 30 dias.
- `granularidade`: `dia` (padrão), `semana` (começa na segunda) ou `mes`. Vale para volume, tempo de resposta e créditos.
- `caixa_id`: só os números de uma caixa.
- `formato=csv`: planilha em UTF-8 com BOM, cabeçalho e colunas sempre na mesma ordem. Textos que começariam com `=`, `+`, `-` ou `@` saem com um apóstrofo na frente, para a planilha não os ler como fórmula.
- Cache: a resposta traz `ETag`. Mande-o em `If-None-Match` e, se nada mudou, a resposta é `304` sem corpo. Os números mudam a cada mensagem: não guarde por mais de 1 minuto.
- Limite próprio: 12 consultas por minuto por chave e 30 por organização (`429 limite_relatorios`). Se a consulta demorar demais, vem `503 relatorio_demorou`: escolha um período menor ou agrupe por semana ou mês.
- O tempo de resposta traz a porcentagem respondida em até 1, 5, 15 e 60 minutos.

**Códigos de erro comuns aqui**: `periodo_longo`, `periodo_invalido`, `granularidade_invalida`, `caixa_invalida`, `limite_relatorios`, `relatorio_demorou` (todos em [Erros](https://docs.forsi.com.br/erros)).

## GET /relatorios/volume — Volume de conversas e mensagens

- URL: `GET https://chat.forsi.com.br/api/v1/relatorios/volume`
- Acesso: escopo `relatorios:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `RelatorioVolume`; ou CSV com `formato=csv`
- Página: https://docs.forsi.com.br/api/relatorios/relatorio-volume (Markdown: https://docs.forsi.com.br/api/relatorios/relatorio-volume.md)

Conversas novas e resolvidas e mensagens recebidas/enviadas no período, em uma linha por dia, semana ou mês, mais o movimento por hora do dia. Os mesmos números da tela Relatórios.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `de` | data AAAA-MM-DD | não | Primeiro dia (AAAA-MM-DD, no fuso da organização). Padrão: 29 dias antes de `ate`. |
| `ate` | data AAAA-MM-DD | não | Último dia, inclusive. Padrão: hoje. O período vai até 366 dias. |
| `granularidade` | "dia" \| "semana" \| "mes" | não | Tamanho de cada linha da série: `dia` (padrão), `semana` (começa na segunda) ou `mes`. |
| `caixa_id` | uuid | não | Só os números desta caixa (WhatsApp, Instagram...). Veja as caixas em GET /me. |
| `formato` | "json" \| "csv" | não | `json` (padrão) ou `csv` (UTF-8 com BOM, separado por vírgula, pronto para planilha). |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/relatorios/volume?de=2026-09-01&ate=2026-09-30&granularidade=semana" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "periodo": {
      "de": "2026-10-12",
      "ate": "2026-10-12",
      "dias": 30,
      "fuso": "America/Sao_Paulo",
      "granularidade": "dia",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
    },
    "resumo": {
      "conversas_novas": 12,
      "conversas_resolvidas": 12,
      "mensagens_recebidas": 12,
      "mensagens_enviadas": 12,
      "mensagens_do_agente": 12,
      "notas_internas": 12
    },
    "por_hora": [{"hora":9,"mensagens_recebidas":12,"mensagens_enviadas":12}],
    "linhas": [
      {
        "inicio": "2026-10-12T17:00:00.000Z",
        "fim": "2026-10-12T17:30:00.000Z",
        "conversas_novas": 12,
        "conversas_resolvidas": 12,
        "mensagens_recebidas": 12,
        "mensagens_enviadas": 12,
        "mensagens_do_agente": 12,
        "notas_internas": 12
      }
    ]
  }
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /relatorios/tempo-de-resposta — Tempo de resposta e de resolução

- URL: `GET https://chat.forsi.com.br/api/v1/relatorios/tempo-de-resposta`
- Acesso: escopo `relatorios:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `RelatorioTempo`; ou CSV com `formato=csv`
- Página: https://docs.forsi.com.br/api/relatorios/relatorio-tempo-de-resposta (Markdown: https://docs.forsi.com.br/api/relatorios/relatorio-tempo-de-resposta.md)

Primeira resposta e resolução das conversas: quantidade, mediana, 90% das conversas, faixas e a porcentagem respondida em até 1, 5, 15 e 60 minutos. Tempos em segundos. Por semana ou mês, a mediana é calculada de novo em cada período (não é média de medianas).

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `de` | data AAAA-MM-DD | não | Primeiro dia (AAAA-MM-DD, no fuso da organização). Padrão: 29 dias antes de `ate`. |
| `ate` | data AAAA-MM-DD | não | Último dia, inclusive. Padrão: hoje. O período vai até 366 dias. |
| `granularidade` | "dia" \| "semana" \| "mes" | não | Tamanho de cada linha da série: `dia` (padrão), `semana` (começa na segunda) ou `mes`. |
| `caixa_id` | uuid | não | Só os números desta caixa (WhatsApp, Instagram...). Veja as caixas em GET /me. |
| `formato` | "json" \| "csv" | não | `json` (padrão) ou `csv` (UTF-8 com BOM, separado por vírgula, pronto para planilha). |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/relatorios/tempo-de-resposta?de=2026-09-01&ate=2026-09-30" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "periodo": {
      "de": "2026-10-12",
      "ate": "2026-10-12",
      "dias": 30,
      "fuso": "America/Sao_Paulo",
      "granularidade": "dia",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
    },
    "resumo": {
      "primeiras_respostas": 12,
      "sem_resposta": 12,
      "mediana_primeira_resposta_s": 240,
      "p90_primeira_resposta_s": 240,
      "respondidas_em_ate_1_min_pct": 87.5,
      "respondidas_em_ate_5_min_pct": 87.5,
      "respondidas_em_ate_15_min_pct": 87.5,
      "respondidas_em_ate_1_h_pct": 87.5,
      "resolvidas": 12,
      "mediana_resolucao_s": 240,
      "p90_resolucao_s": 240
    },
    "faixas_primeira_resposta": [{"faixa":"1 a 5 min","quantidade":12}],
    "faixas_resolucao": [{"faixa":"1 a 5 min","quantidade":12}],
    "linhas": [
      {
        "inicio": "2026-10-12T17:00:00.000Z",
        "fim": "2026-10-12T17:30:00.000Z",
        "primeiras_respostas": 12,
        "mediana_primeira_resposta_s": 240,
        "resolvidas": 12,
        "mediana_resolucao_s": 240
      }
    ]
  }
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /relatorios/atendentes — Desempenho por atendente

- URL: `GET https://chat.forsi.com.br/api/v1/relatorios/atendentes`
- Acesso: escopo `relatorios:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `RelatorioAtendentes`; ou CSV com `formato=csv`
- Página: https://docs.forsi.com.br/api/relatorios/relatorio-atendentes (Markdown: https://docs.forsi.com.br/api/relatorios/relatorio-atendentes.md)

Uma linha por pessoa da equipe com conversas atendidas, mensagens enviadas, resolvidas, abertas agora e tempo de primeira resposta no período todo.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `de` | data AAAA-MM-DD | não | Primeiro dia (AAAA-MM-DD, no fuso da organização). Padrão: 29 dias antes de `ate`. |
| `ate` | data AAAA-MM-DD | não | Último dia, inclusive. Padrão: hoje. O período vai até 366 dias. |
| `caixa_id` | uuid | não | Só os números desta caixa (WhatsApp, Instagram...). Veja as caixas em GET /me. |
| `formato` | "json" \| "csv" | não | `json` (padrão) ou `csv` (UTF-8 com BOM, separado por vírgula, pronto para planilha). |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/relatorios/atendentes?de=2026-09-01&ate=2026-09-30&formato=csv" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "periodo": {
      "de": "2026-10-12",
      "ate": "2026-10-12",
      "dias": 30,
      "fuso": "America/Sao_Paulo",
      "granularidade": "dia",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
    },
    "resumo": {"atendentes":12},
    "linhas": [
      {
        "id": "64ba31d1-11f4-41f2-9d68-33eef70d3495",
        "nome": "Maria Souza",
        "papel": "texto",
        "conversas_atendidas": 12,
        "mensagens_enviadas": 12,
        "conversas_resolvidas": 12,
        "abertas_agora": 12,
        "primeiras_respostas": 12,
        "mediana_primeira_resposta_s": 240
      }
    ]
  }
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /relatorios/caixas — Desempenho por caixa (canal)

- URL: `GET https://chat.forsi.com.br/api/v1/relatorios/caixas`
- Acesso: escopo `relatorios:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `RelatorioCaixas`; ou CSV com `formato=csv`
- Página: https://docs.forsi.com.br/api/relatorios/relatorio-caixas (Markdown: https://docs.forsi.com.br/api/relatorios/relatorio-caixas.md)

Uma linha por caixa (WhatsApp, Instagram etc.) com conversas novas e resolvidas e mensagens no período todo.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `de` | data AAAA-MM-DD | não | Primeiro dia (AAAA-MM-DD, no fuso da organização). Padrão: 29 dias antes de `ate`. |
| `ate` | data AAAA-MM-DD | não | Último dia, inclusive. Padrão: hoje. O período vai até 366 dias. |
| `caixa_id` | uuid | não | Só os números desta caixa (WhatsApp, Instagram...). Veja as caixas em GET /me. |
| `formato` | "json" \| "csv" | não | `json` (padrão) ou `csv` (UTF-8 com BOM, separado por vírgula, pronto para planilha). |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/relatorios/caixas?de=2026-09-01&ate=2026-09-30" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "periodo": {
      "de": "2026-10-12",
      "ate": "2026-10-12",
      "dias": 30,
      "fuso": "America/Sao_Paulo",
      "granularidade": "dia",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
    },
    "resumo": {"caixas":12},
    "linhas": [
      {
        "id": "64ba31d1-11f4-41f2-9d68-33eef70d3495",
        "nome": "Maria Souza",
        "canal": "whatsapp",
        "telefone": "+5531988887777",
        "conversas_novas": 12,
        "conversas_resolvidas": 12,
        "conversas_com_mensagens": 12,
        "mensagens_recebidas": 12,
        "mensagens_enviadas": 12
      }
    ]
  }
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /relatorios/agente-de-ia — Atendimento do agente de IA

- URL: `GET https://chat.forsi.com.br/api/v1/relatorios/agente-de-ia`
- Acesso: escopo `relatorios:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `RelatorioAgenteDeIa`; ou CSV com `formato=csv`
- Página: https://docs.forsi.com.br/api/relatorios/relatorio-agente-de-ia (Markdown: https://docs.forsi.com.br/api/relatorios/relatorio-agente-de-ia.md)

Quantas conversas o agente resolveu sozinho, quantas passou para a equipe e os motivos da passagem.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `de` | data AAAA-MM-DD | não | Primeiro dia (AAAA-MM-DD, no fuso da organização). Padrão: 29 dias antes de `ate`. |
| `ate` | data AAAA-MM-DD | não | Último dia, inclusive. Padrão: hoje. O período vai até 366 dias. |
| `caixa_id` | uuid | não | Só os números desta caixa (WhatsApp, Instagram...). Veja as caixas em GET /me. |
| `formato` | "json" \| "csv" | não | `json` (padrão) ou `csv` (UTF-8 com BOM, separado por vírgula, pronto para planilha). |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/relatorios/agente-de-ia?de=2026-09-01&ate=2026-09-30" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "periodo": {
      "de": "2026-10-12",
      "ate": "2026-10-12",
      "dias": 30,
      "fuso": "America/Sao_Paulo",
      "granularidade": "dia",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
    },
    "resumo": {
      "conversas": 12,
      "sem_agente": 12,
      "com_agente": 12,
      "passadas_para_a_equipe": 12,
      "resolvidas_pelo_agente": 12,
      "em_andamento": 12,
      "taxa_resolucao": 0.62
    },
    "motivos_da_passagem": [{"motivo":"texto","quantidade":12}],
    "linhas": [
      {
        "id": "64ba31d1-11f4-41f2-9d68-33eef70d3495",
        "nome": "Maria Souza",
        "conversas_com_agente": 12,
        "passadas_para_a_equipe": 12,
        "resolvidas_pelo_agente": 12,
        "em_andamento": 12
      }
    ]
  }
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /relatorios/creditos — Créditos de IA usados

- URL: `GET https://chat.forsi.com.br/api/v1/relatorios/creditos`
- Acesso: escopo `relatorios:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `RelatorioCreditos`; ou CSV com `formato=csv`
- Página: https://docs.forsi.com.br/api/relatorios/relatorio-creditos (Markdown: https://docs.forsi.com.br/api/relatorios/relatorio-creditos.md)

Créditos gastos no período (por dia, semana ou mês e por tipo de uso) e o saldo atual. Só créditos: nada em dinheiro.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `de` | data AAAA-MM-DD | não | Primeiro dia (AAAA-MM-DD, no fuso da organização). Padrão: 29 dias antes de `ate`. |
| `ate` | data AAAA-MM-DD | não | Último dia, inclusive. Padrão: hoje. O período vai até 366 dias. |
| `granularidade` | "dia" \| "semana" \| "mes" | não | Tamanho de cada linha da série: `dia` (padrão), `semana` (começa na segunda) ou `mes`. |
| `formato` | "json" \| "csv" | não | `json` (padrão) ou `csv` (UTF-8 com BOM, separado por vírgula, pronto para planilha). |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/relatorios/creditos?granularidade=mes&de=2026-01-01&ate=2026-09-30" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "periodo": {
      "de": "2026-10-12",
      "ate": "2026-10-12",
      "dias": 30,
      "fuso": "America/Sao_Paulo",
      "granularidade": "dia",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
    },
    "resumo": {
      "creditos_usados": 12,
      "creditos_disponiveis": 12,
      "creditos_do_plano": 12,
      "creditos_extras": 12,
      "renovam_em": "2026-10-04T13:05:12.481Z"
    },
    "por_motivo": [{"motivo":"resposta do agente","creditos_usados":12,"vezes":12}],
    "linhas": [
      {
        "inicio": "2026-10-12T17:00:00.000Z",
        "fim": "2026-10-12T17:30:00.000Z",
        "creditos_usados": 12
      }
    ]
  }
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## Objetos das respostas

Campos de cada objeto devolvido em `dados`. Campos novos podem aparecer: ignore os que não conhecer.

### RelatorioVolume

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `periodo` | object | não | O período que valeu na consulta (com os padrões aplicados). |
| `periodo.de` | data AAAA-MM-DD | não |  |
| `periodo.ate` | data AAAA-MM-DD | não |  |
| `periodo.dias` | integer | não |  |
| `periodo.fuso` | string | não | ex.: America/Sao_Paulo |
| `periodo.granularidade` | "dia" \| "semana" \| "mes" | não | Só nos relatórios em série. |
| `periodo.caixa_id` | uuid | não |  |
| `resumo` | object | não |  |
| `resumo.conversas_novas` | integer | não |  |
| `resumo.conversas_resolvidas` | integer | não |  |
| `resumo.mensagens_recebidas` | integer | não |  |
| `resumo.mensagens_enviadas` | integer | não |  |
| `resumo.mensagens_do_agente` | integer | não | Das enviadas, as que o agente de IA mandou. |
| `resumo.notas_internas` | integer | não |  |
| `por_hora` | lista de object | não | 24 itens, hora do dia no fuso da organização. |
| `por_hora[].hora` | integer | não |  |
| `por_hora[].mensagens_recebidas` | integer | não |  |
| `por_hora[].mensagens_enviadas` | integer | não |  |
| `linhas` | lista de object | não | Uma linha por dia, semana ou mês. |
| `linhas[].inicio` | data AAAA-MM-DD | não |  |
| `linhas[].fim` | data AAAA-MM-DD | não | Último dia da linha (nas pontas do período, a linha é cortada). |
| `linhas[].conversas_novas` | integer | não |  |
| `linhas[].conversas_resolvidas` | integer | não |  |
| `linhas[].mensagens_recebidas` | integer | não |  |
| `linhas[].mensagens_enviadas` | integer | não |  |
| `linhas[].mensagens_do_agente` | integer | não |  |
| `linhas[].notas_internas` | integer | não |  |

### RelatorioTempo

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `periodo` | object | não | O período que valeu na consulta (com os padrões aplicados). |
| `periodo.de` | data AAAA-MM-DD | não |  |
| `periodo.ate` | data AAAA-MM-DD | não |  |
| `periodo.dias` | integer | não |  |
| `periodo.fuso` | string | não | ex.: America/Sao_Paulo |
| `periodo.granularidade` | "dia" \| "semana" \| "mes" | não | Só nos relatórios em série. |
| `periodo.caixa_id` | uuid | não |  |
| `resumo` | object | não |  |
| `resumo.primeiras_respostas` | integer | não |  |
| `resumo.sem_resposta` | integer | não |  |
| `resumo.mediana_primeira_resposta_s` | integer ou null | não | Mediana da primeira resposta (segundos) |
| `resumo.p90_primeira_resposta_s` | integer ou null | não | 90% das conversas foram respondidas em até (segundos) |
| `resumo.respondidas_em_ate_1_min_pct` | number ou null | não |  |
| `resumo.respondidas_em_ate_5_min_pct` | number ou null | não |  |
| `resumo.respondidas_em_ate_15_min_pct` | number ou null | não |  |
| `resumo.respondidas_em_ate_1_h_pct` | number ou null | não | Porcentagem (0 a 100) das conversas com primeira resposta em até 1 hora. |
| `resumo.resolvidas` | integer | não |  |
| `resumo.mediana_resolucao_s` | integer ou null | não | Mediana até resolver (segundos) |
| `resumo.p90_resolucao_s` | integer ou null | não | 90% das conversas foram resolvidas em até (segundos) |
| `faixas_primeira_resposta` | lista de object | não |  |
| `faixas_primeira_resposta[].faixa` | string | não | ex.: 1 a 5 min |
| `faixas_primeira_resposta[].quantidade` | integer | não |  |
| `faixas_resolucao` | lista de object | não |  |
| `faixas_resolucao[].faixa` | string | não | ex.: 1 a 5 min |
| `faixas_resolucao[].quantidade` | integer | não |  |
| `linhas` | lista de object | não | Uma linha por dia, semana ou mês. |
| `linhas[].inicio` | data AAAA-MM-DD | não |  |
| `linhas[].fim` | data AAAA-MM-DD | não | Último dia da linha (nas pontas do período, a linha é cortada). |
| `linhas[].primeiras_respostas` | integer | não |  |
| `linhas[].mediana_primeira_resposta_s` | integer ou null | não | Mediana da primeira resposta (segundos) |
| `linhas[].resolvidas` | integer | não |  |
| `linhas[].mediana_resolucao_s` | integer ou null | não | Mediana até resolver (segundos) |

### RelatorioAtendentes

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `periodo` | object | não | O período que valeu na consulta (com os padrões aplicados). |
| `periodo.de` | data AAAA-MM-DD | não |  |
| `periodo.ate` | data AAAA-MM-DD | não |  |
| `periodo.dias` | integer | não |  |
| `periodo.fuso` | string | não | ex.: America/Sao_Paulo |
| `periodo.granularidade` | "dia" \| "semana" \| "mes" | não | Só nos relatórios em série. |
| `periodo.caixa_id` | uuid | não |  |
| `resumo` | object | não |  |
| `resumo.atendentes` | integer | não |  |
| `linhas` | lista de object | não | Uma linha por pessoa da equipe. |
| `linhas[].id` | uuid | não |  |
| `linhas[].nome` | string | não |  |
| `linhas[].papel` | string | não |  |
| `linhas[].conversas_atendidas` | integer | não |  |
| `linhas[].mensagens_enviadas` | integer | não |  |
| `linhas[].conversas_resolvidas` | integer | não |  |
| `linhas[].abertas_agora` | integer | não |  |
| `linhas[].primeiras_respostas` | integer | não |  |
| `linhas[].mediana_primeira_resposta_s` | integer ou null | não | Mediana da primeira resposta (segundos) |

### RelatorioCaixas

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `periodo` | object | não | O período que valeu na consulta (com os padrões aplicados). |
| `periodo.de` | data AAAA-MM-DD | não |  |
| `periodo.ate` | data AAAA-MM-DD | não |  |
| `periodo.dias` | integer | não |  |
| `periodo.fuso` | string | não | ex.: America/Sao_Paulo |
| `periodo.granularidade` | "dia" \| "semana" \| "mes" | não | Só nos relatórios em série. |
| `periodo.caixa_id` | uuid | não |  |
| `resumo` | object | não |  |
| `resumo.caixas` | integer | não |  |
| `linhas` | lista de object | não | Uma linha por caixa. |
| `linhas[].id` | uuid | não |  |
| `linhas[].nome` | string | não |  |
| `linhas[].canal` | string | não |  |
| `linhas[].telefone` | string ou null | não |  |
| `linhas[].conversas_novas` | integer | não |  |
| `linhas[].conversas_resolvidas` | integer | não |  |
| `linhas[].conversas_com_mensagens` | integer | não |  |
| `linhas[].mensagens_recebidas` | integer | não |  |
| `linhas[].mensagens_enviadas` | integer | não |  |

### RelatorioAgenteDeIa

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `periodo` | object | não | O período que valeu na consulta (com os padrões aplicados). |
| `periodo.de` | data AAAA-MM-DD | não |  |
| `periodo.ate` | data AAAA-MM-DD | não |  |
| `periodo.dias` | integer | não |  |
| `periodo.fuso` | string | não | ex.: America/Sao_Paulo |
| `periodo.granularidade` | "dia" \| "semana" \| "mes" | não | Só nos relatórios em série. |
| `periodo.caixa_id` | uuid | não |  |
| `resumo` | object | não |  |
| `resumo.conversas` | integer | não |  |
| `resumo.sem_agente` | integer | não |  |
| `resumo.com_agente` | integer | não |  |
| `resumo.passadas_para_a_equipe` | integer | não |  |
| `resumo.resolvidas_pelo_agente` | integer | não |  |
| `resumo.em_andamento` | integer | não |  |
| `resumo.taxa_resolucao` | number ou null | não | Resolvidas pelo agente / conversas com agente (0 a 1). |
| `motivos_da_passagem` | lista de object | não |  |
| `motivos_da_passagem[].motivo` | string | não |  |
| `motivos_da_passagem[].quantidade` | integer | não |  |
| `linhas` | lista de object | não | Uma linha por agente de IA. |
| `linhas[].id` | uuid | não |  |
| `linhas[].nome` | string | não |  |
| `linhas[].conversas_com_agente` | integer | não |  |
| `linhas[].passadas_para_a_equipe` | integer | não |  |
| `linhas[].resolvidas_pelo_agente` | integer | não |  |
| `linhas[].em_andamento` | integer | não |  |

### RelatorioCreditos

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `periodo` | object | não | O período que valeu na consulta (com os padrões aplicados). |
| `periodo.de` | data AAAA-MM-DD | não |  |
| `periodo.ate` | data AAAA-MM-DD | não |  |
| `periodo.dias` | integer | não |  |
| `periodo.fuso` | string | não | ex.: America/Sao_Paulo |
| `periodo.granularidade` | "dia" \| "semana" \| "mes" | não | Só nos relatórios em série. |
| `periodo.caixa_id` | uuid | não |  |
| `resumo` | object | não |  |
| `resumo.creditos_usados` | integer | não | Créditos gastos no período. |
| `resumo.creditos_disponiveis` | integer | não |  |
| `resumo.creditos_do_plano` | integer | não |  |
| `resumo.creditos_extras` | integer | não |  |
| `resumo.renovam_em` | data e hora ISO 8601 ou null | não |  |
| `por_motivo` | lista de object | não |  |
| `por_motivo[].motivo` | string | não | ex.: resposta do agente |
| `por_motivo[].creditos_usados` | integer | não |  |
| `por_motivo[].vezes` | integer | não |  |
| `linhas` | lista de object | não | Uma linha por dia, semana ou mês. |
| `linhas[].inicio` | data AAAA-MM-DD | não |  |
| `linhas[].fim` | data AAAA-MM-DD | não | Último dia da linha (nas pontas do período, a linha é cortada). |
| `linhas[].creditos_usados` | integer | não |  |

---

Página: https://docs.forsi.com.br/api/relatorios · Índice: https://docs.forsi.com.br/llms.txt · Tudo num arquivo: https://docs.forsi.com.br/llms-full.txt