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

# Referência

> Informações do sistema e importação em lote via Excel

O módulo de Utilitários reúne endpoints que não pertencem a um fluxo de negócio específico: consulta de informações do ambiente conectado e importação em lote de dados a partir de planilhas Excel (.xlsx).

## Informações do sistema

`GET /v2/sistema/info` retorna metadados do usuário autenticado e da empresa vinculada ao token.

<Info>
  Útil para validar rapidamente se o token e a base conectada estão corretos antes de iniciar uma integração.
</Info>

**Resposta:**

```json theme={null}
{
  "success": true,
  "data": {
    "codigoDaEmpresa": 1,
    "nomeComercial": "Sua Empresa Ltda",
    "codigoDoUsuario": "integracao",
    "nomeDoUsuario": "Usuário de Integração",
    "email": "integracao@suaempresa.com.br",
    "administrador": false,
    "ativo": true
  }
}
```

## Importar dados em lote

Os endpoints `/v2/importacao/*` recebem um arquivo Excel (.xlsx) em `multipart/form-data` e importam cadastros, lançamentos financeiros ou movimentações de estoque em lote — por exemplo, `/v2/importacao/cliente` para clientes ou `/v2/importacao/contasreceber` para títulos de Contas a Receber.

<Tip>
  Chame primeiro com `?preview=true` para conferir os registros lidos do arquivo **sem gravar**. Só depois envie `preview=false` (ou omita o parâmetro) para efetivar a importação.
</Tip>

**Exemplo:**

```bash theme={null}
POST /v2/importacao/cliente?preview=true
Content-Type: multipart/form-data

ArquivoExcel: clientes.xlsx
```

<Note>
  O corpo espera um arquivo Excel (`.xlsx`). Erros de layout do arquivo (colunas ausentes, tipos inválidos) retornam `400`.
</Note>

## Importação assíncrona (fila)

Arquivos maiores — como notas fiscais de serviço e contas a pagar — usam um fluxo em duas etapas via fila:

<Steps>
  <Step title="Enfileirar o arquivo">
    Envie o arquivo para `/v2/importacao/nota-fiscal-servico/fila` (ou o endpoint `/fila` equivalente do recurso desejado). A rota apenas enfileira o processamento e retorna o `id` do log de importação criado — o processamento efetivo ocorre depois, em background.
  </Step>

  <Step title="Processar (quando aplicável)">
    Para alguns recursos, dispare o processamento do arquivo já enfileirado com `POST /v2/importacao/processar-arquivo/{id}`, usando o `id` do log obtido na etapa anterior. Um e-mail de notificação é enviado ao concluir.
  </Step>

  <Step title="Acompanhar o resultado">
    Consulte `GET /v2/importacao/log-importacao/{id}` periodicamente para saber se a importação terminou e se houve linhas rejeitadas.
  </Step>
</Steps>

<Tip>
  Consulte o log de importação para conferir tanto o status do processamento quanto o detalhe de eventuais linhas rejeitadas.
</Tip>