API-First Bepolis
API Bepolis para conectar plataformas municipales
Esta documentación define el contrato inicial antes de implementar endpoints productivos. Sirve para validar campos, estados, permisos, seguridad, versionado, errores, rate limits y webhooks con equipos técnicos municipales y proveedores externos.
Contrato OpenAPI
El contrato versionado vive en /openapi/bepolis-integrations.v1.yaml y describe autenticación por API key, scopes, idempotencia, errores RFC7807, 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_test_xxx y bep_live_xxx asociadas a cuenta, entorno, scopes y cuotas.
- 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 firmados con HMAC notifican cambios de incidencias, trámites, documentos, firmas, citas, presupuesto, proyectos y datasets.
- 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 inicial cubre /status, /municipio, catálogos, 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.