Documentation de l'API
Des adresses numériques dans votre système, en un seul appel
Convertissez des coordonnées en AFA Codes (encode) et des AFA Codes en localisation (decode). Exemples prêts à l'emploi sur la zone pilote de Boa Vista (RR).
Introduction
L'API AFA.codes fait deux choses — et chacune fait l'objet d'un contrat distinct, avec sa propre clé et sa propre offre :
Coordonnées → AFA Code
Envoyez une latitude et une longitude (WGS84) et recevez le code du carré de 4 × 4 m. Accepte un point unique ou un lot.
AFA Code → localisation
Envoyez un code dans n'importe quelle graphie et recevez la graphie canonique, le centre et le polygone de la cellule.
Toutes les réponses utilisent la même enveloppe JSON : { "success": true, "data": … } ou { "success": false, "error": { "code", "message" } }. L'API ne renvoie jamais de donnée personnelle — ni CPF, ni CNPJ, ni nom : elle se contente de convertir des coordonnées en code.
URL de base :
https://app.afa.codes/apiDémarrage rapide
- 1
Créez votre compte entreprise ou développeur — cela prend quelques minutes, sans passer par l'équipe commerciale.
- 2
Dans le tableau de bord, générez une clé de sandbox : elle fonctionne sur la zone pilote de Boa Vista (RR) et n'entame pas votre quota.
- 3
Effectuez votre premier appel :
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 }'Réponse · 200
{
"success": true,
"data": {
"afacode": "BR~QYWL9P6U",
"human": "QYWL9-P6U",
"level": "L36",
"center": { "lat": 2.8234874, "lng": -60.675808 }
}
}Vous voulez tester sans clé ? Utilisez le playground, qui exécute de vrais encode et decode avec une clé de démonstration.
Authentification
Chaque appel exige une clé d'API dans l'en-tête X-API-Key. Il n'existe pas d'accès anonyme : chaque clé appartient à un contrat (ENCODE, DECODE ou Territoire) de votre compte.
En-tête
X-API-Key: afa_live_xxxxxxxxxxxxxxxxxxxxxxxx- 1 clé par contrat. Encode et decode sont des contrats distincts : la clé de l'un ne fonctionne pas pour l'autre.
- Sandbox ou production. Les clés de sandbox fonctionnent uniquement sur la zone pilote de Boa Vista (RR), avec jusqu'à 1 000 requêtes par jour, et n'entament pas le quota. Les clés de production fonctionnent dans tout le Brésil.
- Conservez la clé côté serveur. Elle n'est affichée qu'une seule fois ; en cas de fuite, révoquez-la et générez-en une autre dans le tableau de bord.
Graphie canonique
L'AFA Code exposé est toujours de niveau L36 : 8 caractères qui identifient un carré de 4 × 4 m (16 m²). L'API accepte des variantes en entrée et renvoie toujours la graphie canonique.
| Forme | Exemple | Usage |
|---|---|---|
| Lisible | R7FTD-HXU | Documents, plaques, écrans (5 + tiret + 3) |
| API | BR~R7FTDHXU | Champ afacode des réponses (préfixe du pays, sans tiret) |
| Compacte | R7FTDHXU | Acceptée en entrée |
Majuscules et minuscules sont équivalentes en entrée. L'alphabet n'utilise pas de voyelles (sauf le U) pour éviter de former des mots par hasard.
Encode
/v1/encode
Point unique : envoyez lat et lng (WGS84). Champs facultatifs : ref (votre identifiant, renvoyé dans la réponse) et label. Ajoutez ?geometry=true pour recevoir le polygone de la cellule.
Lot · requête
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" }
]
}'Lot · réponse
{
"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}
Accepte R7FTD-HXU, R7FTDHXU ou BR~R7FTDHXU. Renvoie la graphie canonique, le centre et — par défaut — le polygone de la cellule (désactivable avec ?geometry=false).
cURL · decode
curl https://app.afa.codes/api/v1/decode/QYWL9-P6U \
-H "X-API-Key: $AFA_API_KEY"Réponse · 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
Lot : { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Compte également pour N requêtes.
/v1/usage
Consommation du mois de votre compte (quota, volume souscrit, pourcentage utilisé) — utile pour surveiller l'intégration.
Erreurs
Les erreurs arrivent avec success: false, un code stable (à utiliser dans votre code) et un message en portugais.
Exemple · 429
{
"success": false,
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Pacote do mês esgotado. Faça upgrade de plano para continuar."
}
}| Code | HTTP | Cas |
|---|---|---|
API_KEY_REQUIRED | 401 | En-tête X-API-Key absent. |
API_KEY_INVALID | 401 | Clé inexistante ou révoquée. |
CONTRACT_NOT_ACTIVE | 402 | La clé n'a pas de contrat actif (ex. : paiement en attente). |
CONTRACT_SUSPENDED | 402 | Contrat suspendu pour défaut de paiement. |
WRONG_CONTRACT_TYPE | 403 | Clé ENCODE utilisée pour DECODE (ou inversement) : ce sont des contrats distincts. |
OUTSIDE_SANDBOX | 403 | Clé de sandbox utilisée en dehors de la zone pilote de Boa Vista (RR). |
OUTSIDE_TERRITORY | 403 | Point en dehors du territoire souscrit (Forfait Territoire). |
VALIDATION_ERROR | 400 | Corps de requête non valide (ex. : latitude hors de -90..90, lot au-delà du maximum). |
INVALID_AFACODE | 400 | Le code n'est un AFA Code valide dans aucune des graphies acceptées. |
OUT_OF_COVERAGE | 422 | Coordonnées hors couverture (hors du Brésil ou en mer). |
UNKNOWN_AFACODE | 422 | Code bien formé, mais en dehors de la grille brésilienne. |
QUOTA_EXCEEDED | 429 | Quota et volume souscrit du mois épuisés. Passez à une offre supérieure ou attendez le mois suivant. |
RATE_LIMITED | 429 | Limite technique de 50 requêtes par seconde et par clé. |
SANDBOX_LIMIT | 429 | Limite quotidienne de la sandbox (1 000 requêtes) atteinte. |
Limites et facturation
3 000 decode
gratuits par mois et par compte
25 encode
gratuits par mois et par compte
- Le quota appartient au compte (CNPJ/CPF), pas à la clé : ajouter des clés ne multiplie pas le quota. Il se renouvelle chaque mois et n'est pas cumulable.
- Une fois le quota atteint, la consommation est imputée sur le volume souscrit (mensualité fixe par tranche — aucun dépassement n'est facturé).
- La facturation se fait à la requête : un appel par lot de N éléments compte pour N.
- Lorsque vous atteignez 90 % du volume souscrit, nous vous envoyons un e-mail d'alerte. Une fois celui-ci épuisé, les appels sont bloqués (
QUOTA_EXCEEDED) jusqu'au mois suivant ou jusqu'au passage à une offre supérieure. - Limite technique : 50 requêtes par seconde et par clé.
Tarifs
Mensualité fixe par tranche de volume. Encode et decode se souscrivent séparément.
ENCODE
| Niveau | Encode/mois (max.) | Mensualité | R$/1 000 |
|---|---|---|---|
| N1 | 50 | gratuit | — |
| 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 |
Au-delà de 100 000/mois : sur devis (AFACODES Projetos). | |||
DECODE
| Niveau | Decode/mois (max.) | Mensualité | R$/1 000 |
|---|---|---|---|
| N1 | 500 | gratuit | — |
| 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 |
Au-delà de 500 000/mois : sur devis (AFACODES Projetos). | |||
DECODE for Startups
offre annuelle1 500 requêtes par mois pour ceux qui démarrent.
1 800,00 R$/an
Commencez dès maintenant, gratuitement
Le quota mensuel gratuit est inclus avec le compte. Testez dans la sandbox et passez en production quand vous le souhaitez.
