API do Lumina Flow Builder

Bem-vindo à documentação da API do Lumina Flow Builder. Esta API REST permite gerenciar flows, executar automações e integrar o Flow Builder com seus sistemas.

Visão Geral

A API do Lumina Flow Builder fornece acesso programático a todas as funcionalidades da plataforma:

• Criar, atualizar e deletar flows
• Executar flows manualmente
• Consultar histórico de execuções
• Gerenciar variáveis e configurações
• Webhook endpoints para triggers

URL Base

https://api.lumina.app.br/v1

Ambientes

• Produção: https://api.lumina.app.br/v1
• Staging: https://staging-api.lumina.app.br/v1
• Desenvolvimento: http://localhost:3000/v1

Autenticação

Todas as requisições à API requerem autenticação via API Key.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lumina.app.br/v1/flows

Veja mais detalhes em Autenticação.

Estrutura de Resposta

Resposta de Sucesso

{
  "success": true,
  "data": {
    "id": "flow_123",
    "name": "Meu Flow",
    "status": "active"
  }
}

Resposta de Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Nome do flow é obrigatório",
    "details": {
      "field": "name",
      "constraint": "required"
    }
  }
}

Códigos de Status HTTP

Código	Significado
200	OK - Requisição bem-sucedida
201	Created - Recurso criado com sucesso
204	No Content - Sucesso sem conteúdo de resposta
400	Bad Request - Dados inválidos
401	Unauthorized - Autenticação falhou
403	Forbidden - Sem permissão
404	Not Found - Recurso não encontrado
429	Too Many Requests - Rate limit excedido
500	Internal Server Error - Erro no servidor
503	Service Unavailable - Serviço temporariamente indisponível

Rate Limiting

A API implementa rate limiting para garantir estabilidade:

• Tier Free: 100 requisições/hora
• Tier Pro: 1.000 requisições/hora
• Tier Enterprise: 10.000 requisições/hora

Headers de Rate Limit

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Resposta de Rate Limit Excedido

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit excedido. Tente novamente em 3600 segundos.",
    "details": {
      "retryAfter": 3600
    }
  }
}

Paginação

Endpoints que retornam listas suportam paginação:

GET /flows?page=2&limit=20

Parâmetros

• page: Número da página (padrão: 1)
• limit: Itens por página (padrão: 20, máximo: 100)

Resposta Paginada

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": true
  }
}

Filtros e Ordenação

Filtros

GET /flows?status=active&tag=production

Ordenação

GET /flows?sortBy=createdAt&order=desc

Parâmetros: - sortBy: Campo para ordenação - order: asc (crescente) ou desc (decrescente)

Recursos Principais

Flows

Gerencie seus flows de automação.

# Listar flows
GET /flows

# Obter flow específico
GET /flows/:id

# Criar flow
POST /flows

# Atualizar flow
PATCH /flows/:id

# Deletar flow
DELETE /flows/:id

Documentação completa: Endpoints de Flows

Executions

Consulte e gerencie execuções de flows.

# Listar execuções
GET /executions

# Obter execução específica
GET /executions/:id

# Executar flow manualmente
POST /flows/:id/execute

# Cancelar execução
POST /executions/:id/cancel

Documentação completa: Endpoints de Executions

Webhooks

Configure webhooks para receber eventos.

# Listar webhooks
GET /webhooks

# Criar webhook
POST /webhooks

# Deletar webhook
DELETE /webhooks/:id

Exemplos de Uso

Node.js

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://api.lumina.app.br/v1',
  headers: {
    'Authorization': `Bearer ${process.env.LUMINA_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Listar flows
async function listFlows() {
  const response = await api.get('/flows');
  return response.data.data;
}

// Executar flow
async function executeFlow(flowId, data) {
  const response = await api.post(`/flows/${flowId}/execute`, {
    data: data
  });
  return response.data.data;
}

Python

import requests
import os

API_KEY = os.environ.get('LUMINA_API_KEY')
BASE_URL = 'https://api.lumina.app.br/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Listar flows
def list_flows():
    response = requests.get(f'{BASE_URL}/flows', headers=headers)
    return response.json()['data']

# Executar flow
def execute_flow(flow_id, data):
    response = requests.post(
        f'{BASE_URL}/flows/{flow_id}/execute',
        headers=headers,
        json={'data': data}
    )
    return response.json()['data']

cURL

# Listar flows
curl -X GET https://api.lumina.app.br/v1/flows \
  -H "Authorization: Bearer YOUR_API_KEY"

# Executar flow
curl -X POST https://api.lumina.app.br/v1/flows/flow_123/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "userId": "user_456",
      "action": "process"
    }
  }'

Webhooks

Receber Eventos

Configure um webhook para receber eventos em tempo real:

POST /webhooks
{
  "url": "https://meusite.com/webhook",
  "events": ["flow.execution.completed", "flow.execution.failed"],
  "secret": "webhook_secret_123"
}

Validar Webhook

Valide a assinatura do webhook:

const crypto = require('crypto');

function validateWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === hash;
}

Versionamento

A API usa versionamento de URL. A versão atual é v1.

Quando uma nova versão for lançada, a versão anterior será mantida por pelo menos 12 meses.

Changelog

v1.0.0 (atual)

• Release inicial da API
• Endpoints de Flows e Executions
• Suporte a webhooks
• Autenticação via API Key

SDKs Oficiais

Em breve: - JavaScript/TypeScript SDK - Python SDK - PHP SDK

Suporte

Documentação

• Autenticação
• Flows API
• Executions API

Comunidade

• Discord: discord.gg/lumina
• GitHub: github.com/lumina/api-examples

Contato

• Email: api@lumina.app.br
• Status: status.lumina.app.br

Termos de Uso

Ao usar a API do Lumina Flow Builder, você concorda com nossos Termos de Serviço e Política de Privacidade.

---

Próximos passos: 1. Configure sua autenticação 2. Explore os endpoints de Flows 3. Aprenda sobre Executions