POS API — Facturación Electrónica

API REST simulada de Punto de Venta con integración de Facturación Electrónica, siguiendo los estándares de la DIAN - Colombia.

---

Stack Tecnológico

Tecnología	Versión
Java	17 (Records para DTOs)
Spring Boot	3.2.x
Gestor de dependencias	Gradle
JSON	Jackson

---

Estructura del Proyecto

Arquitectura limpia que separa la lógica de control de los contratos de datos:

com.quind.api/
├── PosController.java          # Controlador principal con lógica de endpoints
└── dto/
    ├── FacturaRequest.java
    ├── NotaCreditoRequest.java
    ├── NotaDebitoRequest.java
    ├── DianFullResponse.java          # Respuesta estándar DIAN
    ├── NotaCreditoResponse.java       # Respuesta independiente para Notas Crédito
    └── CalculoImpuestosResponse.java  # Desglose de tributos

---

Configuración y Ejecución

Prerequisitos: JDK 17 o superior instalado.

El puerto por defecto de esta demo es el 7171.

# Ejecutar con Gradle
./gradlew bootRun

También puedes ejecutar la clase PosApplication directamente desde tu IDE.

---

Endpoints

1. POST /api/v1/pos/facturas — Crear Factura Electrónica

Genera un documento electrónico con estructura completa y simulación de CUFE.

Validaciones:

• lineas vacío → 400 Bad Request
• taxAmount = 9999999.99 → 422 Unprocessable Entity (valor centinela)

Ver ejemplo de petición

{
  "traceId": "Factura-Local-001",
  "documentTypeCode": "03",
  "lineas": [
    {
      "id": "1",
      "plu": "2223",
      "description": "Juguito Mora 1.000 ml",
      "quantity": 2.0,
      "priceAmount": 10000.00,
      "lineExtensionAmount": 20000.00
    }
  ],
  "impuestos": [
    {
      "id": "01",
      "percent": 19.00,
      "taxAmount": 3800.00,
      "taxableAmount": 20000.00
    }
  ],
  "totales": {
    "taxExclusiveAmount": 20000.00,
    "taxInclusiveAmount": 23800.00,
    "payableAmount": 23800.00
  }
}

---

2. POST /api/v1/pos/notas-credito — Crear Nota Crédito (Independiente)

Procesa devoluciones con un contrato de respuesta específico. Retorna un NotaCreditoResponse con simulación de CUDE.

Ver ejemplo de petición

{
  "referenceId": "Devolucion por producto dañado",
  "responseCode": "2",
  "invoiceId": "SETT000111",
  "lineas": [
    {
      "id": "1",
      "plu": "122021",
      "description": "Cerv x6 Poker Lata",
      "quantity": 1.0,
      "priceAmount": 14316.12,
      "lineExtensionAmount": 14316.12
    }
  ],
  "totales": {
    "taxExclusiveAmount": 14316.12,
    "taxInclusiveAmount": 17036.18,
    "payableAmount": 17036.18
  }
}

---

3. POST /api/v1/pos/notas-debito — Crear Nota Débito

Aplica cargos adicionales a facturas existentes.

Ver ejemplo de petición

{
  "referenceId": "Cobro de intereses por mora",
  "invoiceId": "SETT000111",
  "reason": "Cargo adicional aplicado post-facturacion",
  "cargoAdicional": 1500.00,
  "totales": {
    "taxExclusiveAmount": 1500.00,
    "taxInclusiveAmount": 1785.00,
    "payableAmount": 1785.00
  }
}

---

4. POST /api/v1/pos/facturas/calculo-avanzado — Cálculo Avanzado de Impuestos

Recibe un saldo base y desglosa automáticamente los impuestos y retenciones de ley colombiana.

Tributo	Tarifa
IVA	19%
ReteFuente	2.5%
ReteICA	9.66 × 1000
ReteIVA	15% sobre el valor del IVA

📋 Ver ejemplo de petición

{
  "saldo": 100000.00
}

---

5. GET /api/v1/pos/productos/{plu} — Consulta de Productos

Simula el escaneo de un producto en caja mediante su código PLU.

GET /api/v1/pos/productos/2223

---

Reglas de Negocio

• Generación de UUID: Los campos uuid (CUFE/CUDE) se generan dinámicamente como cadenas alfanuméricas largas para simular firmas electrónicas.
• Metadatos DIAN: Las respuestas incluyen nodos GeneralData con resolución, prefijos y fechas en formato ISO-8601.
• Manejo de Errores: El campo errorReason en el JSON de respuesta se llena con el detalle del error, acompañado de los códigos HTTP reales (400, 422) para facilitar el manejo de excepciones desde el POS.

---

Licencia

Este proyecto es una demo educativa y no representa una implementación oficial de la DIAN.