Skip to Content

Comprobantes recibidos

Trae las facturas de tus proveedores y las retenciones que te hacen tus clientes, verificadas, y emite la retención de cada factura.

Un comprobante recibido es un comprobante electrónico dirigido a tu negocio: la factura, la nota de crédito o la nota de débito de un proveedor, y la retención que te emite un cliente. Una vez guardado, lo ves con GET /v1/ec/received-documents, y cada uno se identifica por su id.

Cómo llegan

Fiscalbase nunca te pide tu contraseña del SRI. Un comprobante llega porque subes sus archivos, o porque lo emitiste con Fiscalbase.

CaminoQué hacesQué pasa
ArchivosPOST /v1/ec/imports, multipart con file: XML, un ZIP o el reporte de "Comprobantes electrónicos recibidos" o "emitidos" de SRI en línea, en TXT o CSVUna importación: lo que te emitieron va a tus recibidos (resultado received) y lo que emitiste, a tus comprobantes
curl -X POST https://api.fiscalbase.io/v1/ec/imports \
  -H "Authorization: Bearer $FISCALBASE_API_KEY" \
  -H "Idempotency-Key: recibidos-septiembre" \
  -F "file=@recibidos-septiembre.txt"

Cada clave del reporte que te emitieron se pide al SRI: después queda guardada, missing (el SRI no la conoce) u out_of_window (pasaron los 60 días: sube su XML). En Sandbox entra cualquier XML de comprobante dirigido al RUC de tu negocio de Sandbox, sin revisar su firma ni consultar al SRI: queda unconfirmed y sin validez tributaria, para que pruebes tu integración con los archivos que tengas. Una clave de un reporte que el negocio aún no tiene se omite con no_sri_in_sandbox. Pruebas no guarda recibidos.

Cada comprobante se confirma con el SRI por su clave de acceso. Si un proveedor no te mandó el XML, el comprobante queda sin él (xml_status missing u out_of_window) y en el panel de Recibidos tienes un mensaje listo para pedírselo; sube el XML cuando lo tengas. Fiscalbase nunca escribe a tus proveedores. El reporte mensual de "Comprobantes electrónicos recibidos" del SRI, que descargas y subes, deja ver cuáles faltan.

Un comprobante que tu negocio emitió con otro sistema no es una compra: la importación lo guarda en tus comprobantes (GET /v1/ec/documents), y tu numeración sigue después de él.

Cómo sabemos que es auténtico

Cada comprobante trae su nivel de verification, con las mismas reglas que una importación de historial: sri, listed, signature o unconfirmed.

xml_status dice si tenemos el XML del comprobante:

xml_statusQué significa
availableTenemos el XML
pendingLo estamos pidiendo al SRI
missingEl SRI no lo conoce
out_of_windowPasó el plazo del SRI: sube el XML

sri_status dice qué opina el SRI del comprobante: authorized, annulment_pending (la anulación está en trámite y el comprobante sigue valiendo) o annulled.

Listar y leer

curl "https://api.fiscalbase.io/v1/ec/received-documents?needs_review=true&issue_date[gte]=2026-09-01&issue_date[lte]=2026-09-30" \
  -H "Authorization: Bearer $FISCALBASE_API_KEY"

La lista filtra por access_key, needs_review, issue_date[gte] e issue_date[lte] (desde y hasta qué día de emisión), type, issuer, verification y xml_status, y por updated_at[gte] para traer solo lo que cambió desde una fecha. Pagina con cursor como las demás (listas).

GET /v1/ec/received-documents/{id} devuelve el comprobante guardado (object: "received_document"); si no existe, responde 404 con received_document_not_found. Su type dice la familia (invoice, credit_note, withholding…) y document trae el XML leído con la forma de esa familia.

Para leer una factura del SRI sin guardarla, GET /v1/ec/sri/invoices/{access_key} responde con object: "sri_invoice": quién la emitió, a quién, sus impuestos, totales y pagos. La respuesta se puede conservar un minuto (Cache-Control: private, max-age=60). Sus rechazos son sri_invoice_not_found, sri_invoice_expired, sri_invoice_annulled y sri_invoice_not_authorized; si el SRI no responde, sri_unreachable o sri_invoice_not_delivered (503). Con una API key de Sandbox responde con las facturas que recibió tu negocio de Sandbox, sin preguntar al SRI.

Retener al proveedor

Fiscalbase no propone la retención ni lleva su plazo: la emites tú, y la factura recibida dice cuál emitiste. POST /v1/ec/withholding-suggestions arma el borrador a partir de la factura (por su access_key, o con sus datos y el RUC de quien la emitió) y de lo que compraste (kind: goods, services o professional_services): las filas de renta e IVA según lo que el registro del SRI dice del proveedor, con los porcentajes vigentes a la fecha de la retención, y el sustento tributario, 01 si se retiene IVA y 02 si no. Revísalo y emítelo con POST /v1/ec/withholdings, como cualquier comprobante.

curl -X POST https://api.fiscalbase.io/v1/ec/withholding-suggestions \
  -H "Authorization: Bearer $FISCALBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "access_key": "'$ACCESS_KEY'", "kind": "services" }'

Cuando el SRI autoriza la retención, la factura recibida la nombra en withholding: { "object": "document", "type": "withholding", "id", "number" }, la última retención autorizada de tu negocio que la lleva como documento de sustento; es null mientras no hay ninguna, y vuelve a serlo si la anulas. El enlace se hace por el RUC del proveedor, el tipo y el número del sustento, así que también vale para una retención que emitiste antes de que llegara la factura. La exportación de recibidos la trae en la columna retention_number.

En la consola, el panel de una factura recibida muestra la retención emitida con Ver la retención, o el botón Emitir retención, que abre el formulario con la factura como sustento y las filas sugeridas para bienes; Qué compraste las cambia a servicios o servicios profesionales. Agrega el correo del proveedor, que la factura no trae, y emite.

GET /v1/ec/suppliers lista a tus proveedores, cada uno con sus comprobantes y su última compra, y busca con q.

Webhook y volumen

Los eventos received_document.created y received_document.updated llevan el comprobante entero (eventos). Una retención autorizada o anulada avisa con withholding.authorized y withholding.annulled, no con received_document.updated. Los comprobantes recibidos cuentan en el volumen del mes cuando se guardan.

En esta página