El módulo elections-services genera el artefacto elections-ws.war y expone servicios REST bajo la URL base http://<host>:<puerto>/elections-ws. En la ejecución Docker local documentada para v3.0, la base es http://localhost:8098/elections-ws.
La aplicación JAX-RS está declarada con @ApplicationPath("/") y registra dos recursos: ElectionsService para servicios funcionales y ElectionsTablesServices para reportes de tablas.
Fuentes contrastadas: elections-services, ElectionsService.java, ElectionsTablesServices.java, WebServiceAuthentication.java, PagingUtil.java, DTOs de elections-ejb y tests del módulo.
Todos los servicios documentados requieren el header HTTP Authorization. La validación se controla con los parámetros WS_AUTH_METHOD, WS_LACNIC_AUTH_URL, WS_AUTH_TOKEN y WS_AUTHORIZED_IPS. El nombre del endpoint de autenticacion centralizada se conserva por compatibilidad con configuraciones existentes.
Con WS_AUTH_METHOD=APP, el valor de Authorization debe coincidir con WS_AUTH_TOKEN. Si el token es válido, se valida la IP del cliente contra WS_AUTHORIZED_IPS. La IP se toma primero del header X-FORWARDED-FOR y, si no está presente, de la dirección remota del request.
Con WS_AUTH_METHOD en modo centralizado, el servicio reenvía el header Authorization a WS_LACNIC_AUTH_URL y valida la respuesta del servicio centralizado. Los servicios funcionales y de tablas requieren el rol api-Elections; los endpoints de snapshot público v2 requieren el rol api-ElectionsPublicInformation.
Si el token falta o no es válido, el servicio responde 401 con el texto Unauthorized access, Apikey problem. Si la IP no está autorizada, responde 401 con Unauthorized access, IP problem. Si el método de autenticación está mal configurado o ocurre un error interno durante la autenticación, responde 500.
Los listados paginados usan el formato /{pageSize}/{offset}. pageSize debe ser mayor a cero y no puede superar el parámetro WS_MAX_PAGE_SIZE. offset debe ser cero o positivo y representa número de página, no cantidad de filas a saltear.
Si un endpoint paginado se invoca sin esos parámetros o con valores inválidos, responde 200 con un mensaje de ayuda que incluye ejemplos. En la base de referencia de v3.0, WS_MAX_PAGE_SIZE queda cargado con valor 50, aunque cada ambiente debe tomar como vigente el valor configurado en su tabla parameter.
GET /elections-ws/tables/activities/10/0
GET /elections-ws/electionsDetail/10/1
GET /elections-ws/electionsParticipationsByEmail/persona@example.net/10/0Estos endpoints usan la autenticación general del WS. En modo centralizado, requieren el rol api-Elections.
| Método | Endpoint | Respuesta |
|---|---|---|
GET |
/hc |
HealthCheck: intentos de envío, IPs con accesos fallidos, total de accesos fallidos, correos totales, pendientes, enviados y resumen por elección. |
GET |
/elections y /elecciones |
Listado liviano de elecciones ordenado por fecha de inicio descendente. |
GET |
/participations/{org} y /participaciones/{org} |
ParticipationV2: datos de la organización, persona, elección, link, tipo de participación y estado. |
GET |
/old/participations/{org} y /old/participaciones/{org} |
Participation legacy. Se conserva en código para compatibilidad. |
GET |
/electionsDetail/{pageSize}/{offset} |
Lista paginada de ElectionDetailReport, con datos de elección, links, flags, candidatos, padrón, auditores y comisionados. |
GET |
/electionDetail/{id} |
ElectionDetailReport de una elección. Responde 404 si no existe. |
GET |
/electionsParticipationsByEmail/{email}/{pageSize}/{offset} |
Lista paginada de ElectionParticipationDetailReport para el correo indicado. Incluye elección, rol y datos asociados según corresponda. |
GET |
/electionsParticipationsByOrg/{orgID}/{pageSize}/{offset} |
Lista paginada de OrganizationVoterDetailReport para el orgID indicado. Incluye votante, organización y datos básicos de la elección. |
Los endpoints v2 usan la validación authenticatePublicInformation. En modo centralizado, requieren el rol api-ElectionsPublicInformation. Si el snapshot solicitado no existe, responden 404.
| Método | Endpoint | Respuesta |
|---|---|---|
GET |
/v2/elections |
PublicElectionsSnapshot: metadatos y listado público liviano de elecciones. |
GET |
/v2/elections/{id}/public-snapshot/core |
PublicElectionCoreSnapshot: metadatos, datos principales de elección, visibilidad, calendario público, etapas de resultados, resumen de padrón, recuperación pública, catálogo de preguntas, candidatos y resúmenes de nominación. |
GET |
/v2/elections/{id}/public-snapshot/roll |
PublicElectionRollSnapshot: metadatos, elección y filas de padrón público con país, organización y representante enmascarado. |
GET |
/v2/elections/{id}/public-snapshot/photos |
PublicElectionPhotoSnapshot: metadatos, elección y datos de fotos de candidatos. |
Los servicios de tablas exponen listados resumidos y detalles de entidades internas. Los listados devuelven identificador y descripción mediante TablesReportDataLongId o TableReportDataStringId. Los detalles devuelven el report o entidad correspondiente y responden 404 cuando no existe el registro.
Estos endpoints también usan la autenticación general del WS. En modo centralizado, requieren el rol api-Elections. Los endpoints /tables/parameters y /tables/parameter/{id} enmascaran credenciales y tokens como **********; las claves públicas y URLs de configuración pueden permanecer visibles.
| Tabla | Listado | Detalle | Tipo de id |
|---|---|---|---|
| activities | /tables/activities/{pageSize}/{offset} | /tables/activity/{id} | numérico |
| auditors | /tables/auditors/{pageSize}/{offset} | /tables/auditor/{id} | numérico |
| candidates | /tables/candidates/{pageSize}/{offset} | /tables/candidate/{id} | numérico |
| commissioners | /tables/commissioners/{pageSize}/{offset} | /tables/commissioner/{id} | numérico |
| elections | /tables/elections/{pageSize}/{offset} | /tables/election/{id} | numérico |
| electionemailtemplates | /tables/electionemailtemplates/{pageSize}/{offset} | /tables/electionemailtemplate/{id} | numérico |
| emails | /tables/emails/{pageSize}/{offset} | /tables/email/{id} | numérico |
| emailshistory | /tables/emailshistory/{pageSize}/{offset} | /tables/emailhistory/{id} | numérico |
| ipaccesses | /tables/ipaccesses/{pageSize}/{offset} | /tables/ipaccess/{id} | numérico |
| jointelections | /tables/jointelections/{pageSize}/{offset} | /tables/jointelection/{id} | numérico |
| useradmins | /tables/useradmins/{pageSize}/{offset} | /tables/useradmin/{id} | texto |
| uservoters | /tables/uservoters/{pageSize}/{offset} | /tables/uservoter/{id} | numérico |
| votes | /tables/votes/{pageSize}/{offset} | /tables/vote/{id} | numérico |
| Tabla | Listado | Detalle | Tipo de id |
|---|---|---|---|
| customizations | /tables/customizations | /tables/customization/{id} | numérico |
| parameters | /tables/parameters | /tables/parameter/{id} | texto |
Las respuestas exitosas se publican como application/json; charset=UTF-8, salvo el handler de métodos inválidos, que responde texto JSON simple. Los detalles que no encuentran entidad responden 404. Las excepciones no controladas responden 500 y se registran en servicesAppLogger.
Los métodos HEAD, PUT, POST y DELETE sobre cualquier ruta del recurso principal no ejecutan operaciones de negocio; responden 200 con el texto Not a valid operation.. Los servicios documentados son de consulta y se invocan con GET.