{
  "info": {
    "name": "Avalia — API de Integração (Token)",
    "description": "# Avalia — API de Integração\n\nConsulta dos dados da **sua contabilidade** no Avalia, para integrar com os seus sistemas.\n\n## Autenticação\n\nToda requisição leva o seu token no cabeçalho **`X-Api-Key`**:\n\n```\nX-Api-Key: sk_9xK2mQ...\n```\n\nO token é gerado por você mesmo, no Avalia, em **Configurações → Integrações de Sistemas → Gerar Token**. Você pode ter vários (um por sistema), e desativar um não afeta os outros.\n\n> **Trate o token como uma senha.** Ele dá acesso a todos os dados da sua contabilidade. Se vazar, desative-o na mesma tela e gere outro.\n\nPara usar esta collection, preencha a variável `apiKey` (aba **Variables**) com o seu token.\n\n## O que o token pode fazer\n\n- **Ler**: atendimentos, notas, racional da avaliação, transcrição do chat, feedbacks, insights e o consumo do mês.\n- **Escrever**: apenas `POST /webhook/atendimento`, para enviar um atendimento já encerrado do seu sistema para ser avaliado.\n\nQualquer outra escrita é recusada. O token também só enxerga a **sua** contabilidade — não existe forma de acessar dados de outra.\n\n## Respostas de erro\n\n| Código | O que significa | O que fazer |\n| --- | --- | --- |\n| **401** | Token inválido, desativado ou excluído | Confira o valor; se foi desativado, gere um novo |\n| **403** | Operação não permitida para token de API | Só leitura + o webhook são liberados |\n| **402** | Sua assinatura não está vigente | Vale só para o webhook; as consultas continuam funcionando |\n| **404** | Registro não encontrado (ou de outra contabilidade) | Confira o id |\n| **429** | Cota mensal de análises esgotada | Vale só para o webhook; aguarde a virada do ciclo |\n\nErros trazem um corpo JSON com `erro` (mensagem) e, quando aplicável, `motivo` (código estável para tratar no seu código).\n\n## Ambiente\n\nAjuste a variável `baseUrl` para o ambiente que você vai consumir.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_postman_id": "a7c1d200-9001-4b10-8f21-000000000092"
  },
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "key",
        "value": "X-Api-Key",
        "type": "string"
      },
      {
        "key": "value",
        "value": "{{apiKey}}",
        "type": "string"
      },
      {
        "key": "in",
        "value": "header",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.avalia.com.br",
      "type": "string",
      "description": "Base da API. Troque pelo endereço do ambiente que você vai consumir."
    },
    {
      "key": "apiKey",
      "value": "",
      "type": "string",
      "description": "Seu token (sk_...), gerado em Configurações > Integrações de Sistemas > Gerar Token."
    },
    {
      "key": "atendimentoId",
      "value": "1",
      "type": "string",
      "description": "Id numérico de um atendimento, obtido no campo `id` da listagem."
    },
    {
      "key": "insightExternalId",
      "value": "",
      "type": "string",
      "description": "Id de um insight, obtido no campo `id` de GET /insights."
    }
  ],
  "item": [
    {
      "name": "Atendimentos",
      "item": [
        {
          "name": "Listar atendimentos (paginado + filtros)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/atendimentos/filtrar?page=0&size=20",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "atendimentos",
                "filtrar"
              ],
              "query": [
                {
                  "key": "page",
                  "value": "0",
                  "description": "Página, começando em 0.",
                  "disabled": false
                },
                {
                  "key": "size",
                  "value": "20",
                  "description": "Itens por página (padrão 20).",
                  "disabled": false
                },
                {
                  "key": "sort",
                  "value": "dataFechamento,desc",
                  "description": "campo,direção. Ver a descrição para os campos aceitos.",
                  "disabled": true
                },
                {
                  "key": "periodo",
                  "value": "ULTIMOS_7_DIAS",
                  "description": "HOJE | ONTEM | ULTIMOS_7_DIAS | PERSONALIZADO.",
                  "disabled": true
                },
                {
                  "key": "dataInicio",
                  "value": "2026-08-01",
                  "description": "Só com periodo=PERSONALIZADO. Formato aaaa-mm-dd.",
                  "disabled": true
                },
                {
                  "key": "dataFim",
                  "value": "2026-08-31",
                  "description": "Só com periodo=PERSONALIZADO. Formato aaaa-mm-dd.",
                  "disabled": true
                },
                {
                  "key": "status",
                  "value": "CONCLUIDO",
                  "description": "IMPORTADO | EM_ANDAMENTO | CONCLUIDO | NAO_CONCLUIDO | ARQUIVADO.",
                  "disabled": true
                },
                {
                  "key": "cliente",
                  "value": "",
                  "description": "Busca parcial pelo nome do cliente.",
                  "disabled": true
                },
                {
                  "key": "contatoCliente",
                  "value": "",
                  "description": "Busca parcial pelo contato (telefone/nome).",
                  "disabled": true
                },
                {
                  "key": "atendidoPor",
                  "value": "",
                  "description": "Busca parcial pelo nome do atendente.",
                  "disabled": true
                },
                {
                  "key": "ticketId",
                  "value": "",
                  "description": "Número do chamado no sistema de origem.",
                  "disabled": true
                },
                {
                  "key": "notaMinima",
                  "value": "7",
                  "description": "Traz só atendimentos com nota igual ou acima deste valor.",
                  "disabled": true
                }
              ]
            },
            "description": "Lista paginada de atendimentos, com filtros. **É o endpoint principal para integração.**\n\n**Resposta**: `{ records: [...], page, size, total, totalPages }`.\n\nCada item traz `id`, `ticketId`, `dataFechamento`, `cliente`, `contatoCliente`, `atendidoPor`, `status`, as notas por dimensão (`notaComunicacao`, `notaProfissionalismo`, `notaResolucao`), a `notaAtendente`, a `notaCliente` e `possuiFeedback`.\n\n**Paginação**: `page` começa em **0**; `size` padrão 20.\n\n**Ordenação** (`sort=campo,desc`): `effectiveDate` (padrão), `dataFechamento`, `notaMedia`, `cliente`, `atendidoPor`, `ticketId`, `status`, `createdAt`.\n\n> ⚠️ Um nome de campo fora dessa lista faz a requisição falhar com **500**. Use apenas os campos acima.\n\n**Período**: use `periodo` com um dos atalhos (`HOJE`, `ONTEM`, `ULTIMOS_7_DIAS`) **ou** `periodo=PERSONALIZADO` junto de `dataInicio` e `dataFim`.\n\n**Status**: `IMPORTADO` (aguardando análise), `EM_ANDAMENTO`, `CONCLUIDO` (avaliado), `NAO_CONCLUIDO`, `ARQUIVADO` (inelegível ou com erro — some da listagem padrão)."
          },
          "response": []
        },
        {
          "name": "Listar atendimentos (sem paginação)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/atendimentos",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "atendimentos"
              ]
            },
            "description": "Lista simples dos atendimentos da contabilidade, sem filtros nem paginação.\n\n> Para uso em integração prefira **`/atendimentos/filtrar`**: além dos filtros, ele pagina — o que importa quando o volume cresce."
          },
          "response": []
        },
        {
          "name": "Detalhe do atendimento (racional da avaliação)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/atendimentos/{{atendimentoId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "atendimentos",
                "{{atendimentoId}}"
              ]
            },
            "description": "Avaliação completa de um atendimento: `notaAtendente`, `notaCliente`, `resumo`, o array `avaliacoes` (uma entrada por dimensão avaliada, com nota e justificativa) e `chat`.\n\nÉ o conteúdo que a tela do Avalia mostra ao abrir o racional.\n\n**404** se o id não existir ou for de outra contabilidade."
          },
          "response": []
        },
        {
          "name": "Transcrição do chat",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/atendimentos/{{atendimentoId}}/chat",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "atendimentos",
                "{{atendimentoId}}",
                "chat"
              ]
            },
            "description": "Conversa original do atendimento, em Markdown, no campo `textContent`.\n\nInclui cabeçalho com cliente/atendente/datas e as mensagens. Áudios transcritos e anexos aparecem sinalizados no texto.\n\n**404** quando o atendimento não tem chat guardado."
          },
          "response": []
        },
        {
          "name": "Feedbacks dados pela equipe",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/atendimentos/feedbacks",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "atendimentos",
                "feedbacks"
              ]
            },
            "description": "Todos os feedbacks que a sua equipe registrou sobre as avaliações, mais recentes primeiro.\n\nCada item: `atendimentoId`, `ticketId`, `cliente`, `feedbackOk` (nota dada ao trabalho da IA), `feedbackDescritivo` (texto livre) e `createdAt`."
          },
          "response": []
        },
        {
          "name": "Último feedback de um atendimento",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/atendimentos/{{atendimentoId}}/feedback",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "atendimentos",
                "{{atendimentoId}}",
                "feedback"
              ]
            },
            "description": "Feedback mais recente registrado para aquele atendimento. **404** se ainda não houver nenhum."
          },
          "response": []
        }
      ],
      "description": "Consulta dos atendimentos e das avaliações feitas pela IA."
    },
    {
      "name": "Insights",
      "item": [
        {
          "name": "Listar insights",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/insights",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "insights"
              ],
              "query": [
                {
                  "key": "type",
                  "value": "semanal",
                  "description": "semanal | gestor | atendente. Sem o parâmetro, traz todos.",
                  "disabled": true
                }
              ]
            },
            "description": "Histórico dos relatórios de IA já gerados, sem o conteúdo (resposta leve).\n\nCada item: `id`, `type`, `atendente`, `periodoInicio`, `periodoFim`, `totalAtendimentos`, `preview` e `createdAt`. Use o `id` para buscar o relatório completo.\n\nFiltre por tipo com `?type=`: **`semanal`** (o resumo automático de sexta-feira), **`gestor`** (visão geral do período) ou **`atendente`** (por colaborador)."
          },
          "response": []
        },
        {
          "name": "Detalhe do insight",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/insights/{{insightExternalId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "insights",
                "{{insightExternalId}}"
              ]
            },
            "description": "Relatório completo. O campo `content` traz o conteúdo estruturado do relatório — o mesmo que a tela do Avalia renderiza.\n\n> A estrutura de `content` varia conforme o `type` e evolui junto com os relatórios. Se for exibir no seu sistema, navegue os campos de forma defensiva.\n\n**404** se o id não existir ou for de outra contabilidade."
          },
          "response": []
        }
      ],
      "description": "Relatórios de IA já gerados (semanal, por gestor e por atendente)."
    },
    {
      "name": "Consumo do plano",
      "item": [
        {
          "name": "Consumo do mês / limite do plano",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/contabilidades/rate-limit",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "contabilidades",
                "rate-limit"
              ]
            },
            "description": "Consumo de análises no ciclo de faturamento vigente — é o número que aparece como *\"305 de 500 atendimentos avaliados / Limite mensal do plano\"* no painel do Avalia.\n\n```json\n{ \"limiteDiario\": 2000, \"usadoHoje\": 0, \"restanteHoje\": 2000, \"resetEm\": \"2026-09-01T05:00:00-03:00\" }\n```\n\n> ⚠️ **Atenção aos nomes dos campos.** Eles dizem \"diário\"/\"hoje\" por compatibilidade com versões antigas da API, mas **os valores são MENSAIS**:\n> - `limiteDiario` = teto **mensal** do seu plano\n> - `usadoHoje` = análises consumidas **no ciclo atual**\n> - `restanteHoje` = quanto **ainda resta no ciclo**\n> - `resetEm` = quando o contador zera\n>\n> Se for montar um indicador, rotule como *mensal* — os nomes dos campos induzem ao erro."
          },
          "response": []
        }
      ],
      "description": "Quanto da cota mensal de análises já foi usada."
    },
    {
      "name": "Envio de atendimento (webhook)",
      "item": [
        {
          "name": "Enviar atendimento (chat em texto)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/webhook/atendimento",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "webhook",
                "atendimento"
              ]
            },
            "description": "Envia um atendimento **já encerrado** do seu sistema para ser avaliado pelo Avalia. É a **única escrita** permitida ao token.\n\n**Corpo**\n\n- `chat` (obrigatório) — a conversa. Aceita uma **string** (uma mensagem por linha, no formato `Quem: mensagem`) ou um **objeto/array JSON** com a estrutura do seu sistema.\n- `ticketId` (opcional) — o número do chamado no seu sistema. Sem ele, geramos um identificador e adotamos o número que for encontrado no texto.\n\n**Resposta 202**: `{ \"atendimentoId\": 286 }`. O processamento é **assíncrono** — a análise leva alguns instantes. Consulte o resultado depois em `/atendimentos/filtrar` (ou no detalhe, pelo id devolvido).\n\n**Cuidados**\n\n- Envie o atendimento **uma vez só**. Reenvios com o mesmo `ticketId` não criam duplicata, mas evite depender disso.\n- Cada atendimento enviado **consome uma análise** da sua cota mensal.\n- **402** quando a assinatura não está vigente e **429** quando a cota do mês acabou. As consultas continuam funcionando nos dois casos.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"ticketId\": \"12345\",\n  \"chat\": \"Cliente: bom dia, preciso da guia do INSS\\nAtendente: bom dia! Já te envio\\nAtendente: segue em anexo\\nCliente: recebi, obrigado!\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "response": []
        },
        {
          "name": "Enviar atendimento (chat em JSON)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/webhook/atendimento",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "webhook",
                "atendimento"
              ]
            },
            "description": "Mesma rota acima, com o `chat` em JSON em vez de texto.\n\nUse quando for mais simples mandar a estrutura que o seu sistema já tem — nós achatamos o JSON para texto antes de analisar. Quanto mais claro estiver quem falou o quê e quando, melhor a avaliação.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"ticketId\": \"12346\",\n  \"chat\": {\n    \"protocolo\": \"12346\",\n    \"cliente\": \"Padaria do Bairro LTDA\",\n    \"atendente\": \"Roberta\",\n    \"mensagens\": [\n      {\n        \"de\": \"cliente\",\n        \"em\": \"2026-08-19T09:12:00\",\n        \"texto\": \"bom dia, a nota fiscal saiu?\"\n      },\n      {\n        \"de\": \"atendente\",\n        \"em\": \"2026-08-19T09:15:00\",\n        \"texto\": \"bom dia! saiu sim, te mando agora\"\n      },\n      {\n        \"de\": \"cliente\",\n        \"em\": \"2026-08-19T09:20:00\",\n        \"texto\": \"recebi, valeu!\"\n      }\n    ]\n  }\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "response": []
        }
      ],
      "description": "A única escrita liberada ao token: mandar um atendimento encerrado para ser avaliado."
    }
  ]
}