Configuração avançada

O MerxClient funciona com os defaults na maioria dos casos. Quando precisar de mais controle (timeouts, retry, ambiente de preview, observabilidade), tudo é configurado no builder.

Defaults

Opção	Default	Builder
Ambiente	SANDBOX	.environment(...)
Connect timeout	5s	.connectTimeout(...)
Read timeout	30s	.readTimeout(...)
Máx. de retries	3	.maxRetries(...)
Delay inicial do retry	200ms	.initialRetryDelay(...)

Timeouts

import java.time.Duration;

MerxClient merx = MerxClient.builder()
    .apiKey("{SUA_API_KEY}")
    .environment(Environment.PRODUCTION)
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(60))   // relatórios podem ser mais lentos
    .build();

Retry

O SDK retenta automaticamente, com backoff exponencial + jitter, apenas falhas transitórias:

• respostas 5xx e 429 Too Many Requests;
• IOException / timeouts de rede.

Erros 4xx (exceto 429) nunca são retentados — sobem direto como exceção (ver Tratamento de erros). O backoff cresce a partir do initialRetryDelay até um teto de 30s.

MerxClient merx = MerxClient.builder()
    .apiKey("{SUA_API_KEY}")
    .maxRetries(5)
    .initialRetryDelay(Duration.ofMillis(300))
    .build();

Mutações (POST) também são retentadas em falha transitória — a idempotência é responsabilidade do backend. Se precisar de garantia, trate no seu lado.

URL base customizada

Normalmente você só escolhe o ambiente com .environment(...) e o SDK usa a URL padrão correspondente (SANDBOX → homolog.api.merx.tech, PRODUCTION → api.merx.tech). Para casos em que precisa apontar para uma URL diferente, use .baseUrl(...) — quando definido, ele tem prioridade e o .environment(...) é ignorado. Os dois cenários típicos:

• Testes automatizados — apontar para um mock/stub local (ex.: WireMock em localhost) no lugar da API real.
• Endpoint dedicado — uma URL específica fornecida pelo time da Merx para o seu caso.

MerxClient merx = MerxClient.builder()
    .apiKey("{SUA_API_KEY}")
    .baseUrl("http://localhost:8082")   // ex.: mock local nos testes
    .build();

HttpClient / ObjectMapper customizados

Cenários avançados (proxy corporativo, observabilidade, serialização específica) podem injetar o HttpClient do JDK ou o ObjectMapper:

MerxClient merx = MerxClient.builder()
    .apiKey("{SUA_API_KEY}")
    .httpClient(meuHttpClientConfigurado)   // ex: proxy autenticado
    .objectMapper(meuObjectMapper)
    .build();

O MerxClient é thread-safe e feito para ser criado uma vez por token e reutilizado durante toda a vida da aplicação.