Boas Práticas para Integrar APIs de Terceiros em Aplicações LATAM

Desenvolver aplicações para a América Latina geralmente significa depender de APIs de terceiros para dados que não existem no seu sistema — taxas de câmbio, validação de ID fiscal, calendários de feriados, dados geográficos e mais. Embora integrar um único endpoint de API seja direto, construir uma integração de nível produção que lida com falhas de forma elegante, tem bom desempenho sob carga e não desperdiça dinheiro com chamadas desnecessárias exige engenharia deliberada. Neste artigo, cobrimos as principais boas práticas que vimos as equipes mais bem-sucedidas focadas em LATAM adotarem: limite de taxa e estratégias de retry, padrões de caching, idempotência, tratamento de erros, tratamento de respostas multilíngues, isolamento do tráfego de testes da produção e monitoramento. Esses padrões se aplicam seja integrando com a Normadata, APIs governamentais como AFIP ou SAT, processadores de pagamento ou qualquer outro serviço externo.

Limite de taxa e estratégias de retry

Toda API tem limites de taxa, documentados ou não. Atingir esses limites em produção significa que suas requisições serão limitadas ou rejeitadas, o que pode se desdobrar em erros visíveis ao usuário. A melhor defesa é uma combinação de gerenciamento proativo de taxa e retries inteligentes. Primeiro, acompanhe seu uso em relação aos limites conhecidos. Se uma API permite 100 requisições por minuto, construa um contador do lado do cliente que enfileira requisições quando você se aproxima do limite, em vez de bater no limite e tratar erros 429 reativamente. Segundo, implemente backoff exponencial com jitter para retries. Quando uma requisição falha com status 429 ou 5xx, aguarde antes de tentar novamente — e aumente o tempo de espera a cada falha subsequente. Adicionar jitter aleatório previne o problema de thundering herd, onde todas as suas requisições retentadas atingem a API ao mesmo tempo. Veja uma implementação prática:

async function fetchWithRetry(url, options, maxRetries = 3) {
 for (let attempt = 0; attempt <= maxRetries; attempt++) {
 const response = await fetch(url, options);

 if (response.ok) return response.json();

 if (response.status === 429 || response.status >= 500) {
 if (attempt === maxRetries) {
 throw new Error(`Failed after ${maxRetries + 1} attempts`);
 }

 // Exponential backoff: 1s, 2s, 4s + random jitter
 const baseDelay = Math.pow(2, attempt) * 1000;
 const jitter = Math.random() * 1000;
 await new Promise((r) => setTimeout(r, baseDelay + jitter));
 continue;
 }

 // Non-retryable error (4xx)
 const error = await response.json();
 throw new Error(error.message || `HTTP ${response.status}`);
 }
}

Estratégias de caching para diferentes tipos de dados

Nem todos os dados de API têm os mesmos requisitos de atualização. Taxas de câmbio mudam ao longo do dia, mas a lista de estados de um país não muda em anos. Ajustar a duração do cache à volatilidade dos dados economiza chamadas de API (e dinheiro) sem sacrificar a precisão. Para taxas de câmbio, um cache de 30-60 minutos é razoável para fins de exibição, mas transações devem usar a taxa mais recente disponível. Para resultados de validação de ID fiscal, armazene o resultado por 24 horas com chave na entrada exata — um CUIT que era válido esta manhã ainda é válido esta noite. Para dados de referência como países, estados, cidades e listas de bancos, use caching agressivo — 24 horas ou mais. Esses dados mudam raramente, e você pode invalidar no deploy. Para dados de feriados, faça cache por país e por ano — dentro de um determinado ano não mudam depois que o governo os publica (com raras exceções para pontos facultativos anunciados no meio do ano). O princípio fundamental é: quanto mais estáticos os dados, mais tempo você deve armazená-los em cache. Use cabeçalhos de cache retornados pela API (Cache-Control, ETag) quando disponíveis, e recorra à sua própria lógica de TTL quando não estiverem.

Idempotência para chamadas de validação

Endpoints de validação como POST /v1/validate/tax-ids são inerentemente idempotentes — enviar o mesmo CUIT duas vezes sempre retornará o mesmo resultado. Isso significa que você pode retentá-las com segurança sem efeitos colaterais.

const validationCache = new Map();
const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours

async function validateTaxId(country, type, value) {
 const cacheKey = `${country}:${type}:${value}`;
 const cached = validationCache.get(cacheKey);

 if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
 return cached.result;
 }

 const response = await fetchWithRetry(
 "https://api.normadata.io/v1/validate/tax-ids",
 {
 method: "POST",
 headers: {
 "X-API-Key": process.env.NORMADATA_API_KEY,
 "Content-Type": "application/json",
 },
 body: JSON.stringify({ value, country, type }),
 }
 );

 validationCache.set(cacheKey, {
 result: response,
 timestamp: Date.now(),
 });

 return response;
}

Tratando respostas multilíngues

Aplicações LATAM geralmente precisam suportar ao menos espanhol e português, e frequentemente inglês também. Ao integrar APIs, considere como os dados localizados fluem pelo seu sistema. Algumas APIs retornam dados em um único idioma — por exemplo, nomes de feriados podem vir no idioma local do país (espanhol para Argentina, português para Brasil). Sua camada de UI precisa lidar com isso: exibir o nome localizado diretamente, mapeá-lo para uma chave de tradução, ou usar uma API que fornece os nomes tanto no idioma local quanto em inglês. A API da Normadata, por exemplo, retorna tanto um nome local quanto um campo name_en para cada feriado. Planeje seu modelo de dados para armazenar ambos quando disponíveis. Para mensagens de erro voltadas ao usuário, nunca exiba strings de erro brutas da API para os usuários finais. Mapeie códigos de erro para suas próprias mensagens localizadas. Um erro como err_validation_failed deve ser traduzido para "El CUIT ingresado no es valido" em espanhol ou "O CUIT informado não é válido" em português, usando seu sistema de i18n.

Isolando o tráfego de testes da produção

Um erro comum é usar uma única chave de API tanto para o tráfego de desenvolvimento quanto para o de produção. O padrão mais limpo é provisionar chaves separadas por ambiente — uma para desenvolvimento local, uma para staging, uma para produção — e carregá-las via variáveis de ambiente. Isso mantém as chamadas de teste visíveis nos relatórios de uso sem contaminar as métricas de produção, e permite revogar uma chave de desenvolvimento vazada sem interromper os clientes. Para testes unitários, não chame a API real: use stub do cliente HTTP e faça assertions contra seus próprios fixtures. Reserve chamadas reais de API para testes de integração, execute-os com uma chave dedicada e proteja-os para que executem apenas sob demanda (por exemplo, em CI noturno em vez de em cada PR).

• Use uma chave dedicada por ambiente (dev, staging, prod) e carregue-a a partir de variáveis de ambiente.
• Use stub do cliente de API em testes unitários para que eles executem offline e deterministicamente.
• Reserve chamadas reais de API para testes de integração, protegidos por uma flag e uma chave dedicada.
• Nunca faça commit de chaves no controle de versão — rotacione imediatamente se uma for exposta.

Monitoramento e alertas

Depois que sua integração estiver em produção, você precisa de visibilidade sobre sua saúde. Acompanhe quatro métricas principais para cada API externa da qual você depende: tempo de resposta (p50 e p99), taxa de erros (porcentagem de respostas não-2xx), disponibilidade (você consegue alcançar a API?) e uso de cota (quão próximo você está do seu limite de taxa). Configure alertas nessas métricas para que você saiba quando algo degrada antes que seus usuários reportem. Veja um wrapper mínimo de monitoramento que registra essas métricas:

async function monitoredFetch(name, url, options) {
 const start = Date.now();
 let status = "unknown";

 try {
 const response = await fetch(url, options);
 status = response.status;

 // Log metrics to your monitoring system
 logMetric({
 api: name,
 endpoint: url,
 status,
 latency_ms: Date.now() - start,
 success: response.ok,
 });

 return response;
 } catch (error) {
 status = "network_error";

 logMetric({
 api: name,
 endpoint: url,
 status,
 latency_ms: Date.now() - start,
 success: false,
 error: error.message,
 });

 throw error;
 }
}

Conclusão

Construir integrações de API confiáveis na América Latina exige a mesma disciplina de engenharia que qualquer sistema de produção, com a complexidade adicional de dados voláteis, requisitos multilíngues e sistemas governamentais diversos. Os padrões cobertos aqui — backoff exponencial, caching apropriado ao tipo de dado, validação idempotente, tratamento de erros com consciência de localização, testes isolados por ambiente e monitoramento em produção — formam uma base sólida para qualquer aplicação focada em LATAM. As APIs da Normadata são projetadas com esses padrões em mente: códigos de erro consistentes, respostas compatíveis com caching e cabeçalhos abrangentes de limite de taxa. Consulte a documentação da API para explorar a referência completa, ou acesse a página do produto Validate para ver o que você pode validar na América do Sul.