Documentação da API
Endereços digitais no seu sistema, em uma chamada
Converta coordenadas em AFA Codes (encode) e AFA Codes em localização (decode). Exemplos prontos na área-modelo de Boa Vista/RR.
Introdução
A API AFA.codes faz duas coisas — e cada uma é um contrato independente, com a sua própria chave e o seu próprio plano:
Coordenada → AFA Code
Envie latitude e longitude (WGS84) e receba o código do quadrado de 4 × 4 m. Aceita ponto único ou lote.
AFA Code → localização
Envie um código em qualquer grafia e receba a grafia canônica, o centro e o polígono da célula.
Todas as respostas usam o mesmo envelope JSON: { "success": true, "data": … } ou { "success": false, "error": { "code", "message" } }. A API nunca devolve dado pessoal — nem CPF, nem CNPJ, nem nome: só troca coordenada por código.
URL base:
https://app.afa.codes/apiQuickstart
- 1
Crie sua conta de empresa ou desenvolvedor — leva poucos minutos e não precisa falar com vendas.
- 2
No painel, gere uma chave de sandbox: ela funciona na área-modelo de Boa Vista/RR e não consome sua franquia.
- 3
Faça a primeira chamada:
cURL · encode
curl -X POST https://app.afa.codes/api/v1/encode \
-H "X-API-Key: $AFA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "lat": 2.8235, "lng": -60.6758 }'Resposta · 200
{
"success": true,
"data": {
"afacode": "BR~QYWL9P6U",
"human": "QYWL9-P6U",
"level": "L36",
"center": { "lat": 2.8234874, "lng": -60.675808 }
}
}Quiser testar sem chave? Use o playground, que roda encode e decode reais com uma chave de demonstração.
Autenticação
Toda chamada exige uma chave de API no header X-API-Key. Não existe acesso anônimo: cada chave pertence a um contrato (ENCODE, DECODE ou Território) da sua conta.
Header
X-API-Key: afa_live_xxxxxxxxxxxxxxxxxxxxxxxx- 1 chave por contrato. Encode e decode são contratos independentes — a chave de um não funciona no outro.
- Sandbox × produção. Chaves de sandbox funcionam só na área-modelo de Boa Vista/RR, com até 1.000 requisições por dia, e não consomem franquia. Chaves de produção funcionam em todo o Brasil.
- Guarde a chave no servidor. Ela é exibida uma única vez; se vazar, revogue e gere outra no painel.
Grafia canônica
O AFA Code exposto é sempre o nível L36: 8 dígitos que identificam um quadrado de 4 × 4 m (16 m²). A API aceita variações na entrada e sempre devolve a grafia canônica.
| Forma | Exemplo | Uso |
|---|---|---|
| Humana | R7FTD-HXU | Documentos, placas, telas (5 + hífen + 3) |
| API | BR~R7FTDHXU | Campo afacode das respostas (prefixo do país, sem hífen) |
| Compacta | R7FTDHXU | Aceita na entrada |
Maiúsculas e minúsculas são equivalentes na entrada. O alfabeto não usa vogais (exceto U) para evitar palavras acidentais.
Encode
/v1/encode
Ponto único: envie lat e lng (WGS84). Campos opcionais: ref (seu identificador, devolvido na resposta) e label. Adicione ?geometry=true para receber o polígono da célula.
Lote · requisição
curl -X POST "https://app.afa.codes/api/v1/encode?geometry=false" \
-H "X-API-Key: $AFA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"points": [
{ "lat": 2.8235, "lng": -60.6758, "ref": "pedido-1001" },
{ "lat": 2.8199, "lng": -60.6714, "ref": "pedido-1002" }
]
}'Lote · resposta
{
"success": true,
"data": {
"count": 2,
"results": [
{ "ref": "pedido-1001", "afacode": "BR~QYWL9P6U", "human": "QYWL9-P6U", "level": "L36",
"center": { "lat": 2.8234874, "lng": -60.675808 } },
{ "ref": "pedido-1002", "afacode": "BR~QYWLDJ6W", "human": "QYWLD-J6W", "level": "L36",
"center": { "lat": 2.8199166, "lng": -60.6713986 } }
]
}
}Decode
/v1/decode/{code}
Aceita R7FTD-HXU, R7FTDHXU ou BR~R7FTDHXU. Devolve a grafia canônica, o centro e — por padrão — o polígono da célula (desligue com ?geometry=false).
cURL · decode
curl https://app.afa.codes/api/v1/decode/QYWL9-P6U \
-H "X-API-Key: $AFA_API_KEY"Resposta · 200
{
"success": true,
"data": {
"afacode": "BR~QYWL9P6U",
"human": "QYWL9-P6U",
"level": "L36",
"center": { "lat": 2.8234874, "lng": -60.675808 },
"cell": {
"type": "Polygon",
"coordinates": [[[-60.675826, 2.823469], [-60.675791, 2.823469],
[-60.675790, 2.823505], [-60.675825, 2.823506],
[-60.675826, 2.823469]]]
}
}
}/v1/decode
Lote: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Também conta N requisições.
/v1/usage
Consumo do mês da sua conta (franquia, pacote, percentual usado) — útil para monitorar a integração.
Erros
Erros chegam com success: false, um code estável (use-o no seu código) e uma message em português.
Exemplo · 429
{
"success": false,
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Pacote do mês esgotado. Faça upgrade de plano para continuar."
}
}| Código | HTTP | Quando acontece |
|---|---|---|
API_KEY_REQUIRED | 401 | Header X-API-Key ausente. |
API_KEY_INVALID | 401 | Chave inexistente ou revogada. |
CONTRACT_NOT_ACTIVE | 402 | A chave não tem contrato ativo (ex.: aguardando pagamento). |
CONTRACT_SUSPENDED | 402 | Contrato suspenso por inadimplência. |
WRONG_CONTRACT_TYPE | 403 | Chave de ENCODE usada para DECODE (ou vice-versa) — são contratos independentes. |
OUTSIDE_SANDBOX | 403 | Chave de sandbox usada fora da área-modelo de Boa Vista/RR. |
OUTSIDE_TERRITORY | 403 | Ponto fora do território contratado (pacote Território). |
VALIDATION_ERROR | 400 | Corpo inválido (ex.: latitude fora de -90..90, lote acima do máximo). |
INVALID_AFACODE | 400 | O código não é um AFA Code válido em nenhuma grafia aceita. |
OUT_OF_COVERAGE | 422 | Coordenada fora da cobertura (fora do Brasil ou no mar). |
UNKNOWN_AFACODE | 422 | Código bem formado, mas fora da grade brasileira. |
QUOTA_EXCEEDED | 429 | Franquia e pacote do mês esgotados. Faça upgrade ou aguarde a virada do mês. |
RATE_LIMITED | 429 | Limite técnico de 50 requisições por segundo por chave. |
SANDBOX_LIMIT | 429 | Limite diário do sandbox (1.000 requisições) atingido. |
Limites e cobrança
3.000 decode
grátis por mês, por conta
25 encode
grátis por mês, por conta
- A franquia é da conta (CNPJ/CPF), não da chave: mais chaves não multiplicam a franquia. Ela renova todo mês e não acumula.
- Depois da franquia, o consumo entra no pacote contratado (mensalidade fixa por faixa — não há cobrança por excedente).
- A cobrança é por requisição: uma chamada em lote com N itens conta N.
- Ao atingir 90% do pacote, enviamos um e-mail de alerta. Ao esgotar, as chamadas são bloqueadas (
QUOTA_EXCEEDED) até a virada do mês ou um upgrade de plano. - Limite técnico: 50 requisições por segundo por chave.
Preços
Mensalidade fixa por faixa de volume. Encode e decode são contratados separadamente.
ENCODE
| Nível | Encode/mês (até) | Mensalidade | R$/1k |
|---|---|---|---|
| N1 | 50 | grátis | — |
| N2 | 1.000 | R$ 500,00 | 500 |
| N3 | 5.000 | R$ 2.000,00 | 400 |
| N4 | 15.000 | R$ 5.500,00 | 367 |
| N5 | 35.000 | R$ 11.000,00 | 314 |
| N6 | 65.000 | R$ 18.000,00 | 277 |
| N7 | 100.000 | R$ 25.000,00 | 250 |
Acima de 100.000/mês: sob consulta (AFACODES Projetos). | |||
DECODE
| Nível | Decode/mês (até) | Mensalidade | R$/1k |
|---|---|---|---|
| N1 | 500 | grátis | — |
| N2 | 5.000 | R$ 225,00 | 45 |
| N3 | 25.000 | R$ 1.000,00 | 40 |
| N4 | 75.000 | R$ 2.625,00 | 35 |
| N5 | 150.000 | R$ 4.500,00 | 30 |
| N6 | 300.000 | R$ 8.100,00 | 27 |
| N7 | 500.000 | R$ 12.500,00 | 25 |
Acima de 500.000/mês: sob consulta (AFACODES Projetos). | |||
DECODE for Startups
plano anual1.500 consultas por mês para quem está começando.
R$ 1.800,00/ano
Comece agora, de graça
A franquia mensal grátis já vem com a conta. Teste no sandbox e vá para produção quando quiser.
