> ## 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.

# Referencia completa de la API

> Rutas implementadas, autenticación, permisos y proceso de certificación CerteCF.

# 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](https://dgii.gov.do/cicloContribuyente/facturacion/comprobantesFiscalesElectronicosE-CF/Paginas/documentacionSobreE-CF.aspx)).

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:

```bash theme={null}
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:

```bash theme={null}
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](/postman/FactrAPI-Pruebas.postman_collection.json) y el [entorno local](/postman/FactrAPI-Local.postman_environment.json). 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.


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