Primeiros passos
Passo 1 – Instalar o Go
Instale o Go antes de usar o SDK. O SDK declara Go 1.26 nogo.mod. A API pública dele usa iter.Seq2 e log/slog.
1
Acesse o site oficial do Go.
2
Baixe o instalador para o seu sistema operacional (Windows, macOS ou Linux).
Passo 2 – Criar ou usar um projeto Go existente
Criar um projeto Go: Para criar um projeto Go, use o comando a seguir:go.mod na raiz. Caso não haja, execute o comando a seguir para criar um:
Passo 3 – Adicionar o SDK do Midaz
Dentro do diretório do seu projeto, execute o comando a seguir para adicionar o SDK aos arquivosgo.mod e go.sum:
Passo 4 – Importar o SDK
Crie ou abra um arquivomain.go e adicione o conteúdo a seguir. O exemplo cria um cliente para a sua stack local do Midaz com autenticação anônima, lista organizações e, em seguida, cria uma nova.
O exemplo abaixo é para uma stack local do Midaz com autenticação desabilitada. Se você ainda não tem uma rodando, veja Primeiros passos com o Midaz para subir uma antes de executar o snippet.
- O cliente do Midaz para chamar cada serviço da API.
- Modelos de dados prontos (como
CreateOrganizationInput). - Autenticação via Access Manager (produção) ou Anônimo (desenvolvimento local).
- Um sistema de configuração tipado que falha no momento da construção.
Passo 5 – Executar o projeto
Execute o comando a seguir:Arquitetura do SDK
Design em camadas
Services
O Midaz atende duas versões da API do ledger:/v1, que está descontinuada, e /v2. O SDK agrupa os serviços do ledger pela versão que os atende. Desenvolva sobre c.V2. Um recurso que uma versão não atende gera erro de compilação, não um 404.
Transactions tem um contrato diferente em cada versão. Na /v1, você cria uma transação por um de quatro endpoints de criação com um body send aninhado. Na /v2, c.V2.Transactions cria transações com um body plano por meio de CreateDirect, CreateHold, CreateBlock e CreateUnblock. Ele retorna models.TransactionV2.
Uma resposta
201 significa que o Midaz aplicou a transação aos saldos.Models
Cada tipo de modelo representa um conceito de negócio. Você os usa em cada chamada de serviço. Os tipos de modelo mais comuns são reexportados no pacotemidaz. midaz.Account e models.Account são o mesmo tipo, então a maior parte do código precisa de apenas um import.
Tipos de modelo comuns
Utility packages
A pastapkg do SDK guarda pacotes utilitários. Os pacotes Core atendem preocupações que valem para todo o SDK. Os pacotes Helper oferecem utilitários específicos de domínio ou de baixo nível.
Core packages
Helper packages
Autenticação
O SDK exige exatamente uma fonte de autenticação no momento da construção. Se você chamar
midaz.New(...) sem nenhuma das duas, ele retorna um erro de configuração tipado.
Você tem duas opções:
midaz.WithAccessManager(...): OAuth pelo Lerian Access Manager. Use em qualquer stack que não seja local.midaz.WithAnonymous(): sem autenticação. Use apenas em uma stack local do Midaz com autenticação desabilitada.
Produção: Access Manager
Coloque suas credenciais do Access Manager emmidaz.WithAccessManager. O SDK solicita um token ao seu Access Manager, anexa esse token a cada chamada de API e o renova quando ele expira.
Desenvolvimento local: Anônimo
Para uma stack local do Midaz com autenticação desabilitada, desative a autenticação explicitamente:Configurar via variáveis de ambiente
Você também pode apontar o SDK para o seu Access Manager com variáveis de ambiente. Exporte-as no seu shell ou no seu gerenciador de processos:config.FromEnvironment() lê o ambiente de processo, não um arquivo .env. Se você mantém variáveis em um arquivo .env durante o desenvolvimento, carregue-as com uma biblioteca como godotenv antes de chamar config.NewConfig(config.FromEnvironment()).O carregamento por ambiente é explícito. Coloque
config.FromEnvironment() na cadeia de opções. Sem ele, o SDK não lê variáveis de ambiente durante a construção.Escopo de tenant
O escopo do tenant vem do Access Manager / das claims do JWT usadas para obter o token. O SDK não tem configuração de tenant e não envia um header de tenant. Para executar chamadas em um escopo de tenant diferente, use um conjunto separado de credenciais do Access Manager, ou construa um segundo cliente com seu próprio contexto de token.
Listagem e iteração
A maioria dos endpoints de listagem vem em três métodos. Escolha o que corresponde ao seu caso de uso.
Opções de listagem tipadas
Cada método de listagem recebe uma struct de opções tipada. A struct incorpora uma de duas structs base, de acordo com a forma como o endpoint pagina:
Alguns endpoints também expõem uma sub-struct
Filters tipada. Se você definir um campo do formato errado (por exemplo, Page em um endpoint por cursor), o código não compila.
Iterar por cada item com All
O formato mais simples é um loop range sobre cada item em cada página. O SDK busca as páginas internamente.
Iterar envelopes de página com Pages
Quando você precisa de metadados no nível de página (para checkpointing, processamento em lote ou parar no meio de uma página), itere sobre Pages. Cada entrada é um *models.ListResponse[T] com o seu bloco Pagination.
NextCursor e a tabela de decisão entre página e cursor.
Tratamento de erros
A camada de serviços do SDK retorna erros como
*pkg/errors.Error com campos estruturados:
Você pode ramificar com predicados tipados, ler campos com
errors.As ou usar o método Retryable() para guiar a política de novas tentativas.
Ramificar com predicados tipados
O SDK tem um conjunto de predicadosIs*, para que você identifique erros sem ler detalhes internos:
Guiar decisões de novas tentativas com Retryable()
O método Error.Retryable() deriva de Category. Use-o em vez da sua própria classificação.
Envolver erros brutos de transporte
Se você chama código HTTP de nível mais baixo fora do SDK e quer o mesmo formato de erro estruturado, useClassifyTransportError:
Validação local: FieldErrors
A validação local de entrada retorna*pkg/validation.FieldErrors, uma coleção de erros por campo que o SDK encontra antes de qualquer chamada HTTP. Use errors.As para lê-los.
Novas tentativas
A política padrão faz 3 novas tentativas com backoff exponencial e 25% de jitter. Ela tenta de novo em erros de transporte e nos status
408, 425, 429, 500, 502, 503 e 504. O SDK tenta de novo POST, PUT, PATCH e DELETE apenas quando a requisição tem um header X-Idempotency.
midaz.WithCustomRetryPolicy para o seu próprio predicado de novas tentativas. Para desligar as novas tentativas, use midaz.WithoutRetries().
Logging
*slog.Logger é a superfície de logger do SDK. Conecte-o com midaz.WithLogger(...). O SDK é silencioso por padrão: ele usa slog.DiscardHandler até você habilitar.
Você decide o handler, o nível e o destino.
slog.Handler.
Observabilidade
Um provedor de observabilidade oferece spans, métricas e logs correlacionados ao OpenTelemetry por um único ponto de conexão. Passe um provedor que você constrói, ou passe opções que o SDK monta para você.
Conectar um provedor
Ou passar opções inline
traceparent. Os registros de log de negócio carregam apenas IDs seguros: sem payloads, nomes, endereços ou headers de autenticação.
Você também pode envolver um bloco de lógica de negócio em um span com Client.Trace:
Idempotência
A idempotência automática está ligada por padrão. O SDK envia um header
X-Idempotency: <uuid> em cada requisição HTTP não segura (POST, PUT, PATCH, DELETE). Assim, uma nova tentativa depois de uma falha transitória não cria um recurso duas vezes.
Você pode substituir a chave gerada por chamada quando precisa de uma chave estável própria. Isso é comum em etapas de saga, linhas de outbox ou envios de UI.
Definir uma chave estável por requisição
Suprimir a idempotência para uma chamada
Para chamadas administrativas raras, suprima o header por requisição:Desabilitar globalmente
Para desligar a idempotência automática em todos os lugares, desligue-a no nível do cliente:MIDAZ_IDEMPOTENCY=false quando usa config.FromEnvironment().
Variáveis de ambiente
O SDK lê estas variáveis apenas quando
config.FromEnvironment() está na sua cadeia de opções de configuração.
Para a matriz completa de opções de
midaz, pkg/config e pkg/sdkctx, veja o guia de configuração no repositório do SDK.
Exemplos de projetos
concurrency, configuration, context, tracing, tracing-server, pkg-validation-demo, mass-demo-generator e workflow-with-entities.
Explore as APIs
Para mais informações sobre as APIs, consulte os links a seguir:

