Guía de Inicio Rápido

Comienza en minutos

Sigue esta guía paso a paso para realizar tus primeras llamadas exitosas a la API de mindzieStudio y comenzar a integrar capacidades de minería de procesos en tus aplicaciones.

Requisitos previos

• Credenciales de API: Token de acceso, ID de tenant y ID de proyecto
• URL base: El endpoint de la API de tu instancia de mindzie
• Acceso HTTPS: Conexión segura a tu instancia de mindzie
• Entorno de desarrollo: Tu lenguaje de programación y cliente HTTP preferidos

¿No tienes credenciales? Consulta la Guía de Autenticación para aprender cómo obtener tus credenciales de acceso a la API.

Paso 1: Prueba de Conectividad Básica

Comienza probando la conectividad básica para asegurarte que tu instancia de mindzie es accesible:

curl -X GET "https://your-mindzie-instance.com/api/Action/ping"

Respuesta esperada:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Paso 2: Verificar Autenticación

Prueba tus credenciales de autenticación con el endpoint ping autenticado:

curl -X GET "https://your-mindzie-instance.com/api/Action/ping/authenticated" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID" \
  -H "Content-Type: application/json"

Respuesta esperada:

{
  "status": "authenticated",
  "timestamp": "2024-01-15T10:30:00Z",
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "projectId": "87654321-4321-4321-4321-210987654321",
  "userId": "user@company.com",
  "permissions": ["read", "write", "admin"]
}

Paso 3: Tu Primera Llamada a la API

Vamos a hacer una llamada práctica a la API para obtener el historial de acciones:

curl -X GET "https://your-mindzie-instance.com/api/Action/history?limit=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID" \
  -H "Content-Type: application/json"

Ejemplo de respuesta:

{
  "actions": [
    {
      "actionId": "87654321-4321-4321-4321-210987654321",
      "actionType": "analyze",
      "status": "completed",
      "startTime": "2024-01-15T10:30:00Z",
      "endTime": "2024-01-15T10:32:15Z",
      "duration": 135,
      "userId": "user@company.com"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 1,
    "itemsPerPage": 5
  }
}

Ejemplos Específicos por Lenguaje

JavaScript

Usa fetch API o axios para aplicaciones web modernas y backend en Node.js.

Python

Usa la librería requests para flujos de trabajo de ciencia de datos y automatización backend.

C#/.NET

Usa HttpClient para aplicaciones empresariales y microservicios.

Ejemplo en JavaScript

Ejemplo completo usando JavaScript moderno y fetch API:

// Configuración
const API_CONFIG = {
  baseURL: 'https://your-mindzie-instance.com/api',
  token: 'YOUR_ACCESS_TOKEN',
  tenantId: 'YOUR_TENANT_GUID',
  projectId: 'YOUR_PROJECT_GUID'
};

// Función auxiliar para llamadas a la API
async function callMindzieAPI(endpoint, options = {}) {
  const url = `${API_CONFIG.baseURL}${endpoint}`;

  const defaultHeaders = {
    'Authorization': `Bearer ${API_CONFIG.token}`,
    'X-Tenant-Id': API_CONFIG.tenantId,
    'X-Project-Id': API_CONFIG.projectId,
    'Content-Type': 'application/json'
  };

  try {
    const response = await fetch(url, {
      ...options,
      headers: { ...defaultHeaders, ...options.headers }
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Fallo en la llamada API:', error);
    throw error;
  }
}

// Uso de ejemplo
async function quickStartExample() {
  try {
    // 1. Probar conectividad
    console.log('Probando conectividad...');
    const pingResult = await callMindzieAPI('/Action/ping');
    console.log('Ping exitoso:', pingResult);

    // 2. Probar autenticación
    console.log('Probando autenticación...');
    const authResult = await callMindzieAPI('/Action/ping/authenticated');
    console.log('Autenticación exitosa:', authResult);

    // 3. Obtener historial de acciones
    console.log('Obteniendo historial de acciones...');
    const history = await callMindzieAPI('/Action/history?limit=5');
    console.log('Historial de acciones:', history);

    console.log('Inicio rápido completado con éxito!');
    return history;
  } catch (error) {
    console.error('Error en el inicio rápido:', error);
    throw error;
  }
}

// Ejecutar el ejemplo
quickStartExample();

Ejemplo en Python

Ejemplo completo usando la librería requests de Python:

import requests
import json
from typing import Dict, Any

class MindzieQuickStart:
    def __init__(self, base_url: str, token: str, tenant_id: str, project_id: str):
        self.base_url = base_url.rstrip('/')
        self.headers = {
            'Authorization': f'Bearer {token}',
            'X-Tenant-Id': tenant_id,
            'X-Project-Id': project_id,
            'Content-Type': 'application/json'
        }

    def call_api(self, endpoint: str, method: str = 'GET', **kwargs) -> Dict[str, Any]:
        """Realiza una llamada a la API de mindzie"""
        url = f"{self.base_url}{endpoint}"

        try:
            response = requests.request(
                method=method,
                url=url,
                headers=self.headers,
                **kwargs
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"Fallo en la llamada a la API: {e}")
            raise

    def run_quick_start(self):
        """Ejecuta la secuencia de inicio rápido"""
        print("Iniciando Quick Start de la API mindzie...")

        try:
            # 1. Probar conectividad
            print("1. Probando conectividad...")
            ping_result = requests.get(f"{self.base_url}/api/Action/ping")
            ping_result.raise_for_status()
            print(f"   Conectividad OK: {ping_result.json()}")

            # 2. Probar autenticación
            print("2. Probando autenticación...")
            auth_result = self.call_api('/api/Action/ping/authenticated')
            print(f"   Autenticación OK: {auth_result['status']}")

            # 3. Obtener historial de acciones
            print("3. Obteniendo historial de acciones...")
            history = self.call_api('/api/Action/history?limit=5')
            print(f"   Se recuperaron {len(history['actions'])} acciones")

            print("¡Inicio rápido completado con éxito!")
            return history

        except Exception as e:
            print(f"Falló el inicio rápido: {e}")
            raise

# Ejemplo de uso
if __name__ == "__main__":
    # Configura tus credenciales
    quick_start = MindzieQuickStart(
        base_url='https://your-mindzie-instance.com/api',
        token='YOUR_ACCESS_TOKEN',
        tenant_id='YOUR_TENANT_GUID',
        project_id='YOUR_PROJECT_GUID'
    )

    # Ejecuta el inicio rápido
    result = quick_start.run_quick_start()
    print(f"Resultado final: {json.dumps(result, indent=2)}")

Ejemplo en C#/.NET

Ejemplo completo usando HttpClient en C#:

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

public class MindzieQuickStart
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;

    public MindzieQuickStart(string baseUrl, string token, string tenantId, string projectId)
    {
        _baseUrl = baseUrl.TrimEnd('/');

        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
        _httpClient.DefaultRequestHeaders.Add("X-Tenant-Id", tenantId);
        _httpClient.DefaultRequestHeaders.Add("X-Project-Id", projectId);
    }

    public async Task<T> CallApiAsync<T>(string endpoint)
    {
        try
        {
            var response = await _httpClient.GetAsync($"{_baseUrl}{endpoint}");
            response.EnsureSuccessStatusCode();

            var content = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<T>(content, new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            });
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"Fallo en la llamada API: {ex.Message}");
            throw;
        }
    }

    public async Task RunQuickStartAsync()
    {
        Console.WriteLine("Iniciando Quick Start de la API mindzie...");

        try
        {
            // 1. Probar conectividad
            Console.WriteLine("1. Probando conectividad...");
            using var pingClient = new HttpClient();
            var pingResponse = await pingClient.GetAsync($"{_baseUrl}/api/Action/ping");
            pingResponse.EnsureSuccessStatusCode();
            Console.WriteLine("   Conectividad OK");

            // 2. Probar autenticación
            Console.WriteLine("2. Probando autenticación...");
            var authResult = await CallApiAsync<AuthResponse>("/api/Action/ping/authenticated");
            Console.WriteLine($"   Autenticación OK: {authResult.Status}");

            // 3. Obtener historial de acciones
            Console.WriteLine("3. Obteniendo historial de acciones...");
            var history = await CallApiAsync<ActionHistoryResponse>("/api/Action/history?limit=5");
            Console.WriteLine($"   Se recuperaron {history.Actions.Length} acciones");

            Console.WriteLine("¡Inicio rápido completado con éxito!");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Falló el inicio rápido: {ex.Message}");
            throw;
        }
    }

    public void Dispose()
    {
        _httpClient?.Dispose();
    }
}

// Modelos de datos
public class AuthResponse
{
    public string Status { get; set; }
    public string TenantId { get; set; }
    public string ProjectId { get; set; }
    public string UserId { get; set; }
}

public class ActionHistoryResponse
{
    public ActionItem[] Actions { get; set; }
    public PaginationInfo Pagination { get; set; }
}

public class ActionItem
{
    public string ActionId { get; set; }
    public string ActionType { get; set; }
    public string Status { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime? EndTime { get; set; }
}

public class PaginationInfo
{
    public int CurrentPage { get; set; }
    public int TotalPages { get; set; }
    public int TotalItems { get; set; }
}

// Uso
class Program
{
    static async Task Main(string[] args)
    {
        var quickStart = new MindzieQuickStart(
            "https://your-mindzie-instance.com/api",
            "YOUR_ACCESS_TOKEN",
            "YOUR_TENANT_GUID",
            "YOUR_PROJECT_GUID"
        );

        try
        {
            await quickStart.RunQuickStartAsync();
        }
        finally
        {
            quickStart.Dispose();
        }
    }
}

Problemas Comunes y Soluciones

Fallos de Autenticación

• 401 Unauthorized: Verifica que tu token de acceso sea correcto y no esté expirado
• 403 Forbidden: Revisa los IDs de tenant/proyecto y permisos de usuario
• 400 Bad Request: Asegúrate que todos los headers requeridos estén incluidos

Problemas de Conexión

• Timeouts de red: Verifica configuración de firewall y conectividad de red
• Errores SSL/TLS: Comprueba validez del certificado y configuración HTTPS
• Resolución DNS: Confirma que la URL de la instancia mindzie sea correcta

Limitación de Velocidad

• 429 Too Many Requests: Implementa lógica de reintentos con backoff exponencial
• Monitorea límites: Revisa los headers de respuesta para información de límites
• Optimiza solicitudes: Usa paginación y filtrado para reducir llamadas a la API

Próximos Pasos

¡Felicidades! Has completado exitosamente el inicio rápido de mindzieAPI. A continuación, explora la API de Acciones o la API de Bloques para comenzar a construir integraciones poderosas.