AmethysAPI Wallet
API REST · v1

Conecte sua loja à Amethys

Gerencie produtos, cupons, estoque e catálogos por uma API autenticada, com permissões granulares e isolamento automático entre lojas.

Primeiros passos

Uma integração segura em poucos minutos

Crie a chave no painel, guarde-a no servidor e envie apenas o cabeçalho de autenticação.

1. Crie a chave

No painel da loja, abra Integrações, defina um nome, uma validade e somente as permissões necessárias.

2. Salve uma vez

A chave começa com amk_ e o valor completo é mostrado apenas na criação. Depois, somente o hash permanece armazenado.

3. Chame a API

Envie X-Api-Key em seu back-end. A própria chave identifica a loja; não envie X-Store-Id.

Autenticação

A chave já conhece a loja

Cada chave pertence a uma única loja e carrega seu próprio conjunto de permissões.

Mantenha chaves de produção no servidor

Navegadores, apps distribuídos, logs públicos e repositórios não são locais seguros para credenciais permanentes. Para usar Try It, crie uma chave de teste com permissões mínimas e revogue-a depois.

Cabeçalho
X-Api-Key
Prefixo
amk_
Escopo da loja
Resolvido no servidor
Transporte
HTTPS obrigatório
Primeira requisição
curl "https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products" \
  --request GET \
  --header "X-Api-Key: amk_SUA_CHAVE" \
  --header "Accept: application/json"

Contrato

Respostas previsíveis

A API sempre informa success e retorna data em sucesso ou error em falha.

Sucesso
{
  "success": true,
  "data": { ... }
}
Erro
{
  "success": false,
  "error": "Descrição segura do erro"
}

Referência completa

18 operações disponíveis

Os parâmetros com dois-pontos são identificadores de recursos pertencentes à loja autenticada.

Produtos

Crie, consulte, edite e remova produtos da loja vinculada à chave.

GET
/products

Listar produtos

Retorna os produtos pertencentes à loja autenticada.

Permissão exigida

products:list
Requisição
GET https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products
Exemplo de resposta
{
  "success": true,
  "data": [
    {
      "id": "produto_id",
      "name": "Produto digital",
      "description": "Descrição da oferta",
      "delivery_type": "stock",
      "visible": true
    }
  ]
}
POST
/products

Criar produto

Cria um produto inicialmente não publicado para revisão segura no painel.

Permissão exigida

products:create

name é obrigatório. O produto nasce com visible: false.

Requisição
POST https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products
Corpo JSON
{
  "name": "Produto digital",
  "description": "Descrição completa",
  "banner": "https://exemplo.com/banner.png",
  "hex_color": "#8B5CF6",
  "delivery_type": "stock"
}
PATCH
/products/:productId

Editar produto

Altera somente os campos informados de um produto da loja.

Permissão exigida

products:edit
Requisição
PATCH https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId
Corpo JSON
{
  "name": "Novo nome",
  "description": "Nova descrição",
  "banner": "https://exemplo.com/banner.png",
  "hex_color": "#7C3AED",
  "delivery_type": "stock",
  "visible": true
}
DELETE
/products/:productId

Excluir produto

Remove permanentemente um produto pertencente à loja.

Permissão exigida

products:delete

Operação destrutiva. Confirme o identificador antes de executar.

Requisição
DELETE https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId

Cupons

Gerencie descontos associados a um produto específico.

GET
/products/:productId/coupons

Listar cupons

Lista os cupons cadastrados no produto informado.

Permissão exigida

coupons:list
Requisição
GET https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/coupons
POST
/products/:productId/coupons

Criar cupom

Adiciona um novo cupom ao produto.

Permissão exigida

coupons:create

name é obrigatório. percent e duration_days são validados pelo servidor.

Requisição
POST https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/coupons
Corpo JSON
{
  "name": "LANCAMENTO20",
  "percent": 20,
  "duration_days": 7
}
PATCH
/products/:productId/coupons/:couponId

Editar cupom

Atualiza nome, percentual, validade ou estado do cupom.

Permissão exigida

coupons:edit
Requisição
PATCH https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/coupons/:couponId
Corpo JSON
{
  "name": "LANCAMENTO15",
  "percent": 15,
  "duration_days": 14,
  "active": true
}
DELETE
/products/:productId/coupons/:couponId

Excluir cupom

Remove o cupom indicado do produto.

Permissão exigida

coupons:delete
Requisição
DELETE https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/coupons/:couponId

Estoque e opções

Configure opções comerciais e os itens entregues automaticamente.

GET
/products/:productId/stock

Listar opções de estoque

Retorna as opções e a disponibilidade do produto.

Permissão exigida

stock:list
Requisição
GET https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/stock
POST
/products/:productId/stock

Criar opção

Cria uma opção de preço e entrega no produto.

Permissão exigida

stock:create
Requisição
POST https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/stock
Corpo JSON
{
  "name": "Licença mensal",
  "price": 49.9,
  "emoji": "💜",
  "pre_description": "Acesso por 30 dias",
  "description": "Detalhes completos",
  "instructions": "Siga as instruções enviadas por e-mail"
}
PATCH
/products/:productId/stock/:campoId

Editar opção

Atualiza os dados comerciais ou de entrega de uma opção.

Permissão exigida

stock:edit
Requisição
PATCH https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/stock/:campoId
Corpo JSON
{
  "name": "Licença anual",
  "price": 399.9,
  "instructions": "Ative sua licença no portal"
}
DELETE
/products/:productId/stock/:campoId

Excluir opção

Remove uma opção e sua configuração de estoque.

Permissão exigida

stock:delete
Requisição
DELETE https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/stock/:campoId
POST
/products/:productId/stock/:campoId/items

Adicionar itens

Insere itens únicos que poderão ser entregues após pagamentos confirmados.

Permissão exigida

stock:edit

Aceita um array de strings com até 10.000 itens por requisição. Nunca reutilize um segredo entregue.

Requisição
POST https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/stock/:campoId/items
Corpo JSON
{
  "items": [
    "CHAVE-UNICA-001",
    "CHAVE-UNICA-002"
  ]
}
DELETE
/products/:productId/stock/:campoId/items

Limpar itens disponíveis

Remove todos os itens ainda disponíveis daquela opção.

Permissão exigida

stock:edit

Ação destrutiva. Itens já entregues permanecem registrados conforme as regras da plataforma.

Requisição
DELETE https://api.amethys.lat/api/v1/dashboard/store/integrations/public/products/:productId/stock/:campoId/items

Catálogos

Organize produtos em coleções exibidas na vitrine.

GET
/catalogs

Listar catálogos

Retorna os catálogos da loja autenticada.

Permissão exigida

catalogs:list
Requisição
GET https://api.amethys.lat/api/v1/dashboard/store/integrations/public/catalogs
POST
/catalogs

Criar catálogo

Cria uma coleção e opcionalmente associa produtos.

Permissão exigida

catalogs:create
Requisição
POST https://api.amethys.lat/api/v1/dashboard/store/integrations/public/catalogs
Corpo JSON
{
  "name": "Mais vendidos",
  "description": "Produtos em destaque",
  "icon": "Sparkles",
  "product_ids": ["produto_1", "produto_2"]
}
PATCH
/catalogs/:id

Editar catálogo

Atualiza dados, ordem e produtos associados.

Permissão exigida

catalogs:edit
Requisição
PATCH https://api.amethys.lat/api/v1/dashboard/store/integrations/public/catalogs/:id
Corpo JSON
{
  "name": "Destaques",
  "description": "Seleção principal",
  "icon": "Star",
  "product_ids": ["produto_1"],
  "order": 1
}
DELETE
/catalogs/:id

Excluir catálogo

Remove o catálogo sem excluir os produtos associados.

Permissão exigida

catalogs:delete
Requisição
DELETE https://api.amethys.lat/api/v1/dashboard/store/integrations/public/catalogs/:id

Menor privilégio

Permissões granulares

Conceda apenas as ações que sua integração realmente executa.

RecursoListarCriarEditarExcluir
products
stock
coupons
catalogs

Tempo real

WebSocket

A API REST continua disponível para consultas e comandos. Para receber mudanças sem consultar repetidamente, crie uma API Key com events:read e conecte seu servidor ao endereço abaixo. Envie a chave no cabeçalho X-Api-Key; não coloque a chave na URL ou em código de navegador.

wss://api.amethys.lat/api/v1/dashboard/store/integrations/ws

Protocolo

A conexão recebe connected, depois os 25 eventos mais recentes. Cada evento contém event_id, type, store_id, occurred_at e data com identificadores seguros. Envie {"type":"event.ack","event_id":"..."} após processar. Na reconexão, use ?after=<último event_id> para retomar. O servidor consulta a outbox persistida e pode reenviar eventos; trate event_id de forma idempotente.

O canal é somente de eventos. Comandos continuam na API REST. A chave é revalidada durante a conexão e a leitura pode ser revogada no painel.

import WebSocket from "ws";

const socket = new WebSocket(
  "wss://api.amethys.lat/api/v1/dashboard/store/integrations/ws",
  { headers: { "X-Api-Key": process.env.AMETHYS_API_KEY } }
);

socket.on("message", (raw) => {
  const event = JSON.parse(raw.toString());
  if (!event.event_id) return;
  // Persista event.event_id para retomar com ?after=<id>.
  console.log(event.type, event.data);
  socket.send(JSON.stringify({
    type: "event.ack", event_id: event.event_id
  }));
});

Entrega HTTP

Webhooks

Configure um endpoint HTTPS em Configurações → Webhooks da loja e selecione os eventos. Cada endpoint tem um segredo de assinatura próprio. A Amethys envia um POST com id, event, createdAt e data. O cabeçalho X-Amethys-Delivery identifica a tentativa; X-Amethys-Signature contém o HMAC SHA-256 do corpo bruto.

Eventos e entrega

Há eventos de vendas, pagamentos, afiliados, suporte, produtos, estoque, cupons e catálogos. O worker de webhooks entrega eventos da fila persistida e tenta novamente até cinco vezes em falhas. Responda com HTTP 2xx somente após processar com segurança; deduplique pelo identificador de entrega.

Os históricos de WebSocket e Webhooks ficam nas páginas do Menu da dashboard. Ali é possível filtrar WebSocket por API Key e Webhooks por endpoint/chave de assinatura, sem revelar as chaves.

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", process.env.AMETHYS_WEBHOOK_SECRET)
  .update(rawBody).digest("hex");
const received = request.headers["x-amethys-signature"]?.replace(/^sha256=/, "");
if (!received || !/^[0-9a-f]{64}$/i.test(received) || !timingSafeEqual(
  Buffer.from(expected, "hex"), Buffer.from(received, "hex")
)) throw new Error("Assinatura inválida");

Limites de requisição

O limite global é de 180 requisições por minuto por IP. Operações de escrita também respeitam 120 por minuto por IP e 60 por minuto por chave/ator.

Ao receber 429, leia Retry-After, aplique backoff exponencial com aleatoriedade e não repita escritas cegamente.

Validação e isolamento

Permissão, validade da chave, propriedade da loja, identificadores e payloads são validados pelo back-end. Um identificador enviado pelo cliente não altera o escopo associado à chave.

Ainda assim, sua aplicação deve validar entrada do próprio usuário e tratar cada resposta como falível.

Diagnóstico

Códigos de erro

Use o status HTTP para decidir se deve corrigir, autenticar, aguardar ou registrar o incidente.

400

Requisição inválida

Revise JSON, parâmetros e tipos.

401

Não autenticado

X-Api-Key ausente, inválida ou expirada.

403

Sem permissão

A chave não possui a permissão exigida.

404

Não encontrado

O recurso não existe ou não pertence à loja da chave.

409

Conflito

O estado atual impede a operação.

422

Regra de negócio

Os dados são válidos, mas não atendem à regra.

429

Limite excedido

Aguarde o Retry-After antes de tentar novamente.

500

Erro interno

Registre a ocorrência e tente novamente com segurança.

Checklist

Pronto para produção

Cuidados mínimos para uma integração confiável.

Armazene a chave em um cofre de segredos ou variável de ambiente no servidor.

Crie chaves separadas por aplicação e ambiente.

Use o menor conjunto possível de permissões e defina validade.

Revogue imediatamente chaves expostas ou que não são mais utilizadas.

Não registre cabeçalhos de autenticação em logs, erros ou ferramentas de analytics.

Implemente timeout, backoff e idempotência na sua própria camada de negócio.

Valide identificadores e dados antes de chamar a API.

Monitore respostas 401, 403 e 429 sem tentar contornar os controles.