Quickstart

O que você irá aprender com esse artigo?

• Como instanciar o MerxClient.
• Como criar um produtor e uma fazenda em poucas linhas.
• Onde encontrar exemplos completos e executáveis.

Instanciando o cliente

import com.merx.sdk.api.MerxClient;
import com.merx.sdk.core.Environment;

MerxClient merx = MerxClient.builder()
        .apiKey(System.getenv("MERX_API_KEY"))
        .environment(Environment.SANDBOX)
        .build();

Criando um produtor e uma fazenda

import com.merx.sdk.model.baseline.producer.CreateProducerRequest;
import com.merx.sdk.model.baseline.farm.CreateFarmRequest;
import com.merx.sdk.model.common.IdResponse;

IdResponse producer = merx.producers().create(CreateProducerRequest.builder()
        .companyName("Fazenda X LTDA")
        .tradingName("Fazenda X")
        .socialIdentity("12345678000199")
        .build());

System.out.println("Producer id: " + producer.getId());

IdResponse farm = merx.farms().create(producer.getId(), CreateFarmRequest.builder()
        .name("Fazenda X - Sede")
        .own(true)
        .car("PR-1234567890")
        .area("250.50")
        .build());

System.out.println("Farm id: " + farm.getId());

Tratamento de erros

O SDK mapeia respostas de erro para exceções tipadas (MerxBadRequestException, MerxUnauthorizedException, MerxNotFoundException, MerxValidationException, etc.). Falhas transientes (5xx, timeouts) já passam por retry automático com backoff — erros 4xx sobem direto.

import com.merx.sdk.core.exception.MerxNotFoundException;

try {
    // operações que mutam lançam exceção em erro HTTP (finders retornam Optional)
    merx.producers().disable(producerId);
} catch (MerxNotFoundException e) {
    // 404 — recurso não existe
}

Exemplos completos e executáveis

Para fluxos end-to-end prontos para clonar e rodar, use o repositório de exemplos merx-java-sdk-examples. Uma empresa fictícia (Cooperativa Demo) executa a mesma jornada — cadastro, relatórios e negociação — em três stacks, para você comparar lado a lado:

Módulo	Stack
examples-basic	Java puro (console)
examples-spring	Spring Boot (REST)
examples-quarkus	Quarkus (REST)

O módulo examples-core concentra todas as chamadas ao SDK (um método por endpoint), servindo de catálogo de referência copiável.

git clone https://github.com/merx-delevopers/merx-java-sdk-examples.git
cd merx-java-sdk-examples
export MERX_API_KEY=<seu-token>
mvn clean install                      # build dos 4 módulos
mvn -q -pl examples-basic exec:java    # roda a jornada em Java puro