Documentación de la API
Direcciones digitales en tu sistema, con una sola llamada
Convierte coordenadas en códigos AFA (encode) y códigos AFA en ubicaciones (decode). Ejemplos listos para usar en la zona piloto de Boa Vista/RR.
Introducción
La API de AFA.codes hace dos cosas, y cada una es un contrato independiente, con su propia clave y su propio plan:
Coordenada → código AFA
Envía latitud y longitud (WGS84) y recibe el código del cuadrado de 4 × 4 m. Acepta un punto único o un lote.
Código AFA → ubicación
Envía un código en cualquier formato y recibe el formato canónico, el centro y el polígono de la celda.
Todas las respuestas usan la misma estructura JSON: { "success": true, "data": … } o { "success": false, "error": { "code", "message" } }. La API nunca devuelve datos personales —ni CPF, ni CNPJ, ni nombres—: solo convierte coordenadas en códigos.
URL base:
https://app.afa.codes/apiInicio rápido
- 1
Crea tu cuenta de empresa o desarrollador: tarda unos minutos y no necesitas hablar con ventas.
- 2
En el panel, genera una clave de sandbox: funciona en la zona piloto de Boa Vista/RR y no consume tu cuota gratuita.
- 3
Haz la primera llamada:
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 }'Respuesta · 200
{
"success": true,
"data": {
"afacode": "BR~QYWL9P6U",
"human": "QYWL9-P6U",
"level": "L36",
"center": { "lat": 2.8234874, "lng": -60.675808 }
}
}¿Quieres probar sin clave? Usa el playground, que ejecuta encode y decode reales con una clave de demostración.
Autenticación
Toda llamada requiere una clave de API en el encabezado X-API-Key. No hay acceso anónimo: cada clave pertenece a un contrato (ENCODE, DECODE o Territorio) de tu cuenta.
Encabezado
X-API-Key: afa_live_xxxxxxxxxxxxxxxxxxxxxxxx- 1 clave por contrato. Encode y decode son contratos independientes: la clave de uno no funciona en el otro.
- Sandbox frente a producción. Las claves de sandbox solo funcionan en la zona piloto de Boa Vista/RR, con hasta 1000 solicitudes al día, y no consumen cuota gratuita. Las claves de producción funcionan en todo Brasil.
- Guarda la clave en el servidor. Se muestra una sola vez; si se filtra, revócala y genera otra en el panel.
Formato canónico
El código AFA expuesto es siempre el nivel L36: 8 caracteres que identifican un cuadrado de 4 × 4 m (16 m²). La API acepta variaciones en la entrada y siempre devuelve el formato canónico.
| Formato | Ejemplo | Uso |
|---|---|---|
| Legible | R7FTD-HXU | Documentos, placas, pantallas (5 + guion + 3) |
| API | BR~R7FTDHXU | Campo afacode de las respuestas (prefijo del país, sin guion) |
| Compacto | R7FTDHXU | Aceptado en la entrada |
En la entrada, mayúsculas y minúsculas son equivalentes. El alfabeto no usa vocales (excepto la U) para evitar palabras accidentales.
Encode
/v1/encode
Punto único: envía lat y lng (WGS84). Campos opcionales: ref (tu identificador, que se devuelve en la respuesta) y label. Agrega ?geometry=true para recibir el polígono de la celda.
Lote · solicitud
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" }
]
}'Lote · respuesta
{
"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}
Acepta R7FTD-HXU, R7FTDHXU o BR~R7FTDHXU. Devuelve el formato canónico, el centro y, por defecto, el polígono de la celda (desactívalo con ?geometry=false).
cURL · decode
curl https://app.afa.codes/api/v1/decode/QYWL9-P6U \
-H "X-API-Key: $AFA_API_KEY"Respuesta · 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
Lote: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. También cuenta como N solicitudes.
/v1/usage
Consumo del mes de tu cuenta (cuota gratuita, paquete, porcentaje usado): útil para hacer seguimiento de la integración.
Errores
Los errores llegan con success: false, un code estable (úsalo en tu código) y un message en portugués.
Ejemplo · 429
{
"success": false,
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Pacote do mês esgotado. Faça upgrade de plano para continuar."
}
}| Código | HTTP | Cuándo ocurre |
|---|---|---|
API_KEY_REQUIRED | 401 | Falta el encabezado X-API-Key. |
API_KEY_INVALID | 401 | Clave inexistente o revocada. |
CONTRACT_NOT_ACTIVE | 402 | La clave no tiene un contrato activo (p. ej.: pendiente de pago). |
CONTRACT_SUSPENDED | 402 | Contrato suspendido por falta de pago. |
WRONG_CONTRACT_TYPE | 403 | Clave de ENCODE usada para DECODE (o viceversa): son contratos independientes. |
OUTSIDE_SANDBOX | 403 | Clave de sandbox usada fuera de la zona piloto de Boa Vista/RR. |
OUTSIDE_TERRITORY | 403 | Punto fuera del territorio contratado (paquete Territorio). |
VALIDATION_ERROR | 400 | Cuerpo no válido (p. ej.: latitud fuera de -90..90, lote por encima del máximo). |
INVALID_AFACODE | 400 | El código no es un código AFA válido en ninguno de los formatos aceptados. |
OUT_OF_COVERAGE | 422 | Coordenada fuera de la cobertura (fuera de Brasil o en el mar). |
UNKNOWN_AFACODE | 422 | Código bien formado, pero fuera de la cuadrícula brasileña. |
QUOTA_EXCEEDED | 429 | Cuota gratuita y paquete del mes agotados. Cambia a un plan superior o espera al mes siguiente. |
RATE_LIMITED | 429 | Límite técnico de 50 solicitudes por segundo por clave. |
SANDBOX_LIMIT | 429 | Se alcanzó el límite diario del sandbox (1000 solicitudes). |
Límites y facturación
3000 decode
gratis al mes, por cuenta
25 encode
gratis al mes, por cuenta
- La cuota gratuita es de la cuenta (CNPJ/CPF), no de la clave: tener más claves no multiplica la cuota. Se renueva cada mes y no se acumula.
- Una vez agotada la cuota gratuita, el consumo pasa al paquete contratado (mensualidad fija por nivel: no se cobran excedentes).
- La facturación es por solicitud: una llamada en lote con N elementos cuenta como N.
- Al alcanzar el 90 % del paquete, te enviamos un correo de alerta. Cuando se agota, las llamadas se bloquean (
QUOTA_EXCEEDED) hasta el mes siguiente o hasta que cambies a un plan superior. - Límite técnico: 50 solicitudes por segundo por clave.
Precios
Mensualidad fija por nivel de volumen. Encode y decode se contratan por separado.
ENCODE
| Nivel | Encode/mes (hasta) | Mensualidad | 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 |
Más de 100.000/mes: a consultar (AFACODES Proyectos). | |||
DECODE
| Nivel | Decode/mes (hasta) | Mensualidad | 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 |
Más de 500.000/mes: a consultar (AFACODES Proyectos). | |||
DECODE for Startups
plan anual1500 consultas al mes para quienes están empezando.
1800,00 BRL/año
Empieza ahora, gratis
La cuota mensual gratuita viene incluida con la cuenta. Prueba en el sandbox y pasa a producción cuando quieras.
