Skip to main content

​
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.
  2. Ejecuta la colección de 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 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.