Melhores práticas

Siga estas diretrizes para criar integrações confiáveis, econômicas e fáceis de manter.

Eficiência de créditos

Verifique o seu saldo antes de operações em lote

Antes de disparar uma operação de alto volume, verifique se tem créditos suficientes. O endpoint Uso é gratuito e devolve o seu saldo atual em tempo real.

curl "https://api.piloterr.com/v2/usage" \
  -H "x-api-key: YOUR_API_KEY"

Ative a Recarga automática para recarregar automaticamente o seu saldo quando ele descer abaixo de um limite, para que os seus fluxos de trabalho continuem sem interrupção.

Evite chamadas redundantes

Armazene em cache os resultados do seu lado sempre que os dados subjacentes não forem mudar entre os pedidos. Buscar entradas idênticas desperdiça créditos.

const cache = new Map<string, unknown>()

async function fetchCached(key: string, fetcher: () => Promise<unknown>) {
  if (cache.has(key)) return cache.get(key)
  const result = await fetcher()
  cache.set(key, result)
  return result
}

Chame apenas o que precisa

Cada endpoint tem um custo em créditos definido na página Créditos. Prefira endpoints mais leves quando uma resposta completa não for necessária.

Autenticação

Armazene chaves em variáveis de ambiente

Nunca codifique a sua chave de API diretamente no código-fonte. Use variáveis de ambiente e carregue-as em tempo de execução.

const apiKey = process.env.PILOTERR_API_KEY
if (!apiKey) throw new Error("API key is not set")

import os
api_key = os.environ["PILOTERR_API_KEY"]

$apiKey = getenv('PILOTERR_API_KEY');

apiKey := os.Getenv("PILOTERR_API_KEY")

Use chaves separadas por ambiente

Crie chaves de API distintas para desenvolvimento, staging e produção no seu painel. Isso permite revogar ou rodar uma chave comprometida sem afetar outros ambientes.

Rotacione chaves periodicamente

Trate as chaves de API como palavras-passe. Defina uma data de expiração em chaves sensíveis e rode-as regularmente na secção Chaves API das Definições da sua conta.

Tratamento de erros

Sempre verifique o código de estado HTTP

Não assuma que um pedido foi bem-sucedido. Cada resposta deve ser verificada pelo código de estado HTTP antes de processar o corpo. Consulte o guia de Tratamento de erros para uma análise completa.

Tente novamente em erros transitórios

Erros de servidor (500) e timeouts de rede são transitórios. Implemente backoff exponencial para tentar novamente automaticamente:

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const res = await fetch(url, options)
      if (res.status === 500 && attempt < maxRetries) {
        await new Promise(r => setTimeout(r, 500 * 2 ** attempt))
        continue
      }
      return res
    } catch {
      if (attempt === maxRetries) throw new Error("Max retries reached")
      await new Promise(r => setTimeout(r, 500 * 2 ** attempt))
    }
  }
}

Nunca tente novamente um 402 sem recarregar

Um 402 com Payment required, uma mensagem de fatura em aberto ou Insufficient credits: … significa que a chamada não foi executada. Tentar novamente imediatamente não ajudará. Adicione capacidade no seu painel (pack pontual ou melhoria do plano), quite faturas em aberto ou ative a Recarga automática.

Limites de taxa

Distribua os pedidos ao longo do tempo

Se precisar enviar um grande número de chamadas, distribua-as ao longo do tempo em vez de enviá-las todas de uma vez. Um simples atraso entre iterações evita atingir os limites de taxa.

const DELAY_MS = 100 // adjust based on your plan

for (const item of items) {
  await processItem(item)
  await new Promise(r => setTimeout(r, DELAY_MS))
}

Monitore a resposta 401 Rate limit exceeded

Quando o limite de taxa é atingido, a API retorna 401 com uma mensagem Rate limit exceeded… (limites por segundo/minuto do plano ou cota por chave). Aguarde antes de tentar novamente. Considere fazer upgrade do plano ou aumentar as cotas da chave se isso ocorrer com frequência. A API pública não usa HTTP 429 para esses limites.

Segurança

Nunca faça chamadas de API a partir do navegador

A sua chave de API ficaria visível para qualquer pessoa que inspecione a aba de rede. Encaminhe sempre as chamadas através do seu próprio servidor.

Browser → Your backend → Piloterr API

Valide e higienize as entradas

Se a sua aplicação aceitar parâmetros fornecidos pelo utilizador que são passados à API (URLs, consultas de pesquisa, etc.), higienize-os para evitar injeção ou comportamento inesperado.

Monitoramento

Acompanhe o consumo de créditos

Consulte o endpoint Uso regularmente (p. ex. diariamente) e alerte quando o consumo exceder um limite. Isso evita surpresas no final do período de faturação.

Registe o contexto dos pedidos

Armazene o código de estado HTTP e um carimbo de data/hora para cada chamada de API. Isso facilita auditar o consumo de créditos e depurar falhas após o ocorrido.

async function apiCall(endpoint: string, params: Record<string, string>) {
  const url = new URL(`https://api.piloterr.com${endpoint}`)
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v))

  const res = await fetch(url.toString(), {
    headers: { "x-api-key": process.env.API_KEY! },
  })

  console.log(JSON.stringify({
    endpoint,
    status: res.status,
    billed: res.status === 200 || res.status === 201,
    timestamp: new Date().toISOString(),
  }))

  return res
}

Lista de verificação

Use esta lista antes de ir para produção:

• Chave de API armazenada em variável de ambiente, não no código-fonte
• Chaves separadas para desenvolvimento e produção
• Códigos de estado HTTP verificados em cada resposta
• Lógica de nova tentativa com backoff exponencial para erros 500
• Sem novas tentativas em 402 sem adicionar créditos primeiro
• Tratamento de limites de taxa implementado
• Saldo de créditos monitorizado e alertas configurados
• Recarga automática ativada (ou processo de recarga manual definido)
• Todas as chamadas de API encaminhadas através do seu backend

Veja também: Tratamento de erros para uma lista completa de códigos de status e Glossário para definições de termos.