Documentação da API de Câmbio

A BNA Exchange Rate API é uma interface JSON de alta performance projetada para fornecer taxas de câmbio de referência oficiais de Angola. Os dados são sincronizados do site oficial do Banco Nacional de Angola (BNA) de forma inteligente e eficiente.

Esta API foi construída sob a premissa de zero configuração de rede externa. Ela inicializa um banco de dados leve do SQLite localmente e sincroniza as taxas em tempo real sob demanda apenas na primeira requisição diária.

Arquitetura e Cache

Para evitar sobrecarregar o site do BNA e garantir tempos de resposta abaixo de 10ms para seus sistemas de faturamento e ERPs, a API utiliza o seguinte fluxo de cache:

Fluxo de Caching de 24 Horas:

Ao receber uma solicitação, o sistema verifica a base de dados local. Se os dados locais tiverem sido registrados hoje (mesma data do servidor) e possuírem menos de 24h, são retornados imediatamente do SQLite. Caso contrário, a API realiza uma requisição HTTP ao BNA em segundo plano, atualiza o cache local e retorna as taxas frescas.

Resiliência a Falhas (Fallback): Se a rede cair ou o site do BNA estiver temporariamente fora do ar durante a atualização diária, a API intercepta o erro de forma transparente e entrega o último registro cambial válido armazenado localmente.

Referência de API

Listar Taxas de Câmbio

Retorna todas as moedas de câmbio oficiais indexadas pelo BNA do dia útil de referência mais recente.

GET /api/cambio

Retorna o array completo sob a propriedade rates, ordenados alfabeticamente pelo código ISO 4217.

Taxa de Moeda Específica

Retorna a taxa de câmbio isolada e detalhada para uma única moeda indicada no segmento da URL.

GET /api/cambio/{codigo_moeda}

O parâmetro {codigo_moeda} na URL deve ser substituído pelo código da moeda desejada (ex: usd, eur, zar). O parâmetro é case-insensitive.

Tabela de Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
codigo_moeda	string	Sim	Código internacional de 3 letras da moeda (ISO 4217). Ex: `usd`, `eur`, `zar`.

Parâmetros de Consulta (Query Params)

Você pode controlar dinamicamente a atualização do cache anexando argumentos na string de consulta (Query String) da requisição.

Parâmetro	Tipo	Padrão	Descrição
force	boolean	`false`	Se fornecido como `true`, a API ignorará completamente os dados no SQLite e fará uma nova chamada síncrona diretamente ao BNA, forçando a atualização do banco local.