Empezando
Paso 1 – Instalar Go
Antes de usar el SDK, debes instalar Go en tu máquina.1
Ve al sitio web oficial de Go.
2
Descarga el instalador para tu sistema operativo (Windows, macOS o Linux).
3
Sigue las instrucciones de instalación.
Paso 2 - Crear o usar un proyecto Go existente
Crear un proyecto Go: Para crear un proyecto Go, usa el siguiente comando:go.mod en la raíz. Si no, ejecuta el siguiente comando para crear uno:
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 archivosgo.mod y go.sum:
Paso 4 – Importar el SDK
Crea o abre un archivomain.go y agrega el siguiente contenido:
- 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.
Paso 5 - Ejecutar el proyecto
Ejecuta el siguiente comando: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
| Capa | Qué maneja |
|---|---|
| Client | El punto de entrada principal que conecta todo. |
| Entities | Acceso de alto nivel a cada servicio Midaz (Organizations, Ledgers, Accounts, etc.). |
| Models | Las estructuras de datos principales que reflejan la lógica de dominio de Midaz. |
| Utility Packages | Ayudantes modulares para configuración, observabilidad, validación, concurrencia, y más. |
Entities
La capaEntities 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
| Servicio | Qué hace |
|---|---|
OrganizationsService | Gestionar organizaciones. |
LedgersService | Crear y recuperar ledgers. |
AssetsService | Definir y gestionar assets. |
AssetRatesService | Configurar y obtener tasas de cambio de assets. |
AccountsService | Gestionar cuentas y verificar saldos. |
PortfoliosService | Agrupar cuentas bajo portfolios. |
SegmentsService | Categorizar cuentas usando segments. |
TransactionsService | Crear y buscar transacciones financieras. |
OperationsService | Profundizar en las operaciones atómicas en una transacción. |
BalancesService | Obtener saldos de cuenta en tiempo real. |
Models
LosModels 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
| Modelo | Qué representa |
|---|---|
Organization | Una entidad empresarial que posee ledgers y cuentas. |
Ledger | Una colección de cuentas y transacciones. |
Asset | Una unidad de valor (moneda, token, etc.) que puede almacenarse o moverse. |
Account | Representa una cuenta para rastrear assets y saldos. |
Portfolio | Una colección de cuentas para agrupación y gestión. |
Segment | Una unidad de categorización para una organización más granular. |
Transaction | Un evento financiero con operaciones (débitos y créditos). |
Operation | Una entrada contable individual dentro de una transacción. |
Balance | El estado actual de las tenencias de una cuenta. |
Utility packages
En la carpetapkg 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
| Paquete | Qué resuelve |
|---|---|
config | Manejo de configuración centralizado, sobrescrituras de env y URLs de servicio personalizadas soportadas. |
concurrent | Herramientas para procesamiento por lotes, limitación de tasa y pools de workers. |
observability | Tracing, métricas y logs para mantener tu integración visible y depurable. |
pagination | Respuestas paginadas. |
validation | Validación de entrada con mensajes de error claros y estructurados. |
errors | Tipos de error enriquecidos, incluyendo detalle a nivel de campo y clasificación de errores. |
format | Utilidades para formatear datos al estilo Midaz (fechas, horas, etc.). |
retry | Lógica de reintento con backoff exponencial. |
performance | Ayudantes 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
Opción 1: Configurar vía código
Opción 2: Configurar vía variables de entorno
Cambia las siguientes variables en el archivo.env:
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.| Variable | Descripción |
|---|---|
MIDAZ_AUTH_TOKEN | Token de autenticación (usado cuando no se configura ningún plugin). |
MIDAZ_ENVIRONMENT | Entorno objetivo (local, development, production). |
MIDAZ_ONBOARDING_URL | Sobrescribir la URL base del servicio de onboarding. |
MIDAZ_TRANSACTION_URL | Sobrescribir la URL base del servicio de transacciones. |
MIDAZ_DEBUG | Habilitar logs de depuración (true o false). |
MIDAZ_MAX_RETRIES | Establecer el número máximo de intentos de reintento. |
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.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
Procesar en lotes con Batch
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.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 comoValidationError, 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.
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.
- 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:Configurar vía variables de entorno
Usa este enfoque para gestionar el comportamiento de reintento usando las variables de entorno (en el archivo.env):

