AFA.codes
Générer mon adresse

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

Essayer dans le playground Créer un compte gratuit

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 :

ENCODE

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.

DECODE

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

Démarrage rapide

  1. 1

    Créez votre compte entreprise ou développeur — cela prend quelques minutes, sans passer par l'équipe commerciale.

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

FormeExempleUsage
LisibleR7FTD-HXUDocuments, plaques, écrans (5 + tiret + 3)
APIBR~R7FTDHXUChamp afacode des réponses (préfixe du pays, sans tiret)
CompacteR7FTDHXUAccepté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

POST

/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 } }
    ]
  }
}
Lot : jusqu'à 1 000 points par appel. Un appel de N points compte pour N requêtes dans le quota et dans le volume souscrit.

Decode

GET

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

/v1/decode

Lot : { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Compte également pour N requêtes.

GET

/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."
  }
}
CodeHTTPCas
API_KEY_REQUIRED401En-tête X-API-Key absent.
API_KEY_INVALID401Clé inexistante ou révoquée.
CONTRACT_NOT_ACTIVE402La clé n'a pas de contrat actif (ex. : paiement en attente).
CONTRACT_SUSPENDED402Contrat suspendu pour défaut de paiement.
WRONG_CONTRACT_TYPE403Clé ENCODE utilisée pour DECODE (ou inversement) : ce sont des contrats distincts.
OUTSIDE_SANDBOX403Clé de sandbox utilisée en dehors de la zone pilote de Boa Vista (RR).
OUTSIDE_TERRITORY403Point en dehors du territoire souscrit (Forfait Territoire).
VALIDATION_ERROR400Corps de requête non valide (ex. : latitude hors de -90..90, lot au-delà du maximum).
INVALID_AFACODE400Le code n'est un AFA Code valide dans aucune des graphies acceptées.
OUT_OF_COVERAGE422Coordonnées hors couverture (hors du Brésil ou en mer).
UNKNOWN_AFACODE422Code bien formé, mais en dehors de la grille brésilienne.
QUOTA_EXCEEDED429Quota et volume souscrit du mois épuisés. Passez à une offre supérieure ou attendez le mois suivant.
RATE_LIMITED429Limite technique de 50 requêtes par seconde et par clé.
SANDBOX_LIMIT429Limite 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

NiveauEncode/mois (max.)MensualitéR$/1 000
N1 50gratuit—
N2 1 000500,00 R$500
N3 5 0002 000,00 R$400
N4 15 0005 500,00 R$367
N5 35 00011 000,00 R$314
N6 65 00018 000,00 R$277
N7 100 00025 000,00 R$250

Au-delà de 100 000/mois : sur devis (AFACODES Projetos).

DECODE

NiveauDecode/mois (max.)MensualitéR$/1 000
N1 500gratuit—
N2 5 000225,00 R$45
N3 25 0001 000,00 R$40
N4 75 0002 625,00 R$35
N5 150 0004 500,00 R$30
N6 300 0008 100,00 R$27
N7 500 00012 500,00 R$25

Au-delà de 500 000/mois : sur devis (AFACODES Projetos).

DECODE for Startups

offre annuelle

1 500 requêtes par mois pour ceux qui démarrent.

1 800,00 R$/an

Voir toutes les solutions

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.

Créer un comptePlayground