Guia de relatórios

Como pedir um relatório, acompanhar a geração, baixar o arquivo e quais parâmetros cada tipo aceita.

Um relatório é um arquivo (CSV, XLSX ou PDF) gerado em segundo plano. Você pede, recebe um trabalho na fila, acompanha a situação e baixa o arquivo quando ele fica pronto. As rotas estão no grupo Relatórios da Referência da API.

RotaPara que serve
GET /reports/kindsOs tipos que este servidor gera e os formatos de cada um.
POST /reportsPede um relatório. Responde 202 com o trabalho.
GET /reports/{id}A situação do trabalho.
GET /reportsOs relatórios recentes do workspace, com filtros por tipo, situação e data.
GET /reports/{id}/fileO arquivo pronto.

Pedir um relatório

O corpo de POST /reports tem quatro campos:

CampoRegra
kindO tipo do relatório, obrigatório. Os tipos estão na seção Parâmetros por tipo, abaixo.
formatcsv, xlsx ou pdf. Vazio vale csv. O formato precisa estar entre os do tipo em GET /reports/kinds.
localeIdioma dos rótulos do arquivo, como pt.
paramsOs parâmetros do tipo, um objeto de até 64 KB.
curl -X POST "https://api.vozkoia.com/reports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "whatsapp_dispatch",
    "format": "csv",
    "locale": "pt",
    "params": { "dateFrom": "2026-10-01", "dateTo": "2026-10-31" }
  }'

A resposta é o trabalho, ainda na fila:

{
  "id": "0b6c8f3e-6a43-4c55-9d6e-2f1f0f6f4a10",
  "workspaceId": "5f1d2c7a-7f0e-4a4b-8a43-0c1d9b1e2f30",
  "requestedBy": "8e2a7c51-3b1f-4f0e-9c1a-6d5e4b3a2f10",
  "kind": "whatsapp_dispatch",
  "format": "csv",
  "locale": "pt",
  "params": { "dateFrom": "2026-10-01", "dateTo": "2026-10-31" },
  "status": "queued",
  "progress": 0,
  "sizeBytes": 0,
  "rowCount": 0,
  "expiresAt": "2026-11-09T14:00:00Z",
  "createdAt": "2026-11-02T14:00:00Z",
  "updatedAt": "2026-11-02T14:00:00Z"
}

Um pedido igual ao anterior (mesma pessoa, tipo, formato, idioma e parâmetros) feito em até 2 minutos devolve o mesmo trabalho, sem gerar outro arquivo.

Acompanhar e baixar

statusSignificado
queuedNa fila.
runningGerando; progress vai de 0 a 100.
donePronto. filename, sizeBytes e rowCount descrevem o arquivo.
failedFalhou; o motivo está em failureCode.
expiredO arquivo passou de expiresAt (7 dias depois do pedido) e não pode mais ser baixado.
failureCodeSignificado
empty_resultOs filtros não encontraram nenhuma linha.
too_many_rowsO resultado passou do limite de linhas de um arquivo.
forbiddenQuem pediu perdeu as permissões do tipo antes da geração.
unknown_kind, unsupported_format, renderer_not_configuredO servidor não gera mais esse tipo ou formato.
source_unavailable, render_failed, upload_failed, cancelledA geração não terminou; peça de novo.

GET /reports/{id}/file devolve o arquivo com o nome no cabeçalho Content-Disposition e em X-Report-Filename. Enquanto o trabalho não está pronto a resposta é 409; depois de expirado, 410.

Quem pede e quem lê

Cada tipo exige permissões, conferidas no pedido e de novo na geração. O escopo de departamento e de responsável vem sempre de quem pediu, nunca dos parâmetros. Nos tipos marcados como "só quem pediu", só a pessoa que pediu vê o trabalho e baixa o arquivo; nos demais, também quem tem as mesmas permissões do tipo.

TipoPermissõesLeitura
attendance_overviewattendance:readQuem tem as permissões
conversation_entriesread no recurso do canal de filter.entryType, como whatsapp_campaigns:read ou email_inboxes:readSó quem pediu
opportunitiesconversations:readSó quem pediu
balance_transactionsbalance:readQuem tem as permissões
whatsapp_dispatchattendance:read e whatsapp_campaigns:readSó quem pediu
whatsapp_form_responsesAs da capacidade whatsapp_forms.exportSó quem pediu
leadsAs da ação de exportar leadsQuem tem as permissões

O tipo leads nasce só pela exportação de POST /leads/actions; em POST /reports ele responde 400 report_kind_not_offered.

Formatos

Todos os tipos geram CSV. balance_transactions e whatsapp_form_responses geram também XLSX. attendance_overview, conversation_entries, opportunities e balance_transactions geram PDF quando o servidor tem a impressão em PDF ligada; GET /reports/kinds diz o que vale agora.

Erros

StatuscodeQuando
400report_invalid_paramsO tipo não consegue gerar com esses parâmetros, como um período maior que o limite do tipo.
400report_kind_not_offeredO tipo é pedido pela própria tela, como leads.
400sem códigoTipo desconhecido ou vazio, formato inválido ou fora do tipo, ou parâmetros acima de 64 KB.
403report_forbiddenFalta alguma permissão do tipo.
404sem códigoO relatório não existe ou você não pode lê-lo.
409sem códigoO arquivo ainda não está pronto.
410sem códigoO arquivo expirou.

Parâmetros por tipo

Esta seção é gerada a partir do catálogo de parâmetros dos geradores de relatório, o mesmo tipo em que cada gerador lê params. Campos não listados são ignorados.

attendance_overview

A visão de atendimento em CSV ou PDF, com os mesmos filtros da tela de atendimento.

ParâmetroTipoRegra
dateFromtextoPrimeiro dia do período, em YYYY-MM-DD. Um valor em outro formato é ignorado.
dateTotextoÚltimo dia do período, em YYYY-MM-DD, incluído inteiro. Um valor em outro formato é ignorado.
departmentIdtextoRestringe a um departamento.
memberIdtextoRestringe a um membro da equipe.
campaignIdtextoRestringe a uma campanha.
campaignTypetextoRestringe a um tipo de campanha.
channeltextoRestringe a um canal.
origintextoOrigem da conversa pela primeira mensagem: receptive, campaign, outreach ou unknown. Outro valor faz a geração falhar.
includeAibooleanoInclui os agentes de IA no ranking da equipe. Omitido vale true.
rankMetrictextoMétrica de ordenação da equipe: resolved (padrão), volume ou revenue_cents.
trendBucketsinteiroMeses da série histórica.
workspaceNametextoTexto mostrado no cabeçalho do arquivo como o workspace.
departmentLabeltextoTexto mostrado no cabeçalho do arquivo como o departamento filtrado.
memberLabeltextoTexto mostrado no cabeçalho do arquivo como o membro filtrado.
channelLabeltextoTexto mostrado no cabeçalho do arquivo como o canal filtrado.
originLabeltextoTexto mostrado no cabeçalho do arquivo como a origem filtrada.

conversation_entries

As conversas (entradas) de um canal, uma linha por conversa, com a análise e a etapa quando existem.

ParâmetroTipoRegra
filterobjetoO filtro das conversas.
filter.scopeobjetoOnde procurar.
filter.scope.containerIdtextoO id do contêiner do canal (a campanha, a conta, a página, o chat do site ou a caixa). Vazio cobre todos.
filter.scope.containerTypetextoO tipo do contêiner. No WhatsApp oficial filtra pelo tipo da campanha; no WhatsApp não oficial, campaign faz containerId ser uma campanha.
filter.scope.departmentIdslista de textosDepartamentos, sempre limitados aos de quem pediu. Uma lista sem nenhum departamento ao alcance de quem pediu dá empty_result.
filter.scope.statuseslista de textosSituações da conversa, comparadas sem diferenciar maiúsculas.
filter.scope.createdFromdata e hora RFC 3339Só no WhatsApp oficial: campanhas criadas a partir deste instante.
filter.scope.createdTodata e hora RFC 3339Só no WhatsApp oficial: campanhas criadas até este instante.
filter.entryTypetextoO canal, obrigatório: whatsapp, instagram, telegram, unofficial_whatsapp, facebook, webchat, mercadolivre, tiktok, email, rcs, sms.
filter.stageIdtextoSó conversas nesta etapa do funil.
filter.numbertextoSó conversas cujo número contém este trecho.
filter.interesttextoValor de interest da análise da conversa, sem diferenciar maiúsculas.
filter.dispositiontextoValor de disposition da análise da conversa.
filter.sentimenttextoValor de sentiment da análise da conversa.
filter.qualificationtextoValor de qualification da análise da conversa.
filter.nextActiontextoValor de nextAction da análise da conversa.
filter.attendanceQualityMininteiroNota mínima de qualidade do atendimento na análise.
filter.attendanceQualityMaxinteiroNota máxima de qualidade do atendimento na análise.
filter.hasAnalysisbooleanotrue só conversas analisadas; false só as sem análise.
filter.hasToolCallsbooleanoAceito, mas a exportação não aplica este filtro hoje.
filter.toolNametextoAceito, mas a exportação não aplica este filtro hoje.
filter.messageTypetextoAceito, mas a exportação não aplica este filtro hoje.
filter.minMessageCountinteiroAceito, mas a exportação não aplica este filtro hoje.
filter.maxMessageCountinteiroAceito, mas a exportação não aplica este filtro hoje.
labeltextoTexto usado no nome do arquivo.

opportunities

As negociações de um funil.

ParâmetroTipoRegra
pipelineIdtextoO funil das negociações.
labeltextoTexto usado no nome do arquivo.

balance_transactions

As transações do saldo do workspace.

ParâmetroTipoRegra
serviceTypetextoSó transações deste serviço: voice_campaign, voice_call, whatsapp_campaign, whatsapp_conversation, ai, manual_adjustment, top_up, addon, advertising, email, rcs, sms.
typetextocredit ou debit.
startDatetextoInício do período, em RFC 3339. Outro formato faz a geração falhar.
endDatetextoFim do período, em RFC 3339, não anterior a startDate.

leads

A exportação de leads de uma seleção congelada. Este tipo nasce só em POST /leads/actions; os parâmetros aparecem aqui para leitura do trabalho.

ParâmetroTipoRegra
snapshotIdtextoA seleção congelada de leads, criada pela ação de exportar.
addressesbooleanoInclui os endereços.
sensitivebooleanoInclui os campos sensíveis.
selectedinteiroQuantos leads a seleção tinha no pedido.

whatsapp_dispatch

O bloco de disparo de campanhas de WhatsApp da visão de atendimento (funil, dias, campanhas, motivos de falha e etiquetas), para um período de até 731 dias, conferido no pedido.

ParâmetroTipoRegra
dateFromtextoPrimeiro dia, em YYYY-MM-DD, obrigatório.
dateTotextoÚltimo dia, em YYYY-MM-DD, obrigatório; o período vai até 731 dias.
campaignIdtextoRestringe a uma campanha.
departmentIdtextoRestringe a um departamento, dentro do escopo de quem pediu.

whatsapp_form_responses

As respostas de um formulário do WhatsApp. Os parâmetros são conferidos no pedido.

ParâmetroTipoRegra
formIdtextoO id (UUID) do formulário, obrigatório.
fromtextoInício: um dia YYYY-MM-DD ou um instante RFC 3339.
totextoFim: um dia YYYY-MM-DD (incluído inteiro) ou um instante RFC 3339, não anterior a from.
originslista de textosDe onde o formulário foi enviado: inbox, template_start, template_scheduled, template_bulk, template, campaign, workflow, elo.
phoneIdslista de textosNúmeros de WhatsApp que enviaram o formulário.
versionIdslista de textosVersões do formulário.
campaignIdtextoRestringe a uma campanha.
matchtextoVazio traz todas; matched só as respostas ligadas a um envio; unmatched só as sem envio ligado.