Pular para o conteúdo principal

Quick Start

Vá do zero à primeira chamada autenticada em menos de 10 minutos.

Passo 1 — Obtenha suas credenciais​

A Merx utiliza autenticação via API key gerenciada pelo gateway Kong. Para obter suas credenciais de sandbox, envie um e-mail para support-api@merx.tech com:

  • Assunto: Chave de Integração - Sandbox
  • Corpo: Informe o nome da empresa, nome do responsável técnico e o objetivo da integração.

É obrigatório utilizar o e-mail corporativo da empresa solicitante.

Você receberá:

  • Authorization — chave de autenticação validada pelo gateway
Tempo de resposta

A equipe responde em até 1 dia útil para ambientes de sandbox.

Passo 2 — Faça sua primeira chamada​

Com suas credenciais em mãos, execute o comando abaixo no terminal para consultar um produtor da sua cooperativa pelo CPF/CNPJ:

curl -X GET \
  https://api.merx.tech/api/v1/integration/producers/-/documents/12345678000190 \
  -H "Authorization: {SUA_API_KEY}"

Substitua {SUA_API_KEY} pelo valor recebido no e-mail.

Header obrigatório em toda requisição:

HeaderDescrição
AuthorizationSua chave de API (validada pelo Kong gateway)

Passo 3 — Interprete a resposta​

Uma chamada bem-sucedida retorna HTTP 200 com o produtor em JSON. Exemplo de response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "company_name": "Agro Exemplo Ltda",
  "trading_name": "Agro Exemplo",
  "social_identity": "12345678000190",
  "email": "contato@agroexemplo.com.br",
  "date_of_birth": "1980-01-15",
  "address": {
    "street": "Rua das Palmeiras",
    "number": "100",
    "neighborhood": "Centro",
    "zip_code": "14400000",
    "city": "Franca",
    "state": "SP",
    "country": "Brasil"
  },
  "enabled": true,
  "removed": false,
  "created_at": 1709837511.870898000,
  "updated_at": 1709902655.467719000
}
Campos de data e campos nulos

A API usa três formatos de data, e o mesmo objeto pode misturar os três:

  • Epoch em segundos, com fração — o caso mais comum, incluindo created_at e updated_at (ex: 1709837511.870898000 — sempre 9 casas decimais)
  • Epoch em milissegundos — alguns campos legados, como initial_delivery_date, end_delivery_date e data_situacao (ex: 1734048000000)
  • ISO 8601 — apenas os campos com formato explícito, como date_of_birth e delivery_date (yyyy-MM-dd)

Confira o formato campo a campo na página do endpoint: a diferença entre os dois primeiros é de três ordens de grandeza.

Campos sem valor são omitidos da resposta em vez de virem como null — por isso rg, marital_status, dap_code, caf_code e ricaf_code não aparecem no exemplo acima.

Respostas de erro:

CódigoCausaBody
401Authorization inválida ou ausente{"data": [], "error": {...}} (resposta do Kong)
404Nenhum produtor cadastrado{"messages": ["message.producer.not-found"]}

Próximos passos​