API REST — Envío y Consulta de Lotes SIFEN

1. Resumen del pipeline

DTEs firmados → POST /api/sifen/dtes/lote
    → recibeLote (SOAP) → prot_lote
    → Job polling cada 5 min
    → consultaResultadoLote (SOAP) → estados por DTE

Los DTEs de un lote deben ser del mismo tipo de documento (tipo_documento) y pertenecer al mismo emisor. El lote es procesado de forma asíncrona: la respuesta inmediata devuelve el prot_lote, y los estados finales se obtienen por polling.

---

2. Endpoints implementados

POST /api/sifen/dtes/lote

Envía un lote de DTEs al SIFEN.

Auth: Sanctum bearer + permiso sifen:send

Header opcional:

Idempotency-Key: <UUID-v4>

Si se envía la misma Idempotency-Key en una segunda llamada dentro de las 24 horas, la respuesta es devuelta del cache sin procesar el lote nuevamente. La segunda respuesta incluye el header Idempotency-Replay: true.

Body:

{
  "dte_ids":    [101, 102, 103],
  "emitter_id": 1
}

Campo	Tipo	Requerido	Descripción
dte_ids	array(int)	Sí	IDs internos de DTEs a enviar
emitter_id	int	Sí	ID de la empresa emisora

Validaciones:

• Máximo 50 DTEs por lote.
• Todos los DTEs deben tener el mismo tipo_documento.
• Todos los DTEs deben pertenecer al emisor autenticado.
• Estado de los DTEs: signed o draft.

Response 200:

{
  "message":   "Lote enviado al SIFEN.",
  "prot_lote": "LOTE-20260429-000123"
}

---

3. Idempotencia (anti-doble envío)

El endpoint de lote implementa idempotencia mediante el header Idempotency-Key:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Comportamiento:

1. Primera llamada con key X → se procesa, resultado cacheado por 24 h.
2. Segunda llamada con key X → respuesta cacheada, header Idempotency-Replay: true.
3. Llamada sin header → se procesa normalmente.

Generar UUID-v4 nuevo por intento deliberado. Reutilizar en reintentos por timeout.

---

4. Códigos SIFEN relevantes

Código	Significado
0300	Aprobado
0301	Aprobado con observaciones
0302	Rechazado
0360	En proceso
0361	Lote recibido
0362	Procesando lote

---

5. Limitaciones actuales

• Máximo 50 DTEs por lote.
• Todos del mismo tipo_documento.
• Polling cada 5 min — el resultado no es inmediato.

---

6. Roadmap (próximo sprint)

• GET /api/sifen/lotes — listar lotes
• GET /api/sifen/lotes/{prot_lote} — estado de un lote
• POST /api/sifen/lotes/{prot_lote}/sync — forzar sincronización
• POST /api/sifen/lotes/{prot_lote}/reenviar-rechazados
• POST /api/sifen/lotes/desde-cdc