====== API: puntos finales (visión operativa) ======

===== Propósito =====

Documentar los endpoints HTTP realmente consumidos por ''Machine'' y ''RutaPAE''.

===== Base URL =====

  * Formato: ''https://{host}/v1.0''
  * Definición en ''MachineData/.../local/Server.kt'' (''Server.BASE_URL'')
  * En ''RutaPAE'', el fallback es ''https://${BuildConfig.DEFAULT_API_HOST}/v1.0''

===== Endpoints consumidos por Machine =====

^ Método ^ Endpoint ^ Consumido desde ^ Propósito ^
| ''POST'' | ''/machines'' | ''Machine.ensureMachineIdRegistered'' | Registrar/recrear máquina remota |
| ''POST'' | ''/health-checks'' | ''HealthCheck'' | Latido operativo del dispositivo |
| ''POST'' | ''/logs'' | ''SyncLogs'' | Envío de logs remotos |
| ''GET'' | ''/machine-enrollments?page={p}&size={s}&machineId={id}&machine.id={id}'' | ''SyncMachineEnrollment'' | Sincronizar jornadas/sedes de la máquina |
| ''GET'' | ''/beneficiaries-enrollments?page={p}&size={s}&campusOfferIds={ids}'' | ''SyncBeneficiaries'' | Descarga paginada de beneficiarios por oferta |
| ''GET'' | ''/photos/{beneficiaryId}/beneficiary?nameFrom=machine'' | ''SyncBeneficiaries'' | Descargar foto de beneficiario |
| ''GET'' | ''/beneficiaries?page={p}&size={s}&machineEnrollmentId={id}'' | ''MachineEndpoints'' | Consultas de beneficiarios por jornada máquina |
| ''GET'' | ''/beneficiaries?page={p}&size={s}&institutionContractId={id}'' | ''MachineEndpoints'' | Consultas por contrato institucional |
| ''GET'' | ''/beneficiaries?page={p}&size={s}&sinceModified={ts}'' | ''MachineEndpoints'' | Delta de beneficiarios por fecha de modificación |
| ''GET'' | ''/beneficiaries?page={p}&size={s}&beneficiaryEnrollmentIds={ids}'' | ''MachineEndpoints'' | Consulta por ids de matrícula |
| ''GET'' | ''/beneficiaries-enrollments?page={p}&size={s}&beneficiaryId={id}'' | ''MachineEndpoints'' | Matrículas por beneficiario |
| ''GET'' | ''/campuses?page={p}&size={s}&campusOfferIds={ids}'' | ''MachineEndpoints'' | Resolver sedes por ofertas |
| ''GET'' | ''/campus-offers?page={p}&size={s}&ids={ids}'' | ''MachineEndpoints'' | Resolver ofertas por ids |
| ''GET'' | ''/modalities?page={p}&size={s}&campusOfferIds={ids}'' | ''MachineEndpoints'' | Resolver modalidades por ofertas |
| ''GET'' | ''/minuta-menu-dues?page={p}&size={s}&modality.id={ids}'' | ''MachineEndpoints'' | Resolver minuta/cuotas por modalidad |
| ''GET'' | ''/minuta-menu-dues/delivery-goals?since={yyyy-MM-dd}&until={yyyy-MM-dd}&campusId={id}'' | ''SyncDeliveryGoals'' | Sincronizar metas de entrega |
| ''GET'' | ''/shifts?page={p}&size={s}&campusOfferIds={ids}'' | ''MachineEndpoints'' | Resolver turnos por ofertas |
| ''PATCH'' | ''/beneficiaries/{beneficiaryId}'' | ''MachineEndpoints.patchBeneficiary'' | Actualizar beneficiario |
| ''PATCH'' | ''/minuta-menu-dues/{minutaMenuDueId}'' | ''MachineEndpoints.patchMinutaMenuDue'' | Actualizar minuta/cuota |
| ''POST'' | ''/deliveries/data'' | ''SyncDeliveries.postDeliveryData'' | Subir datos de entrega |
| ''POST'' | ''/deliveries/photos'' | ''SyncDeliveries.postDeliveryPhotos'' | Subir evidencia fotográfica |

===== Endpoints consumidos por RutaPAE =====

^ Método ^ Endpoint ^ Consumido desde ^ Propósito ^
| ''POST'' | ''/deliveries/data'' | ''RutaPAEDomain.SyncDeliveries.sendDeliveryData'' | Subir datos de entrega desde ruta |
| ''POST'' | ''/deliveries/photos'' | ''RutaPAEDomain.SyncDeliveries.sendDeliveryPhotos'' | Subir fotos de entrega desde ruta |

Notas de RutaPAE:

  * ''RutaPAE'' puede usar ''delivery.url'' y ''delivery.photosUrl'' almacenados por registro.
  * Si esos campos no están presentes, usa fallback al host por defecto (''DEFAULT_API_HOST'') en ''v1.0''.

===== Consideraciones operativas =====

  * La entrega se valida/persiste primero en local; HTTP sincroniza después.
  * Los errores HTTP no deben bloquear la captura en campo.
  * Hay manejo explícito de conflictos ''208'' (entrega ya existente).
  * Para fotos de entrega existe reintento por consistencia eventual cuando el backend responde ''404'' temporal.

===== Flujo paso a paso =====

Para ver el orden de ejecución, paralelismo, condiciones de disparo y cómo impacta el filtrado de jornadas en ''ShiftSelectionScreen'', revisar:

  * [[ada:howto:sicoferp:factory:new-migracion-sicoferp:machine:..:flujos-clave:flujo-de-sincronizacion-http|Flujo De Sincronizacion Http]]

===== Fuentes de verdad =====

  * ''MachineData/src/main/java/co/ada/data/local/Server.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/MachineEndpoints.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncMachineEnrollment.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncBeneficiaries.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncDeliveries.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncDeliveryGoals.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncLogs.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/HealthCheck.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/util/Machine.kt''
  * ''RutaPAEDomain/src/main/java/co/ada/rutapaedomain/network/request/SyncDeliveries.kt''

===== Ultima verificacion =====

  * Fecha: ''2026-04-23''
  * Verificado contra definición de URLs y consumidores HTTP activos en dominio.