# Comprobantes recibidos de proveedores (facturas de compra)

Permiso de la clave: `recibidos:leer`.

BusinessLink recibe los e-CF que los proveedores de la empresa le envían (a través de los servicios de recepción y aprobación comercial de la DGII). Cada comprobante queda disponible por API con su XML firmado, su PDF y el documento completo ya leído, listo para convertirse en una factura de compra en un ERP o en un sistema contable.

## Listar

`GET /v1/recibidos`: del más reciente al más antiguo.

| Parámetro | Para qué |
|---|---|
| `desde`, `hasta` | Rango por fecha de emisión (AAAA-MM-DD). |
| `recibido_desde` | Momento de llegada a BusinessLink (ISO 8601, p. ej. `2026-10-10T14:00:00-04:00`). Úselo para **sincronizar solo lo nuevo** guardando la última hora consultada. |
| `emisor_rnc` | Un proveedor. |
| `tipo_ecf` | Un tipo de comprobante. |
| `limite` (máx. 200), `offset` | Paginación; `siguiente_offset` es `null` en la última página. |

## Un comprobante completo

`GET /v1/recibidos/{emisor_rnc}/{encf}` devuelve el resumen y `documento`: la factura leída del XML firmado con líneas (códigos, cantidad, precio, descuento, ITBIS por línea, impuestos adicionales), descuentos o recargos globales, totales por tasa, moneda y referencias (orden de compra, NCF modificado).

`documento.cuadre` indica si líneas + impuestos suman el total y si los montos de las líneas incluyen el ITBIS (muchos emisores lo declaran mal): revíselo antes de contabilizar.

## Descargar

- `GET /v1/recibidos/{emisor_rnc}/{encf}/xml`: XML firmado original del proveedor.
- `GET /v1/recibidos/{emisor_rnc}/{encf}/pdf`: representación impresa.

## Leer un XML que usted ya tiene

`POST /v1/recibidos/leer` con `{"xml": "<XML en base64>"}`: devuelve el mismo `documento`, indica si el comprador es su empresa (`para_su_empresa`) y si la firma digital es válida (`firma`). No guarda nada. Sirve para facturas que llegaron por correo o que un usuario arrastra a su sistema.

## Flujo típico para un sistema contable o ERP

1. Cada X minutos, `GET /v1/recibidos?recibido_desde=<última consulta>`.
2. Para cada nuevo, `GET /v1/recibidos/{emisor_rnc}/{encf}` y crear la factura de compra con `documento`.
3. Guardar el XML (`/xml`) como respaldo fiscal del documento.
4. Validar al proveedor con `GET /v1/rnc/{rnc}` (estado en el directorio de la DGII).

El conector de Odoo (`l10n_do_ecf_businesslink`) hace exactamente este flujo y crea las facturas de proveedor completas (líneas, impuestos, retenciones aprendidas del hábito del contable).

Las claves `bl_test_` ven lo recibido en los ambientes de prueba de la DGII.
