SDK de Midaz para Go

Crea aplicaciones en Go sobre Midaz con el SDK oficial para Go: paginación tipada, errores estructurados, reintentos y observabilidad con OpenTelemetry.

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 los servicios que lista la tabla Servicios (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.

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 – Crea o usa un proyecto de Go existente

Crea un proyecto de Go:

Para crear un proyecto de Go, usa el siguiente comando:

Bash

mkdir my-midaz-app
cd my-midaz-app
go mod init my-midaz-app

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:

Bash

go mod init your-module-name

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.

Bash

go get 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.

Go

package main

import (
	"context"
	"fmt"
	"log"

	midaz "github.com/LerianStudio/midaz-sdk-golang/v6"
	"github.com/LerianStudio/midaz-sdk-golang/v6/models"
)

func main() {
	// Build a client. The SDK requires exactly one auth source: use
	// midaz.WithAnonymous() for a local stack, or midaz.WithAccessManager(...)
	// for a development or production environment.
	c, err := midaz.New(
		midaz.WithEnvironment(midaz.EnvironmentLocal),
		midaz.WithAnonymous(),
	)
	if err != nil {
		log.Fatalf("midaz.New: %v", err)
	}
	defer c.Shutdown(context.Background())

	ctx := context.Background()

	// List the first 5 organizations using a typed list-opts struct.
	page, err := c.V2.Organizations.List(ctx, models.OrganizationsListOpts{
		PageListOpts: models.PageListOpts{Limit: 5},
	})
	if err != nil {
		log.Fatalf("list organizations: %v", err)
	}

	for _, org := range page.Items {
		fmt.Printf("- %s (%s)\n", org.LegalName, org.ID)
	}

	// Create a new organization. midaz.CreateOrganizationInput is the same
	// type as models.CreateOrganizationInput, re-exported on the midaz package.
	dba := "Example Inc."
	org, err := c.V2.Organizations.Create(ctx, &midaz.CreateOrganizationInput{
		LegalName:       "Example Corporation",
		LegalDocument:   "123456789",
		DoingBusinessAs: &dba, // optional fields are *string
		Address: midaz.Address{
			Line1:   "123 Main St",
			City:    "New York",
			State:   "NY",
			ZipCode: "10001",
			Country: "US",
		},
	})
	if err != nil {
		log.Fatalf("create organization: %v", err)
	}

	fmt.Printf("Organization created: %s\n", org.ID)
}

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:

Bash

go run main.go

Arquitectura del SDK

---

Diseño en capas

Capa	Qué maneja
Cliente	El punto de entrada principal. midaz.New(...) conecta la autenticación, los reintentos y la observabilidad.
Servicios	Los servicios de Midaz que el SDK encapsula, agrupados por la versión de la API que los atiende.
Modelos	Las estructuras de datos del dominio de Midaz. Las más comunes se reexportan en el paquete midaz.
Paquetes de utilidades	Ayudantes para configuración, errores, observabilidad, reintentos, idempotencia y más.

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.

Go

orgs, err := c.V2.Organizations.List(ctx, opts)
account, err := c.V2.Accounts.Get(ctx, orgID, ledgerID, accountID)
tx, err := c.V2.Transactions.CreateDirect(ctx, orgID, ledgerID, input)

// /v1 only:
rate, err := c.V1.AssetRates.GetAssetRate(ctx, orgID, ledgerID, externalID)

Grupo	Servicios
c.V2 y c.V1	Organizations, Ledgers, Accounts, AccountTypes, Assets, Balances, Operations, Portfolios, Segments, OperationRoutes, TransactionRoutes, Transactions, MetadataIndexes
Solo c.V2	Holders, Instruments, Encryption, Composition, ProtectionAudit, BillingPackages, FeePackages, FeeEstimates, BillingCalculations
Solo c.V1	AssetRates
Tracer, en el cliente	c.Rules, c.Limits, c.Validations, c.AuditEvents

Transactions tiene un contrato distinto en cada versión. En /v1, creas una transacción mediante uno de seis métodos 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.

Para publicar varias transacciones direct y hold como un lote ordenado, usa c.V2.Transactions.CreateBatch. Midaz aplica todos los ítems, en orden, o ninguno. Cada ítem es un models.TransactionBatchItemV2 con una Action (direct o hold) y un Order (empieza en uno y es consecutivo). La llamada devuelve las transacciones en ese orden. El lote tiene una sola clave de idempotencia, que defines con sdkctx.WithIdempotencyKey. Se rechaza un ítem que define su propia IdempotencyKey.

Una respuesta 201 significa que Midaz aplicó la transacción a los saldos.

Lee la versión del servidor

c.ServerVersion lee la versión del ledger de Midaz con el que se comunica el cliente. Devuelve un error cuando el ledger no responde con una versión.

midaz.SupportsRulesOnly indica si el Tracer de esa versión acepta la validación solo por reglas. c.Validations.EvaluateRulesOnly juzga una transacción solo por sus reglas: no revisa ningún límite de gasto y no cuenta nada contra uno.

Go

v, err := c.ServerVersion(ctx)
if err != nil {
    return fmt.Errorf("read server version: %w", err)
}

if midaz.SupportsRulesOnly(v) {
    verdict, err := c.Validations.EvaluateRulesOnly(ctx, input) // input is a *models.ValidateTransactionInput
    if err != nil {
        return err
    }
    _ = verdict
}

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.

midaz.Account incluye ClosedAt, el momento en que Midaz cerró la cuenta. Es nil mientras la cuenta está abierta. Cerrar una cuenta no cambia Status.

Tipos de modelo comunes

Modelo	Qué representa
midaz.Organization	Una entidad de negocio que es dueña de ledgers y cuentas.
midaz.Ledger	Una colección de cuentas y transacciones.
midaz.Asset	Una unidad de valor (moneda, token, etc.) que se puede almacenar o mover.
midaz.Account	Una cuenta para seguir activos y saldos.
midaz.Portfolio	Una colección de cuentas para agrupar y administrar.
midaz.Segment	Una unidad de categorización para una organización granular.
midaz.Transaction	Un evento financiero compuesto por varias operaciones.
midaz.Operation	Un asiento individual de débito o crédito dentro de una transacción.
midaz.Balance	El estado actual de las posiciones de una cuenta.

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

Paquete	Qué resuelve
auth	OAuth de Access Manager y ciclo de vida del token.
config	Manejo de configuración, carga desde el entorno y URLs de servicio personalizadas.
concurrent	Herramientas para lotes, limitación de tasa y pools de workers.
errors	Tipos de error estructurados, clasificadores y el predicado Retryable().
observability	Trazas, métricas y registros mediante un solo proveedor de OpenTelemetry.
retry	Opciones de política de reintentos con backoff exponencial y jitter.
sdkctx	Indicadores de contexto por solicitud, como las claves de idempotencia.
validation	Validación de entrada con mensajes de error estructurados.

Paquetes Helper

Paquete	Qué resuelve
accounts	Ayudantes específicos de cuentas y funciones de conveniencia.
conversion	Ayudantes de conversión de tipos entre modelos y formatos externos.
data	Utilidades de datos y ayudantes faker para pruebas y demostraciones.
format	Utilidades para dar formato a los datos al estilo de Midaz (fechas, horas, etc.).
generator	Generación de datos de demostración y masivos para escenarios de extremo a extremo.
integrity	Utilidades de checksum y verificación de integridad.
performance	Ayudantes para ajustar operaciones en lote y tareas de alto rendimiento.
security	Utilidades de seguridad, incluida la protección contra SSRF y la validación de TLS.
stats	Estadísticas de procesamiento y agregación de métricas.
transaction	Ayudantes de transacciones, como la espera de liquidación.
utils	Ayudantes de uso general que se usan en todo el SDK.
version	Metadatos de versión e identificación del SDK.

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.

Go

package main

import (
	"context"
	"log"
	"os"

	midaz "github.com/LerianStudio/midaz-sdk-golang/v6"
)

func main() {
	// Configure Access Manager. Load ClientID and ClientSecret from
	// environment variables; do not hardcode them.
	c, err := midaz.New(
		midaz.WithEnvironment(midaz.EnvironmentProduction),
		midaz.WithAccessManager(midaz.AccessManager{
			Address:      "https://auth.example.com",
			ClientID:     os.Getenv("MIDAZ_CLIENT_ID"),
			ClientSecret: os.Getenv("MIDAZ_CLIENT_SECRET"),
		}),
	)
	if err != nil {
		log.Fatalf("midaz.New: %v", err)
	}
	defer c.Shutdown(context.Background())

	// Use c.V2.Organizations, c.V2.Ledgers, c.V2.Accounts, ...
}

Desarrollo local: Anonymous

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

Go

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentLocal),
    midaz.WithAnonymous(),
)

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:

Bash

export PLUGIN_AUTH_ENABLED=true
export PLUGIN_AUTH_ADDRESS=https://your-auth-service.com
export MIDAZ_CLIENT_ID=your-client-id
export MIDAZ_CLIENT_SECRET=your-client-secret

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:

Go

import "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/config"

cfg, err := config.NewConfig(config.FromEnvironment())
if err != nil {
    log.Fatalf("config: %v", err)
}

c, err := midaz.New(midaz.WithConfig(cfg))

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.

Método	Retorna	Úsalo cuando
List	*models.ListResponse[T] (una página)	Quieres exactamente una página y decides cuándo avanzar.
All	iter.Seq2[T, error]	Quieres cada elemento. El SDK maneja la paginación internamente.
Pages	iter.Seq2[*models.ListResponse[T], error]	Necesitas metadatos en el nivel de página para checkpoints o procesamiento por lotes.

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:

Forma de paginación	Endpoints	Struct base
Basada en página	Organizations, Ledgers, Assets, Portfolios, Segments, Accounts, AccountTypes, FeePackages, BillingPackages	models.PageListOpts{Limit, Page, SortDirection, StartDate, EndDate}
Basada en cursor	Transactions, Balances, Holders, Operations, OperationRoutes, TransactionRoutes, AssetRates	models.CursorListOpts{Limit, Cursor, SortDirection, StartDate, EndDate}

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.

Go

opts := models.AccountsListOpts{
    PageListOpts: models.PageListOpts{Limit: 100},
    Filters: models.AccountsFilters{
        Status:    "ACTIVE",
        AssetCode: "USD",
    },
}

for account, err := range c.V2.Accounts.All(ctx, orgID, ledgerID, opts) {
    if err != nil {
        return fmt.Errorf("list accounts: %w", err)
    }
    process(account)
}

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.

Go

opts := models.TransactionsListOpts{
    CursorListOpts: models.CursorListOpts{Limit: 50},
}

for page, err := range c.V2.Transactions.Pages(ctx, orgID, ledgerID, opts) {
    if err != nil {
        return fmt.Errorf("page iter: %w", err)
    }
    log.Printf("items=%d next_cursor=%q", len(page.Items), page.Pagination.NextCursor)

    for _, tx := range page.Items {
        process(tx)
    }

    if shouldStop(page) {
        break // The SDK stops paging.
    }
}

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:

Campo	Qué contiene
Category	La clase del error (validación, autenticación, red, configuración, etc.).
Code	Un código de texto estable para ramificar la lógica o para telemetría.
Operation	La operación del SDK que produjo el error.
Resource	La familia de recursos a la que se refiere el error, cuando corresponde.

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:

Go

import (
    "errors"
    "fmt"

    sdkerrors "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/errors"
)

acc, err := c.V2.Accounts.Get(ctx, orgID, ledgerID, accountID)
if err != nil {
    switch {
    case sdkerrors.IsNotFoundError(err):
        return fmt.Errorf("account not found: %w", err)
    case sdkerrors.IsAuthError(err):
        return fmt.Errorf("auth failure: %w", err)
    case sdkerrors.IsValidationError(err):
        return fmt.Errorf("invalid input: %w", err)
    case sdkerrors.IsInsufficientBalanceError(err):
        return fmt.Errorf("not enough balance: %w", err)
    case sdkerrors.IsTransactionReservationDenied(err):
        return fmt.Errorf("refused by Tracer: %w", err)
    case sdkerrors.IsConflictError(err):
        return fmt.Errorf("already exists: %w", err)
    case sdkerrors.IsRateLimitError(err):
        return fmt.Errorf("rate limited: %w", err)
    case sdkerrors.IsNetworkError(err):
        return fmt.Errorf("transient transport: %w", err)
    case sdkerrors.IsConfigurationError(err):
        return fmt.Errorf("setup mistake: %w", err)
    }

    // Read the structured fields when you need them.
    var sdkErr *sdkerrors.Error
    if errors.As(err, &sdkErr) {
        log.Printf("op=%s resource=%s code=%s retryable=%v",
            sdkErr.Operation, sdkErr.Resource, sdkErr.Code, sdkErr.Retryable())
    }
}

Guía las decisiones de reintento con Retryable()

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

Go

var sdkErr *sdkerrors.Error
if errors.As(err, &sdkErr) && sdkErr.Retryable() {
    // Apply your retry logic: backoff, jitter, max attempts, etc.
}

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:

Go

import sdkerrors "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/errors"

resp, err := httpClient.Do(req)
if err != nil {
    return sdkerrors.ClassifyTransportError("PaymentService.Charge", err)
}

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.

Go

import (
    "errors"
    "fmt"

    "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/validation"
)

var fieldErrs *validation.FieldErrors
if errors.As(err, &fieldErrs) {
    for _, fe := range fieldErrs.Errs() {
        fmt.Printf("- %s: %s\n", fe.Field, fe.Message)
    }
}

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 un POST, PUT, PATCH o DELETE cuando la solicitud tiene un header X-Idempotency, o cuando es la creación de una transacción, de un titular o de un instrumento, que Midaz responde con el primer resultado cuando llega de nuevo la misma solicitud. Envía una sola vez cualquier otra escritura.

Después de que una escritura falla, el SDK deja de reintentar cuando la ventana de idempotencia ya pasó desde el inicio de la llamada. La ventana es el valor de X-TTL de la solicitud, o 300 segundos cuando el header no existe. Un 409 con el código 0084 bajo una clave que definiste tú vuelve como error. El SDK solo reintenta un 0084 bajo su propia clave aleatoria o en una creación sin clave.

Go

import (
    "time"

    "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/retry"
)

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentLocal),
    midaz.WithAnonymous(),
    midaz.WithRetryOptions(
        retry.WithMaxRetries(5),
        retry.WithInitialDelay(200*time.Millisecond),
    ),
)

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.

Go

package main

import (
    "context"
    "log"
    "log/slog"
    "os"

    midaz "github.com/LerianStudio/midaz-sdk-golang/v6"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    }))

    c, err := midaz.New(
        midaz.WithEnvironment(midaz.EnvironmentLocal),
        midaz.WithAnonymous(),
        midaz.WithLogger(logger),
    )
    if err != nil {
        log.Fatalf("midaz.New: %v", err)
    }
    defer c.Shutdown(context.Background())

    // SDK log lines now go to your handler.
}

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.

Pasa un proveedor que construyes tú, o pasa opciones que el SDK arma por ti.

Conecta un proveedor

Go

package main

import (
    "context"
    "log"

    midaz "github.com/LerianStudio/midaz-sdk-golang/v6"
    "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/observability"
)

func main() {
    ctx := context.Background()

    provider, err := observability.New(ctx,
        observability.WithServiceName("payments-api"),
        observability.WithEnvironment("production"),
        observability.WithComponentEnabled(true, true, true), // tracing, metrics, logs
    )
    if err != nil {
        log.Fatalf("observability.New: %v", err)
    }
    defer provider.Shutdown(ctx)

    c, err := midaz.New(
        midaz.WithEnvironment(midaz.EnvironmentProduction),
        midaz.WithAccessManager(midaz.AccessManager{ /* ... */ }),
        midaz.WithObservabilityProvider(provider),
    )
    if err != nil {
        log.Fatalf("midaz.New: %v", err)
    }
    defer c.Shutdown(ctx)
}

O pasa opciones en línea

Go

import "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/observability"

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentProduction),
    midaz.WithAccessManager(am),
    midaz.WithObservabilityOptions(
        observability.WithServiceName("payments-api"),
        observability.WithComponentEnabled(true, true, true),
    ),
)

Sin observability.WithCollectorEndpoint, el SDK usa los proveedores de OpenTelemetry de tu aplicación y no los reemplaza. c.Shutdown cierra solo un proveedor que el SDK construyó. Si pasas tu propio proveedor, ciérralo después del último cliente que lo usa.

Llamadas como c.V2.Accounts.Get no crean ningún span ni envían el header traceparent por sí solas. Para trazarlas, envuelve el transporte del cliente con el middleware de observabilidad:

Go

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentProduction),
    midaz.WithAccessManager(am),
    midaz.WithObservabilityProvider(provider),
    midaz.WithHTTPTransport(observability.NewHTTPMiddleware(provider)),
)

WithHTTPTransport conserva el cliente HTTP propio del SDK, con su timeout, autenticación y reintentos, y envuelve su transporte.

También puedes envolver un bloque de lógica de negocio en un span con Client.Trace:

Go

err = c.Trace("create-organization", func(ctx context.Context) error {
    _, err := c.V2.Organizations.Create(ctx, input)
    return err
})

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

---

El SDK no genera una clave X-Idempotency aleatoria a menos que la actives. Sin una clave tuya, Midaz trata una creación de transacción idéntica dentro de la ventana de idempotencia (300 segundos por defecto) como una repetición y devuelve la primera transacción. Una segunda transacción intencional con la misma solicitud no se publica. Para ver cómo trata Midaz la falta de clave, consulta Reintentos e idempotencia.

Define una clave distinta para cada transacción que quieres publicar. Esto es habitual en pasos de saga, filas de outbox o envíos de UI.

Define una clave estable por solicitud

Go

import "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/sdkctx"

ctx := sdkctx.WithIdempotencyKey(context.Background(), "tx-2026-05-06-001")

tx, err := c.V2.Transactions.CreateDirect(ctx, orgID, ledgerID, input)

Una clave que defines siempre prevalece sobre la opción del cliente y sobre sdkctx.WithoutAutoIdempotency.

Midaz usa la clave en las creaciones de transacción y en las creaciones de titular e instrumento. Tracer no la usa. Si se pierde una respuesta, el reintento del SDK en cualquier otra escritura puede ejecutarla por segunda vez, incluso con clave. Desactiva los reintentos del SDK para esas escrituras, o lee el recurso antes de reintentar.

Activa una clave aleatoria de forma global

Para enviar una clave X-Idempotency aleatoria en cada creación, actualización y eliminación, actívala en el nivel del cliente:

Go

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentLocal),
    midaz.WithAnonymous(),
    midaz.WithIdempotency(true),
)

También puedes definir MIDAZ_IDEMPOTENCY=true cuando usas config.FromEnvironment(). Cada llamada lleva entonces su propia clave, así que dos transacciones intencionales con la misma solicitud se publican por separado. Un reintento de una llamada reutiliza la clave de esa llamada.

Detén la clave aleatoria en una llamada

Cuando el cliente tiene la clave aleatoria activada, puedes detenerla en una llamada:

Go

ctx := sdkctx.WithoutAutoIdempotency(context.Background())

Variables de entorno

---

El SDK lee estas variables solo cuando config.FromEnvironment() está en tu cadena de opciones de configuración.

Variable	Descripción
MIDAZ_ENVIRONMENT	Entorno de destino (local, development, production).
MIDAZ_BASE_URL	URL base de los servicios de Midaz, que se usa cuando las URLs específicas de servicio no están definidas. No agregues un sufijo /v1 o /v2.
MIDAZ_LEDGER_URL	URL de la API del ledger. Atiende los endpoints de onboarding y de transacciones.
MIDAZ_TRACER_URL	URL de la API de Tracer.
MIDAZ_TRACER_API_KEY	Clave de API opcional para Tracer. Cuando no la defines, las llamadas a Tracer usan el bearer token del ledger.
PLUGIN_AUTH_ENABLED	Activa la autenticación de Access Manager (true o false).
PLUGIN_AUTH_ADDRESS	Dirección del servicio de Access Manager.
MIDAZ_CLIENT_ID	Client ID para la autenticación de Access Manager.
MIDAZ_CLIENT_SECRET	Client secret para la autenticación de Access Manager.
MIDAZ_TIMEOUT	Tiempo de espera de la solicitud HTTP en segundos.
MIDAZ_DEBUG	Activa los registros de depuración (true o false).
MIDAZ_MAX_RETRIES	Número máximo de reintentos para las solicitudes que fallan.
MIDAZ_IDEMPOTENCY	Envía una clave de idempotencia aleatoria en cada creación, actualización y eliminación (true o false). Valor por defecto: false.
MIDAZ_ERROR_EXPOSE_BODY	Incluye el cuerpo sin procesar de la respuesta en *pkg/errors.Error.
MIDAZ_ACCESS_MANAGER_ALLOW_INSECURE_HTTP	Permite HTTP simple hacia Access Manager. El SDK lo rechaza cuando MIDAZ_ENVIRONMENT=production.
MIDAZ_ALLOW_INSECURE_HTTP	Permite HTTP simple hacia las URLs del ledger y de Tracer en hosts que no son loopback. El SDK lo rechaza cuando MIDAZ_ENVIRONMENT=production.

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–11), además de ejemplos avanzados y de referencia. Cada ejemplo numerado enseña un concepto. Explóralos en el directorio de ejemplos en GitHub.

Ejemplo	Qué demuestra
01-hello-world	Inicialización mínima más la primera llamada a la API.
02-auth	Autenticación de Access Manager (configuración de producción).
03-end-to-end	Creación de una transacción en /v2 con CreateDirect.
04-listing-cursor	Paginación basada en cursor con iter.Seq2.
05-listing-pages	Paginación basada en página con List, All y Pages.
06-idempotency	Sin clave y clave propia.
07-retries	Política predeterminada, política personalizada, reintentos desactivados.
08-logging-slog	Integración con *slog.Logger.
09-testing-with-mocks	Una interfaz estrecha propia más un mock escrito a mano.
10-observability-otel	Superficie completa de OpenTelemetry (trazas + métricas + registros).
11-server-version	Leer la versión del servidor al iniciar y actualizarla con un temporizador.

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