📊 Documentação de Solicitações de Relatório

📋 Visão Geral

As Solicitações de Relatório permitem solicitar a geração de arquivos exportados com dados estruturados da loja — pedidos, produtos, clientes, categorias, marcas, tabelas de frete, sitemaps e feeds de comparadores.

Cada solicitação é processada de forma assíncrona: após a criação, um worker em segundo plano executa a consulta e produz o arquivo no formato configurado.

O cliente deve monitorar o status da solicitação até que ela conclua e, em seguida, acionar o endpoint de download para obter o arquivo gerado.

O recurso é indicado para integrações de BI, exportações recorrentes, auditorias de catálogo e qualquer fluxo que exija dados em lote fora do ciclo de requisição síncrona.

🔄 Entidades Envolvidas

Solicitação de relatório (ReportRequest)

É o objeto central que representa uma requisição de exportação.

Reúne todas as configurações da consulta: qual entidade será exportada (reportCode), quais campos serão incluídos (fields), filtros (condition), ordenação (order), parâmetros adicionais (params) e o formato de saída (output).

A solicitação também registra metadados de autoria — userId, userName e userEmail do usuário que a criou — e as marcações de tempo createdAt, executedAt e finishedAt para rastreabilidade completa do ciclo de vida.

Códigos de relatório (reportCode)

O campo reportCode define qual conjunto de dados será consultado. Os valores aceitos são:

• order — pedidos individuais
• orderGroup — grupos de pedidos
• product — produtos do catálogo
• customer — clientes cadastrados
• brand — marcas
• category — categorias
• shippingTable — tabela de frete (requer entityId com o identificador da tabela)
• productSitemap — sitemap de produtos
• categorySitemap — sitemap de categorias
• brandSitemap — sitemap de marcas
• pageSitemap — sitemap de páginas
• productImageSitemap — sitemap de imagens de produtos
• googleShopping — feed para Google Shopping

Formatos de saída (output)

O campo output determina o formato do arquivo gerado. Os valores aceitos são csv, xlsx e xml.

Ciclo de vida e status

Após a criação, a solicitação percorre os seguintes estados:

• pending — solicitação criada, aguardando processamento pelo worker assíncrono.
• running — worker iniciou a execução da consulta e está gerando o arquivo.
• finished — processamento concluído com sucesso; os arquivos estão disponíveis em files[].
• error — a execução falhou; o campo errorCode descreve a causa.

Download (ReportRequestDownload)

Ao acionar o endpoint de download de uma solicitação com status finished, a API emite um redirecionamento 302 para a URL do arquivo gerado.

O objeto de download registra id, userId, userName, userEmail e createdAt como histórico de quem acessou o arquivo.

📌 Notas e Considerações

• O processamento é assíncrono — a criação retorna imediatamente com status pending.
• Monitore o status via o endpoint de detalhe antes de tentar o download.
• O campo entityId é obrigatório apenas para o reportCode igual a shippingTable, onde deve conter o identificador da tabela de frete a ser exportada.
• O campo showSensitiveData controla o mascaramento de dados sensíveis (como CPF e e-mail de clientes) na exportação.
• Quando false, esses valores são omitidos ou mascarados no arquivo gerado.
• O endpoint de download retorna um redirecionamento HTTP 302 para a URL do arquivo.
• Certifique-se de que o cliente HTTP utilizado na integração segue redirecionamentos automaticamente, ou trate o cabeçalho Location da resposta manualmente.
• Relatórios com status error expõem a causa no campo errorCode.
• Corrija os parâmetros da solicitação e crie uma nova solicitação para tentar novamente.

📋 Listagem de Solicitações de Relatório

Descrição

Endpoint utilizado para listar todas as solicitações de relatório registradas na loja, com suporte a paginação, filtros e ordenação.

O acesso às solicitações é controlado pelo perfil do usuário autenticado: usuários com perfil não-admin (nível acima de 2) visualizam somente as próprias solicitações, pois o filtro por userId é aplicado automaticamente pelo sistema.

Usuários com perfil admin visualizam todas as solicitações da loja, sem restrição de usuário.

Por padrão, o campo opcional downloads não é retornado em cada registro.

Para carregá-lo, informe-o no parâmetro fields — útil para auditar o histórico de downloads de cada solicitação.

Parâmetros

🏷️ Headers Obrigatórios

🗂️ Campos Disponíveis (fields)

🔍 Campos de Condição Disponíveis

🔃 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url {{MAIN_URL}}/reports/requests \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "fields": ["downloads"],
7    "limit": 10,
8    "offset": 0,
9    "order": [],
10    "condition": {
11      "type": "AND",
12      "conditions": []
13    }
14  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 42,
7        "storeId": 1,
8        "tradePolicyId": 1,
9        "salesChannelId": 1,
10        "entityId": null,
11        "reportCode": "order",
12        "name": "Exportação de Pedidos - Março",
13        "fields": ["id", "status", "createdAt"],
14        "condition": { "type": "AND", "conditions": [] },
15        "order": [],
16        "params": [],
17        "output": "csv",
18        "showSensitiveData": false,
19        "status": "finished",
20        "files": [
21          { "url": "https://storage.exemplo.com.br/reports/pedidos-marco.csv" }
22        ],
23        "errorCode": null,
24        "downloads": [
25          {
26            "id": 7,
27            "userId": 2,
28            "userName": "Admin Loja",
29            "userEmail": "admin@minhaloja.com.br",
30            "createdAt": "2026-03-15 14:30:00"
31          }
32        ],
33        "userId": 2,
34        "userName": "Admin Loja",
35        "userEmail": "admin@minhaloja.com.br",
36        "createdAt": "2026-03-15 10:00:00",
37        "executedAt": "2026-03-15 10:01:00",
38        "finishedAt": "2026-03-15 10:02:00"
39      }
40    ],
41    "pagination": {
42      "limit": 10,
43      "offset": 0,
44      "pages": 1,
45      "registers": 1
46    }
47  }
48}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🔍 Detalhamento de Solicitação de Relatório

Descrição

Endpoint utilizado para carregar os dados completos de uma solicitação de relatório, identificada pelo reportRequestId informado na URL.

O relacionamento downloads é sempre carregado automaticamente na resposta, sem necessidade de solicitá-lo via parâmetro fields.

Controle de acesso: usuários não-administradores (perfil superior a 2) só conseguem visualizar suas próprias solicitações. Usuários administradores podem consultar qualquer solicitação da loja.

Caso o reportRequestId não pertença à loja autenticada ou não exista, a API retorna o erro UAPPI_TOOLS_REPORT_REQUEST_NOT_FOUND.

Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/reports/requests/42 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 42,
5    "storeId": 1,
6    "tradePolicyId": 1,
7    "salesChannelId": 1,
8    "entityId": null,
9    "reportCode": "order",
10    "name": "Exportação de Pedidos - Março",
11    "fields": ["id", "status", "createdAt"],
12    "condition": { "type": "AND", "conditions": [] },
13    "order": [],
14    "params": [],
15    "output": "csv",
16    "showSensitiveData": false,
17    "status": "finished",
18    "files": [
19      { "url": "https://storage.exemplo.com.br/reports/pedidos-marco.csv" }
20    ],
21    "errorCode": null,
22    "downloads": [
23      {
24        "id": 7,
25        "userId": 2,
26        "userName": "Admin Loja",
27        "userEmail": "admin@minhaloja.com.br",
28        "createdAt": "2026-03-15 14:30:00"
29      }
30    ],
31    "userId": 2,
32    "userName": "Admin Loja",
33    "userEmail": "admin@minhaloja.com.br",
34    "createdAt": "2026-03-15 10:00:00",
35    "executedAt": "2026-03-15 10:01:00",
36    "finishedAt": "2026-03-15 10:02:00"
37  }
38}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

➕ Criação de Solicitação de Relatório

📋 Descrição

Endpoint responsável por criar uma nova solicitação de relatório para a loja autenticada.

O processamento é assíncrono: a solicitação é criada imediatamente com o status pending e um worker em segundo plano é responsável por executar e gerar os arquivos do relatório.

Os campos userId, userName e userEmail são capturados automaticamente a partir do token de autenticação — não devem ser enviados no corpo da requisição.

O campo entityId é obrigatório apenas quando reportCode for shippingTable; para todos os demais tipos de relatório, ele pode ser omitido.

O array fields deve conter os nomes das colunas a serem exportadas, sendo que cada reportCode possui seu próprio conjunto de campos válidos, validado pelo servidor.

O campo showSensitiveData controla se dados sensíveis como CPF e e-mail serão exibidos sem mascaramento. Quando omitido, o padrão é false.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

Parâmetros obrigatórios:

📌 Valores Aceitos para reportCode

👤 Campos Aceitos em fields para customer

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/reports/requests \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "tradePolicyId": 1,
7    "salesChannelId": 1,
8    "reportCode": "order",
9    "name": "Exportação de Pedidos - Março 2026",
10    "fields": ["id", "status", "customerName", "totalValue"],
11    "output": "csv",
12    "condition": {
13      "type": "AND",
14      "conditions": []
15    },
16    "order": []
17  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "storeId": 1,
6    "tradePolicyId": 1,
7    "salesChannelId": 1,
8    "entityId": null,
9    "reportCode": "order",
10    "name": "Exportação de Pedidos - Março 2026",
11    "fields": ["id", "status", "customerName", "totalValue"],
12    "condition": { "type": "AND", "conditions": [] },
13    "order": [],
14    "params": [],
15    "output": "csv",
16    "showSensitiveData": false,
17    "status": "pending",
18    "files": [],
19    "errorCode": null,
20    "downloads": [],
21    "userId": 2,
22    "userName": "Admin Loja",
23    "userEmail": "admin@minhaloja.com.br",
24    "createdAt": "2026-03-15 10:00:00",
25    "executedAt": null,
26    "finishedAt": null
27  }
28}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

⚠️ Erro de validação retornado

O response retornado quando o payload enviado é inválido é:

1{
2  "status": false,
3  "data": {
4    "code": 400,
5    "errorCode": "INVALID_REQUEST_PAYLOAD",
6    "message": "The requested payload is not valid!",
7    "details": {
8      "tradePolicyId": ["The trade policy id field is required."],
9      "reportCode": ["The report code field is required."]
10    }
11  }
12}

✏️ Atualização de Solicitação de Relatório

📋 Descrição

Endpoint responsável por atualizar uma solicitação de relatório, identificada pelo reportRequestId informado na URL.

Apenas o campo name pode ser modificado após a criação da solicitação. Todos os demais campos — como reportCode, fields, output, condition, order e showSensitiveData — são imutáveis e não são aceitos no corpo desta requisição.

A atualização não possui restrição de status: o name pode ser alterado independentemente do estado atual da solicitação, seja ele pending, running, finished ou error.

A resposta retorna o registro completo e atualizado da solicitação de relatório, incluindo sempre o campo downloads, com os dados refletindo a alteração recém-aplicada.

O escopo de loja é aplicado automaticamente: a solicitação de relatório deve pertencer à loja do usuário autenticado.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/reports/requests/42 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Exportação de Pedidos - Abril 2026"
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 42,
5    "storeId": 1,
6    "tradePolicyId": 1,
7    "salesChannelId": 1,
8    "entityId": null,
9    "reportCode": "order",
10    "name": "Exportação de Pedidos - Abril 2026",
11    "fields": ["id", "status", "customerName", "totalValue"],
12    "condition": { "type": "AND", "conditions": [] },
13    "order": [],
14    "params": [],
15    "output": "csv",
16    "showSensitiveData": false,
17    "status": "finished",
18    "files": [
19      { "url": "https://storage.exemplo.com.br/reports/pedidos-abril.csv" }
20    ],
21    "errorCode": null,
22    "downloads": [],
23    "userId": 2,
24    "userName": "Admin Loja",
25    "userEmail": "admin@minhaloja.com.br",
26    "createdAt": "2026-04-10 08:00:00",
27    "executedAt": "2026-04-10 08:01:00",
28    "finishedAt": "2026-04-10 08:02:00"
29  }
30}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🗑️ Exclusão de Solicitação de Relatório

📋 Descrição

Endpoint responsável por remover permanentemente uma solicitação de relatório, identificada pelo reportRequestId na URL.

A exclusão pode ser realizada independentemente do status atual da solicitação — seja pending, running, finished ou error, o registro pode ser removido a qualquer momento.

Quando o relatório já possui arquivos gerados, eles são excluídos recursivamente do armazenamento AWS S3 antes da remoção do registro no banco de dados.

Relatórios nos formatos CSV e XLSX são removidos do caminho de armazenamento de planilhas, enquanto relatórios XML são removidos de seu caminho dedicado no bucket correspondente.

Após a limpeza dos arquivos, o registro da solicitação é removido do banco de dados.

Este endpoint não requer corpo na requisição — apenas o parâmetro reportRequestId na URL.

O escopo da loja é aplicado automaticamente: a solicitação deve pertencer à loja do usuário autenticado.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/reports/requests/42 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

⬇️ Download de Solicitação de Relatório

📋 Descrição

Endpoint responsável por iniciar o download do arquivo gerado por uma solicitação de relatório.

A resposta de sucesso deste endpoint é atípica: em vez de retornar um corpo JSON, o servidor emite um HTTP 302 Found redirecionando o cliente para uma URL pré-assinada do S3.

O cliente deve seguir o redirecionamento presente no header Location para efetuar o download do arquivo.

A URL pré-assinada expira em 60 segundos após a emissão — após esse prazo, o link se torna inválido e um novo download deve ser solicitado.

Este endpoint só está disponível quando a solicitação de relatório possui status finished e o formato de saída é csv ou xlsx.

Relatórios no formato xml não podem ser baixados por este endpoint — eles utilizam um mecanismo de entrega diferente.

Cada execução de download é registrada na tabela report_request_download com os dados do usuário autenticado (userId, userName, userEmail) e o instante (createdAt).

O histórico de downloads fica visível no campo downloads retornado pelos endpoints de listagem e detalhe da solicitação.

O escopo da loja é validado — o usuário só consegue baixar relatórios pertencentes à sua própria loja.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/reports/requests/42/download \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 302 Found

A resposta não possui corpo JSON.

O download é iniciado por meio dos headers da resposta:

1HTTP/1.1 302 Found
2Location: https://s3.exemplo.com/reports/report-2026-04-10-part-1.zip?X-Amz-Expires=60&...
3Content-Disposition: attachment; filename="report-2026-04-10-part-1.zip"

O header Location contém a URL pré-assinada do S3 para o arquivo compactado.

O header Content-Disposition sinaliza ao cliente que o conteúdo deve ser tratado como um anexo para download.

A maioria dos clientes HTTP — como curl com a flag -L, navegadores e bibliotecas como Guzzle — segue redirecionamentos automaticamente, iniciando o download sem necessidade de tratamento adicional.

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🔄 Forçar Reprocessamento de Solicitação de Relatório

📋 Descrição

Este endpoint força o reprocessamento de uma solicitação de relatório, enfileirando-a novamente para geração assíncrona.

Ao ser executado com sucesso, o status da solicitação é atualizado para running e o campo executedAt é atualizado com o instante atual.

O reprocessamento pode ser disparado independentemente do status atual da solicitação — os valores pending, running, finished e error são todos aceitos sem restrição de status.

A única restrição existente é o cooldown de 5 minutos, que se aplica exclusivamente quando o status atual é running: nesse caso, é necessário aguardar ao menos 5 minutos desde o último executedAt antes de forçar novamente.

Quando o status atual é diferente de running (por exemplo, pending, finished ou error), o cooldown não se aplica e o reprocessamento é disparado imediatamente.

A geração do relatório é assíncrona — o endpoint retorna true imediatamente enquanto o worker processa o relatório em segundo plano.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/reports/requests/42/force \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.