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.
| Rota | Para que serve |
|---|---|
GET /reports/kinds | Os tipos que este servidor gera e os formatos de cada um. |
POST /reports | Pede um relatório. Responde 202 com o trabalho. |
GET /reports/{id} | A situação do trabalho. |
GET /reports | Os relatórios recentes do workspace, com filtros por tipo, situação e data. |
GET /reports/{id}/file | O arquivo pronto. |
Pedir um relatório
O corpo de POST /reports tem quatro campos:
| Campo | Regra |
|---|---|
kind | O tipo do relatório, obrigatório. Os tipos estão na seção Parâmetros por tipo, abaixo. |
format | csv, xlsx ou pdf. Vazio vale csv. O formato precisa estar entre os do tipo em GET /reports/kinds. |
locale | Idioma dos rótulos do arquivo, como pt. |
params | Os 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
status | Significado |
|---|---|
queued | Na fila. |
running | Gerando; progress vai de 0 a 100. |
done | Pronto. filename, sizeBytes e rowCount descrevem o arquivo. |
failed | Falhou; o motivo está em failureCode. |
expired | O arquivo passou de expiresAt (7 dias depois do pedido) e não pode mais ser baixado. |
failureCode | Significado |
|---|---|
empty_result | Os filtros não encontraram nenhuma linha. |
too_many_rows | O resultado passou do limite de linhas de um arquivo. |
forbidden | Quem pediu perdeu as permissões do tipo antes da geração. |
unknown_kind, unsupported_format, renderer_not_configured | O servidor não gera mais esse tipo ou formato. |
source_unavailable, render_failed, upload_failed, cancelled | A 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.
| Tipo | Permissões | Leitura |
|---|---|---|
attendance_overview | attendance:read | Quem tem as permissões |
conversation_entries | read no recurso do canal de filter.entryType, como whatsapp_campaigns:read ou email_inboxes:read | Só quem pediu |
opportunities | conversations:read | Só quem pediu |
balance_transactions | balance:read | Quem tem as permissões |
whatsapp_dispatch | attendance:read e whatsapp_campaigns:read | Só quem pediu |
whatsapp_form_responses | As da capacidade whatsapp_forms.export | Só quem pediu |
leads | As da ação de exportar leads | Quem 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
| Status | code | Quando |
|---|---|---|
| 400 | report_invalid_params | O tipo não consegue gerar com esses parâmetros, como um período maior que o limite do tipo. |
| 400 | report_kind_not_offered | O tipo é pedido pela própria tela, como leads. |
| 400 | sem código | Tipo desconhecido ou vazio, formato inválido ou fora do tipo, ou parâmetros acima de 64 KB. |
| 403 | report_forbidden | Falta alguma permissão do tipo. |
| 404 | sem código | O relatório não existe ou você não pode lê-lo. |
| 409 | sem código | O arquivo ainda não está pronto. |
| 410 | sem código | O 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
attendance_overviewA visão de atendimento em CSV ou PDF, com os mesmos filtros da tela de atendimento.
| Parâmetro | Tipo | Regra |
|---|---|---|
dateFrom | texto | Primeiro dia do período, em YYYY-MM-DD. Um valor em outro formato é ignorado. |
dateTo | texto | Último dia do período, em YYYY-MM-DD, incluído inteiro. Um valor em outro formato é ignorado. |
departmentId | texto | Restringe a um departamento. |
memberId | texto | Restringe a um membro da equipe. |
campaignId | texto | Restringe a uma campanha. |
campaignType | texto | Restringe a um tipo de campanha. |
channel | texto | Restringe a um canal. |
origin | texto | Origem da conversa pela primeira mensagem: receptive, campaign, outreach ou unknown. Outro valor faz a geração falhar. |
includeAi | booleano | Inclui os agentes de IA no ranking da equipe. Omitido vale true. |
rankMetric | texto | Métrica de ordenação da equipe: resolved (padrão), volume ou revenue_cents. |
trendBuckets | inteiro | Meses da série histórica. |
workspaceName | texto | Texto mostrado no cabeçalho do arquivo como o workspace. |
departmentLabel | texto | Texto mostrado no cabeçalho do arquivo como o departamento filtrado. |
memberLabel | texto | Texto mostrado no cabeçalho do arquivo como o membro filtrado. |
channelLabel | texto | Texto mostrado no cabeçalho do arquivo como o canal filtrado. |
originLabel | texto | Texto mostrado no cabeçalho do arquivo como a origem filtrada. |
conversation_entries
conversation_entriesAs conversas (entradas) de um canal, uma linha por conversa, com a análise e a etapa quando existem.
| Parâmetro | Tipo | Regra |
|---|---|---|
filter | objeto | O filtro das conversas. |
filter.scope | objeto | Onde procurar. |
filter.scope.containerId | texto | O 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.containerType | texto | O 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.departmentIds | lista de textos | Departamentos, sempre limitados aos de quem pediu. Uma lista sem nenhum departamento ao alcance de quem pediu dá empty_result. |
filter.scope.statuses | lista de textos | Situações da conversa, comparadas sem diferenciar maiúsculas. |
filter.scope.createdFrom | data e hora RFC 3339 | Só no WhatsApp oficial: campanhas criadas a partir deste instante. |
filter.scope.createdTo | data e hora RFC 3339 | Só no WhatsApp oficial: campanhas criadas até este instante. |
filter.entryType | texto | O canal, obrigatório: whatsapp, instagram, telegram, unofficial_whatsapp, facebook, webchat, mercadolivre, tiktok, email, rcs, sms. |
filter.stageId | texto | Só conversas nesta etapa do funil. |
filter.number | texto | Só conversas cujo número contém este trecho. |
filter.interest | texto | Valor de interest da análise da conversa, sem diferenciar maiúsculas. |
filter.disposition | texto | Valor de disposition da análise da conversa. |
filter.sentiment | texto | Valor de sentiment da análise da conversa. |
filter.qualification | texto | Valor de qualification da análise da conversa. |
filter.nextAction | texto | Valor de nextAction da análise da conversa. |
filter.attendanceQualityMin | inteiro | Nota mínima de qualidade do atendimento na análise. |
filter.attendanceQualityMax | inteiro | Nota máxima de qualidade do atendimento na análise. |
filter.hasAnalysis | booleano | true só conversas analisadas; false só as sem análise. |
filter.hasToolCalls | booleano | Aceito, mas a exportação não aplica este filtro hoje. |
filter.toolName | texto | Aceito, mas a exportação não aplica este filtro hoje. |
filter.messageType | texto | Aceito, mas a exportação não aplica este filtro hoje. |
filter.minMessageCount | inteiro | Aceito, mas a exportação não aplica este filtro hoje. |
filter.maxMessageCount | inteiro | Aceito, mas a exportação não aplica este filtro hoje. |
label | texto | Texto usado no nome do arquivo. |
opportunities
opportunitiesAs negociações de um funil.
| Parâmetro | Tipo | Regra |
|---|---|---|
pipelineId | texto | O funil das negociações. |
label | texto | Texto usado no nome do arquivo. |
balance_transactions
balance_transactionsAs transações do saldo do workspace.
| Parâmetro | Tipo | Regra |
|---|---|---|
serviceType | texto | Só transações deste serviço: voice_campaign, voice_call, whatsapp_campaign, whatsapp_conversation, ai, manual_adjustment, top_up, addon, advertising, email, rcs, sms. |
type | texto | credit ou debit. |
startDate | texto | Início do período, em RFC 3339. Outro formato faz a geração falhar. |
endDate | texto | Fim do período, em RFC 3339, não anterior a startDate. |
leads
leadsA 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âmetro | Tipo | Regra |
|---|---|---|
snapshotId | texto | A seleção congelada de leads, criada pela ação de exportar. |
addresses | booleano | Inclui os endereços. |
sensitive | booleano | Inclui os campos sensíveis. |
selected | inteiro | Quantos leads a seleção tinha no pedido. |
whatsapp_dispatch
whatsapp_dispatchO 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âmetro | Tipo | Regra |
|---|---|---|
dateFrom | texto | Primeiro dia, em YYYY-MM-DD, obrigatório. |
dateTo | texto | Último dia, em YYYY-MM-DD, obrigatório; o período vai até 731 dias. |
campaignId | texto | Restringe a uma campanha. |
departmentId | texto | Restringe a um departamento, dentro do escopo de quem pediu. |
whatsapp_form_responses
whatsapp_form_responsesAs respostas de um formulário do WhatsApp. Os parâmetros são conferidos no pedido.
| Parâmetro | Tipo | Regra |
|---|---|---|
formId | texto | O id (UUID) do formulário, obrigatório. |
from | texto | Início: um dia YYYY-MM-DD ou um instante RFC 3339. |
to | texto | Fim: um dia YYYY-MM-DD (incluído inteiro) ou um instante RFC 3339, não anterior a from. |
origins | lista de textos | De onde o formulário foi enviado: inbox, template_start, template_scheduled, template_bulk, template, campaign, workflow, elo. |
phoneIds | lista de textos | Números de WhatsApp que enviaram o formulário. |
versionIds | lista de textos | Versões do formulário. |
campaignId | texto | Restringe a uma campanha. |
match | texto | Vazio traz todas; matched só as respostas ligadas a um envio; unmatched só as sem envio ligado. |