API-Dokumentation
Digitale Adressen in Ihrem System – mit einem einzigen Aufruf
Wandeln Sie Koordinaten in AFA-Codes (Encode) und AFA-Codes in Standorte (Decode) um. Fertige Beispiele im Modellgebiet Boa Vista/RR.
Einführung
Die AFA.codes-API kann zwei Dinge – und jedes davon ist ein eigener Vertrag mit eigenem Schlüssel und eigenem Tarif:
Koordinate → AFA-Code
Senden Sie Breiten- und Längengrad (WGS84) und erhalten Sie den Code des 4 × 4 m großen Quadrats. Einzelpunkt oder Batch.
AFA-Code → Standort
Senden Sie einen Code in beliebiger Schreibweise und erhalten Sie die kanonische Schreibweise, den Mittelpunkt und das Polygon der Zelle.
Alle Antworten verwenden denselben JSON-Umschlag: { "success": true, "data": … } oder { "success": false, "error": { "code", "message" } }. Die API liefert niemals personenbezogene Daten – weder CPF noch CNPJ noch Namen: Sie wandelt nur Koordinaten in Codes um.
Basis-URL:
https://app.afa.codes/apiSchnellstart
- 1
Erstellen Sie Ihr Konto als Unternehmen oder Entwickler – das dauert nur wenige Minuten, ganz ohne Vertriebsgespräch.
- 2
Erstellen Sie im Dashboard einen Sandbox-Schlüssel: Er funktioniert im Modellgebiet Boa Vista/RR und verbraucht kein Freikontingent.
- 3
Führen Sie den ersten Aufruf aus:
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 }'Antwort · 200
{
"success": true,
"data": {
"afacode": "BR~QYWL9P6U",
"human": "QYWL9-P6U",
"level": "L36",
"center": { "lat": 2.8234874, "lng": -60.675808 }
}
}Sie möchten ohne Schlüssel testen? Nutzen Sie den Playground, der echte Encode- und Decode-Aufrufe mit einem Demo-Schlüssel ausführt.
Authentifizierung
Jeder Aufruf erfordert einen API-Schlüssel im Header X-API-Key. Anonymen Zugriff gibt es nicht: Jeder Schlüssel gehört zu einem Vertrag (ENCODE, DECODE oder Gebiet) Ihres Kontos.
Header
X-API-Key: afa_live_xxxxxxxxxxxxxxxxxxxxxxxx- 1 Schlüssel pro Vertrag. Encode und Decode sind unabhängige Verträge – der Schlüssel des einen funktioniert nicht beim anderen.
- Sandbox vs. Produktion. Sandbox-Schlüssel funktionieren nur im Modellgebiet Boa Vista/RR, mit bis zu 1.000 Anfragen pro Tag, und verbrauchen kein Freikontingent. Produktionsschlüssel funktionieren in ganz Brasilien.
- Bewahren Sie den Schlüssel auf dem Server auf. Er wird nur ein einziges Mal angezeigt; falls er bekannt wird, widerrufen Sie ihn und erstellen Sie im Dashboard einen neuen.
Kanonische Schreibweise
Der ausgegebene AFA-Code ist immer die Stufe L36: 8 Zeichen, die ein Quadrat von 4 × 4 m (16 m²) bezeichnen. Die API akzeptiert bei der Eingabe Varianten und liefert immer die kanonische Schreibweise.
| Form | Beispiel | Verwendung |
|---|---|---|
| Lesbar | R7FTD-HXU | Dokumente, Adressschilder, Bildschirme (5 + Bindestrich + 3) |
| API | BR~R7FTDHXU | Feld afacode in den Antworten (Länderpräfix, ohne Bindestrich) |
| Kompakt | R7FTDHXU | Als Eingabe akzeptiert |
Groß- und Kleinschreibung sind bei der Eingabe gleichwertig. Das Alphabet verwendet keine Vokale (außer U), um zufällige Wörter zu vermeiden.
Encode
/v1/encode
Einzelpunkt: Senden Sie lat und lng (WGS84). Optionale Felder: ref (Ihre Kennung, wird in der Antwort zurückgegeben) und label. Fügen Sie ?geometry=true hinzu, um das Polygon der Zelle zu erhalten.
Batch · Anfrage
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" }
]
}'Batch · Antwort
{
"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}
Akzeptiert R7FTD-HXU, R7FTDHXU oder BR~R7FTDHXU. Liefert die kanonische Schreibweise, den Mittelpunkt und – standardmäßig – das Polygon der Zelle (abschaltbar mit ?geometry=false).
cURL · Decode
curl https://app.afa.codes/api/v1/decode/QYWL9-P6U \
-H "X-API-Key: $AFA_API_KEY"Antwort · 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
Batch: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Zählt ebenfalls als N Anfragen.
/v1/usage
Monatsverbrauch Ihres Kontos (Freikontingent, Paket, genutzter Anteil) – nützlich zur Überwachung der Integration.
Fehler
Fehler kommen mit success: false, einem stabilen code (verwenden Sie ihn in Ihrem Code) und einer message auf Portugiesisch.
Beispiel · 429
{
"success": false,
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Pacote do mês esgotado. Faça upgrade de plano para continuar."
}
}| Code | HTTP | Wann er auftritt |
|---|---|---|
API_KEY_REQUIRED | 401 | Header X-API-Key fehlt. |
API_KEY_INVALID | 401 | Schlüssel existiert nicht oder wurde widerrufen. |
CONTRACT_NOT_ACTIVE | 402 | Der Schlüssel hat keinen aktiven Vertrag (z. B. Zahlung ausstehend). |
CONTRACT_SUSPENDED | 402 | Vertrag wegen Zahlungsverzugs ausgesetzt. |
WRONG_CONTRACT_TYPE | 403 | ENCODE-Schlüssel für DECODE verwendet (oder umgekehrt) – es sind unabhängige Verträge. |
OUTSIDE_SANDBOX | 403 | Sandbox-Schlüssel außerhalb des Modellgebiets Boa Vista/RR verwendet. |
OUTSIDE_TERRITORY | 403 | Punkt außerhalb des vertraglich vereinbarten Gebiets (Gebietspaket). |
VALIDATION_ERROR | 400 | Ungültiger Body (z. B. Breitengrad außerhalb von -90..90, Batch über dem Maximum). |
INVALID_AFACODE | 400 | Der Code ist in keiner akzeptierten Schreibweise ein gültiger AFA-Code. |
OUT_OF_COVERAGE | 422 | Koordinate außerhalb des Abdeckungsbereichs (außerhalb Brasiliens oder auf dem Meer). |
UNKNOWN_AFACODE | 422 | Code korrekt aufgebaut, aber außerhalb des brasilianischen Rasters. |
QUOTA_EXCEEDED | 429 | Freikontingent und Paket des Monats ausgeschöpft. Führen Sie ein Upgrade durch oder warten Sie bis zum Monatswechsel. |
RATE_LIMITED | 429 | Technisches Limit von 50 Anfragen pro Sekunde und Schlüssel. |
SANDBOX_LIMIT | 429 | Tageslimit der Sandbox (1.000 Anfragen) erreicht. |
Limits und Abrechnung
3.000 Decode
kostenlos pro Monat und Konto
25 Encode
kostenlos pro Monat und Konto
- Das Freikontingent gilt pro Konto (CNPJ/CPF), nicht pro Schlüssel: Mehr Schlüssel vervielfachen das Freikontingent nicht. Es erneuert sich jeden Monat und verfällt am Monatsende.
- Nach dem Freikontingent wird der Verbrauch auf das vertraglich vereinbarte Paket angerechnet (feste Monatsgebühr je Stufe – Mehrverbrauch wird nicht berechnet).
- Abgerechnet wird pro Anfrage: Ein Batch-Aufruf mit N Elementen zählt als N.
- Bei 90 % des Pakets senden wir eine Warn-E-Mail. Ist es ausgeschöpft, werden die Aufrufe bis zum Monatswechsel oder bis zu einem Tarif-Upgrade gesperrt (
QUOTA_EXCEEDED). - Technisches Limit: 50 Anfragen pro Sekunde und Schlüssel.
Preise
Feste Monatsgebühr je Volumenstufe. Encode und Decode werden separat gebucht.
ENCODE
| Stufe | Encode/Monat (bis) | Monatsgebühr | R$/1.000 |
|---|---|---|---|
| N1 | 50 | kostenlos | — |
| N2 | 1.000 | 500,00 R$ | 500 |
| N3 | 5.000 | 2.000,00 R$ | 400 |
| N4 | 15.000 | 5.500,00 R$ | 367 |
| N5 | 35.000 | 11.000,00 R$ | 314 |
| N6 | 65.000 | 18.000,00 R$ | 277 |
| N7 | 100.000 | 25.000,00 R$ | 250 |
Über 100.000/Monat: auf Anfrage (AFACODES Projetos). | |||
DECODE
| Stufe | Decode/Monat (bis) | Monatsgebühr | R$/1.000 |
|---|---|---|---|
| N1 | 500 | kostenlos | — |
| N2 | 5.000 | 225,00 R$ | 45 |
| N3 | 25.000 | 1.000,00 R$ | 40 |
| N4 | 75.000 | 2.625,00 R$ | 35 |
| N5 | 150.000 | 4.500,00 R$ | 30 |
| N6 | 300.000 | 8.100,00 R$ | 27 |
| N7 | 500.000 | 12.500,00 R$ | 25 |
Über 500.000/Monat: auf Anfrage (AFACODES Projetos). | |||
DECODE for Startups
Jahrestarif1.500 Abfragen pro Monat für den Einstieg.
1.800,00 R$/Jahr
Jetzt kostenlos starten
Das monatliche Freikontingent ist im Konto enthalten. Testen Sie in der Sandbox und wechseln Sie in die Produktion, wann Sie möchten.
