API Documentation - LAQUS Cadastro Automático

Objetivo

Esta API permite automatizar o cadastro de emissores no sistema Frontier da LAQUS, incluindo enriquecimento de dados via Receita Federal e Uplexis.

📡 Como Usar Esta API

Esta API é servida pelo Flask e pode ser consumida de duas formas:

Via Interface Web: A interface gráfica em https://fastcadastro.laqus.io já consome estas APIs automaticamente.
Via Chamadas Diretas: Você pode chamar os endpoints diretamente usando ferramentas como curl, Postman, ou código Python/JavaScript.

Autenticação: As APIs utilizam autenticação por sessão Flask. Para usar via chamadas diretas:

Faça login via POST /auth/login para obter o cookie de sessão
Inclua o cookie session em todas as requisições subsequentes
Ou acesse a interface web, faça login, e use as mesmas credenciais do navegador

Base URL

// Produção
https://fastcadastro.laqus.io/api

// Desenvolvimento Local
http://localhost:5000/api

💡 Use a URL de produção para integrações externas. A URL local é apenas para desenvolvimento.

Exemplo de Uso (Python)

import requests

BASE_URL = "https://fastcadastro.laqus.io/api"
session = requests.Session()

# 1. Login
login = session.post(f"{BASE_URL}/auth/login", json={
    "username": "seu_usuario",
    "password": "sua_senha"
})

# 2. Usar APIs (sessão já autenticada)
emissores = session.get(f"{BASE_URL}/emissores")
print(emissores.json())

Fluxo de Trabalho

Criar emissor com dados básicos (CNPJ, Razão Social)
Enriquecer dados via Receita Federal (opcional)
Buscar representantes legais via Uplexis (opcional)
Fazer upload de documentos
Cadastrar no Frontier (API externa)

Formatos de Resposta

Todas as respostas são retornadas em formato JSON.

{
  "success": true,
  "data": {...},
  "message": "Operação realizada com sucesso"
}

🎯 Sobre Este Diagrama

O diagrama abaixo mostra o fluxo completo do sistema, desde o upload da planilha até o cadastro final no Frontier Admin. Clique na imagem para ampliar.

📋 Etapas do Fluxo:

Upload: Planilha Excel ou entrada manual de CNPJs
Completar: Consulta automática à Receita Federal
Uplexis: Due Diligence e análise de risco (opcional)
Matriz: Importação de matriz de risco PLD-CFT
Representantes: Cadastro de representantes legais
Revisar: Validação final dos dados
Cadastrar: Envio para API Frontier
Concluído: Verificação e download de relatórios

POST /auth/login Realizar login

Autentica um usuário e retorna um token de sessão.

Parâmetros do Body

username string obrigatório

Nome de usuário

password string obrigatório

Senha do usuário

Exemplo de Resposta

{
  "success": true,
  "user": {
    "id": 1,
    "username": "admin",
    "nome": "Administrador"
  }
}

GET /auth/check Verificar autenticação

Verifica se o usuário está autenticado na sessão atual.

Exemplo de Resposta

{
  "authenticated": true,
  "user": {
    "id": 1,
    "username": "admin"
  }
}

POST /emissor Criar novo emissor

Cria um novo emissor no sistema com dados básicos.

Parâmetros do Body

cnpj string obrigatório

CNPJ do emissor (com ou sem formatação)

razao_social string obrigatório

Razão social do emissor

email string opcional

Email de contato

Exemplo de Resposta

{
  "success": true,
  "emissor": {
    "id": 1,
    "cnpj": "12345678000190",
    "razao_social": "Empresa Exemplo LTDA",
    "email": "contato@exemplo.com"
  }
}

GET /emissor/{id} Obter emissor

Retorna os dados de um emissor específico.

Parâmetros da URL

id integer obrigatório

ID do emissor

PUT /emissor/{id} Atualizar emissor

Atualiza os dados de um emissor existente.

DELETE /emissor/{id} Remover emissor

Remove um emissor do sistema.

POST /representante Criar representante

Adiciona um representante legal a um emissor.

Parâmetros do Body

emissor_id integer obrigatório

ID do emissor

nome string obrigatório

Nome completo do representante

cpf string obrigatório

CPF do representante

GET /emissor/{id}/representantes Listar representantes

Lista todos os representantes de um emissor.

Restrições de Upload

Formatos suportados: PDF, JPG, PNG
Tamanho máximo: 10MB por arquivo
Nome do arquivo: Apenas caracteres alfanuméricos, hífens e underlines

POST /emissor/documentos/upload Upload de documentos

Faz upload de documentos para um emissor.

Parâmetros (multipart/form-data)

emissor_id integer obrigatório

ID do emissor

files file[] obrigatório

Arquivos para upload (múltiplos)

DELETE /emissor/{id}/documentos/limpar Limpar documentos

Remove todos os documentos de um emissor.

POST /receita/consultar Consultar CNPJ

Consulta dados de um CNPJ na Receita Federal e enriquece os dados do emissor.

Parâmetros do Body

emissor_id integer obrigatório

ID do emissor

Dados Retornados

A consulta retorna: endereço completo, situação cadastral, capital social, atividade econômica principal, entre outros.

POST /uplexis/consultar Buscar representantes

Busca representantes legais de um CNPJ na base Uplexis.

Parâmetros do Body

emissor_id integer obrigatório

ID do emissor

Representantes Encontrados

Os representantes são automaticamente adicionados ao emissor com seus dados completos (nome, CPF, qualificação).

POST /frontier/cadastrar Cadastrar no Frontier

Envia os dados do emissor para cadastro no sistema Frontier (API externa da LAQUS).

Parâmetros do Body

emissores_ids integer[] obrigatório

Array com IDs dos emissores a cadastrar

ambiente string obrigatório

Ambiente Frontier: sandbox, homolog ou production

Pré-requisitos

Antes de cadastrar no Frontier, certifique-se de que:

Dados do emissor estão completos
Representantes legais foram adicionados (CPF com 11 dígitos)
Documentos foram enviados

GET /api/verificar-frontier Verificar cadastros no Frontier

Consulta a API do Frontier para verificar se os emissores do processamento atual foram cadastrados com sucesso.

Resposta

{
  "success": true,
  "total": 3,
  "confirmados_frontier": 3,
  "ambiente": "homolog",
  "emissores": [
    {
      "cnpj": "12345678000190",
      "razao_social": "Empresa Exemplo",
      "encontrado_frontier": true,
      "frontier_id": "abc123",
      "dados_frontier": {
        "id": "abc123",
        "documentos": 5,
        "docs_enviados": 5,
        "docs_pendentes": 0
      }
    }
  ]
}

Uso

Este endpoint é chamado automaticamente na etapa 8 (Concluído) para confirmar que os emissores foram cadastrados. Também pode ser chamado manualmente clicando em "Verificar Novamente".

POST /api/frontier/login Autenticar no Frontier

Autentica no Frontier usando API Key e Secret Key para obter token de acesso.

Parâmetros do Body

ambiente string obrigatório

Ambiente: "sandbox", "homolog" ou "production"

Credenciais

As credenciais (API Key e Secret Key) são configuradas no arquivo .env do servidor. Cada ambiente tem suas próprias credenciais.

Documentação da API

Base URL

Exemplo de Uso (Python)

Fluxo de Trabalho

Formatos de Resposta

📊 Resumo do Projeto

📋 Etapas do Fluxo:

Autenticação

Emissores

Representantes

Documentos

Receita Federal

Uplexis

Frontier API