Saltar al contenido principal
El SDK de Midaz para Go es el cliente de Go para las API del ledger y de Tracer de Midaz. Te da acceso tipado a cada servicio (Organizations, Ledgers, Accounts, Transactions y más) con una sola superficie para autenticación, paginación, errores, reintentos, registro y observabilidad.

Primeros pasos


Paso 1 – Instala Go

Instala Go antes de usar el SDK. El SDK declara Go 1.26 en go.mod. Su API pública usa iter.Seq2 y log/slog.
2
Descarga el instalador para tu sistema operativo (Windows, macOS o Linux).

Paso 2 – Crea o usa un proyecto de Go existente

Crea un proyecto de Go: Para crear un proyecto de Go, usa el siguiente comando:
Usa un proyecto de Go existente: Si trabajas en un proyecto existente, confirma que hay un archivo go.mod en la raíz. Si no lo hay, ejecuta el siguiente comando para crear uno:

Paso 3 – Agrega el SDK de Midaz

Dentro del directorio de tu proyecto, ejecuta el siguiente comando para agregar el SDK a tus archivos go.mod y go.sum:
La ruta del módulo requiere el sufijo /v6. Si lo omites, Go resuelve una versión v1 antigua. Importa github.com/LerianStudio/midaz-sdk-golang/v6.
En VS Code o GoLand, tu IDE puede ejecutar go get automáticamente cuando importas un paquete nuevo.

Paso 4 – Importa el SDK

Crea o abre un archivo main.go y agrega el siguiente contenido. El ejemplo crea un cliente para tu stack local de Midaz con autenticación anónima, lista las organizaciones y después crea una nueva.
El ejemplo de abajo apunta a un stack local de Midaz con la autenticación desactivada. Si todavía no tienes uno en ejecución, consulta Primeros pasos con Midaz para levantarlo antes de ejecutar el fragmento.
Esto te da acceso a:
  • El cliente de Midaz para llamar a cada servicio de la API.
  • Modelos de datos incluidos (como CreateOrganizationInput).
  • Autenticación mediante Access Manager (producción) o Anonymous (desarrollo local).
  • Un sistema de configuración tipado que falla en el momento de la construcción.
Para la configuración completa, consulta la sección Autenticación.

Paso 5 – Ejecuta el proyecto

Ejecuta el siguiente comando:

Arquitectura del SDK


Diseño en capas

Servicios

Midaz atiende dos versiones de la API del ledger: /v1, que está obsoleta, y /v2. El SDK agrupa los servicios del ledger por la versión que los atiende. Desarrolla sobre c.V2. Un recurso que una versión no atiende produce un error de compilación, no un 404.
Transactions tiene un contrato distinto en cada versión. En /v1, creas una transacción mediante uno de cuatro endpoints de creación con un cuerpo send anidado. En /v2, c.V2.Transactions crea transacciones con un cuerpo plano mediante CreateDirect, CreateHold, CreateBlock y CreateUnblock. Devuelve models.TransactionV2.
Una respuesta 201 significa que Midaz aplicó la transacción a los saldos.

Modelos

Cada tipo de modelo representa un concepto de negocio. Los usas en cada llamada de servicio. Los tipos de modelo más comunes se reexportan en el paquete midaz. midaz.Account y models.Account son el mismo tipo, así que la mayor parte del código necesita solo un import.

Tipos de modelo comunes

Para un tipo que no se reexporta, como models.TransactionV2, importa github.com/LerianStudio/midaz-sdk-golang/v6/models directamente. Los alias de midaz conservan la identidad del tipo, así que las dos rutas de import funcionan juntas.

Paquetes de utilidades

La carpeta pkg del SDK contiene paquetes de utilidades. Los paquetes Core atienden aspectos que aplican a todo el SDK. Los paquetes Helper ofrecen utilidades específicas de dominio o de bajo nivel.

Paquetes Core

Paquetes Helper

Autenticación


El SDK requiere exactamente una fuente de autenticación en el momento de la construcción. Si llamas a midaz.New(...) sin ninguna de las dos, devuelve un error de configuración tipado. Tienes dos opciones:
  • midaz.WithAccessManager(...): OAuth mediante Lerian Access Manager. Úsalo en cualquier stack que no sea local.
  • midaz.WithAnonymous(): sin autenticación. Úsalo solo en un stack local de Midaz con la autenticación desactivada.
Si aplicas las dos opciones, gana la última.

Producción: Access Manager

Coloca tus credenciales de Access Manager en midaz.WithAccessManager. El SDK solicita un token a tu Access Manager, lo adjunta a cada llamada a la API y lo renueva cuando vence.
Reemplaza los valores del bloque // Configure Access Manager con tus propias credenciales antes de ejecutar.

Desarrollo local: Anonymous

Para un stack local de Midaz con la autenticación desactivada, desactívala de forma explícita:

Configura mediante variables de entorno

También puedes apuntar el SDK a tu Access Manager con variables de entorno. Expórtalas en tu shell o en tu gestor de procesos:
config.FromEnvironment() lee el entorno del proceso, no un archivo .env. Si guardas variables en un archivo .env durante el desarrollo, cárgalas con una biblioteca como godotenv antes de llamar a config.NewConfig(config.FromEnvironment()).
Después, activa la carga desde el entorno en el momento de la configuración:
La carga desde el entorno es explícita. Coloca config.FromEnvironment() en la cadena de opciones. Sin ella, el SDK no lee variables de entorno durante la construcción.
Para la guía completa de autenticación, consulta la guía de autenticación en el repositorio del SDK.

Alcance del tenant


El alcance del tenant viene de Access Manager / de los claims del JWT que se usan para obtener el token. El SDK no tiene configuración de tenant y no envía un header de tenant. Para ejecutar llamadas con un alcance de tenant distinto, usa un conjunto separado de credenciales de Access Manager o crea un segundo cliente con su propio contexto de token.

Listado e iteración


La mayoría de los endpoints de listado viene en tres métodos. Elige el que corresponde a tu caso de uso.

Opciones de listado tipadas

Cada método de listado recibe un struct de opciones tipado. El struct incorpora uno de dos structs base, según cómo pagina el endpoint: Algunos endpoints también exponen un sub-struct Filters tipado. Si defines un campo de la forma incorrecta (por ejemplo, Page en un endpoint basado en cursor), el código no compila.
El listado de transacciones no filtra por Status, AssetCode, Reference, SourceAccount, DestinationAccount ni Route. Si defines uno de estos filtros en List, el SDK rechaza la llamada con un error. Count acepta Status y Route.

Itera cada elemento con All

La forma más simple es un bucle range sobre cada elemento de cada página. El SDK obtiene las páginas internamente.

Itera los sobres de página con Pages

Cuando necesitas metadatos en el nivel de página (para checkpoints, procesamiento por lotes o detenerte a mitad de página), itera sobre Pages. Cada entrada es un *models.ListResponse[T] con su bloque Pagination.
Consulta la guía de paginación en el repositorio del SDK para el manejo de NextCursor y la tabla de decisión entre página y cursor.

Manejo de errores


La capa de servicios del SDK devuelve los errores como *pkg/errors.Error con campos estructurados: Puedes ramificar la lógica con predicados tipados, leer campos con errors.As o usar el método Retryable() para guiar la política de reintentos.

Ramifica la lógica con predicados tipados

El SDK tiene un conjunto de predicados Is*, para que identifiques errores sin leer detalles internos:

Guía las decisiones de reintento con Retryable()

El método Error.Retryable() deriva de Category. Úsalo en lugar de tu propia clasificación.

Envuelve errores de transporte sin procesar

Si llamas a código HTTP de bajo nivel fuera del SDK y quieres la misma forma de error estructurado, usa ClassifyTransportError:

Validación local: FieldErrors

La validación local de entrada devuelve *pkg/validation.FieldErrors, una colección de errores por campo que el SDK encuentra antes de cualquier llamada HTTP. Usa errors.As para leerlos.
Para el mapa completo de categorías, cada código y los límites de reintento, consulta la guía de manejo de errores en el repositorio del SDK.

Reintentos


La política predeterminada reintenta 3 veces con backoff exponencial y 25% de jitter. Reintenta los errores de transporte y los estados 408, 425, 429, 500, 502, 503 y 504. El SDK reintenta POST, PUT, PATCH y DELETE solo cuando la solicitud tiene un header X-Idempotency.
Usa midaz.WithCustomRetryPolicy para tu propio predicado de reintento. Para desactivar los reintentos, usa midaz.WithoutRetries().

Registro


*slog.Logger es la superficie de logger del SDK. Conéctalo con midaz.WithLogger(...). El SDK es silencioso de forma predeterminada: usa slog.DiscardHandler hasta que lo activas. Tú decides el handler, el nivel y el destino.
charmbracelet/log, zap y zerolog se integran mediante slog.Handler.
La guía de registro tiene recetas de adaptadores para bibliotecas de registro comunes.

Observabilidad


Un proveedor de observabilidad te da spans, métricas y registros correlacionados con OpenTelemetry mediante un solo punto de conexión. Pasa un proveedor que construyes tú, o pasa opciones que el SDK arma por ti.

Conecta un proveedor

O pasa opciones en línea

El SDK emite un span HTTP por cada solicitud saliente con propagación W3C traceparent. Los registros de log de negocio llevan solo IDs seguros: sin payloads, nombres, direcciones ni headers de autenticación. También puedes envolver un bloque de lógica de negocio en un span con Client.Trace:
WithObservabilityOptions y WithObservabilityProvider reemplazan el proveedor instalado. No combinan. Para empezar desde una base, coloca observability.WithDevelopmentDefaults o observability.WithProductionDefaults primero en la cadena de opciones.
Consulta el ejemplo 10-observability-otel en el repositorio del SDK para los atributos de span, los nombres de métricas y la configuración de exporters.

Idempotencia


La idempotencia automática está activada de forma predeterminada. El SDK envía un header X-Idempotency: <uuid> en cada solicitud HTTP no segura (POST, PUT, PATCH, DELETE). Así, un reintento después de una falla transitoria no crea un recurso dos veces. Puedes reemplazar la clave generada en cada llamada cuando necesitas una clave estable propia. Esto es habitual en pasos de saga, filas de outbox o envíos de UI.

Define una clave estable por solicitud

Suprime la idempotencia para una llamada

Para llamadas administrativas poco frecuentes, suprime el header por solicitud:
Sin el header, el SDK no reintenta esa solicitud no segura.

Deshabilita de forma global

Para desactivar la idempotencia automática en todas partes, desactívala en el nivel del cliente:
También puedes definir MIDAZ_IDEMPOTENCY=false cuando usas config.FromEnvironment().

Variables de entorno


El SDK lee estas variables solo cuando config.FromEnvironment() está en tu cadena de opciones de configuración. Para la matriz completa de opciones de midaz, pkg/config y pkg/sdkctx, consulta la guía de configuración en el repositorio del SDK.

Proyectos de ejemplo


El SDK tiene un conjunto numerado de tutoriales enfocados (ejemplos 01–10), además de ejemplos avanzados y de referencia. Cada ejemplo numerado enseña un concepto. Explóralos en el directorio de ejemplos en GitHub.
El repositorio también incluye ejemplos de referencia: concurrency, configuration, context, tracing, tracing-server, pkg-validation-demo, mass-demo-generator y workflow-with-entities.

Explora las API


Para obtener más información sobre las API, consulta los siguientes enlaces:

Mapeo de la API externa

Mapeo de la API interna

Documentación de Godoc