La API de AdminFiel

Qué puedes hacer

La API v1 cubre cuatro módulos, para leer y para escribir:

• Personas: directorio con filtros, alta, edición y baja (a la papelera), familias y sus miembros, catálogos de la iglesia.
• Grupos: grupos, miembros y líderes, redes, reuniones y su asistencia.
• Finanzas: tesorerías, categorías, movimientos (registrar, editar y anular), resumen por periodo y presupuestos.
• Servicios: fechas de servicio (también en serie), orden del servicio, voluntarios, canciones y ministerios.

La lista completa de operaciones, con sus campos y respuestas, está en la referencia de la API. El documento OpenAPI se puede descargar desde ahí para generar clientes o importarlo en Postman.

Crear una API key

En AdminFiel, entra a tu menú de cuenta → Desarrolladores → Crear API key. Elige una plantilla («Personas — lectura», «Finanzas — registrar movimientos»…) o marca uno a uno los privilegios.

• Privilegios: los mismos permisos de la matriz de AdminFiel (por ejemplo, ver personas o registrar movimientos), con su alcance.
• Nunca más que tú: una key no puede más que la persona que la creó. Si a esa persona le quitan un permiso, la key también lo pierde.
• Solo lectura, vencimiento y IPs permitidas son opcionales y recomendables.

La key se muestra una sola vez. Guárdala en un gestor de contraseñas o en las variables de entorno de tu sistema; nunca en el código de una página web. Si se filtra, revócala y crea otra (o rótala: la anterior sigue sirviendo 24 horas para que migres sin cortes).

Tu primera petición

Manda la key en el encabezado Authorization. La iglesia sale de la key; no hace falta ningún otro dato.

curl https://api.adminfiel.com/v1/me \
  -H "Authorization: Bearer af_live_TU_KEY"

GET /me responde con tu iglesia, los privilegios efectivos de la key y cuánto llevas del límite diario. Es la mejor forma de comprobar que todo está bien configurado.

curl "https://api.adminfiel.com/v1/people?search=maria&per_page=10" \
  -H "Authorization: Bearer af_live_TU_KEY"

Listas, filtros y paginación

Las listas responden con data (los registros), meta (página actual, total) y links (siguiente y anterior). Usa per_page (hasta 100) y page.

Para sincronizar, pide solo lo que cambió con updated_since (fecha ISO 8601). Fechas en formato AAAA-MM-DD; montos como texto decimal ("150.00") con su currency, para no perder centavos.

Escribir sin duplicar

Cuando crees o edites algo, manda un encabezado Idempotency-Key con un valor único por operación (por ejemplo, un UUID). Si la conexión se corta y reintentas con la misma clave, AdminFiel devuelve la respuesta original en vez de registrar dos veces. En Finanzas es obligatorio.

curl -X POST https://api.adminfiel.com/v1/transactions \
  -H "Authorization: Bearer af_live_TU_KEY" \
  -H "Idempotency-Key: 6f1c2a0e-ofrenda-domingo" \
  -H "Content-Type: application/json" \
  -d '{"treasury_id": 12, "offering": true, "date": "2026-10-18",
       "amount": "1250.00", "description": "Ofrenda del domingo"}'

Las reglas son las mismas que en la app: un periodo cerrado no se puede tocar, los movimientos no se borran (se anulan), el tope de personas de tu plan se respeta y los avisos salen igual que si lo hicieras desde AdminFiel.

Errores

Todos los errores tienen la misma forma: {"error": {"code": "…", "message": "…"}}.

• 401 — key ausente, inválida, revocada, vencida o suspendida.
• 402 — tu plan no incluye ese módulo o llegaste a un tope del plan.
• 403 — a la key le falta el privilegio (insufficient_scope, indica cuál) o es de solo lectura.
• 404 — no existe o está fuera del alcance de la key.
• 409 — conflicto (por ejemplo, la persona ya está en el grupo).
• 422 — datos inválidos; fields dice cuáles.
• 423 — el periodo de esa tesorería está cerrado.
• 429 — demasiadas peticiones; espera lo que diga Retry-After.

Límites

Cada plan tiene un número de keys activas y un límite de peticiones por minuto (por key) y por día (por iglesia). Los encabezados X-RateLimit-Limit y X-RateLimit-Remaining te dicen cuánto queda. Si tu integración necesita más, escríbenos a soporte@adminfiel.com.

Asistentes de IA (MCP)

AdminFiel tiene un servidor MCP (Model Context Protocol) para que asistentes como Claude, ChatGPT o Cursor consulten los datos de tu iglesia con tu API key. Disponible desde el plan Básico.

Dirección: https://api.adminfiel.com/mcp, con el encabezado Authorization: Bearer af_live_TU_KEY. En AdminFiel → Desarrolladores → MCP están las instrucciones listas para copiar en cada cliente.

El asistente solo ve las herramientas que tu key permite: con una key de «Personas — lectura» puede buscar personas, pero no ver finanzas. También trae informes prearmados: resumen pastoral de la semana, personas sin seguimiento, preparar el servicio del domingo, finanzas del mes, avance de una campaña e informe para el consejo.

Lo que el asistente lee se envía al proveedor de IA que elijas: revisa sus condiciones de privacidad.

Webhooks

Recibe un aviso en tu sistema cuando pasa algo en AdminFiel: persona nueva, donación recibida, movimiento registrado, asistencia de un grupo, solicitud resuelta, voluntario asignado y más. Configúralos en AdminFiel → Desarrolladores → Webhooks, o suscríbete por la API con POST /webhooks (así lo hacen Zapier, Make y n8n).

Cada aviso es un POST JSON {"id", "type", "created_at", "church_id", "data"} firmado con el encabezado X-AdminFiel-Signature: t=…,v1=…. Para verificarlo calcula HMAC-SHA256(secreto, t + "." + cuerpo) y compáralo con v1; rechaza avisos con t de hace más de 5 minutos.

// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const ok = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex') === v1;

Responde con un código 2xx en menos de 10 segundos. Si falla, reintentamos durante unos dos días (1 min, 5 min, 30 min, 2 h, 12 h y 24 h). Un webhook que lleva 3 días sin responder se desactiva y le avisamos al titular. Usa id para no procesar dos veces el mismo aviso.

Privacidad

La información de tu iglesia incluye datos personales y, en muchos países, datos sensibles como la afiliación religiosa. Tu iglesia es responsable de a quién le da una key: compártela solo con sistemas de confianza, dale los privilegios mínimos y revócala cuando ya no se use. Cada key tiene su bitácora de uso en AdminFiel.

Versiones y cambios

La v1 no se rompe: podemos agregar campos y operaciones, pero no quitar ni renombrar. Un cambio incompatible sería la v2, anunciada con tiempo. Ignora los campos que no conozcas.

• Octubre 2026 — Lanzamiento de la v1: personas, grupos, finanzas y servicios (lectura y escritura), API keys con privilegios, idempotencia; calendario, donaciones y solicitudes en lectura; servidor MCP y webhooks firmados.