# Documentación Detallada de la API de Facturación

Esta guía explica cómo estructurar las peticiones para los diferentes tipos de comprobantes electrónicos (Factura, Boleta y Nota de Crédito).

## 1. Configuración de Acceso
- **Base URL**: `https://tu-dominio.com/api_service.php`
- **Header**: `X-API-Key: rest_api_key_2026_xYz`
- **Content-Type**: `application/json`

---

## 2. Ambientes de Prueba y Producción

Puedes elegir el ambiente mediante el parámetro `tipo_proceso` en el JSON:

- **1**: Producción (SUNAT Real)
- **3**: Beta / Prueba (SUNAT Demo) - **Valor por defecto por seguridad**

> [!IMPORTANT]
> Si no se especifica `tipo_proceso`, la API usará el ambiente **Beta (3)** para evitar envíos accidentales a SUNAT Real.

---

## 2. Definición de Tipos de Documento

| Código | Descripción | Documento del Cliente |
| :--- | :--- | :--- |
| **01** | Factura | RUC (Tipo 6) |
| **03** | Boleta | DNI (Tipo 1) o Sin Doc (Tipo 0) |
| **07** | Nota de Crédito | Referencia a Factura o Boleta |

---

## 3. Estructura de Comprobantes (Factura y Boleta)

La estructura es idéntica para ambos, cambiando solo el `cod_tipo_documento` y el tipo de documento del cliente.

### JSON Schema (Factura/Boleta)
```json
{
  "action": "emitir_directo",
  "tipo_proceso": "3", // 1=Producción, 3=Beta (Recomendado para pruebas)
  "cod_tipo_documento": "01", // 01=Factura, 03=Boleta
  "serie_comprobante": "F001", // F para Factura, B para Boleta
  "numero_comprobante": "15",
  "fecha_comprobante": "2026-05-23",
  "cod_moneda": "PEN",
  "total_letras": "CIENTO DIECIOCHO CON 00/100 SOLES",
  
  "cliente_numerodocumento": "20600000001",
  "cliente_nombre": "CLIENTE SOCIEDAD ANONIMA",
  "cliente_tipodocumento": "6", // 6=RUC, 1=DNI
  "cliente_direccion": "Calle Las Flores 456",
  
  "total_gravadas": "100.00",
  "total_igv": "18.00",
  "total": "118.00",
  "porcentaje_igv": 18,
  
  "emisor": {
    "ruc": "10427XXXXXX",
    "usuariosol": "MODDATOS",
    "clavesol": "MODDATOS",
    "razon_social": "MI RESTAURANTE E.I.R.L."
  },
  
  "detalle": [
    {
      "txtITEM": 1,
      "txtUNIDAD_MEDIDA_DET": "NIU",
      "txtCANTIDAD_DET": "1",
      "txtPRECIO_DET": "118.00",
      "txtPRECIO_SIN_IGV_DET": "100.00",
      "txtIMPORTE_DET": "100.00",
      "txtIGV": "18.00",
      "txtCOD_TIPO_OPERACION": "10", // 10=Gravado, 20=Exonerado
      "txtCODIGO_DET": "P001",
      "txtDESCRIPCION_DET": "CEBICHE DE PESCADO"
    }
  ]
}
```

---

## 4. Nota de Crédito (Tipo 07)

Se usa para anular o corregir un comprobante emitido anteriormente. Requiere campos adicionales de referencia.

### Campos Adicionales para Nota de Crédito
- `tipo_comprobante_modifica`: El tipo del documento original (01 o 03).
- `nro_documento_modifica`: El número del documento original (Ej: F001-10).
- `cod_tipo_motivo`: Código del motivo según SUNAT.
- `descripcion_motivo`: Explicación del motivo.

### Tabla de Motivos (Nota de Crédito)
| Código | Motivo |
| :--- | :--- |
| **01** | Anulación de la operación |
| **02** | Anulación por error en el RUC |
| **06** | Devolución total |
| **07** | Devolución por ítem |

### JSON Schema (Nota de Crédito)
```json
{
  "cod_tipo_documento": "07",
  "serie_comprobante": "FC01",
  "numero_comprobante": "5",
  "fecha_comprobante": "2026-05-23",
  "cod_moneda": "PEN",
  
  "tipo_comprobante_modifica": "01",
  "nro_documento_modifica": "F001-15",
  "cod_tipo_motivo": "01",
  "descripcion_motivo": "ERROR EN EL MONTO DE VENTA",
  
  "cliente_numerodocumento": "20600000001",
  "cliente_nombre": "CLIENTE SOCIEDAD ANONIMA",
  "cliente_tipodocumento": "6",
  
  "total_gravadas": "100.00",
  "total_igv": "18.00",
  "total": "118.00",
  "porcentaje_igv": 18,
  
  "emisor": { ...mismo que factura... },
  "detalle": [ ...mismo que factura... ]
}
```

---

  ]
}
```

---

## 5. Pagos al Crédito (Novedad 2026)

Para ventas al crédito, debe especificarse `forma_pago: "Credito"`, el `total_pendiente` y un array de `cuotas`.

### Ejemplo JSON (Crédito)
```json
{
  "action": "emitir_directo",
  "forma_pago": "Credito",
  "total_pendiente": "118.00",
  "cuotas": [
    { "monto": "59.00", "fecha": "2026-06-23" },
    { "monto": "59.00", "fecha": "2026-07-23" }
  ],
  ...resto de campos...
}
```

---

## 6. Detracciones (Novedad 2026)

Requerido para servicios sujetos a detracción que superen los 700 soles.

### Ejemplo JSON (Detracción)
```json
{
  "action": "emitir_directo",
  "detraccion_codigo": "022", // Código SUNAT (ej: otros servicios empresariales)
  "detraccion_porcentaje": "12",
  "detraccion_monto": "120.00",
  "detraccion_cuenta": "00-000-000000", // Cuenta Banco de la Nación
  ...resto de campos...
}
```

---

---

## 8. Multi-moneda (Soles y Dólares)

La API soporta ventas tanto en Soles (**PEN**) como en Dólares (**USD**).

### Parámetro `cod_moneda`
- **PEN**: Soles (Perú)
- **USD**: Dólares Americanos

> [!NOTE]
> Cuando se emite un documento en USD, todos los montos (`total`, `total_igv`, etc.) deben enviarse en la moneda USD. La API generará el XML con los atributos de moneda correspondientes.

---

## 9. Cumplimiento SUNAT 2026 (UBL 2.1)

Esta API está actualizada para cumplir con las normativas vigentes hasta el **2026**:

1. **UBL 2.1 Estándar**: Generación de archivos XML bajo el estándar 2.1 requerido por SUNAT.
2. **Formas de Pago (Crédito/Contado)**: Inclusión obligatoria de la forma de pago y el detalle de cuotas para ventas al crédito.
3. **Detracciones**: Soporte para operaciones sujetas a detracción, con conversión automática a Soles (PEN) para el monto de la detracción, cumpliendo con la regla de SUNAT.
4. **ICBPER**: Soporte para el impuesto a las bolsas plásticas.
5. **Validaciones Estrictas**: Estructura de datos alineada con los últimos catálogos de SUNAT (Catalogo 01, 06, 07, 51, 53).