Saltar al contenido principal

Empezando

Paso 1 – Instalar Go

Antes de usar el SDK, debes instalar Go en tu máquina.
2
Descarga el instalador para tu sistema operativo (Windows, macOS o Linux).

Paso 2 - Crear o usar un proyecto Go existente

Crear un proyecto Go: Para crear un proyecto Go, usa el siguiente comando:
mkdir my-midaz-app
cd my-midaz-app
go mod init my-midaz-app
Usar un proyecto Go existente: Si estás trabajando en un proyecto existente, asegúrate de que haya un archivo go.mod en la raíz. Si no, ejecuta el siguiente comando para crear uno:
go mod init your-module-name

Paso 3 – Agregar el Midaz SDK

Dentro del directorio de tu proyecto, ejecuta el siguiente comando para descargar el Midaz SDK y agregarlo a tus archivos go.mod y go.sum:
go get github.com/LerianStudio/midaz-sdk-golang
Tip¿Usas VS Code o GoLand? Tu IDE puede ejecutar automáticamente go get cuando importas un paquete nuevo.

Paso 4 – Importar el SDK

Crea o abre un archivo main.go y agrega el siguiente contenido:
AtenciónRecuerda cambiar los valores en la sección // Configure plugin access manager del código con tus propias credenciales antes de ejecutarlo.
package main

import (
	"context"
	"fmt"
	"log"

	client "github.com/LerianStudio/midaz-sdk-golang"
	"github.com/LerianStudio/midaz-sdk-golang/models"
	auth "github.com/LerianStudio/midaz-sdk-golang/pkg/access-manager"
	"github.com/LerianStudio/midaz-sdk-golang/pkg/config"
)

func main() {
	// Configure plugin access manager
	AccessManager := auth.AccessManager{
		Enabled:      true,
		Address:      "https://your-auth-service.com",
		ClientID:     "your-client-id",
		ClientSecret: "your-client-secret",
	}

	// Create a configuration with plugin access manager
	cfg, err := config.NewConfig(
		config.WithAccessManager(AccessManager),
	)
	if err != nil {
		log.Fatalf("Failed to create config: %v", err)
	}

	// Create a client
	c, err := client.New(
		client.WithConfig(cfg),
		client.WithEnvironment(config.EnvironmentProduction),
		client.UseAllAPIs(),
	)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Create an organization
	ctx := context.Background()
	org, err := c.Entity.Organizations.CreateOrganization(
		ctx,
		&models.CreateOrganizationInput{
			LegalName:       "Example Corporation",
			LegalDocument:   "123456789",
			DoingBusinessAs: "Example Inc.",
			Address: models.Address{
				Line1:   "123 Main St",
				City:    "New York",
				State:   "NY",
				ZipCode: "10001",
				Country: "US",
			},
		},
	)
	if err != nil {
		log.Fatalf("Failed to create organization: %v", err)
	}

	fmt.Printf("Organization created: %s\n", org.ID)
}
Esto te da acceso a:
  • El cliente Midaz para llamar APIs.
  • Modelos de datos incorporados (como CreateOrganizationInput).
  • Soporte de plugin de autenticación vía Access Manager.
  • Un sistema de configuración flexible.
Tip¿Quieres saber más sobre Access Manager? Consulta la sección Access Manager para más detalles.

Paso 5 - Ejecutar el proyecto

Ejecuta el siguiente comando:
go run main.go
Tip¿Quieres profundizar? Consulta la página de Ejemplos de Midaz Go SDK para fragmentos de código prácticos que te ayudarán a comenzar.

Arquitectura del SDK

El Midaz SDK for Go está diseñado para claridad y flexibilidad. Su arquitectura en capas te permite trabajar con confianza, ya sea que estés configurando cuentas o procesando miles de transacciones.

Diseño en capas

CapaQué maneja
ClientEl punto de entrada principal que conecta todo.
EntitiesAcceso de alto nivel a cada servicio Midaz (Organizations, Ledgers, Accounts, etc.).
ModelsLas estructuras de datos principales que reflejan la lógica de dominio de Midaz.
Utility PackagesAyudantes modulares para configuración, observabilidad, validación, concurrencia, y más.
Tip¿Quieres profundizar? Consulta la página de Arquitectura de Midaz Go SDK para más información.

Entities

La capa Entities sirve como punto de acceso a todos los servicios de Midaz, proporcionándote interfaces simples y fáciles de usar. Cada interfaz maneja un recurso particular y se encarga de los detalles por ti. Todo se conecta sin problemas a través de client.Entity, tu centro principal para comandos SDK.

Servicios disponibles

ServicioQué hace
OrganizationsServiceGestionar organizaciones.
LedgersServiceCrear y recuperar ledgers.
AssetsServiceDefinir y gestionar assets.
AssetRatesServiceConfigurar y obtener tasas de cambio de assets.
AccountsServiceGestionar cuentas y verificar saldos.
PortfoliosServiceAgrupar cuentas bajo portfolios.
SegmentsServiceCategorizar cuentas usando segments.
TransactionsServiceCrear y buscar transacciones financieras.
OperationsServiceProfundizar en las operaciones atómicas en una transacción.
BalancesServiceObtener saldos de cuenta en tiempo real.

Models

Los Models en el SDK reflejan cómo Midaz piensa sobre finanzas, cada uno vinculado estrechamente a conceptos de negocio del mundo real. Los usarás en todos los servicios y operaciones, desde la incorporación de cuentas hasta el registro de eventos financieros complejos.

Tipos de modelos comunes

ModeloQué representa
OrganizationUna entidad empresarial que posee ledgers y cuentas.
LedgerUna colección de cuentas y transacciones.
AssetUna unidad de valor (moneda, token, etc.) que puede almacenarse o moverse.
AccountRepresenta una cuenta para rastrear assets y saldos.
PortfolioUna colección de cuentas para agrupación y gestión.
SegmentUna unidad de categorización para una organización más granular.
TransactionUn evento financiero con operaciones (débitos y créditos).
OperationUna entrada contable individual dentro de una transacción.
BalanceEl estado actual de las tenencias de una cuenta.

Utility packages

En la carpeta pkg del SDK, encontrarás varios paquetes de utilidades que abordan desafíos de desarrollo comunes, desde manejo de configuración hasta lógica de reintentos.

Paquetes incluidos

PaqueteQué resuelve
configManejo de configuración centralizado, sobrescrituras de env y URLs de servicio personalizadas soportadas.
concurrentHerramientas para procesamiento por lotes, limitación de tasa y pools de workers.
observabilityTracing, métricas y logs para mantener tu integración visible y depurable.
paginationRespuestas paginadas.
validationValidación de entrada con mensajes de error claros y estructurados.
errorsTipos de error enriquecidos, incluyendo detalle a nivel de campo y clasificación de errores.
formatUtilidades para formatear datos al estilo Midaz (fechas, horas, etc.).
retryLógica de reintento con backoff exponencial.
performanceAyudantes para acelerar operaciones masivas o tareas de alto rendimiento.

Access Manager

El Access Manager te da una forma segura y flexible de manejar la autenticación a través de proveedores de identidad externos. En lugar de codificar tokens en tu aplicación, simplemente conecta tu servicio de autenticación y deja que el SDK maneje el resto.

Por qué usarlo

  • Seguro: Sin tokens codificados.
  • Flexible: Funciona con cualquier proveedor de identidad que soporte credenciales de cliente.
  • Centralizado: Gestiona la configuración de autenticación en un solo lugar.
  • Automático: La renovación de tokens está completamente manejada por el SDK.

Configuración

Puedes configurar el Access Manager de dos formas:
  • Vía código
  • Vía variables de entorno
AtenciónRecuerda cambiar los valores en la sección // Set up plugin-based authentication del código con tus propias credenciales antes de ejecutarlo.

Opción 1: Configurar vía código

// Import the access manager package
import (
    auth "github.com/LerianStudio/midaz-sdk-golang/pkg/access-manager"
    "github.com/LerianStudio/midaz-sdk-golang/pkg/config"
)

// Set up plugin-based authentication
AccessManager := auth.AccessManager{
    Enabled:      true,
    Address:      "https://your-auth-service.com",
    ClientID:     "your-client-id",
    ClientSecret: "your-client-secret",
}

// Pass it to the SDK configuration
cfg, err := config.NewConfig(
    config.WithAccessManager(AccessManager),
)
if err != nil {
    log.Fatalf("Failed to create config: %v", err)
}

client, err := client.New(
    client.WithConfig(cfg),
    client.UseAllAPIs(),
)

Opción 2: Configurar vía variables de entorno

Cambia las siguientes variables en el archivo .env:
PLUGIN_AUTH_ENABLED=true
PLUGIN_AUTH_ADDRESS=https://your-auth-service.com
MIDAZ_CLIENT_ID=your-client-id
MIDAZ_CLIENT_SECRET=your-client-secret
Luego cárgalas en tu aplicación:
AccessManager := auth.AccessManager{
    Enabled:      os.Getenv("PLUGIN_AUTH_ENABLED") == "true",
    Address:      os.Getenv("PLUGIN_AUTH_ADDRESS"),
    ClientID:     os.Getenv("MIDAZ_CLIENT_ID"),
    ClientSecret: os.Getenv("MIDAZ_CLIENT_SECRET"),
}

Qué hace el SDK por ti

Una vez habilitada la autenticación basada en plugin, el SDK se hace cargo:
  • Solicita un token de tu servicio de autenticación usando las credenciales del cliente.
  • Autentica todas las llamadas API usando el token.
  • Renueva automáticamente el token cuando expira.

Variables de entorno

También puedes configurar el SDK usando variables de entorno; no necesitas codificar nada.
VariableDescripción
MIDAZ_AUTH_TOKENToken de autenticación (usado cuando no se configura ningún plugin).
MIDAZ_ENVIRONMENTEntorno objetivo (local, development, production).
MIDAZ_ONBOARDING_URLSobrescribir la URL base del servicio de onboarding.
MIDAZ_TRANSACTION_URLSobrescribir la URL base del servicio de transacciones.
MIDAZ_DEBUGHabilitar logs de depuración (true o false).
MIDAZ_MAX_RETRIESEstablecer el número máximo de intentos de reintento.
Tip¿Quieres profundizar? Consulta la página de Variables de entorno en Midaz Go SDK para más información.

Características avanzadas

Lleva tu integración más lejos con soporte incorporado para paginación, concurrencia y observabilidad.

Paginación

Trabaja con resultados paginados de la manera fácil. El SDK te da una interfaz estilo iterador para que puedas concentrarte en la lógica, no en las matemáticas de paginación. No necesitas gestionar cursores manualmente, solo itera y continúa.
// Create a paginator for accounts
paginator := client.Entity.Accounts.GetAccountPaginator(ctx, "org-id", "ledger-id", &models.ListOptions{
	Limit: 10,
})

// Iterate through all pages
for paginator.HasNext() {
	accounts, err := paginator.Next()
	if err != nil {
		// Handle error
	}

	for _, account := range accounts.Items {
		// Process each account
	}
}
Tip¿Quieres profundizar? Consulta la página de Paginación en Midaz Go SDK para más información.

Utilidades de concurrencia

¿Necesitas acelerar las cosas? El SDK viene con ayudantes poderosos para ejecutar tareas en paralelo o por lotes. Estos ayudantes son ideales para trabajos de alto rendimiento como sincronizar cuentas o procesar transacciones masivas.

Ejecutar en paralelo con WorkerPool

// Process accounts in parallel
results := concurrent.WorkerPool(
	ctx,
	accountIDs,
	func(ctx context.Context, accountID string) (*models.Account, error) {
		// Fetch account details
		return client.Entity.Accounts.GetAccount(ctx, "org-id", "ledger-id", accountID)
	},
	concurrent.WithWorkers(5), // Use 5 workers
)

Procesar en lotes con Batch

// Process items in batches
batchResults := concurrent.Batch(
	ctx,
	transactionIDs,
	10, // Process 10 items per batch
	func(ctx context.Context, batch []string) ([]string, error) {
		// Process the batch and return results
		return processedIDs, nil
	},
	concurrent.WithWorkers(3), // Process 3 batches concurrently
)

Observabilidad

Obtén visibilidad completa de lo que tu código está haciendo, sin cableado extra. Habilita tracing, métricas y logs estructurados en una línea. Ya sea que estés depurando u optimizando el rendimiento, la observabilidad te da la ventaja.
// Create a client with observability enabled
client, err := client.New(
	client.WithPluginAccessManager("your-auth-token"),
	client.WithObservability(true, true, true), // Enable tracing, metrics, and logging
	client.UseAllAPIs(),
)
También puedes rastrear bloques específicos de lógica:
// Trace an operation
err = client.Trace("create-organization", func(ctx context.Context) error {
	_, err := client.Entity.Organizations.CreateOrganization(ctx, input)
	return err
})

Manejo de errores

El Midaz Go SDK ofrece un sistema robusto de manejo de errores para ayudarte a identificar, clasificar y responder a errores de API de manera efectiva. Define un conjunto de tipos de error como ValidationError, AuthenticationError, ResourceNotFoundError y otros, permitiendo una categorización precisa de problemas. Cada error incluye datos estructurados, incluyendo el tipo de error, código, mensaje, estado HTTP, recurso asociado y un ID de solicitud para depuración o propósitos de soporte. Para simplificar el manejo de errores, el SDK proporciona funciones auxiliares que verifican tipos de error específicos y códigos de estado HTTP. Esto permite respuestas adaptadas a escenarios comunes como entrada inválida, limitación de tasa o recursos faltantes. Para fallos transitorios, el SDK soporta mecanismos de reintento incorporados que manejan errores de red, límites de tasa y errores de servidor con políticas de reintento configurables. Estos pueden establecerse programáticamente o vía variables de entorno.
Tip¿Quieres profundizar? Consulta la página de Manejo de errores en Midaz Go SDK para más información.

Mecanismo de reintento

El Midaz Go SDK te ayuda a construir integraciones resilientes manejando errores transitorios automáticamente. Si una solicitud falla debido a un problema temporal, como problemas de red o límite de tasa, el SDK puede reintentar la operación por ti, para que tu aplicación no tenga que hacerlo. Por defecto, el SDK reintenta:
  • Problemas de red temporales.
  • Respuestas de limitación de tasa (con backoff inteligente).
  • Errores del lado del servidor (HTTP 5xx).
  • Respuestas API explícitamente marcadas como reintentables.
Hay dos formas de configurar los parámetros de reintento:
  • En ambos ejemplos, el SDK reintentará hasta 3 veces, esperando al menos 500ms y como máximo 5s entre intentos.

Configurar vía opciones del cliente

Usa este enfoque para definir programáticamente cuántas veces reintentar y cuánto tiempo esperar entre intentos:
client, err := client.New(
    client.WithRetries(3, 500*time.Millisecond, 5*time.Second),
    // Other options...
)

Configurar vía variables de entorno

Usa este enfoque para gestionar el comportamiento de reintento usando las variables de entorno (en el archivo .env):
# Retry configuration
MIDAZ_MAX_RETRIES=3               # Maximum retry attempts for failed requests (default: 3)
MIDAZ_ENABLE_RETRIES=true         # Enable retry mechanism (default: true)
MIDAZ_RETRY_WAIT_MIN=500ms        # Minimum wait time between retries in ms (default: 1000ms)
MIDAZ_RETRY_WAIT_MAX=50000ms      # Maximum wait time between retries in ms (default: 30000ms)

Explorar las APIs

Para más información sobre las APIs, consulta los siguientes enlaces