Referencia completa de la API

Esta página enumera las rutas HTTP declaradas por los controladores de FactrAPI. En la instancia local también puedes consultar Swagger UI en /docs y el JSON OpenAPI en /docs-json. En producción, esas dos rutas requieren OPENAPI_ENABLED=true. Las rutas públicas de /api/v1 están disponibles en español; las rutas anteriores en inglés se conservan como alias para las integraciones existentes. Los nombres de campos JSON, filtros, encabezados y scopes se mantienen como parte del contrato actual. Las rutas de recepción /{ambiente}/{servicio}/fe/* conservan el formato requerido por la DGII.

Autenticación y formatos

Grupo	Autenticación
Integradores: `/api/v1/*`	`x-api-key` más el scope indicado para cada ruta.
Receptor: `/{ambiente}/{servicio}/fe/*`	Estándar de receptor DGII; el token se exige si `RECEIVER_AUTH_MODE=required`. XML entrante firmado.
Factra Cloud: `/internal/cloud/v1/*`	Autenticación de servicio a servicio validada por `CloudAuthGuard`.
Operaciones: `/metrics` y `/internal/*`	`Authorization: Bearer <OPS_TOKEN>`. Deshabilitadas si `OPS_TOKEN` no está definido.
Salud: `/health` y `/ready`	Públicas.

Las respuestas JSON de negocio tienen forma { "data": ..., "meta": { "correlationId", "timestamp" } }. Los errores usan application/problem+json. X-Correlation-ID se acepta en las solicitudes; Idempotency-Key está disponible para crear documentos. Scopes derivados: sequences:manage concede sequences:allocate; documents:create y documents:read conceden taxpayers:read; documents:read también concede received:read.

Empresa y perfil de integración

Método	Ruta	Acceso	Descripción
`GET`	`/api/v1/empresa`	API key válida	Devuelve la empresa, entitlement, acceso por capacidad, ambiente y scopes de la clave.

Documentos e-CF

Método	Ruta	Scope	Descripción
`POST`	`/api/v1/documentos`	`documents:create`	Valida y crea un e-CF desde JSON; lo firma y archiva, sin enviarlo a la DGII. Admite `Idempotency-Key`.
`POST`	`/api/v1/documentos/xml-firmado`	`documents:create`	Recibe un e-CF ya firmado, verifica firma/XSD y lo archiva. Admite XML directo o JSON `{ "xml": "..." }`.
`GET`	`/api/v1/documentos`	`documents:read`	Lista documentos; filtros `status`, `ecfType`, `limit` y `cursor`.
`GET`	`/api/v1/documentos/:id`	`documents:read`	Obtiene el documento.
`GET`	`/api/v1/documentos/:id/normalizado`	`documents:read`	Reconstruye el modelo desde el XML firmado archivado y verifica integridad.
`GET`	`/api/v1/documentos/:id/impresion`	`documents:read`	Obtiene datos de representación impresa, código de seguridad y URL QR.
`GET`	`/api/v1/documentos/:id/cronologia`	`documents:read`	Devuelve la cronología de estados y eventos.
`GET`	`/api/v1/documentos/:id/artefactos/:type`	`documents:read`	Descarga `source-json`, `source-xml` o `signed-xml`; admite `version`. La respuesta incluye `X-Content-SHA256`.

Envío y seguimiento DGII

Método	Ruta	Scope	Descripción
`POST`	`/api/v1/documentos/:id/enviar`	`documents:send`	Encola el envío; respuesta `202`. Consulta el resultado luego.
`POST`	`/api/v1/documentos/:id/actualizar-estado`	`documents:send`	Solicita actualización de estado al servicio DGII.
`POST`	`/api/v1/documentos/:id/reintentar`	`documents:send`	Reintenta documentos elegibles que fallaron o no fueron recibidos.
`GET`	`/api/v1/trabajos-fallidos`	`documents:read`	Lista trabajos fiscales fallidos; filtros `open`, `limit` y `cursor`.
`POST`	`/api/v1/dgii/prueba-conexion`	`certification:manage`	Prueba conexión real, certificado y autenticación en el ambiente de la API key. No devuelve el token DGII.
`GET`	`/api/v1/dgii/sesion/semilla`	`documents:send`	Emite semilla de autenticación de un solo uso para firma externa.
`POST`	`/api/v1/dgii/sesion`	`documents:send`	Recibe semilla firmada e inyecta la sesión DGII; el token no se devuelve.

Secuencias y anulaciones

Los rangos autorizados se registran en FactrAPI; no se consultan automáticamente a la DGII.

Método	Ruta	Scope	Descripción
`POST`	`/api/v1/secuencias/rangos`	`sequences:manage`	Registra rango autorizado.
`GET`	`/api/v1/secuencias/rangos`	`sequences:read`	Lista rangos; filtro opcional `ecfType`.
`GET`	`/api/v1/secuencias/rangos/:id`	`sequences:read`	Consulta rango y disponibilidad.
`POST`	`/api/v1/secuencias/asignaciones`	`sequences:allocate`	Reserva bloque de e-NCF para uso offline.
`GET`	`/api/v1/secuencias/asignaciones`	`sequences:read`	Lista bloques; filtros `status` y `deviceId`.
`GET`	`/api/v1/secuencias/asignaciones/:id`	`sequences:read`	Consulta bloque reservado.
`POST`	`/api/v1/secuencias/asignaciones/:id/cancelar`	`sequences:manage`	Cancela una reserva.
`POST`	`/api/v1/secuencias/anulaciones`	`sequences:manage`	Solicita anulación DGII de e-NCF no utilizados. Respuesta `202`.
`GET`	`/api/v1/secuencias/anulaciones`	`sequences:read`	Lista solicitudes de anulación.
`GET`	`/api/v1/secuencias/anulaciones/quemadas`	`sequences:read`	Lista números consumidos por fallos pendientes de anulación.
`GET`	`/api/v1/secuencias/anulaciones/:id`	`sequences:read`	Consulta una solicitud.
`POST`	`/api/v1/secuencias/anulaciones/:id/reintentar`	`sequences:manage`	Reintenta la solicitud de anulación.

Catálogos y contribuyentes

Método	Ruta	Scope	Descripción
`GET`	`/api/v1/catalogos`	`documents:read`	Lista catálogos oficiales disponibles.
`GET`	`/api/v1/catalogos/:catalog`	`documents:read`	Consulta elementos; acepta `limit` y `cursor`.
`GET`	`/api/v1/esquemas/ecf/:type`	`documents:read`	Devuelve esquema JSON derivado del XSD oficial.
`GET`	`/api/v1/contribuyentes/:rnc`	`taxpayers:read`	Consulta padrón por RNC de 9 dígitos o cédula de 11. Este scope se concede también a claves con `documents:create` o `documents:read`.

Documentos recibidos

Método	Ruta	Scope	Descripción
`GET`	`/api/v1/recibidos`	`received:read`	Lista los e-CF recibidos por la empresa; admite `limit` y `cursor`.
`GET`	`/api/v1/recibidos/:id`	`received:read`	Consulta documento recibido.
`GET`	`/api/v1/recibidos/:id/artefactos/:type`	`received:read`	Descarga `received-xml`, `arecf-xml` o `acecf-xml`.
`POST`	`/api/v1/recibidos/:id/respuesta-comercial`	`documents:send`	Acepta o rechaza comercialmente el e-CF recibido; crea y entrega el ACECF.

received:read también se concede a claves con documents:read.

Webhooks

Todas estas rutas requieren webhooks:manage.

Método	Ruta	Descripción
`GET`	`/api/v1/notificaciones/tipos-evento`	Lista tipos de evento.
`POST`	`/api/v1/notificaciones`	Crea destino de webhook.
`GET`	`/api/v1/notificaciones`	Lista destinos de la empresa.
`GET`	`/api/v1/notificaciones/entregas`	Lista entregas; admite `endpointId`, `status`, `limit` y `cursor`.
`POST`	`/api/v1/notificaciones/entregas/:deliveryId/reenvios`	Reencola una entrega. Respuesta `202`.
`GET`	`/api/v1/notificaciones/:id`	Consulta destino.
`PATCH`	`/api/v1/notificaciones/:id`	Cambia URL, eventos, descripción o estado.
`POST`	`/api/v1/notificaciones/:id/rotar-secreto`	Rota el secreto de firma.
`POST`	`/api/v1/notificaciones/:id/prueba`	Envía entrega de prueba. Respuesta `202`.

Las entregas incluyen firma HMAC y cabeceras X-Factra-Event, X-Factra-Delivery, X-Factra-Timestamp y X-Factra-Signature.

Certificación en CerteCF

FactrAPI puede ejecutar los casos de prueba técnicos contra servicios DGII, seguir su resultado y calcular el checklist. No automatiza el Portal de Certificación: la postulación, carga de archivos, URLs, representación impresa y declaración jurada se hacen en el portal. El contribuyente descarga allí el set de pruebas y envía los XML a los servicios de validación de la DGII (documentación oficial). Requisitos: API key del ambiente CERT con certification:manage, empresa/permisos de certificación habilitados, autenticación DGII configurada y set de datos oficial descargado del portal. Convierte el Excel a JSON localmente:

pnpm build
node scripts/certification/convert-set.mjs "DGII/Certificacion/<set-oficial>.xlsx" casos.json

No subas al repositorio el Excel del portal ni el JSON convertido. El conversor genera { "label": "...", "cases": [...] }; los casos tienen kind, caseKey, payload y, para e-CF/RFCE, ecfType.

Método	Ruta	Descripción
`GET`	`/api/v1/certificacion`	Proceso más reciente y checklist.
`POST`	`/api/v1/certificacion/iniciar`	Importa el set convertido e inicia proceso. Solo `CERT`.
`GET`	`/api/v1/certificacion/:id`	Progreso y pasos; reconcilia resultados DGII.
`GET`	`/api/v1/certificacion/:id/casos`	Casos con filtro opcional `status`.
`POST`	`/api/v1/certificacion/:id/ejecutar?limit=10`	Ejecuta casos pendientes, 10 por defecto, máximo 50 por llamada. Solo `CERT`.
`POST`	`/api/v1/certificacion/:id/pasos/:key/confirmar`	Confirma paso manual ya completado en el portal; cuerpo opcional `{ "note": "..." }`. Solo `CERT`.
`POST`	`/api/v1/certificacion/:id/cancelar`	Cancela proceso con motivo `{ "reason": "..." }`. Solo `CERT`.
`POST`	`/api/v1/certificacion/:id/completar`	Completa cuando checklist y pasos están cumplidos. Solo `CERT`.

Pasos automáticos: 2 datos e-CF/RFCE, 3 aprobaciones/rechazos del set, 4 simulación de e-CF, 9 recepción y ARECF, 11 recepción de aprobaciones comerciales. Pasos del portal que el usuario confirma tras completarlos: 1 postulación; 5–8 representación impresa, validaciones y URLs; 10 inicio de prueba de aprobaciones; 12 URLs de producción; 13 declaración jurada; 14 estatus del contribuyente. FactrAPI calcula el avance y registra las confirmaciones manuales de forma auditable; la DGII determina la cantidad de pruebas de simulación. Claves que acepta POST /:id/steps/:key/confirm para los pasos manuales: registrado, representacion_impresa_envio, representacion_impresa_validacion, url_servicio_prueba, url_pruebas_comunicacion, inicio_prueba_aprobaciones, url_produccion, declaracion_jurada y verificacion_estatus. Ejemplo de confirmación tras completar la acción en el portal:

curl -X POST "$FACTRAPI_URL/api/v1/certificacion/$PROCESS_ID/steps/registrado/confirm" \
  -H "x-api-key: $FACTRAPI_CERT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"Postulación firmada y enviada en CerteCF"}'

Para iniciar el proceso, primero convierte localmente el Excel del set oficial con node scripts/certification/convert-set.mjs <set.xlsx> casos.json; luego envía ese JSON a POST /api/v1/certificacion/iniciar. A continuación llama POST /api/v1/certificacion/:id/ejecutar?limit=10 para enviar el siguiente bloque a CerteCF y GET /api/v1/certificacion/:id para consultar el progreso. run ejecuta hasta 50 casos por llamada; esta operación sí envía XML y crea estado fiscal de certificación. El conversor versionado procesa las hojas ECF y RFCE del Excel oficial. El servicio de certificación también acepta casos ACECF, pero no los genera ese conversor; revisa los materiales oficiales del set antes de afirmar que esos casos están importados. Si un caso del set es rechazado, no lo reintentes como parte del mismo proceso: la guía de DGII requiere regenerar el set y abrir un proceso nuevo. Los XML de postulación y declaración jurada se firman actualmente con la herramienta de firma de la DGII u otra herramienta compatible, no mediante este módulo de FactrAPI.

Recepción de e-CF (DGII → FactrAPI)

El patrón de las URL receptoras es /{ambiente}/{servicio}/fe/.... Los segmentos reconocidos son testecf (TEST), certecf (CERT) y ecf (PRODUCTION). Un ejemplo de prueba local es /testecf/emisorreceptor/fe/recepcion/api/ecf.

Método	Ruta	Descripción
`GET`	`/{ambiente}/{servicio}/fe/autenticacion/api/semilla`	Genera semilla XML de un solo uso.
`POST`	`/{ambiente}/{servicio}/fe/autenticacion/api/validacioncertificado`	Valida semilla firmada e intercambia token de receptor.
`POST`	`/{ambiente}/{servicio}/fe/recepcion/api/ecf`	Recibe e-CF firmado y responde ARECF firmado en XML.
`POST`	`/{ambiente}/{servicio}/fe/aprobacioncomercial/api/ecf`	Recibe ACECF firmado y responde su resultado.

Envía el XML como multipart/form-data en el campo xml o con Content-Type: application/xml. El límite receptor es 5 MB. La autenticación del receptor se configura mediante RECEIVER_AUTH_MODE; no usa la API key del integrador.

Factra Cloud → FactrAPI

Rutas internas autenticadas por CloudAuthGuard; no son públicas para integradores.

Método	Ruta	Descripción
`POST`	`/internal/cloud/v1/events`	Recibe eventos de aprovisionamiento y cambios de permisos.
`POST`	`/internal/cloud/v1/companies/:companyId/api-keys`	Emite API key para una empresa; la clave completa se muestra una sola vez.
`GET`	`/internal/cloud/v1/companies/:companyId/api-keys`	Lista API keys de la empresa.
`DELETE`	`/internal/cloud/v1/companies/:companyId/api-keys/:keyId`	Revoca API key. Respuesta `204`.

Salud y operación

Método	Ruta	Autenticación	Descripción
`GET`	`/health`	Pública	Liveness del proceso HTTP.
`GET`	`/ready`	Pública	Readiness de PostgreSQL, Redis y almacenamiento; no comprueba la DGII.
`GET`	`/metrics`	`OPS_TOKEN`	Métricas Prometheus.
`GET`	`/internal/health/dgii`	`OPS_TOKEN`	Disponibilidad, interruptores y documentos pendientes por ambiente.
`GET`	`/internal/archive/findings`	`OPS_TOKEN`	Hallazgos de integridad del archivo fiscal.

Postman

Importa la colección segura de FactrAPI y el entorno local. Las solicitudes de lectura y salud incluyen pruebas de respuesta. No crean documentos ni envían solicitudes a la DGII. Para ejecutar emisión o llamadas de certificación, configura explícitamente el ambiente CERT, una empresa con el set oficial y sus permisos; esas operaciones sí cambian estado y pueden enviar XML a los servicios de DGII.

FactrAPI

Factra Cloud

Factra Local

FactraLink

Referencia completa de la API

Referencia completa de la API

Autenticación y formatos

Empresa y perfil de integración

Documentos e-CF

Envío y seguimiento DGII

Secuencias y anulaciones

Catálogos y contribuyentes

Documentos recibidos

Webhooks

Certificación en CerteCF

Recepción de e-CF (DGII → FactrAPI)

Factra Cloud → FactrAPI

Salud y operación

Postman

​Referencia completa de la API

​Autenticación y formatos

​Empresa y perfil de integración

​Documentos e-CF

​Envío y seguimiento DGII

​Secuencias y anulaciones

​Catálogos y contribuyentes

​Documentos recibidos

​Webhooks

​Certificación en CerteCF

​Recepción de e-CF (DGII → FactrAPI)

​Factra Cloud → FactrAPI

​Salud y operación

​Postman

Referencia completa de la API

Autenticación y formatos

Empresa y perfil de integración

Documentos e-CF

Envío y seguimiento DGII

Secuencias y anulaciones

Catálogos y contribuyentes

Documentos recibidos

Webhooks

Certificación en CerteCF

Recepción de e-CF (DGII → FactrAPI)

Factra Cloud → FactrAPI

Salud y operación

Postman