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.
Introduzione
L'API AFA.codes fa due cose, e ciascuna è un contratto indipendente, con la propria chiave e il proprio piano:
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.
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/apiAvvio rapido
- 1
Crea il tuo account aziendale o da sviluppatore: bastano pochi minuti e non serve contattare l'ufficio vendite.
- 2
Nella dashboard, genera una chiave sandbox: funziona nell'area modello di Boa Vista/RR e non consuma la tua franchigia.
- 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.
| Formato | Esempio | Uso |
|---|---|---|
| Leggibile | R7FTD-HXU | Documenti, targhe, schermate (5 + trattino + 3) |
| API | BR~R7FTDHXU | Campo afacode delle risposte (prefisso del Paese, senza trattino) |
| Compatto | R7FTDHXU | Accettato in input |
Maiuscole e minuscole sono equivalenti in input. L'alfabeto non usa vocali (tranne la U) per evitare parole accidentali.
Encode
/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 } }
]
}
}Decode
/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]]]
}
}
}/v1/decode
Lotto: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Anche qui valgono N richieste.
/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."
}
}| Codice | HTTP | Quando si verifica |
|---|---|---|
API_KEY_REQUIRED | 401 | Header X-API-Key mancante. |
API_KEY_INVALID | 401 | Chiave inesistente o revocata. |
CONTRACT_NOT_ACTIVE | 402 | La chiave non ha un contratto attivo (es.: in attesa di pagamento). |
CONTRACT_SUSPENDED | 402 | Contratto sospeso per mancato pagamento. |
WRONG_CONTRACT_TYPE | 403 | Chiave ENCODE usata per DECODE (o viceversa): sono contratti indipendenti. |
OUTSIDE_SANDBOX | 403 | Chiave sandbox usata fuori dall'area modello di Boa Vista/RR. |
OUTSIDE_TERRITORY | 403 | Punto fuori dal territorio sottoscritto (pacchetto Territorio). |
VALIDATION_ERROR | 400 | Corpo non valido (es.: latitudine fuori da -90..90, lotto oltre il massimo). |
INVALID_AFACODE | 400 | Il codice non è un AFA Code valido in nessuno dei formati accettati. |
OUT_OF_COVERAGE | 422 | Coordinate fuori copertura (fuori dal Brasile o in mare). |
UNKNOWN_AFACODE | 422 | Codice ben formato, ma fuori dalla griglia brasiliana. |
QUOTA_EXCEEDED | 429 | Franchigia e pacchetto del mese esauriti. Passa a un piano superiore o attendi l'inizio del mese successivo. |
RATE_LIMITED | 429 | Limite tecnico di 50 richieste al secondo per chiave. |
SANDBOX_LIMIT | 429 | Raggiunto 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
| Livello | Encode/mese (fino a) | Canone mensile | R$/1k |
|---|---|---|---|
| N1 | 50 | gratis | — |
| N2 | 1000 | 500,00 BRL | 500 |
| N3 | 5000 | 2000,00 BRL | 400 |
| N4 | 15.000 | 5500,00 BRL | 367 |
| N5 | 35.000 | 11.000,00 BRL | 314 |
| N6 | 65.000 | 18.000,00 BRL | 277 |
| N7 | 100.000 | 25.000,00 BRL | 250 |
Oltre 100.000/mese: su richiesta (AFACODES Projetos). | |||
DECODE
| Livello | Decode/mese (fino a) | Canone mensile | R$/1k |
|---|---|---|---|
| N1 | 500 | gratis | — |
| N2 | 5000 | 225,00 BRL | 45 |
| N3 | 25.000 | 1000,00 BRL | 40 |
| N4 | 75.000 | 2625,00 BRL | 35 |
| N5 | 150.000 | 4500,00 BRL | 30 |
| N6 | 300.000 | 8100,00 BRL | 27 |
| N7 | 500.000 | 12.500,00 BRL | 25 |
Oltre 500.000/mese: su richiesta (AFACODES Projetos). | |||
DECODE for Startups
piano annuale1500 consultazioni al mese per chi sta iniziando.
1800,00 BRL/anno
Inizia ora, gratis
La franchigia mensile gratuita è inclusa nell'account. Fai le tue prove nella sandbox e passa in produzione quando vuoi.
