API REST¶

Referencia de los endpoints REST (Spring MVC) de TiFacturaOnlineNext: versión, flujo CAEA para el POS y el contrato de errores. Los endpoints SOAP están en API SOAP; el ciclo de negocio, en El ciclo de facturación.

El Cockpit (ABM de SucPosPV, observabilidad) expone sus propios endpoints REST y se documenta aparte: ver Cockpit.

Endpoints¶

Todos son @RestController Spring MVC; el produces/consumes es application/json. La columna Acceso refleja el estado actual de seguridad (ver nota más abajo).

VersionController¶

El más simple: GET / devuelve un string JSON con la versión.

@GetMapping(value = "/", produces = "application/json")
public String getVersion() { return VERSION; } // "v20250328"

En el sistema real la versión es ParentEntityManager.VERSION; acá la constante actúa de stand-in del contrato.

CaeaWsRestController — GET /caeaWS/getCaea¶

Paso 1 del flujo POS: lista los CAEAs vigentes/futuros del comercio en JSON. Es la reescritura del legacy JAX-RS (CaeaWSRest) a Spring MVC; delega en CaeaConsultaService.

Acepta query params opcionales para identificar el comercio (multi-comercio) y el POS, todos Integer/String (para distinguir "no vino" de 0/vacío):

Sin cuit ni ente y con un solo comercio habilitado, funciona en modo single-comercio (paridad previa); con dos o más habilitados y sin identificador, la resolución falla (error claro, no 500 crudo).

GET /caeaWS/getCaea                          # single-comercio
GET /caeaWS/getCaea?cuit=20111111112         # v2: identifica el comercio por CUIT
GET /caeaWS/getCaea?ente=1                    # v1: identifica el comercio por ente.id
GET /caeaWS/getCaea?cuit=20111111112&nrosuc=12&nropos=3

# Mismo handler también en el path legacy completo (compat POS V1):
GET /TiFacturaOnlineManager/resource/rest/caeaWS/getCaea

El lookup de PV ya NO es un handoff de una sola vez: nropvcae/nropvcaea se devuelven en cada getCaea que traiga nrosuc+nropos (el POS los necesita siempre), vía findSucPosPV — lookup read-only que no sella fechaUltObtencionPos. (El método viejo obtenerPVParaPOS, que sí sellaba una única vez, ya no lo usa este handler.)

La respuesta es GetCaeaResponse (@JsonInclude(NON_NULL) — los extras nulos no se serializan):

{
  "caeas": [
    { "caea": "...", "periodo": 202606, "orden": 1,
      "fchVigDesde": "...", "fchVigHasta": "...",
      "fchTopeInf": "...", "fchProceso": "..." }
  ],
  "nropvcae": "5",
  "nropvcaea": "6",
  "cuit": "..."
}

CaeaNotificacionRestController — notificador DINO¶

Endpoints consumidos por el notificador DINO (fase 2 anti-doble-factura). No usa @RequestMapping de clase para evitar colisión con /caeaWS: ambos cuelgan de la raíz del context-path.

POST /fecaeaSolicitar¶

Recibe el Trx JSON del notificador (TrxCaeaRequest, no la entidad JPA), lo registra en ARCA y persiste la fila CAEA. Es idempotente: si el comprobante ya existe (mismo ptoVta + comprobante + CAEA + V2) lo devuelve sin re-insertar ni re-reportar a ARCA. Delega en CaeaNotificacionService.registrarCaea. Devuelve ResponseEntity<TrxCaeaResponse> — un DTO plano, no la entidad JPA Trx.

TrxCaeaRequest espeja los campos que envía DINO (TiFacturaOnlineManagerClient.fecaeaSolicitar): cabecera del comprobante, receptor, importes, fechas de servicio, caea / cbteFchHsGen, datos POS (nroTicketPos / nroSuc / nroPos) y las colecciones alicuotaIvas / tributos / comprobantesAsociados. Es un DTO explícito para aislar el contrato JSON del modelo de dominio.

GET /feCompUltimoAutorizado¶

Devuelve el último número de comprobante autorizado en ARCA para el (ptoVta, cbteTipo) dado. Contrato del notificador: devuelve Integer (0 si no hay ninguno).

GET /feCompUltimoAutorizado?ptoVta=5&cbteTipo=6

Contrato de errores REST (DefaultExceptionHandler)¶

INVARIANTE (REFERENCE.md §5.8). Es la reescritura funcional del legacy (JAX-RS @Provider ExceptionMapper<Exception>) a un @RestControllerAdvice Spring MVC, con comportamiento observable idéntico.

Ante cualquier excepción (@ExceptionHandler(Exception.class)) devuelve:

return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
        .header(ERROR_TYPE, e.getClass().getName())       // "exception-class"
        .header(ERROR_MESSAGE, String.valueOf(e.getMessage())) // "exception-message"
        .contentType(MediaType.APPLICATION_JSON)
        .body(errors.toString());                          // stacktrace

Hardening de errores de mapeo (MappingErrorHardeningHandler)¶

Hay errores que Spring lanza antes de resolver el controller (en la fase de mapeo): path inexistente y verbo HTTP equivocado. Sin tratarlos aparte, los cazaba el DefaultExceptionHandler global como cualquier Exception → 500 + headers exception-class/exception-message + stacktrace en el body, filtrando estructura interna a cualquier scanner. Un @RestControllerAdvice con @Order(HIGHEST_PRECEDENCE) los endurece. Como se lanzan antes de resolver el controller, no pueden scopearse por paquete: el discriminado es por URI.

Por dónde seguir¶

• API SOAP — los 3 endpoints SOAP (incluida la variante SOAP de getCaea).
• Cockpit — los endpoints REST de administración y observabilidad.
• El ciclo de facturación — dónde encaja el flujo CAEA del POS.