# API histórica de facturas promocionales y boletos

Este documento queda como referencia de transición.

## Estado actual

El flujo administrativo basado en `promotion_invoices` quedó obsoleto.

El endpoint anterior:

- `POST /api/v1/admin/promotions/{promotion}/invoices`

responde actualmente:

- `410 PROMOTION_MANUAL_SELECTION_DEPRECATED`

## Reemplazo oficial

Usar:

- `docs/frontend/invoices-api.md`
- `docs/frontend/participant-participations-api.md`

## Qué cambió

- `Invoice` representa la factura física.
- el administrador no selecciona promoción manualmente.
- una factura puede generar múltiples aplicaciones.
- una participación vigente es una `InvoicePromotionApplication`.
- las correcciones crean revisiones.
- los boletos previos se anulan.
- los números de boleto no se reutilizan.
- la numeración visible futura es global y configurable.
- la aceptación de términos se valida por promoción y por versión vigente.
- una factura puede crearse con éxito parcial si al menos una promoción coincidente tiene términos vigentes aceptados.
- las promociones omitidas por términos pendientes se reportan en `omitted_promotions`.

## Regla de aceptación vigente

Solo cuenta una aceptación cuando coincide con:

- el mismo dependiente
- la misma promoción
- la versión vigente publicada
- el contenido vigente de términos

Una aceptación histórica de otra versión no bloquea el historial, pero ya no permite aplicar la promoción hasta aceptar la versión nueva.

## Permisos

Permisos nuevos:

- `invoices.view_any`
- `invoices.view`
- `invoices.create`
- `invoices.correct`
- `invoices.view_revisions`
- `invoices.view_eligible_dependents`

Permisos obsoletos:

- `promotion_invoices.view_any`
- `promotion_invoices.view`
- `promotion_invoices.create`
- `promotion_invoices.view_eligible_dependents`

## Boletos

Los endpoints de boletos siguen vigentes:

- `GET /api/v1/admin/promotion-tickets`
- `GET /api/v1/admin/promotion-tickets/{ticket}`
- `POST /api/v1/admin/promotion-tickets/print`
- `GET /api/v1/participant/tickets`
- `GET /api/v1/participant/tickets/{ticket}`

pero ahora se apoyan internamente en el dominio general de facturas.

Para impresión administrativa por rango usar además:

- `docs/frontend/promotion-ticket-printing-api.md`