AFA.codes
Genera il mio indirizzo

Documentazione dell'API

Indirizzi digitali nel tuo sistema, con una sola chiamata

Converti coordinate in AFA Code (encode) e AFA Code in posizioni (decode). Esempi pronti nell'area modello di Boa Vista/RR.

Provalo nel playground Crea un account gratuito

Introduzione

L'API AFA.codes fa due cose, e ciascuna è un contratto indipendente, con la propria chiave e il proprio piano:

ENCODE

Coordinate → AFA Code

Invia latitudine e longitudine (WGS84) e ricevi il codice del quadrato di 4 × 4 m. Accetta un singolo punto o un lotto.

DECODE

AFA Code → posizione

Invia un codice in qualsiasi formato e ricevi il formato canonico, il centro e il poligono della cella.

Tutte le risposte usano lo stesso involucro JSON: { "success": true, "data": … } oppure { "success": false, "error": { "code", "message" } }. L'API non restituisce mai dati personali, né CPF, né CNPJ, né nomi: converte soltanto coordinate in codici.

URL di base:

https://app.afa.codes/api

Avvio rapido

  1. 1

    Crea il tuo account aziendale o da sviluppatore: bastano pochi minuti e non serve contattare l'ufficio vendite.

  2. 2

    Nella dashboard, genera una chiave sandbox: funziona nell'area modello di Boa Vista/RR e non consuma la tua franchigia.

  3. 3

    Effettua la prima chiamata:

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 }'

Risposta · 200

{
  "success": true,
  "data": {
    "afacode": "BR~QYWL9P6U",
    "human": "QYWL9-P6U",
    "level": "L36",
    "center": { "lat": 2.8234874, "lng": -60.675808 }
  }
}

Vuoi fare una prova senza chiave? Usa il playground, che esegue encode e decode reali con una chiave dimostrativa.

Autenticazione

Ogni chiamata richiede una chiave API nell'header X-API-Key. Non esiste accesso anonimo: ogni chiave appartiene a un contratto (ENCODE, DECODE o Territorio) del tuo account.

Header

X-API-Key: afa_live_xxxxxxxxxxxxxxxxxxxxxxxx
  • 1 chiave per contratto. Encode e decode sono contratti indipendenti: la chiave dell'uno non funziona con l'altro.
  • Sandbox e produzione. Le chiavi sandbox funzionano solo nell'area modello di Boa Vista/RR, con un massimo di 1.000 richieste al giorno, e non consumano la franchigia. Le chiavi di produzione funzionano in tutto il Brasile.
  • Conserva la chiave sul server. Viene mostrata una sola volta; se viene divulgata, revocala e generane un'altra nella dashboard.

Formato canonico

L'AFA Code esposto è sempre di livello L36: 8 caratteri che identificano un quadrato di 4 × 4 m (16 m²). L'API accetta varianti in input e restituisce sempre il formato canonico.

FormatoEsempioUso
LeggibileR7FTD-HXUDocumenti, targhe, schermate (5 + trattino + 3)
APIBR~R7FTDHXUCampo afacode delle risposte (prefisso del Paese, senza trattino)
CompattoR7FTDHXUAccettato in input

Maiuscole e minuscole sono equivalenti in input. L'alfabeto non usa vocali (tranne la U) per evitare parole accidentali.

Encode

POST

/v1/encode

Punto singolo: invia lat e lng (WGS84). Campi facoltativi: ref (il tuo identificativo, restituito nella risposta) e label. Aggiungi ?geometry=true per ricevere il poligono della cella.

Lotto · richiesta

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" }
    ]
  }'

Lotto · risposta

{
  "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 } }
    ]
  }
}
Lotto: fino a 1.000 punti per chiamata. Una chiamata con N punti vale N richieste nella franchigia e nel pacchetto.

Decode

GET

/v1/decode/{code}

Accetta R7FTD-HXU, R7FTDHXU o BR~R7FTDHXU. Restituisce il formato canonico, il centro e, per impostazione predefinita, il poligono della cella (disattivalo con ?geometry=false).

cURL · decode

curl https://app.afa.codes/api/v1/decode/QYWL9-P6U \
  -H "X-API-Key: $AFA_API_KEY"

Risposta · 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

Lotto: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Anche qui valgono N richieste.

GET

/v1/usage

Consumo mensile del tuo account (franchigia, pacchetto, percentuale utilizzata): utile per monitorare l'integrazione.

Errori

Gli errori arrivano con success: false, un code stabile (usalo nel tuo codice) e un message in portoghese.

Esempio · 429

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Pacote do mês esgotado. Faça upgrade de plano para continuar."
  }
}
CodiceHTTPQuando si verifica
API_KEY_REQUIRED401Header X-API-Key mancante.
API_KEY_INVALID401Chiave inesistente o revocata.
CONTRACT_NOT_ACTIVE402La chiave non ha un contratto attivo (es.: in attesa di pagamento).
CONTRACT_SUSPENDED402Contratto sospeso per mancato pagamento.
WRONG_CONTRACT_TYPE403Chiave ENCODE usata per DECODE (o viceversa): sono contratti indipendenti.
OUTSIDE_SANDBOX403Chiave sandbox usata fuori dall'area modello di Boa Vista/RR.
OUTSIDE_TERRITORY403Punto fuori dal territorio sottoscritto (pacchetto Territorio).
VALIDATION_ERROR400Corpo non valido (es.: latitudine fuori da -90..90, lotto oltre il massimo).
INVALID_AFACODE400Il codice non è un AFA Code valido in nessuno dei formati accettati.
OUT_OF_COVERAGE422Coordinate fuori copertura (fuori dal Brasile o in mare).
UNKNOWN_AFACODE422Codice ben formato, ma fuori dalla griglia brasiliana.
QUOTA_EXCEEDED429Franchigia e pacchetto del mese esauriti. Passa a un piano superiore o attendi l'inizio del mese successivo.
RATE_LIMITED429Limite tecnico di 50 richieste al secondo per chiave.
SANDBOX_LIMIT429Raggiunto il limite giornaliero della sandbox (1.000 richieste).

Limiti e addebiti

3000 decode

gratuiti al mese, per account

25 encode

gratuiti al mese, per account

  • La franchigia è dell'account (CNPJ/CPF), non della chiave: più chiavi non moltiplicano la franchigia. Si rinnova ogni mese e non è cumulabile.
  • Superata la franchigia, il consumo rientra nel pacchetto sottoscritto (canone mensile fisso per fascia, senza addebiti per eccedenze).
  • L'addebito è per richiesta: una chiamata in lotto con N elementi vale N.
  • Al raggiungimento del 90% del pacchetto, inviamo un'e-mail di avviso. Una volta esaurito, le chiamate vengono bloccate (QUOTA_EXCEEDED) fino all'inizio del mese successivo o al passaggio a un piano superiore.
  • Limite tecnico: 50 richieste al secondo per chiave.

Prezzi

Canone mensile fisso per fascia di volume. Encode e decode si sottoscrivono separatamente.

ENCODE

LivelloEncode/mese (fino a)Canone mensileR$/1k
N1 50gratis—
N2 1000500,00 BRL500
N3 50002000,00 BRL400
N4 15.0005500,00 BRL367
N5 35.00011.000,00 BRL314
N6 65.00018.000,00 BRL277
N7 100.00025.000,00 BRL250

Oltre 100.000/mese: su richiesta (AFACODES Projetos).

DECODE

LivelloDecode/mese (fino a)Canone mensileR$/1k
N1 500gratis—
N2 5000225,00 BRL45
N3 25.0001000,00 BRL40
N4 75.0002625,00 BRL35
N5 150.0004500,00 BRL30
N6 300.0008100,00 BRL27
N7 500.00012.500,00 BRL25

Oltre 500.000/mese: su richiesta (AFACODES Projetos).

DECODE for Startups

piano annuale

1500 consultazioni al mese per chi sta iniziando.

1800,00 BRL/anno

Vedi tutte le soluzioni

Inizia ora, gratis

La franchigia mensile gratuita è inclusa nell'account. Fai le tue prove nella sandbox e passa in produzione quando vuoi.

Crea un accountPlayground