AFA.codes
Generar mi dirección

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.

Pruébala en el playground Crear cuenta gratis

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:

ENCODE

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.

DECODE

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

Inicio rápido

  1. 1

    Crea tu cuenta de empresa o desarrollador: tarda unos minutos y no necesitas hablar con ventas.

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

FormatoEjemploUso
LegibleR7FTD-HXUDocumentos, placas, pantallas (5 + guion + 3)
APIBR~R7FTDHXUCampo afacode de las respuestas (prefijo del país, sin guion)
CompactoR7FTDHXUAceptado 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

POST

/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 } }
    ]
  }
}
Lote: hasta 1000 puntos por llamada. Una llamada con N puntos cuenta como N solicitudes en la cuota gratuita y en el paquete.

Decode

GET

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

/v1/decode

Lote: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. También cuenta como N solicitudes.

GET

/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ódigoHTTPCuándo ocurre
API_KEY_REQUIRED401Falta el encabezado X-API-Key.
API_KEY_INVALID401Clave inexistente o revocada.
CONTRACT_NOT_ACTIVE402La clave no tiene un contrato activo (p. ej.: pendiente de pago).
CONTRACT_SUSPENDED402Contrato suspendido por falta de pago.
WRONG_CONTRACT_TYPE403Clave de ENCODE usada para DECODE (o viceversa): son contratos independientes.
OUTSIDE_SANDBOX403Clave de sandbox usada fuera de la zona piloto de Boa Vista/RR.
OUTSIDE_TERRITORY403Punto fuera del territorio contratado (paquete Territorio).
VALIDATION_ERROR400Cuerpo no válido (p. ej.: latitud fuera de -90..90, lote por encima del máximo).
INVALID_AFACODE400El código no es un código AFA válido en ninguno de los formatos aceptados.
OUT_OF_COVERAGE422Coordenada fuera de la cobertura (fuera de Brasil o en el mar).
UNKNOWN_AFACODE422Código bien formado, pero fuera de la cuadrícula brasileña.
QUOTA_EXCEEDED429Cuota gratuita y paquete del mes agotados. Cambia a un plan superior o espera al mes siguiente.
RATE_LIMITED429Límite técnico de 50 solicitudes por segundo por clave.
SANDBOX_LIMIT429Se 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

NivelEncode/mes (hasta)MensualidadR$/1k
N1 50gratis—
N2 1000500,00 BRL500
N3 50002000,00 BRL400
N4 15.0005500,00 BRL367
N5 35.00011.000,00 BRL314
N6 65.00018.000,00 BRL277
N7 100.00025.000,00 BRL250

Más de 100.000/mes: a consultar (AFACODES Proyectos).

DECODE

NivelDecode/mes (hasta)MensualidadR$/1k
N1 500gratis—
N2 5000225,00 BRL45
N3 25.0001000,00 BRL40
N4 75.0002625,00 BRL35
N5 150.0004500,00 BRL30
N6 300.0008100,00 BRL27
N7 500.00012.500,00 BRL25

Más de 500.000/mes: a consultar (AFACODES Proyectos).

DECODE for Startups

plan anual

1500 consultas al mes para quienes están empezando.

1800,00 BRL/año

Ver todas las soluciones

Empieza ahora, gratis

La cuota mensual gratuita viene incluida con la cuenta. Prueba en el sandbox y pasa a producción cuando quieras.

Crear cuentaPlayground