API-First Bepolis
API Bepolis para conectar plataformas municipales
Esta documentación describe las 37 operaciones que ejecuta la API Bepolis v1. El runtime aplica autenticación, scopes, aislamiento municipal, errores normalizados, rate limits y trazabilidad por request_id. Las operaciones de publicación incluyen ETag y revalidación condicional.
Contrato OpenAPI
El contrato versionado vive en /openapi/bepolis-integrations.v1.yaml y describe autenticación por API key, scopes, idempotencia, errores RFC7807, publicación WordPress, incidencias, trámites, documentos, firmas, agenda, presupuesto, proyectos, fuentes, datasets, WhatsApp, notificaciones, sitio municipal, bases variables, mapping, SIG/GIS, webhooks y adaptadores legacy SOAP/XML.
La gobernanza exige OpenAPI 3.1, x-api-id, x-summary, x-audience, termsOfService, operationId estable, versión semántica y validación automatizable antes de escribir backend.
Seguridad e interoperabilidad
- API keys bep_live_xxx asociadas a cuenta, scopes, cuotas, expiración y revocación.
- cuenta_id se deriva desde la credencial, no desde el body de la petición.
- external_id e Idempotency-Key permiten sincronizar proveedores sin duplicados.
- RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset y Retry-After documentan cuotas por credencial, tenant y módulo.
- /webhooks/test envía entregas de prueba firmadas con HMAC a endpoints configurados.
- SOAP/XML entra por un traductor controlado con Bepolis-Legacy-Profile y nunca escribe directo en tablas internas.
- WhatsApp entra como canal normalizado, no como recurso aislado.
- Mapping y bases variables permiten adaptar códigos, columnas, formularios y schemas por municipio.
- SIG/GIS registra capas, geometría, CRS, bbox, fuentes territoriales y permisos de publicación.
Módulos documentados
La superficie operativa cubre /status, /municipio, catálogos, publicación de solo lectura, incidencias, trámites, documentos, firmas, agenda, citas, presupuesto, proyectos, datasets, fuentes, WhatsApp, notificaciones, sitio municipal, bases variables, mapping, SIG/GIS, legacy SOAP/XML y webhooks de prueba.
Cada módulo declara campos mínimos, estados esperados, scopes, idempotencia, tenant derivado de credencial, mapping, reglas territoriales y tratamiento de datos sensibles.
Los campos canónicos normalizados incluyen external_id, source, service_code, document_type, hash_sha256, source_url, period, budget_line, timezone, resource_id, source_key, schema_key, mapping_key y layer_key.