📘 API de Demonstrações Financeiras

A API da Niunai permite acesso padronizado a demonstrações financeiras de empresas brasileiras. Consulte Balanço Patrimonial (BP) e DRE usando filtros como CNPJ, ano, tipo de documento.

🧭 Como Funciona

Buscar empresa pelo CNPJ
Listar demonstrações por filtros
Consumir dados estruturados em JSON

🔐 Autenticação

Inclua o token no header Authorization:

Authorization: Bearer SEU_TOKEN

Obtenha seu token em /painel.

📂 Endpoints

🔍 Periodos

GET /api/client/periodos?cnpj=12345678000190

🔍 Buscar Empresa

GET /api/empresas/:cnpj

📄 Buscar Demonstrações

GET /api/client/demonstracoes

Parâmetro	Tipo	Obrigatório	Descrição
cnpj	string	sim	CNPJ da empresa
periodo	string	sim	Periodo da demonstração (FY21, FY22)
tipo-df	string	não	true = consolidado

🧪 Exemplos

curl

curl -H "Authorization: Bearer SEU_TOKEN" \
        "https://api.niunai.com.br/api/demonstracoes?cnpj=12345678000195&ano=2023"

JavaScript (fetch)

fetch("https://api.niunai.com.br/api/demonstracoes?cnpj=123...", {
        headers: { Authorization: "Bearer SEU_TOKEN" }
        })

📤 Modelos de Resposta

{
        "empresa": "12345678000195",
        "ano": 2023,
        "tipo": "bp",
        "consolidado": false,
        "itens": [
            {
            "conta": "Ativo Circulante",
            "valor": 12345678.9,
            "moeda": "BRL"
            }
        ]
        }

🚫 Códigos de Erro

Código	Significado	Solução
401	Token inválido ou ausente	Verifique o header Authorization
404	Empresa ou DF não encontrada	Confirme o CNPJ e ano
429	Limite de requisições	Aguarde ou aumente o plano

📤 Upload de Documentos — Explicação

A UI de teste (TestUploadPage) realiza um envio multipart/form-data para/api/client/documentos. Campos enviados:

cnpj (string) — CNPJ da empresa (campo obrigatório).
files (arquivo) — Um ou mais PDFs. O front envia vários campos files (mesmo nome repetido).
Autenticação — Pode vir via header Authorization: Bearer <token> ou via query-string ?token=... (opção de teste).

Como o frontend envia

O componente monta um FormData com fd.append("cnpj", cnpj) e para cada arquivo fd.append("files", file). O fetch é simples: método POST, body = formdata, sem Content-Type definido (o browser coloca o boundary).

Exemplo: curl (multipart)

curl -X POST "https://api.niunai.com.br/api/client/documentos" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -F "cnpj=12345678000195" \
  -F "files=@/caminho/arquivo1.pdf" \
  -F "files=@/caminho/arquivo2.pdf"

Exemplo: fetch (browser)

const fd = new FormData();
          fd.append("cnpj", "12345678000195");
          fd.append("files", fileInput.files[0]);
          fetch("/api/client/documentos", { method: "POST", body: fd, headers: { Authorization: "Bearer SEU_TOKEN" } })
            .then(r => r.json()).then(console.log)

Formato de resposta esperado

// sucesso
          HTTP/1.1 201
          {
            "status": "ok",
            "uploaded": [
              { "id": 123, "filename": "arquivo1.pdf", "size": 34567, "gcsPath": "bucket/docs/123/arquivo1.pdf" }
            ]
          }

          // erro
          HTTP/1.1 400
          { "error": "cnpj inválido" }