Lotes

Endpoints de sesión para consulta de lotes y transmisiones SIFEN del contribuyente.

Esta API utiliza autenticación Keycloak. Ver Autenticación para obtener un token JWT.

Sifende agrupa los documentos electrónicos en lotes antes de transmitirlos a SIFEN. Cada lote pasa por una serie de estados hasta que SIFEN devuelve el resultado de procesamiento. Estos endpoints permiten consultar lotes, reintentar los fallidos y revisar el historial de transmisiones.

Endpoints

Método	Path	Query	Descripción
`GET`	`/api/v1/contribuyentes/:id/lotes`	`page`, `size`	Lista paginada de lotes
`GET`	`/api/v1/contribuyentes/:id/lotes/:loteId`	—	Detalle de un lote
`POST`	`/api/v1/contribuyentes/:id/lotes/:loteId/reintentar`	—	Re-encola un lote fallido
`GET`	`/api/v1/contribuyentes/:id/lotes/:loteId/transmisiones`	—	Historial de transmisiones SIFEN

Estados de un lote

PREPARADO → INTENTANDO → ENVIADO → PROCESADO
                ↓             ↓
              ERROR        FALLIDO

Estado	Descripción
`PREPARADO`	Lote armado, listo para envío
`INTENTANDO`	El scheduler está intentando transmitirlo
`ENVIADO`	Recibido por SIFEN, esperando resultado
`PROCESADO`	Resultado aplicado a los DEs (APROBADO/RECHAZADO)
`ERROR`	Error técnico permanente
`FALLIDO`	Reintentable: podés re-encolarlo (`reintentable=true`)

LoteDTO

Campo	Tipo	Descripción
`loteId`	`long`	ID interno
`contribuyenteId`	`long`	Contribuyente emisor
`numeroLote`	`long`	Número de lote enviado a SIFEN
`iTiDe`	`short`	Tipo de DE: `1`=FE, `5`=NCE, `6`=NDE
`tipoDocumentoLabel`	`string`	Label legible (`FACTURA_ELECTRONICA`, etc.)
`cantidadDocumentos`	`int`	DEs incluidos en el lote
`estado`	`string`	Ver estados arriba
`codigoRespuesta`	`string?`	Código SIFEN (`0360`, `0363`, …)
`mensajeRespuesta`	`string?`	Mensaje devuelto por SIFEN
`fechaCreacion`	`datetime`	Alta del lote
`fechaEnvio`	`datetime?`	Cuando se transmitió
`fechaProcesamientoCompleto`	`datetime?`	Cuando se aplicó el resultado final
`reintentable`	`boolean`	`true` si `estado=FALLIDO`
`intentosConsulta`	`int`	Número de consultas a SIFEN realizadas
`intentosEnvio`	`int`	Número de envíos intentados

GET /api/v1/contribuyentes/:id/lotes

Lista paginada (server-side) de lotes. Default: page=0&size=10.

curl "https://api.sifende.com.py/api/v1/contribuyentes/12/lotes?page=0&size=20" \
  -H "Authorization: Bearer $KEYCLOAK_JWT"

Respuesta 200 OK:

{
  "status": "success",
  "payload": {
    "content": [
      {
        "loteId": 4521,
        "contribuyenteId": 12,
        "numeroLote": 9876543,
        "iTiDe": 1,
        "tipoDocumentoLabel": "FACTURA_ELECTRONICA",
        "cantidadDocumentos": 8,
        "estado": "PROCESADO",
        "codigoRespuesta": "0360",
        "mensajeRespuesta": "Lote procesado correctamente",
        "fechaCreacion": "2026-04-15T10:30:00",
        "fechaEnvio": "2026-04-15T10:30:12",
        "fechaProcesamientoCompleto": "2026-04-15T10:31:45",
        "reintentable": false,
        "intentosConsulta": 2,
        "intentosEnvio": 1
      }
    ],
    "page": 0,
    "size": 20,
    "totalElements": 87,
    "totalPages": 5
  }
}

POST /api/v1/contribuyentes/:id/lotes/:loteId/reintentar

Re-encola un lote FALLIDO para que el scheduler vuelva a intentar transmitirlo. Sólo funciona si el campo reintentable es true.

curl -X POST https://api.sifende.com.py/api/v1/contribuyentes/12/lotes/4521/reintentar \
  -H "Authorization: Bearer $KEYCLOAK_JWT"

Respuesta 200 OK. Ver la guía Reintentar rechazados para la estrategia recomendada.

GET /api/v1/contribuyentes/:id/lotes/:loteId/transmisiones

Historial completo de transmisiones SIFEN para un lote. Útil para depurar problemas de comunicación.

TransmisionSifenDTO

Campo	Tipo	Descripción
`transmisionSifenId`	`long`	ID interno
`loteId`	`long`	Lote asociado
`tipoTransmision`	`string`	`ENVIO`, `CONSULTA`, etc.
`numeroIntento`	`int`	Número de intento
`estadoProcesamiento`	`string`	Resultado del intento
`fechaEnvio`	`datetime`	Cuándo se envió
`fechaRespuesta`	`datetime?`	Cuándo respondió SIFEN

Los códigos SIFEN más relevantes en codigoRespuesta: 0360 (procesado OK → PROCESADO), 0361 (lote no encontrado, reintentar consulta), 0362 (aún procesando), 0363 (errores de validación → ERROR) y 0364 (rechazado).