Documentación API

Integra consultas electorales, antecedentes y digitalización de documentos en tus aplicaciones.

La API de Avappi ofrece múltiples servicios para consultar información de ciudadanos colombianos de manera rápida y confiable. Ideal para campañas políticas, verificaciones de identidad, y digitalización de documentos.

Precios

Todos los precios están en Pesos Colombianos (COP). El saldo se descuenta automáticamente por cada consulta exitosa.

Nota: Clientes Enterprise pueden negociar tarifas personalizadas.

Autenticación

Todas las peticiones deben incluir tu API Key. Puedes obtener una registrándote en nuestro dashboard.

Métodos de envío

Consulta Individual (Censo)

Obtén la información de votación de una sola cédula. Costo: $80 COP

Ejemplo de Solicitud

curl -X GET "https://avappi.avapp.com.co/consultar/1234567890" \
  -H "X-API-Key: tu_api_key"content_copyCopiar

Respuesta Exitosa

{
  "success": true,
  "data": {
    "departamento": "BOGOTA D.C.",
    "municipio": "BOGOTA D.C.",
    "puesto": "COLEGIO NUEVA GRANADA",
    "direccion": "CR 2 E # 70 - 20",
    "mesa": "1"
  },
  "duration": 1245,
  "fromCache": false
}

Consulta Masiva (Censo)

Consulta hasta 10 cédulas en una sola petición. Costo: $80 COP × cantidad de cédulas

Body (JSON)

{
  "cedulas": ["1234567890", "9876543210"]
}

Ejemplo de Solicitud

curl -X POST "https://avappi.avapp.com.co/consultar/bulk" \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"cedulas": ["1234567890", "9876543210"]}'content_copyCopiar

Digitalización de Documentos

Extrae datos estructurados de documentos mediante OCR. Costo: $100 COP por registro

Headers

Body (Form Data)

Ejemplo con cURL

curl -X POST "https://avappi.avapp.com.co/api/digitization" \
  -H "X-API-Key: tu_api_key" \
  -F "file=@documento.jpg" \
  -F "type=cedula"content_copyCopiar

Respuesta Exitosa

{
  "success": true,
  "records": 1,
  "data": [
    {
      "nombre": "JUAN PEREZ GARCIA",
      "cedula": "1234567890",
      "fecha_nacimiento": "1990-05-15",
      "confidence": 0.95
    }
  ],
  "cost": 100
}

Envíos WhatsApp

Envía mensajes de WhatsApp desde tus propios sistemas, por los números que ya tiene tu organización en Avappi. Sirve tanto para avisos sueltos (un recibo, una confirmación) como para lotes de hasta 100 mensajes en una sola petición.

Autenticación

La clave va en un encabezado. Aquí no funciona el parámetro ?apiKey= de las consultas.

X-Api-Key: avp_tu_clave

# o, si tu cliente ya trabaja con Bearer:
Authorization: Bearer avp_tu_clavecontent_copyCopiar

Permisos de la clave

Cada clave lleva permisos y, si se quiere, una lista de números desde los que puede enviar.

Una clave sin el permiso que pide la ruta recibe 403.

Cobro

Se descuenta por mensaje aceptado por WhatsApp, según la regla acordada con tu organización (algunas cobran por mensaje enviado, otras por categoría de plantilla). Puedes ver el saldo y la regla vigente en GET /api/envios/saldo. Si no alcanza, la petición responde 402 y no se envía nada del lote.

Enviar mensajes

Campos del mensaje

* Hace falta plantilla o texto, uno de los dos.

Un mensaje

curl -X POST "https://avappi.avapp.com.co/api/envios/mensajes" \
  -H "X-Api-Key: avp_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "para": "3001234567",
    "plantilla": "recordatorio_pago",
    "idioma": "es",
    "variables": { "1": "Ana", "2": "45.000" }
  }'content_copyCopiar

Varios de una vez

Hasta 100 mensajes por petición. El saldo se revisa una sola vez para todo el lote, así que no te quedas a mitad sin saber qué salió.

curl -X POST "https://avappi.avapp.com.co/api/envios/mensajes" \
  -H "X-Api-Key: avp_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recibos-2026-08-14-lote-7" \
  -d '{
    "desde": "573001110000",
    "mensajes": [
      { "para": "3001234567", "plantilla": "recordatorio_pago", "variables": { "1": "Ana" } },
      { "para": "3007654321", "plantilla": "recordatorio_pago", "variables": { "1": "Luis" } }
    ]
  }'content_copyCopiar

Respuesta

El resultado viene mensaje por mensaje: que la petición sea 200 no quiere decir que todos hayan salido.

{
  "ok": true,
  "enviados": 1,
  "fallidos": 1,
  "desde": "573001110000",
  "resultados": [
    { "ok": true,  "para": "573001234567", "wamid": "wamid.HBgMNTc..." },
    { "ok": false, "para": "573007654321", "error": "No existe la plantilla \"recordatorio_pago\" en esa cuenta" }
  ]
}

Cuando falla toda la petición

{
  "ok": false,
  "error": "Saldo insuficiente para enviar 2 mensajes",
  "saldo": 1200
}

Estado e historial

Un mensaje aceptado no es un mensaje entregado. WhatsApp avisa después si se entregó, si lo leyeron o si rebotó, y eso queda aquí.

curl -X GET "https://avappi.avapp.com.co/api/envios/mensajes/wamid.HBgMNTc..." \
  -H "X-Api-Key: avp_tu_clave"content_copyCopiar

{
  "ok": true,
  "mensaje": {
    "wamid": "wamid.HBgMNTc...",
    "telefono": "573001234567",
    "desde": "573001110000",
    "tipo": "template",
    "estado": "delivered",
    "origen": "api",
    "eventos": [
      { "estado": "sent",      "ocurrido_en": "2026-08-14T15:02:11.000Z" },
      { "estado": "delivered", "ocurrido_en": "2026-08-14T15:02:14.000Z" }
    ]
  }
}

Los mensajes salientes de tu organización, para conciliar contra tus propios registros.

curl -X GET "https://avappi.avapp.com.co/api/envios/mensajes?desde=2026-08-01&limite=50" \
  -H "X-Api-Key: avp_tu_clave"content_copyCopiar

Plantillas, cuentas y saldo

Las plantillas aprobadas que puedes usar, con sus variables. Consúltalas antes de enviar en vez de asumir nombres: Meta puede rechazar o pausar una plantilla en cualquier momento.

{
  "ok": true,
  "plantillas": [
    {
      "nombre": "recordatorio_pago",
      "idioma": "es",
      "categoria": "UTILITY",
      "estado": "APPROVED",
      "desde": "573001110000"
    }
  ]
}

Los números desde los que puede enviar esta clave. El id es lo que va en waAccountId.

{
  "ok": true,
  "cuentas": [
    { "id": 3, "etiqueta": "Principal", "numero": "573001110000", "verificada": true }
  ]
}

Cuánto queda y cómo se cobra. Vale la pena mirarlo antes de un lote grande.

{
  "ok": true,
  "organizacion": "Partido Ejemplo",
  "saldo": 250000,
  "modo": "prepago",
  "limiteCredito": 0,
  "cobraPor": "enviado",
  "gastadoEsteMes": 48000
}

Códigos de Error