Pular para conteúdo

Flows API

A API de Flows permite gerenciar seus fluxos de automação programaticamente.

Endpoints

Listar Flows

Lista todos os flows da sua conta.

GET /flows

Query Parameters

Parâmetro Tipo Descrição
page integer Número da página (padrão: 1)
limit integer Itens por página (padrão: 20, máx: 100)
status string Filtrar por status: active, inactive, draft
tag string Filtrar por tag
search string Buscar por nome ou descrição
sortBy string Campo para ordenação: name, createdAt, updatedAt
order string Ordem: asc, desc

Exemplo de Requisição

curl -X GET "https://api.lumina.app.br/v1/flows?status=active&limit=10" \
  -H "Authorization: Bearer lumina_sk_your_api_key"

Resposta de Sucesso (200)

{
  "success": true,
  "data": [
    {
      "id": "flow_abc123",
      "name": "Processar Pedidos WhatsApp",
      "description": "Automatiza processamento de pedidos via WhatsApp",
      "status": "active",
      "tags": ["whatsapp", "vendas"],
      "trigger": {
        "type": "webhook",
        "config": {
          "url": "https://api.lumina.app.br/v1/webhooks/wh_xyz789"
        }
      },
      "nodes": [
        {
          "id": "node_1",
          "type": "http-request",
          "name": "Validar Estoque",
          "config": {...}
        }
      ],
      "createdAt": "2025-01-10T10:00:00Z",
      "updatedAt": "2025-01-15T14:30:00Z",
      "lastExecutedAt": "2025-01-15T16:45:00Z",
      "executionCount": 1523
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Obter Flow

Retorna detalhes de um flow específico.

GET /flows/:id

Path Parameters

Parâmetro Tipo Descrição
id string ID do flow

Exemplo de Requisição

curl -X GET "https://api.lumina.app.br/v1/flows/flow_abc123" \
  -H "Authorization: Bearer lumina_sk_your_api_key"

Resposta de Sucesso (200)

{
  "success": true,
  "data": {
    "id": "flow_abc123",
    "name": "Processar Pedidos WhatsApp",
    "description": "Automatiza processamento de pedidos via WhatsApp",
    "status": "active",
    "tags": ["whatsapp", "vendas"],
    "variables": {
      "apiKey": "encrypted_value",
      "maxRetries": 3
    },
    "trigger": {
      "type": "webhook",
      "config": {
        "url": "https://api.lumina.app.br/v1/webhooks/wh_xyz789",
        "method": "POST"
      }
    },
    "nodes": [
      {
        "id": "node_1",
        "type": "http-request",
        "name": "Validar Estoque",
        "position": { "x": 100, "y": 100 },
        "config": {
          "method": "GET",
          "url": "https://api.example.com/stock/{{ $trigger.body.productId }}"
        }
      },
      {
        "id": "node_2",
        "type": "if-else",
        "name": "Verificar Disponibilidade",
        "position": { "x": 300, "y": 100 },
        "config": {
          "condition": "{{ $nodes['node_1'].output.available === true }}"
        }
      }
    ],
    "edges": [
      {
        "source": "node_1",
        "target": "node_2"
      }
    ],
    "createdAt": "2025-01-10T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "lastExecutedAt": "2025-01-15T16:45:00Z",
    "executionCount": 1523,
    "averageExecutionTime": 2450
  }
}

Resposta de Erro (404)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Flow não encontrado"
  }
}

Criar Flow

Cria um novo flow.

POST /flows

Request Body

{
  "name": "Meu Novo Flow",
  "description": "Descrição do flow",
  "status": "draft",
  "tags": ["tag1", "tag2"],
  "variables": {
    "apiUrl": "https://api.example.com",
    "timeout": 30000
  },
  "trigger": {
    "type": "webhook",
    "config": {
      "method": "POST"
    }
  },
  "nodes": [
    {
      "id": "node_1",
      "type": "http-request",
      "name": "Fetch Data",
      "position": { "x": 100, "y": 100 },
      "config": {
        "method": "GET",
        "url": "{{ $vars.apiUrl }}/data"
      }
    }
  ],
  "edges": []
}

Campos

Campo Tipo Obrigatório Descrição
name string Sim Nome do flow
description string Não Descrição do flow
status string Não Status: active, inactive, draft (padrão: draft)
tags array Não Tags para organização
variables object Não Variáveis globais do flow
trigger object Sim Configuração do trigger
nodes array Sim Lista de nós
edges array Não Conexões entre nós

Exemplo de Requisição

curl -X POST "https://api.lumina.app.br/v1/flows" \
  -H "Authorization: Bearer lumina_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu Novo Flow",
    "description": "Automatização de exemplo",
    "status": "draft",
    "trigger": {
      "type": "webhook"
    },
    "nodes": []
  }'

Resposta de Sucesso (201)

{
  "success": true,
  "data": {
    "id": "flow_new123",
    "name": "Meu Novo Flow",
    "description": "Automatização de exemplo",
    "status": "draft",
    "tags": [],
    "variables": {},
    "trigger": {
      "type": "webhook",
      "config": {
        "url": "https://api.lumina.app.br/v1/webhooks/wh_generated"
      }
    },
    "nodes": [],
    "edges": [],
    "createdAt": "2025-01-15T17:00:00Z",
    "updatedAt": "2025-01-15T17:00:00Z"
  }
}

Resposta de Erro (400)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "details": {
      "name": "Nome é obrigatório",
      "trigger": "Trigger é obrigatório"
    }
  }
}

Atualizar Flow

Atualiza um flow existente.

PATCH /flows/:id

Path Parameters

Parâmetro Tipo Descrição
id string ID do flow

Request Body

{
  "name": "Nome Atualizado",
  "description": "Nova descrição",
  "status": "active",
  "tags": ["novo-tag"],
  "nodes": [...]
}

Nota: Apenas os campos enviados serão atualizados.

Exemplo de Requisição

curl -X PATCH "https://api.lumina.app.br/v1/flows/flow_abc123" \
  -H "Authorization: Bearer lumina_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "tags": ["produção", "whatsapp"]
  }'

Resposta de Sucesso (200)

{
  "success": true,
  "data": {
    "id": "flow_abc123",
    "name": "Processar Pedidos WhatsApp",
    "status": "active",
    "tags": ["produção", "whatsapp"],
    "updatedAt": "2025-01-15T17:30:00Z"
  }
}

Deletar Flow

Deleta um flow permanentemente.

DELETE /flows/:id

Path Parameters

Parâmetro Tipo Descrição
id string ID do flow

Query Parameters

Parâmetro Tipo Descrição
deleteExecutions boolean Se true, deleta também todas as execuções (padrão: false)

Exemplo de Requisição

curl -X DELETE "https://api.lumina.app.br/v1/flows/flow_abc123?deleteExecutions=true" \
  -H "Authorization: Bearer lumina_sk_your_api_key"

Resposta de Sucesso (204)

No Content

Resposta de Erro (404)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Flow não encontrado"
  }
}

Executar Flow

Executa um flow manualmente.

POST /flows/:id/execute

Path Parameters

Parâmetro Tipo Descrição
id string ID do flow

Request Body

{
  "data": {
    "userId": "user_123",
    "action": "process",
    "items": [...]
  },
  "async": true,
  "metadata": {
    "source": "api",
    "requestId": "req_xyz"
  }
}
Campo Tipo Obrigatório Descrição
data object Não Dados de entrada para o flow
async boolean Não Se true, retorna imediatamente (padrão: true)
metadata object Não Metadados adicionais

Exemplo de Requisição

curl -X POST "https://api.lumina.app.br/v1/flows/flow_abc123/execute" \
  -H "Authorization: Bearer lumina_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "userId": "user_456",
      "productId": "prod_789",
      "quantity": 2
    },
    "async": true
  }'

Resposta de Sucesso - Async (202)

{
  "success": true,
  "data": {
    "executionId": "exec_123456",
    "status": "running",
    "startedAt": "2025-01-15T18:00:00Z",
    "flowId": "flow_abc123"
  }
}

Resposta de Sucesso - Sync (200)

{
  "success": true,
  "data": {
    "executionId": "exec_123456",
    "status": "completed",
    "startedAt": "2025-01-15T18:00:00Z",
    "completedAt": "2025-01-15T18:00:03Z",
    "duration": 3000,
    "output": {
      "result": "success",
      "orderId": "order_999"
    },
    "nodes": [
      {
        "nodeId": "node_1",
        "status": "completed",
        "output": {...}
      }
    ]
  }
}

Duplicar Flow

Cria uma cópia de um flow existente.

POST /flows/:id/duplicate

Request Body

{
  "name": "Cópia de Flow Original",
  "includeVariables": true,
  "includeConnections": true
}

Exemplo de Requisição

curl -X POST "https://api.lumina.app.br/v1/flows/flow_abc123/duplicate" \
  -H "Authorization: Bearer lumina_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Flow Duplicado"
  }'

Resposta de Sucesso (201)

{
  "success": true,
  "data": {
    "id": "flow_new456",
    "name": "Flow Duplicado",
    "status": "draft",
    "createdAt": "2025-01-15T18:10:00Z"
  }
}

Exportar Flow

Exporta a definição do flow em JSON.

GET /flows/:id/export

Query Parameters

Parâmetro Tipo Descrição
includeVariables boolean Incluir variáveis (padrão: true)
includeExecutions boolean Incluir histórico de execuções (padrão: false)

Exemplo de Requisição

curl -X GET "https://api.lumina.app.br/v1/flows/flow_abc123/export" \
  -H "Authorization: Bearer lumina_sk_your_api_key" \
  -o flow-export.json

Resposta de Sucesso (200)

{
  "version": "1.0",
  "exportedAt": "2025-01-15T18:15:00Z",
  "flow": {
    "name": "Processar Pedidos WhatsApp",
    "description": "...",
    "trigger": {...},
    "nodes": [...],
    "edges": [...],
    "variables": {...}
  }
}

Importar Flow

Importa um flow a partir de um JSON exportado.

POST /flows/import

Request Body

{
  "name": "Flow Importado",
  "data": {
    "version": "1.0",
    "flow": {...}
  },
  "overwriteVariables": false
}

Exemplo de Requisição

curl -X POST "https://api.lumina.app.br/v1/flows/import" \
  -H "Authorization: Bearer lumina_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d @flow-export.json

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}`
  }
});

// Listar flows ativos
async function listActiveFlows() {
  const response = await api.get('/flows', {
    params: { status: 'active', limit: 50 }
  });
  return response.data.data;
}

// Criar novo flow
async function createFlow(flowData) {
  const response = await api.post('/flows', flowData);
  return response.data.data;
}

// Atualizar flow
async function updateFlow(flowId, updates) {
  const response = await api.patch(`/flows/${flowId}`, updates);
  return response.data.data;
}

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

// Deletar flow
async function deleteFlow(flowId) {
  await api.delete(`/flows/${flowId}`);
}

Python

import requests
import os

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

class FlowsAPI:
    def __init__(self):
        self.headers = {
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        }

    def list_flows(self, status=None, limit=20):
        params = {'limit': limit}
        if status:
            params['status'] = status

        response = requests.get(
            f'{BASE_URL}/flows',
            headers=self.headers,
            params=params
        )
        return response.json()['data']

    def get_flow(self, flow_id):
        response = requests.get(
            f'{BASE_URL}/flows/{flow_id}',
            headers=self.headers
        )
        return response.json()['data']

    def create_flow(self, flow_data):
        response = requests.post(
            f'{BASE_URL}/flows',
            headers=self.headers,
            json=flow_data
        )
        return response.json()['data']

    def execute_flow(self, flow_id, input_data):
        response = requests.post(
            f'{BASE_URL}/flows/{flow_id}/execute',
            headers=self.headers,
            json={'data': input_data, 'async': True}
        )
        return response.json()['data']

Próximos Passos

← Autenticação | Executions API →