O que são Seções?
Quando você cria um relatório através da API, ele é dividido em seções (sections). Cada seção representa uma parte específica do relatório, como “Resumo Executivo”, “Análise Financeira”, ou “Conclusão”.
As seções são geradas de forma assíncrona - você receberá o relatório imediatamente, mas o conteúdo das seções será processado em segundo plano pela nossa IA.
Estrutura de uma Seção
Cada seção contém as seguintes informações:
| Campo | Tipo | Descrição |
|---|
id | string | Identificador único da seção |
title | string | Título/nome da seção |
status | string | Status do processamento (veja abaixo) |
order | number | Ordem da seção no relatório (1, 2, 3…) |
content | string | Conteúdo gerado pela IA (texto) |
Status das Seções
Uma seção pode ter os seguintes status:
| Status | Significado | O que fazer |
|---|
queued | Na fila para processamento | Aguarde, será processada em breve |
processing | Sendo gerada pela IA | Aguarde, o conteúdo está sendo criado |
done | Concluída com sucesso | O conteúdo está pronto em content |
error | Erro no processamento | Verifique logs ou tente novamente |
Exemplo Prático
{
"id": "rep_xyz789",
"status": "processing",
"sections": [
{
"id": "sec_abc123",
"title": "Resumo Executivo",
"status": "done",
"order": 1,
"content": "Este relatório apresenta uma análise completa da Empresa XYZ. Principais pontos: ..."
},
{
"id": "sec_def456",
"title": "Análise Financeira",
"status": "processing",
"order": 2,
"content": null
},
{
"id": "sec_ghi789",
"title": "Conclusão",
"status": "queued",
"order": 3,
"content": null
}
]
}
- ✅ Primeira seção está pronta e você pode usar o conteúdo
- ⏳ Segunda seção está sendo processada
- ⏸️ Terceira seção está na fila aguardando
Como Usar as Seções
1. Criar um Relatório
POST /reports
{
"target": {
"document": "12345678901"
},
"template": "tpl_abc123"
}
{
"id": "rep_xyz789",
"sections": [
{
"id": "sec_abc123",
"title": "Resumo Executivo",
"status": "queued",
"order": 1,
"content": null
}
]
}
2. Verificar o Progresso
Para ver se as seções foram processadas, faça uma nova requisição GET:
Resposta:
{
"id": "rep_xyz789",
"status": "completed",
"sections": [
{
"id": "sec_abc123",
"title": "Resumo Executivo",
"status": "done",
"order": 1,
"content": "Análise completa da empresa..."
}
]
}
3. Reprocessar Seções
Se precisar gerar novamente o conteúdo de um relatório:
POST /reports/rep_xyz789/run
Monitoramento em Tempo Real
Polling (Recomendado)
Faça requisições periódicas para verificar o status:
async function waitForReport(reportId) {
while (true) {
const response = await fetch(`https://api.base39.com.br/v1/reports/${reportId}`);
const report = await response.json();
// Verifica se todas as seções estão prontas
const allDone = report.sections.every(s => s.status === 'done');
if (allDone) {
return report;
}
// Aguarda 5 segundos antes de verificar novamente
await new Promise(resolve => setTimeout(resolve, 5000));
}
}
Webhooks (Futuro)
Em breve, você poderá configurar webhooks para receber notificações quando as seções forem concluídas.
Boas Práticas
✅ Faça
- Verifique o status antes de usar o conteúdo
- Implemente retry para seções com erro
- Use polling com intervalos adequados (5-10 segundos)
- Processe seções individualmente conforme ficam prontas
❌ Evite
- Não assuma que o conteúdo está pronto imediatamente
- Não faça polling muito frequente (< 3 segundos)
- Não ignore o campo
status
- Não processe seções com
content: null
Tempos Estimados
| Tipo de Seção | Tempo Estimado |
|---|
| Resumo curto | 10-30 segundos |
| Análise média | 30-60 segundos |
| Relatório completo | 1-3 minutos |
Os tempos podem variar dependendo da complexidade da análise e da carga do sistema.
Exemplos de Código
Python
import requests
import time
def create_and_wait_report(document, template):
# Criar relatório
response = requests.post(
'https://api.base39.com.br/v1/reports',
headers={'Authorization': 'Bearer YOUR_TOKEN'},
json={'target': {'document': document}, 'template': template}
)
report_id = response.json()['id']
# Aguardar conclusão
while True:
response = requests.get(
f'https://api.base39.com.br/v1/reports/{report_id}',
headers={'Authorization': 'Bearer YOUR_TOKEN'}
)
report = response.json()
# Verificar se todas as seções estão prontas
all_done = all(s['status'] == 'done' for s in report['sections'])
if all_done:
return report
time.sleep(5)
# Usar
report = create_and_wait_report('12345678901', 'tpl_abc123')
for section in report['sections']:
print(f"{section['title']}: {section['content'][:100]}...")
JavaScript/TypeScript
async function createAndWaitReport(document: string, template: string) {
// Criar relatório
const createResponse = await fetch('https://api.base39.com.br/v1/reports', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
target: { document },
template
})
});
const { id } = await createResponse.json();
// Aguardar conclusão
while (true) {
const response = await fetch(`https://api.base39.com.br/v1/reports/${id}`, {
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const report = await response.json();
// Verificar se todas as seções estão prontas
const allDone = report.sections.every(s => s.status === 'done');
if (allDone) {
return report;
}
await new Promise(resolve => setTimeout(resolve, 5000));
}
}
// Usar
const report = await createAndWaitReport('12345678901', 'tpl_abc123');
report.sections.forEach(section => {
console.log(`${section.title}:`, section.content.substring(0, 100));
});
Tratamento de Erros
async function processReport(reportId) {
const report = await getReport(reportId);
for (const section of report.sections) {
switch (section.status) {
case 'done':
// Processar conteúdo
console.log(section.content);
break;
case 'error':
// Tentar reprocessar
console.error(`Erro na seção ${section.title}`);
await retrySection(reportId);
break;
case 'processing':
case 'queued':
// Aguardar
console.log(`Aguardando seção ${section.title}...`);
break;
}
}
}
Perguntas Frequentes
As seções são geradas por IA que precisa analisar múltiplas fontes de dados, realizar pesquisas e processar informações. Isso leva alguns segundos a minutos dependendo da complexidade.
Posso processar apenas algumas seções?
Atualmente, todas as seções são processadas juntas. Em breve, será possível processar seções individualmente.
O que acontece se houver erro em uma seção?
A seção ficará com status: "error". As outras seções continuarão o processamento normalmente. Você pode tentar reprocessar o relatório completo usando o endpoint /run.
Quanto tempo os relatórios ficam disponíveis?
Os relatórios e suas seções ficam disponíveis indefinidamente na sua conta.
