LUPPA API

Valida que a chave API é válida e o serviço está acessível. Use como healthcheck antes de iniciar pipelines.

curl https://app.luppaia.pt/api/v1/ping \
  -H "Authorization: Bearer lup_xxxx"

{ "status": "success", "message": "Autenticação bem-sucedida.", "timestamp": "2026-06-18T12:00:00.000Z" }

Processa e armazena um SAF-T XML. Resposta em streaming (SSE). O evento final contém o importId.

Modo A — FormData

Modo B — JSON (ficheiro já em Storage)

{ "type": "done", "importId": "uuid", "companyId": "uuid" }

Devolve os dados públicos da empresa associada à chave API.

curl https://app.luppaia.pt/api/v1/company \
  -H "Authorization: Bearer lup_xxxx"

{
  "status": "success",
  "data": {
    "id":            "uuid",
    "name":          "Empresa Exemplo Lda",
    "nif":           "509123456",
    "cae":           "69200",
    "address":       "Rua Exemplo, 123",
    "city":          "Lisboa",
    "postal_code":   "1000-001",
    "email_contact": "geral@empresa.pt",
    "primary_color": "#4F46E5",
    "created_at":    "2026-01-15T10:00:00.000Z"
  }
}

Lista as chaves API activas da empresa. Útil para auditar o que está configurado. Inclui a chave que está a fazer o pedido.

{
  "status": "success",
  "data": [{
    "id":           "uuid",
    "name":         "Chave JANUS",
    "key_hint":     "xxxx",    // últimos 4 chars — identificação visual
    "created_at":   "2026-01-15T10:00:00.000Z",
    "last_used_at": "2026-06-18T12:00:00.000Z"
  }]
}

Lista os últimos 50 imports SAF-T da empresa, ordenados do mais recente para o mais antigo.

{
  "status": "success",
  "data": [{
    "import_id":    "uuid",
    "company_name": "Empresa Exemplo Lda",
    "fiscal_year":  "2025",
    "saft_type":    "FINAL",         // FINAL | INTERCALAR
    "framework":    "NCRF-PE",       // NCRF-PE | NC-ME
    "status":       "completed",     // completed | processing | error
    "error_message":null,
    "created_at":   "2026-06-18T12:00:00.000Z"
  }]
}

Devolve o status e metadados de um import específico. Use para polling após /api/saft/ingest.

curl https://app.luppaia.pt/api/v1/imports/{importId} \
  -H "Authorization: Bearer lup_xxxx"

{
  "status": "success",
  "data": {
    "import_id":    "uuid",
    "company_name": "Empresa Exemplo Lda",
    "fiscal_year":  "2025",
    "saft_type":    "FINAL",
    "framework":    "NCRF-PE",
    "status":       "completed",
    "error_message":null,
    "created_at":   "2026-06-18T12:00:00.000Z"
  }
}

Devolve o relatório CFO completo de um import — findings de auditoria, resumo financeiro e balancete por rubrica.

{
  "status": "success",
  "data": {
    "import_id":            "uuid",
    "fiscal_year":          "2025",
    "accounting_framework": "NCRF-PE",
    "audit": {
      "findings":          [],  // array de anomalias detectadas
      "executive_summary": "..."   // parecer em Markdown
    },
    "financial_summary": {
      "sales":          480000,
      "services":       0,
      "cmvmc":          210000,
      "fse":            95000,
      "staff":          180000,
      "net_income":     90000,
      "pre_tax_income": 95000,
      "current_tax":    5000
    },
    "balances": {
      "pl_sales":   480000,
      "bs_ac_cash": 12000,
      // ... bucket_id: amount por rubrica
    }
  }
}

Análise 100% determinística — sem IA. Valida NIFs (checksum PT), detecta gaps de numeração e erros matemáticos em faturas.

Parâmetros (multipart/form-data)

{
  "status": "success",
  "data": {
    "nif_empresa_auditada": "509123456",
    "risk_score":           42,    // 0–100
    "summary":              "Analisadas 120 fichas...",
    "anomalies": [{
      "type":               "invalid_nif",  // structure|sequence_gap|invalid_nif|math_error
      "description":        "NIF 999999999 inválido",
      "severity":           "high",        // low|medium|high|critical
      "document_reference": "FT 2025/1042"
    }]
  }
}

Auditoria multimodal de facturas PDF ou imagem. Verifica NIF, matrícula (combustíveis), cálculo de IVA e tributações autónomas. Processamento paralelo — resultados devolvidos directamente, sem persistência.

Parâmetros (multipart/form-data)

{
  "status": "success",
  "data": [{
    "fileName":  "fatura_001.pdf",
    "success":  true,
    "findings": {
      "date":                "2026-05-15",
      "doc_number":         "FT 2026/1042",
      "supplier":           "Fornecedor Exemplo Lda",
      "nif":                "509123456",
      "net":                1000.00,
      "tax":                230.00,
      "total":              1230.00,
      "category":           "Outros",
      "license_plate":      null,
      "status":             "success",  // success|warning|critical
      "risk":               null,
      "autonomous_tax_rate": 0,
      "autonomous_tax_amount":0
    }
  }]
}

Analisa notificações da Autoridade Tributária (PDF ou imagem) e extrai dados estruturados: tipo de documento, prazo, referência de pagamento e rascunho de email.

Parâmetros (multipart/form-data)

{
  "status": "success",
  "data": {
    "docType":  "Notificação de Liquidação",
    "taxType":  "IVA",
    "summary":  "Liquidação adicional de IVA — 2024-Q3.",
    "deadline": "2026-07-15",    // YYYY-MM-DD ou null
    "payment": {
      "hasPayment": true,
      "entidade":  "21",
      "referencia":"999 1234 5678",
      "valor":     "1.250,00",
      "dataLimite":"2026-07-15"
    },
    "emailDraft": {
      "subject": "Notificação AT — Liquidação IVA",
      "body":    "Exmo(a) Sr(a)..."
    }
  }
}

Cruza o SAF-T com o CSV do e-Fatura. Identifica faturas em falta e divergências de valor. 100% determinístico.

Parâmetros (multipart/form-data)

{
  "status": "success",
  "data": {
    "nif_empresa_auditada":      "509123456",
    "summary": {
      "total_faturas_analisadas":  340,
      "total_faturas_em_falta":    3,
      "total_faturas_divergentes": 1,
      "valor_iva_em_risco":        138.00,
      "valor_base_em_risco":       600.00
    },
    "missing_invoices":   [],
    "divergent_invoices": []
  }
}

Motor determinístico em 4 camadas; IA apenas para resíduos genuinamente ambíguos.

Parâmetros (multipart/form-data)

{
  "status": "success",
  "data": {
    "summary": {
      "total_movimentos_banco":       87,
      "movimentos_reconciliados":     82,
      "valor_reconciliado":          124580.40,
      "movimentos_banco_pendentes":   5,
      "valor_banco_por_reconciliar":  1200.00,
      "faturas_pendentes":           9,
      "valor_faturas_por_reconciliar":4350.00
    },
    "unreconciled_bank_transactions": [],
    "unpaid_invoices":               []
  }
}

Confronta saldos de terceiros no SAF-T com o extrato de conta-corrente do terceiro.

Parâmetros (multipart/form-data)

{
  "status": "success",
  "data": {
    "summary": {
      "saldo_saft":              12450.00,
      "saldo_terceiro":          12680.00,
      "desvio":                  230.00,
      "faturas_reconciliadas":   18,
      "faturas_em_falta_saft":   1,
      "faturas_em_falta_terceiro":0
    },
    "missing_in_saft":        [],
    "missing_in_third_party": []
  }
}

Extrai métricas financeiras do SAF-T e gera observações de gestão. Para o relatório completo com findings de auditoria, use GET /api/v1/reports/:importId após processar na plataforma.

Parâmetros (multipart/form-data)

{
  "status": "success",
  "data": {
    "financial_summary": {
      "total_rendimentos":   480000.00,
      "vendas_e_servicos":   475000.00,
      "total_gastos":        390000.00,
      "margem_bruta":        210000.00,
      "resultado_operacional":90000.00
    },
    "insights": ["A margem bruta de 44% está acima da média sectorial..."]
  }
}

Gera o Anexo ao Relatório & Contas (NCRF-PE ou NC-ME) a partir de um import já processado. Devolve ficheiro Word (.docx) ou JSON estruturado.

Parâmetros (application/json)

curl https://app.luppaia.pt/api/v1/annex/generate \
  -H "Authorization: Bearer lup_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"import_id":"uuid","format":"docx","config":{"fiscal_year":2025}}' \
  --output Anexo_2025.docx

Binary DOCX — Content-Disposition: attachment; filename="Anexo_NCRF_PE_Empresa_2025.docx"

{ "status": "success", "data": { /* estrutura completa do anexo */ } }