> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base39.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Entendendo as Seções dos Relatórios

> Como interpretar e usar as seções que compõem os relatórios gerados

## 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

```json theme={null}
{
  "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
    }
  ]
}
```

Neste exemplo:

* ✅ 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

```bash theme={null}
POST /reports
{
  "target": {
    "document": "12345678901"
  },
  "template": "tpl_abc123"
}
```

**Resposta:**

```json theme={null}
{
  "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:

```bash theme={null}
GET /reports/rep_xyz789
```

**Resposta:**

```json theme={null}
{
  "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:

```bash theme={null}
POST /reports/rep_xyz789/run
```

Isso iniciará um novo processamento de todas as seções.

## Monitoramento em Tempo Real

### Polling (Recomendado)

Faça requisições periódicas para verificar o status:

```javascript theme={null}
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    |

<Note>
  Os tempos podem variar dependendo da complexidade da análise e da carga do sistema.
</Note>

## Exemplos de Código

### Python

```python theme={null}
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

```typescript theme={null}
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

```javascript theme={null}
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

### Por que as seções não estão prontas imediatamente?

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.