# Emitir comprobantes fiscales electrónicos (e-CF)

Permiso de la clave: `facturas:emitir`. Consultar: `facturas:leer`.

## Dos formas de emitir

| Endpoint | Cuándo usarlo |
|---|---|
| `POST /v1/facturas` | **Factura simple.** Usted envía líneas (descripción, cantidad, precio, tasa de ITBIS); BusinessLink calcula totales e impuestos y, si la empresa usa numeración de BusinessLink, asigna el e-NCF. Ideal para apps nuevas. |
| `POST /v1/ecf` | **Documento completo de la DGII** (`Encabezado`, `DetallesItems`, ...). Para ERP que ya calculan todo y ya numeran (como el conector de Odoo). BusinessLink no recalcula: firma, valida contra el XSD y envía. |

Ambos exigen la cabecera `Idempotency-Key`.

## Tipos de e-CF

| Tipo | Uso |
|---|---|
| 31 | Crédito fiscal: el comprador tiene RNC y puede usarlo como gasto. |
| 32 | Consumo (consumidor final). **No es una nota de crédito.** RNC del comprador obligatorio desde RD$250,000. |
| 33 | Nota de débito (lleva `referencia`). |
| 34 | Nota de crédito (siempre con `referencia` al e-NCF que modifica; no puede devolver más de lo facturado). |
| 41 | Compras a proveedor informal (`proveedor` y `retencion` por línea). |
| 43 | Gastos menores (sin comprador, líneas exentas). |
| 44 | Regímenes especiales (exento). |
| 45 | Gubernamental. |
| 46 | Exportaciones (ITBIS tasa 0; comprador extranjero con `id_extranjero` y `pais`). |
| 47 | Pagos al exterior (proveedor extranjero, exento, ISR retenido en cada línea). |

## Ejemplo de factura simple

```json
{
  "tipo_ecf": "31",
  "comprador": {"rnc": "101000228", "razon_social": "Cliente Ejemplo SRL", "correo": "compras@cliente.do"},
  "lineas": [
    {"descripcion": "Consultoria", "cantidad": 2, "precio_unitario": 1500, "itbis": "18", "tipo": "servicio"},
    {"descripcion": "Libro", "cantidad": 1, "precio_unitario": 800, "itbis": "exento", "tipo": "bien", "descuento": {"porcentaje": 10}}
  ],
  "tipo_pago": "credito",
  "fecha_limite_pago": "2026-11-30"
}
```

- `itbis` por línea: `"18"`, `"16"`, `"0"` o `"exento"`.
- `precios_incluyen_itbis: true` si el precio ya trae el impuesto.
- Otra moneda: `moneda: "USD"` y precios en dólares; `tipo_cambio` es opcional con USD (por defecto, venta del Banco Central del cierre anterior; ver `GET /v1/tasas`).
- Si omite `razon_social` y el RNC está en el directorio de la DGII, se completa sola.

## Nota de crédito (E34)

```json
{
  "tipo_ecf": "34",
  "comprador": {"rnc": "101000228"},
  "lineas": [{"descripcion": "Devolución consultoría", "cantidad": 1, "precio_unitario": 1500, "itbis": "18", "tipo": "servicio"}],
  "referencia": {"encf": "E310000000123", "fecha": "2026-11-02", "codigo_modificacion": "3"}
}
```

`codigo_modificacion`: 1 anula, 2 corrige texto, 3 corrige montos, 4 reemplazo por contingencia, 5 referencia a consumo.

## Estados del comprobante

`en_proceso` (enviado, esperando a la DGII) → `Aceptado`, `Aceptado Condicional` o `Rechazado`. Con clave `bl_test_` el resultado se simula al instante; use `numero_factura_interna: "SIMULAR-RECHAZO"` o `"SIMULAR-CONDICIONAL"` para probar esos casos.

- `GET /v1/facturas/{encf}` estado de uno.
- `POST /v1/ecf/estados` con `{"encfs": [...]}` estado de hasta 500.
- `GET /v1/facturas/{encf}/pdf` y `/xml` representación impresa (con QR) y XML firmado. En sandbox el PDF lleva el sello "SIN VALIDEZ FISCAL".
- Webhooks: ver [webhooks.md](https://api.businesslink.do/docs/webhooks.md).

## Numeración (e-NCF)

Cada empresa numera de una de dos maneras (nunca las dos a la vez): **su ERP** (el e-NCF viene en el documento) o **BusinessLink** (el secuenciador lo asigna). Detalles en [secuencias-encf.md](https://api.businesslink.do/docs/secuencias-encf.md).

## Reglas de seguridad

- Con `bl_live_` el comprobante es real y se reporta a la DGII; no se puede deshacer desde la API.
- Una clave `bl_test_` solo ve comprobantes de prueba y una `bl_live_` solo los reales.
- Siempre repita el **mismo** `Idempotency-Key` al reintentar una factura tras un timeout. Si el documento cambia, use otra clave.
