Boas práticas

Ajuste a frequência de consulta ao seu plano

Cada plano entrega preços em um intervalo de atualização fixo: diário no Free, 30 minutos no Lite, 10 minutos no Standard, 60 segundos no Advanced e no Pro, 15 segundos no Ultra e no Business, e 5 segundos no Enterprise. Solicitar /latest com mais frequência do que isso retorna os mesmos preços e gasta cota à toa.

Como regra geral, mantenha /latest em cache pelo intervalo de atualização do seu plano e guarde em cache para sempre os dados de dias passados.

Solicite vários símbolos de uma vez

Uma requisição pode retornar qualquer número de símbolos e custa o mesmo que uma requisição de um único símbolo. Peça tudo de que você precisa em uma só chamada:

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XAU,XAG,XPT,XPD,EUR,GBP

Consultar uma vez a cada 10 minutos consome cerca de 4.500 requisições por mês, e consultar uma vez por minuto consome cerca de 45.000. Escolha o seu plano de acordo.

Use cache do seu lado

Um pequeno cache na frente da API mantém o seu app rápido e o seu uso previsível. Ele também permite continuar servindo os últimos preços válidos se uma requisição falhar:

const TTL = 10 * 60 * 1000; // Plano Standard: atualizações a cada 10 minutos
let cache = { at: 0, data: null };

export async function getPrices() {
  if (cache.data && Date.now() - cache.at < TTL) return cache.data;

  const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG,XPT,XPD", {
    headers: { "X-API-Key": process.env.METALAPI_KEY },
  });
  const data = await res.json();

  if (!data.success) {
    if (cache.data) return cache.data; // serve os últimos preços válidos
    throw new Error(`${data.error.code}: ${data.error.info}`);
  }
  cache = { at: Date.now(), data };
  return data;
}

Use o stream em vez de polling

Para painéis e ferramentas de trading que precisam de cada atualização, use /stream a partir do plano Pro. Uma única conexão Server-Sent Events de longa duração entrega os novos preços assim que eles chegam, sem nenhum loop de polling para ajustar.

Para lógicas de limiar como “me avise quando o ouro passar de US$ 4.000”, use alertas de preço e webhooks e dispense o polling por completo.

Trate os erros com elegância

• Verifique success em toda resposta e tome decisões com base em error.code.
• Repita 104, 500 e 503 com backoff. Não repita erros de validação.
• Se a API estiver inacessível, continue exibindo o último preço válido junto com o seu timestamp.
• Acompanhe o cabeçalho X-RateLimit-Remaining e a página de status do sistema.

Detalhes e código em Tratamento de erros.

Mantenha sua integração segura

• Armazene as chaves em variáveis de ambiente ou em um gerenciador de segredos, nunca no Git nem em bundles do lado do cliente.
• Use chaves restritas por domínio para qualquer chamada feita a partir do navegador.
• Use uma chave por aplicação e ambiente, e faça a rotação das chaves quando alguém sair da equipe ou quando uma chave puder ter vazado.
• Verifique o cabeçalho X-MetalAPI-Signature de todo webhook e rejeite timestamps antigos.

Dicas de desempenho

• Reutilize um único cliente HTTP para que as conexões sejam mantidas abertas entre as requisições.
• Aceite respostas compactadas (gzip ou br). A maioria dos clientes HTTP faz isso por padrão.
• Defina um timeout de requisição de cerca de 10 segundos para que uma rede lenta nunca trave o seu app.
• Carregue /symbols uma vez na inicialização e valide a entrada do usuário com essa lista, em vez de deixar que símbolos inválidos façam as requisições falharem.
• Chame /usage a partir do seu monitoramento para ser avisado antes de esgotar a cota. É gratuito.