API Keys

Autenticação e escopos da API affiliate Lomadee

Visão geral

A API affiliate usa chaves no header x-api-key. Cada chave de afiliado possui escopos que limitam quais endpoints podem ser chamados.

Formato da chave

• Legado (v1): string de 32 caracteres — continua válida durante a transição
• Novo (v2): lmd_{env}_{prefix}_{secret} — lookup por prefix + hash; o segredo não é armazenado em texto plano

Escopos affiliate

Escopo	Endpoints
brands:read	GET /affiliate/brands, GET /affiliate/brands/{brandId}
campaigns:read	GET /affiliate/campaigns, GET /affiliate/campaigns/{campaignId}
channels:read	GET /affiliate/channels, GET /affiliate/channels/{channelId}
orders:read	GET /affiliate/orders, GET /affiliate/orders/{orderId}
products:read	GET /affiliate/products
shortener:read	GET /affiliate/shortener/urls, GET /affiliate/shortener/urls/{id}
shortener:write	POST /affiliate/shortener/url

Todos os escopos declarados em uma rota são obrigatórios (AND). Sem o escopo necessário, a API retorna 403 Forbidden.

Partner scopes

Keys of type partner authenticate /api/partner/* (catalog, no affiliate context).

Scope	Endpoints
organizations:read	GET /api/partner/organizations
brands:read	GET /api/partner/brands, GET /api/partner/brands/{brandId}
campaigns:read	GET /api/partner/campaigns, GET /api/partner/campaigns/{campaignId}

New partner keys include all three scopes. Older keys with only organizations:read still work on that route; brands and campaigns require the matching scope.

An affiliate key on a partner route (and the reverse) returns 401.

Rate limiting

Limite global: 60 requests / 60 seconds por API key e IP do cliente.

Header	Descrição
X-RateLimit-Limit	Máximo de requests na janela
X-RateLimit-Remaining	Requests restantes na janela
X-RateLimit-Reset	Unix timestamp do reset da janela

Ao exceder o limite, a API retorna 429 com código TOO_MANY_REQUESTS e headers Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining (0) e X-RateLimit-Reset.

Requisições com campos desconhecidos no body (ex.: POST /affiliate/shortener/url) retornam 400 por validação estrita (whitelist).

Erros de autenticação

Status	Código	Causa
401	UNAUTHORIZED	Header ausente, chave inválida ou tipo incorreto
403	FORBIDDEN	Chave válida sem escopo necessário

{
  "success": false,
  "message": "Insufficient scope",
  "code": "FORBIDDEN"
}

Provisionamento

Chaves affiliate são criadas via GraphQL no serviço open-api (autenticação de dashboard com JWT em x-api-token):

Operação	Descrição
listApiKeys	Lista chaves do usuário
createApiKey	Cria chave com nome e escopos opcionais
rotateApiKey	Gera novo segredo mantendo metadados
revokeApiKey	Revoga chave

A resposta de criação/rotação inclui o segredo completo apenas uma vez no campo apiKey. Guarde-o com segurança.