Autenticação

A Merx Integration API usa autenticação via API key gerenciada pelo gateway Kong. Toda requisição deve incluir o header de autenticação abaixo.

Header obrigatório

Header	Tipo	Descrição
Authorization	String	Chave de API obtida via support-api@merx.tech. Validada pelo Kong gateway antes de a requisição chegar à aplicação.

Header obrigatório

Toda requisição à API Merx — sem exceção — deve incluir Authorization. A ausência resulta em erro.

Exemplo de requisição autenticada

curl -X GET \
  https://api.merx.tech/api/v1/integration/producers \
  -H "Authorization: minha-api-key-aqui"

Para requisições com body (POST/PUT), adicione também Content-Type: application/json:

curl -X POST \
  https://api.merx.tech/api/v1/integration/producers \
  -H "Authorization: minha-api-key-aqui" \
  -H "Content-Type: application/json" \
  -d '{"trading_name": "Produtor Exemplo", "social_identity": "12345678000190"}'

Como obter suas credenciais

Envie um e-mail para support-api@merx.tech:

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

Use obrigatoriamente o e-mail corporativo da empresa solicitante.

Ambientes

Ambiente	Base URL	Uso
Sandbox	https://homolog.api.merx.tech	Desenvolvimento e testes. Use credentials de sandbox.
Produção	https://api.merx.tech	Ambiente de produção. Requer aprovação e credentials de produção.

Os exemplos desta documentação usam a URL base do ambiente em que este portal está publicado (sandbox ou produção). Para chamar o outro ambiente, basta trocar o host pela Base URL correspondente na tabela acima — o restante do path permanece igual.

Erros de autenticação

Código HTTP	Causa	Response Body
401	Authorization ausente ou inválida (rejeitada pelo Kong)	sem body (resposta direta do gateway)
403	Sem permissão de acesso ao recurso	mensagem de texto simples (sem wrapper JSON)
502	Serviço downstream indisponível	{"messages": ["message.integration.connection.refused"]}

Formato de erros da API

Erros gerados pela aplicação Merx usam o formato {"messages": ["..."]} — um objeto com array de strings. Erros gerados pelo Kong (401) não têm body padrão. Não espere o formato {"timestamp": "...", "status": 400, "error": "..."} — esse é o default do Spring Boot e não é o que a Merx retorna.

Arquitetura de autenticação

Requisição do Parceiro
        │
        ▼
  ┌──────────┐
  │   Kong   │ ← valida "Authorization" header
  │ Gateway  │   rejeita com 401 se inválida
  └────┬─────┘
       │ (Authorization válida — Kong forwarda a requisição)
       ▼
  ┌──────────────────┐
  │ Merx Integration │
  │      API         │
  └──────────────────┘