Saltar al contenido principal
El SDK simplifica la conexión entre su aplicación y los sistemas financieros de Lerian. Ya sea que esté desarrollando Ledgers (Libros Mayores), gestionando Portafolios o procesando Transacciones, este SDK proporciona abstracciones claras y una base confiable para sus necesidades de desarrollo.

Comenzando

Paso 1 – Instalar Go

Antes de usar el SDK, debe instalar Go en su máquina.
2

Descargue el instalador para su SO (Windows, macOS o Linux).

Paso 2 - Crear o usar un proyecto Go existente

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

Paso 3 – Agregar el SDK de Midaz

Dentro del directorio de su proyecto, ejecute el siguiente comando para obtener el SDK de Midaz y agregarlo a sus archivos go.mod y go.sum:
go get github.com/LerianStudio/midaz-sdk-golang
¿Usa VS Code o GoLand? Su IDE puede ejecutar automáticamente go get cuando importe un nuevo paquete.

Paso 4 – Importar el SDK

Cree o abra un archivo main.go y agregue el siguiente contenido:
Recuerde cambiar los valores en la sección // Configure plugin access manager del código con sus 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() {
	// Configurar plugin de gestor de acceso
	AccessManager := auth.AccessManager{
		Enabled:      true,
		Address:      "https://tu-auth-service.com",
		ClientID:     "tu-client-id",
		ClientSecret: "tu-client-secret",
	}

	// Crear una configuración con plugin de gestor de acceso
	cfg, err := config.NewConfig(
		config.WithAccessManager(AccessManager),
	)
	if err != nil {
		log.Fatalf("Error al crear la configuración: %v", err)
	}

	// Crear un cliente
	c, err := client.New(
		client.WithConfig(cfg),
		client.WithEnvironment(config.EnvironmentProduction),
		client.UseAllAPIs(),
	)
	if err != nil {
		log.Fatalf("Error al crear el cliente: %v", err)
	}

	// Crear una organización
	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("Error al crear la organización: %v", err)
	}

	fmt.Printf("Organización creada: %s\n", org.ID)
}
Esto le da acceso a:
  • El cliente de Midaz para llamar a las API.
  • Modelos de datos integrados (como CreateOrganizationInput).
  • Soporte de plugin de autenticación a través de Access Manager.
  • Un sistema de configuración flexible.
¿Quiere aprender más sobre Access Manager? Consulte la sección Access Manager para más detalles.

Paso 5 - Ejecutar el proyecto

Ejecute el siguiente comando:
go run main.go
¿Quiere profundizar más? Consulte la página de Ejemplos del SDK de Go de Midaz para fragmentos de código prácticos que le ayudarán a comenzar.

Arquitectura del SDK

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

Diseño en capas

CapaQué maneja
ClienteEl punto de entrada principal que conecta todo.
EntidadesAcceso de alto nivel a cada servicio de Midaz (Organizaciones, Ledgers, Cuentas, etc.).
ModelosLas estructuras de datos centrales que reflejan la lógica de dominio de Midaz.
Paquetes de UtilidadAyudantes modulares para configuración, observabilidad, validación, concurrencia y más.
¿Quiere profundizar más? Consulte la página de Arquitectura del SDK de Go de Midaz para más información.

Entidades

La capa de Entidades sirve como el punto de acceso a todos los servicios de Midaz, proporcionándole interfaces simples y fáciles de usar. Cada interfaz maneja un recurso particular y se encarga de los detalles por usted. Todo se conecta sin problemas a través de client.Entity, su centro central para comandos del SDK.

Servicios disponibles

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

Modelos

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

Tipos de modelo comunes

ModeloQué representa
OrganizationUna entidad comercial 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 activos 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.

Paquetes de utilidad

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

Paquetes incluidos

PaqueteQué resuelve
configManejo de configuración centralizado, sobrescrituras de entorno y URL de servicio personalizadas soportadas.
concurrentHerramientas para procesamiento por lotes, limitación de tasa y pools de trabajadores.
observabilityRastreo, métricas y registros para mantener su integración visible y depurable.
paginationRespuestas paginadas.
validationValidación de entrada con mensajes de error claros y estructurados.
errorsTipos de error ricos, incluido detalle a nivel de campo y clasificación de errores.
formatUtilidades para formatear datos a la manera de Midaz (fechas, horas, etc.).
retryLógica de reintento con retroceso exponencial.
performanceAyudantes para acelerar operaciones masivas o tareas de alto rendimiento.

Access Manager

El Access Manager le brinda una forma segura y flexible de manejar la autenticación a través de proveedores de identidad externos. En lugar de codificar tokens en su aplicación, simplemente conecte su servicio de autenticación y deje que el SDK maneje el resto.

Por qué usarlo

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

Configuración

Puede configurar el Access Manager de dos maneras:
  • A través de código
  • A través de variables de entorno
Recuerde cambiar los valores en la sección // Set up plugin-based authentication del código con sus propias credenciales antes de ejecutarlo.

Opción 1: Configurar a través de código

// Importar el paquete de Access Manager
import (
    auth "github.com/LerianStudio/midaz-sdk-golang/pkg/access-manager"
    "github.com/LerianStudio/midaz-sdk-golang/pkg/config"
)

// Configurar la autenticación basada en plugin
AccessManager := auth.AccessManager{
    Enabled:      true,
    Address:      "https://tu-auth-service.com",
    ClientID:     "tu-client-id",
    ClientSecret: "tu-client-secret",
}

// Pasar la configuración al SDK
cfg, err := config.NewConfig(
    config.WithAccessManager(AccessManager),
)
if err != nil {
    log.Fatalf("Error al crear la configuración: %v", err)
}

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

Opción 2: Configurar a través de variables de entorno

Cambie las siguientes variables en el archivo .env:
PLUGIN_AUTH_ENABLED=true
PLUGIN_AUTH_ADDRESS=https://tu-auth-service.com
MIDAZ_CLIENT_ID=tu-client-id
MIDAZ_CLIENT_SECRET=tu-client-secret
Luego cárguelas en su 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 usted

Una vez que la autenticación basada en plugin está habilitada, el SDK se hace cargo:
  • Solicita un token de su 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 puede configurar el SDK usando variables de entorno; no es necesario codificar nada.
VariableDescripción
MIDAZ_AUTH_TOKENToken de autenticación (usado cuando no hay plugin configurado).
MIDAZ_ENVIRONMENTEntorno objetivo (local, development, production).
MIDAZ_ONBOARDING_URLSobrescribir la URL base del servicio de incorporación.
MIDAZ_TRANSACTION_URLSobrescribir la URL base del servicio de transacciones.
MIDAZ_DEBUGHabilitar registros de depuración (true o false).
MIDAZ_MAX_RETRIESEstablecer el número máximo de intentos de reintento.
¿Quiere profundizar más? Consulte la página Variables de Entorno en el SDK de Go de Midaz para más información.

Características avanzadas

Lleve su integración más allá con soporte integrado para paginación, concurrencia y observabilidad.

Paginación

Trabaje con resultados paginados de manera fácil. El SDK le brinda una interfaz de estilo iterador para que pueda enfocarse en la lógica, no en las matemáticas de paginación. No es necesario administrar cursores manualmente, solo itere y avance.
// Crear un paginador para cuentas
paginator := client.Entity.Accounts.GetAccountPaginator(ctx, "org-id", "ledger-id", &models.ListOptions{
	Limit: 10,
})

// Iterar a través de todas las páginas
for paginator.HasNext() {
	accounts, err := paginator.Next()
	if err != nil {
		// Manejar error
	}

	for _, account := range accounts.Items {
		// Procesar cada cuenta
	}
}
¿Quiere profundizar más? Consulte la página Paginación en el SDK de Go de Midaz para más información.

Utilidades de concurrencia

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

Ejecutar en paralelo con WorkerPool

// Procesar cuentas en paralelo
results := concurrent.WorkerPool(
	ctx,
	accountIDs,
	func(ctx context.Context, accountID string) (*models.Account, error) {
		// Obtener detalles de la cuenta
		return client.Entity.Accounts.GetAccount(ctx, "org-id", "ledger-id", accountID)
	},
	concurrent.WithWorkers(5), // Usar 5 workers
)

Procesar en lotes con Batch

// Procesar elementos en lotes
batchResults := concurrent.Batch(
	ctx,
	transactionIDs,
	10, // Procesar 10 elementos por lote
	func(ctx context.Context, batch []string) ([]string, error) {
		// Procesar el lote y devolver los resultados
		return processedIDs, nil
	},
	concurrent.WithWorkers(3), // Procesar 3 lotes en paralelo
)

Observabilidad

Obtenga visibilidad completa de lo que está haciendo su código, con cero cableado adicional. Habilite rastreo, métricas y registros estructurados en una línea. Ya sea que esté depurando u optimizando el rendimiento, la observabilidad le da la ventaja.
// Crear un cliente con observabilidad habilitada
client, err := client.New(
	client.WithPluginAccessManager("tu-auth-token"),
	client.WithObservability(true, true, true), // Habilita trazas, métricas y registros
	client.UseAllAPIs(),
)
También puede 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 SDK de Go de Midaz ofrece un sistema robusto de manejo de errores para ayudarle 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, incluido 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 personalizadas a escenarios comunes como entrada inválida, limitación de tasa o recursos faltantes. Para fallos transitorios, el SDK admite mecanismos de reintento integrados que manejan errores de red, límites de tasa y errores del servidor con políticas de reintento configurables. Estos pueden configurarse programáticamente o a través de variables de entorno.
¿Quiere profundizar más? Consulte la página Manejo de Errores en el SDK de Go de Midaz para más información.

Mecanismo de reintento

El SDK de Go de Midaz le 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 usted, por lo que su aplicación no tiene que hacerlo. Por defecto, el SDK reintenta:
  • Problemas temporales de red.
  • Respuestas de limitación de tasa (con retroceso 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 a través de opciones del cliente

Use 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 a través de variables de entorno

Use 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 API

Para más información sobre las API, consulte los siguientes enlaces
I