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. Envie o token cru, sem o prefixo Bearer. 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/-/documents/12345678000190 \
  -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	Valor de enumeração que a API não sabe mapear	a mensagem da exceção, sem envelope JSON — o texto é Unexpected value: <valor>
502	Serviço downstream indisponível	{"messages": ["message.integration.connection.refused"]}

Formato de erros da API

Não existe um formato único de erro. O mais comum é {"messages": ["..."]} — um objeto com array de strings —, usado na maioria dos 400, 404, 409 e 502. Mas um parâmetro de caminho ou query com tipo errado devolve um objeto de quatro chaves ({"timestamp": "...", "status": 400, "error": "Bad Request", "message": "message.{parametro}.invalid"}), e os erros 403 e 405 devolvem apenas a mensagem, sem envelope JSON (podendo chegar como texto puro ou como string entre aspas, conforme a negociação de conteúdo). Os 401 do Kong vêm com body, no formato {"data": [], "error": {...}}, e os 415 vêm sem body. Trate erros sempre pelo código HTTP e de forma defensiva — verifique se o corpo é um objeto antes de acessar messages. O catálogo completo está em Erros.

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