> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factra.net/llms.txt
> Use this file to discover all available pages before exploring further.

# FactrAPI

> API fiscal para emisión, recepción e integración con la DGII.

# FactrAPI

FactrAPI es el servicio fiscal del ecosistema Factra. Expone una API HTTP para integraciones autorizadas y se ejecuta junto con un worker y un scheduler para procesar tareas asíncronas.

## Capacidades principales

* Crear documentos fiscales desde JSON o recibir XML ya firmado.
* Validar XML y contenido fiscal con esquemas oficiales.
* Gestionar rangos e-NCF, reservas y anulaciones.
* Enviar e-CF y consultar su estado ante la DGII.
* Recibir e-CF como receptor y emitir respuestas comerciales.
* Archivar documentos y artefactos, verificar su integridad y entregar webhooks.
* Consultar catálogos, esquemas y el padrón de contribuyentes.

## Autenticación y versión

Las rutas de negocio usan el prefijo `/api/v1` y la cabecera `x-api-key`. Los permisos se asignan por scopes, entre ellos `documents:create`, `documents:read`, `documents:send`, `received:read`, `sequences:read`, `sequences:allocate`, `sequences:manage`, `taxpayers:read` y `webhooks:manage`.

La API admite `Idempotency-Key` en la creación de documentos y acepta `X-Correlation-ID` para relacionar solicitudes y tareas asíncronas. Las respuestas de negocio usan la envoltura `{ "data": ..., "meta": ... }`.

## Primeras pruebas

1. Sigue el [inicio rápido](inicio).
2. Ejecuta la [colección de Postman](pruebas-postman).
3. Consulta la documentación interactiva de una instancia en desarrollo en `/docs` y su contrato en `/docs-json`.

## Certificación DGII desde la API

FactrAPI puede importar el set oficial, enviar casos al ambiente `CERT`, reconciliar sus resultados y mostrar los pasos de certificación. Requiere una API key `CERT` con `certification:manage`. El portal de CerteCF continúa siendo necesario para enviar la postulación, cargar la representación impresa y la declaración jurada, configurar las URLs y completar los pasos que la API marca como manuales. Tras ejecutar una acción en el portal, `POST /api/v1/certification/:id/steps/:key/confirm` registra que se completó; esa llamada no envía el archivo al portal.

Revisa la [referencia completa de rutas y el flujo de certificación](api-reference) antes de usar `POST /api/v1/certification/:id/run`; esa operación envía XML a CerteCF y cambia el estado del proceso.

## Guías técnicas del repositorio

Las guías detalladas viven en `docs/` dentro del repositorio `factrApi`:

* `docs/ARCHITECTURE.md`: arquitectura interna y aislamiento por empresa.
* `docs/DGII.md`: conexión y ambientes de la DGII.
* `docs/SEQUENCES.md` y `docs/OFFLINE.md`: e-NCF y operación sin conexión.
* `docs/SIGNING.md`: firma remota y XML firmado.
* `docs/STORAGE.md`: archivo de artefactos y almacenamiento S3.
* `docs/SECURITY.md`: autenticación, credenciales y datos sensibles.
* `docs/OPERATIONS.md`: despliegue, operación y lista previa a producción.

## Preparación para producción

Que una ruta esté implementada o responda correctamente no implica que la empresa esté autorizada a emitir en producción. Antes del despliegue fiscal se requiere completar la certificación real de la DGII, configurar almacenamiento con Object Lock, respaldos recuperables y secretos de producción, y probar todos los flujos en el ambiente correspondiente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.