AFA.codes
Entrar Gerar meu endereço

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.

Experimente no playground Criar conta grátis

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:

ENCODE

Coordenada → AFA Code

Envie latitude e longitude (WGS84) e receba o código do quadrado de 4 × 4 m. Aceita ponto único ou lote.

DECODE

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/api

Quickstart

  1. 1

    Crie sua conta de empresa ou desenvolvedor — leva poucos minutos e não precisa falar com vendas.

  2. 2

    No painel, gere uma chave de sandbox: ela funciona na área-modelo de Boa Vista/RR e não consome sua franquia.

  3. 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.

FormaExemploUso
HumanaR7FTD-HXUDocumentos, placas, telas (5 + hífen + 3)
APIBR~R7FTDHXUCampo afacode das respostas (prefixo do país, sem hífen)
CompactaR7FTDHXUAceita 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

POST

/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 } }
    ]
  }
}
Lote: até 1.000 pontos por chamada. Uma chamada com N pontos conta N requisições na franquia e no pacote.

Decode

GET

/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]]]
    }
  }
}
POST

/v1/decode

Lote: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Também conta N requisições.

GET

/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ódigoHTTPQuando acontece
API_KEY_REQUIRED401Header X-API-Key ausente.
API_KEY_INVALID401Chave inexistente ou revogada.
CONTRACT_NOT_ACTIVE402A chave não tem contrato ativo (ex.: aguardando pagamento).
CONTRACT_SUSPENDED402Contrato suspenso por inadimplência.
WRONG_CONTRACT_TYPE403Chave de ENCODE usada para DECODE (ou vice-versa) — são contratos independentes.
OUTSIDE_SANDBOX403Chave de sandbox usada fora da área-modelo de Boa Vista/RR.
OUTSIDE_TERRITORY403Ponto fora do território contratado (pacote Território).
VALIDATION_ERROR400Corpo inválido (ex.: latitude fora de -90..90, lote acima do máximo).
INVALID_AFACODE400O código não é um AFA Code válido em nenhuma grafia aceita.
OUT_OF_COVERAGE422Coordenada fora da cobertura (fora do Brasil ou no mar).
UNKNOWN_AFACODE422Código bem formado, mas fora da grade brasileira.
QUOTA_EXCEEDED429Franquia e pacote do mês esgotados. Faça upgrade ou aguarde a virada do mês.
RATE_LIMITED429Limite técnico de 50 requisições por segundo por chave.
SANDBOX_LIMIT429Limite 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ívelEncode/mês (até)MensalidadeR$/1k
N1 50grátis—
N2 1.000R$ 500,00500
N3 5.000R$ 2.000,00400
N4 15.000R$ 5.500,00367
N5 35.000R$ 11.000,00314
N6 65.000R$ 18.000,00277
N7 100.000R$ 25.000,00250

Acima de 100.000/mês: sob consulta (AFACODES Projetos).

DECODE

NívelDecode/mês (até)MensalidadeR$/1k
N1 500grátis—
N2 5.000R$ 225,0045
N3 25.000R$ 1.000,0040
N4 75.000R$ 2.625,0035
N5 150.000R$ 4.500,0030
N6 300.000R$ 8.100,0027
N7 500.000R$ 12.500,0025

Acima de 500.000/mês: sob consulta (AFACODES Projetos).

DECODE for Startups

plano anual

1.500 consultas por mês para quem está começando.

R$ 1.800,00/ano

Ver todas as soluções

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.

Criar contaPlayground