Importar tu historial

Si vienes de otro sistema de facturación, tus comprobantes autorizados pueden venir contigo. Una vez importados son comprobantes comunes de Fiscalbase: aparecen en tus listas, tus clientes los ven en el portal, una nota de crédito puede referirse a ellos, y la numeración sigue después del último número que usaste.

Qué puedes subirCopiar enlace a esta sección

Un ZIP puede traer también listados de claves (.txt o .csv), que leemos igual que si los subieras aparte, y los RIDE en PDF, que contamos y dejamos de lado. Un PDF suelto, en cambio, se rechaza: el RIDE es solo una representación impresa y no prueba que el comprobante esté autorizado. Pide a tu sistema anterior el XML. Una hoja de Excel también se rechaza: guárdala como CSV y súbela así. Leemos los XML en UTF-8, UTF-16 o ISO-8859-1, lo diga el archivo o no.

Si emitías con el Facturador del SRICopiar enlace a esta sección

El Facturador del SRI te deja descargar cada comprobante como XML firmado, pero sin la autorización del SRI alrededor. Igual puedes importarlos todos:

1. En el Facturador, entra a Comprobantes › Administración y busca por rangos de hasta 60 días.
2. Descarga el XML de cada comprobante desde su menú. Puedes juntarlos en un ZIP.
3. Descarga el listado con Descargar reporte. Si te llega como hoja de Excel, guárdala como CSV. Si tienes el reporte de comprobantes emitidos de SRI en línea, también sirve, y además trae la fecha de autorización.
4. Sube los XML y el listado juntos, en la misma importación.

Cada XML cuya clave aparece en el listado entra como listed: el listado del SRI muestra que está autorizado. El del Facturador no trae la fecha de autorización, así que esos comprobantes quedan sin fecha de autorización (authorized_at en null) y su RIDE no la imprime; el reporte de SRI en línea sí la trae.

Si subes solo los XML, igual se importan, como unconfirmed: tu firma es válida, pero nada muestra todavía que el SRI los autorizó, así que no aparecen en el portal de tus clientes. Sube el listado cuando lo tengas, en otra importación: los que aparezcan pasan a listed sin importarse de nuevo, con el resultado evidence_added. Lo mismo vale si tu sistema anterior solo guardó los XML firmados.

SúbeloCopiar enlace a esta sección

Desde la consola: en Comprobantes › Importar historial eliges tus archivos (o los arrastras) y tocas Importar. La consola te lleva a la importación y la sigue sola: el avance mientras decide cada comprobante, luego cuántos se importaron, cuántos ya estaban, cuántos se omitieron y cuáles tienen un problema, junto con lo que sumaron los comprobantes importados (sales_total: facturas y notas de débito menos notas de crédito), con el mensaje de cada uno, y tu numeración con la opción de activar una serie que la importación abrió apagada. Mientras corre puedes cancelarla; lo ya importado se queda.

Desde la API, es un formulario multipart, con hasta 20 archivos y 50 MB por solicitud:

curl -X POST https://api.fiscalbase.io/v1/ec/imports \
  -H "Authorization: Bearer $FISCALBASE_API_KEY" \
  -H "Idempotency-Key: historial-2025" \
  -F "file=@facturas-2025.zip" \
  -F "file=@emitidos-septiembre.txt"

Si tu organización tiene varios negocios de la clase que tu clave emite, agrega -F "entity_id=…". Todos los campos están en la referencia. La respuesta llega apenas guardamos los archivos, con la importación en queued:

{
  "id": "01926f3a-…",
  "object": "import",
  "country": "ec",
  "currency": "USD",
  "status": "queued",
  "files": [
    {
      "name": "facturas-2025.zip",
      "kind": "zip",
      "size": 812345,
      "sha256": "9f2c…",
      "ignored_entries": 0
    },
    {
      "name": "emitidos-septiembre.txt",
      "kind": "keys",
      "size": 20211,
      "sha256": "41aa…",
      "ignored_entries": 0
    }
  ],
  "counts": {
    "found": 0,
    "pending": 0,
    "imported": 0,
    "duplicate": 0,
    "skipped": 0,
    "failed": 0
  }
}

Leer miles de comprobantes y consultar al SRI por los recientes toma minutos. Consulta la importación con GET /v1/ec/imports/{id}, o espera el evento import.completed en tus webhooks. Si subes los mismos archivos mientras su importación sigue en curso (un doble clic), te devolvemos esa misma importación.

Qué pasa con cada comprobanteCopiar enlace a esta sección

Cada comprobante que encontramos es un elemento de la importación, en GET /v1/ec/imports/{id}/items, con su resultado:

Cada uno trae un code estable y un message en español que te dice qué hacer. Para ver solo lo que necesita tu atención:

curl "https://api.fiscalbase.io/v1/ec/imports/$IMPORT_ID/items?result=failed" \
  -H "Authorization: Bearer $FISCALBASE_API_KEY"

{
  "object": "import_item",
  "file": "facturas-2025.zip",
  "entry": "2025/03/FAC-001-001-000004120.xml",
  "number": "001-001-000004120",
  "result": "failed",
  "code": "invalid_signature",
  "message": "No tiene una firma válida: falta, o el comprobante cambió después de firmarse."
}

La importación termina en completed cuando cada comprobante tiene su resultado; counts te dice cuántos entraron. Solo termina en failed si los archivos en conjunto no se pueden usar, por ejemplo un ZIP dañado o un ZIP dentro de otro, y entonces failure explica por qué.

Cómo sabemos que es auténticoCopiar enlace a esta sección

Un XML autorizado dice AUTORIZADO, pero esa envoltura no la firma el SRI: cualquiera podría escribirla. Por eso verificamos cada comprobante:

1. La firma electrónica. El comprobante debe estar firmado con un certificado de tu RUC (o de tu cédula, si eres persona natural), vigente cuando se firmó, y no haber cambiado después.
2. El SRI, cuando todavía responde. Si el comprobante tiene menos de 60 días, le preguntamos al SRI si está autorizado. Así también detectamos los anulados, que no se importan. Si tiene menos de un mes y el SRI no lo conoce, no se importa (unknown_to_sri).

Lo más antiguo el SRI ya no lo recuerda: pasado el mes a veces todavía responde, y si no, o si tiene más de 60 días, decide lo que venga con el comprobante. Cada comprobante importado te dice en verification qué muestra que está autorizado, de más a menos:

Los unconfirmed no aparecen en el portal de tus clientes hasta que subas un listado que los nombre. Puedes subirlo después, solo: los que nombre pasan a listed sin importarse de nuevo, cada elemento es duplicate con el código evidence_added, y la importación del listado te dice en upgraded cuántos confirmó, según lo que tenían (signature o unconfirmed). Salvo con sri, no podemos saber si anulaste el comprobante después: si anulaste alguno, no lo incluyas.

Tu numeración continúaCopiar enlace a esta sección

Un número que el SRI autorizó ya está usado, lo haya emitido quien lo haya emitido. Por eso, al importar, la numeración de cada establecimiento y punto de emisión avanza hasta el número más alto que encontremos, y tu próximo comprobante sale con el siguiente.

Eso incluye los comprobantes que no podemos importar pero que son tuyos y el SRI conoce: los que el SRI ya no recuerda y de los que solo tenemos la clave (xml_unavailable: sube su XML de tu sistema anterior o del Facturador para importarlos), los anulados y los no autorizados. No entran a Fiscalbase, pero su número queda reservado. Así, subir los reportes de emitidos de SRI en línea basta para continuar tu numeración, sin un solo XML. Una clave que el SRI no conoce no reserva nada.

La importación te lo muestra en numbering:

{
  "establishment": "001",
  "emission_point": "001",
  "document_type": "invoice",
  "highest_imported": 4812,
  "highest_reserved": 4815,
  "next_number": 4816,
  "active": true,
  "created": false
}

highest_imported es el número más alto importado y highest_reserved el más alto reservado sin importar; 0 si no hubo ninguno.

Si importas comprobantes de un punto de emisión que aún no tenías, abrimos su numeración apagada (created: true). Para seguir emitiendo desde ahí, enciéndela con { "active": true }; en Pruebas y Producción comprobamos antes que el SRI registre ese establecimiento como abierto.

Cambiar de sistema sin parar de facturarCopiar enlace a esta sección

1. Importa tu historial: el ZIP de tu sistema anterior.
2. Te recomendamos emitir desde un punto de emisión nuevo, por ejemplo 001-002. Así ambos sistemas pueden funcionar a la vez y ninguno toma los números del otro. Los puntos de emisión no se registran en el SRI: los eliges tú.
3. Si prefieres seguir en el mismo punto: apaga tu sistema anterior, descarga de SRI en línea los reportes de emitidos y súbelos. La numeración avanza hasta lo último que emitió. Si algo se escapó, el SRI devuelve el comprobante con el error 45 y lo renumeras con una llamada.

Ensaya en SandboxCopiar enlace a esta sección

Con una clave fb_sandbox_ puedes importar tus archivos reales para ver qué entraría antes de hacerlo en Producción. Sandbox acepta comprobantes de Pruebas y de Producción, verifica la firma, pero nunca consulta al SRI: importa cada XML como Producción importaría uno que el SRI ya no recuerda (listed, signature o unconfirmed) y deja de lado las claves de acceso sin XML, aunque reserva sus números como lo haría Producción. Nada de lo que importes ahí llega al portal ni a nadie por correo.

En Pruebas y Producción, en cambio, el ambiente del comprobante debe ser el de tu clave: un comprobante de Pruebas no entra en Producción.

Lo que conviene saberCopiar enlace a esta sección

• No se envían correos ni webhooks por comprobante. Tus clientes ya recibieron esos comprobantes cuando los emitiste. Si necesitas reenviar uno, envíalo por correo cuando quieras. La importación sí te avisa al terminar, con import.completed o import.failed.
• Un comprobante importado no se corrige. Ya está autorizado: resubmit responde 409.
• Las fechas son las del SRI. authorization.authorized_at es la fecha de autorización que muestra el SRI, un listado o el archivo, no la de la importación, y tus listas ubican cada comprobante según ella. Si nada la muestra, queda en null.
• Puedes volver a intentarlo. Si un comprobante falló porque el SRI aún no lo conocía o no respondía, sube el archivo de nuevo cuando la importación haya terminado: lo que ya entró sale como duplicate.
• Puedes cancelar. POST /v1/ec/imports/{id}/cancel detiene una importación en curso; lo ya importado se queda.
• Límites. 20 archivos y 50 MB por solicitud (no más: un XML autorizado pesa de 4 a 8 KB y un ZIP lo comprime de 5 a 10 veces, así que 50 MB alcanzan para más de los 20.000 comprobantes que admite una importación, y la API sostiene la subida entera en memoria; un historial más grande va en varias importaciones, por ejemplo una por año), 20.000 comprobantes por importación, 1 MB por XML y 50 MB por listado dentro de un ZIP. Tres importaciones en curso a la vez por ambiente. Los archivos que subes se guardan 30 días después de terminar; los comprobantes importados, 7 años, como todos.