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 (rejeitada pelo Kong)	{"data": [], "error": {"code": "401", "message": "Unauthenticated"}}
401	Authorization presente porém inválida (rejeitada pelo Kong)	{"data": [], "error": {"code": "401", "message": "Authentication refused the resquest"}} — texto literal do gateway, incluindo a grafia resquest
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) usam o formato {"data": [], "error": {"code": "...", "message": "..."}}. Não espere o formato {"timestamp": "...", "status": 400, "error": "..."} — esse é o default do Spring Boot e não é o que a Merx retorna. Trate erros sempre pelo código HTTP, nunca pelo texto de message — as mensagens do gateway podem mudar sem aviso.

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         │
  └──────────────────┘