Probar FactrAPI con Postman

La colección sirve para comprobar que la API responde y que una API key puede consultar los recursos de su empresa. Empieza con un ambiente local, TEST o CERT. No uses una clave de producción para estas comprobaciones.

Archivos para importar

En Postman, selecciona Importar, elige el archivo JSON y confirma la importación. Selecciona el entorno FactrAPI | Local y pruebas.

Configurar variables

Abre las variables del entorno importado y configura:

Variable	Valor local	Descripción
`baseUrl`	`http://localhost:3000`	Dirección de la API. Para otro entorno, usa la URL HTTPS correspondiente.
`apiKey`	API key de ambiente `TEST` o `CERT`	Necesaria para solicitudes de negocio. Guárdala como valor secreto en Postman.
`opsToken`	Valor de `OPS_TOKEN`	Necesario solo para la comprobación de salud de DGII.
`correlationId`	Cualquier identificador legible	Permite encontrar la solicitud en los registros operativos.

No exportes ni compartas un entorno que tenga claves o tokens reales. No guardes secretos en la colección.

Ejecutar las comprobaciones

Ejecuta primero el grupo 01 · Salud y documentación:

Comprobar que la API está activa espera HTTP 200 y {"status":"ok"}.
Comprobar dependencias listas espera HTTP 200 y {"status":"ready"} con PostgreSQL, Redis y almacenamiento en estado up.
Consultar contrato OpenAPI comprueba que la API en desarrollo publica /docs-json.

Después ejecuta las solicitudes del grupo 02 · Consultas con API key:

Solicitud	Permiso requerido	Resultado esperado
Consultar empresa y permisos de la clave	API key válida	`200`; incluye empresa, ambiente y scopes.
Listar tipos de catálogos DGII	`documents:read`	`200`; devuelve los catálogos disponibles.
Listar documentos recientes	`documents:read`	`200`; devuelve la lista paginada de esa empresa.
Consultar salud de la DGII	`OPS_TOKEN`	`200`; muestra el estado por ambiente. Esta consulta no envía documentos.

La colección incluye pruebas automáticas de estado HTTP y estructura básica de respuesta. Usa Run collection para ejecutar las solicitudes en orden y consultar los resultados en la pestaña Test Results.

Interpretar errores comunes

Código	Qué revisar
`401`	Que `apiKey` tenga una clave completa, vigente y del entorno configurado en `baseUrl`.
`403`	Que la API key tenga el scope requerido y que la empresa tenga permisos vigentes.
`404` en `/docs-json`	En producción, configura `OPENAPI_ENABLED=true`; en desarrollo comprueba que iniciaste FactrAPI.
`503` en `/ready`	Revisa el cuerpo `checks` y el estado de PostgreSQL, Redis y almacenamiento.
`404` en endpoints operativos	`OPS_TOKEN` puede no estar definido; sin ese secreto, las rutas operativas están deshabilitadas.

Cada respuesta de negocio incluye data y meta. meta.correlationId identifica la solicitud y meta.timestamp indica cuándo respondió el servicio.

Probar emisión fiscal

La colección incluida es de solo lectura para que se pueda ejecutar varias veces sin consumir rangos e-NCF ni crear registros fiscales. Para probar POST /api/v1/documents o POST /api/v1/documents/signed-xml, usa un ambiente TEST o CERT, una empresa de pruebas con secuencias disponibles y un caso fiscal aprobado. Crear un documento puede consumir un número e-NCF aun cuando la llamada no lo envíe inmediatamente a la DGII. Consulta el XSD y el esquema JSON vigentes con GET /api/v1/schemas/ecf/:type; la creación de documentos valida el contenido contra las reglas fiscales y los esquemas oficiales. No uses datos reales de contribuyentes o clientes para una prueba.

​Probar FactrAPI con Postman

​Archivos para importar

​Configurar variables

​Ejecutar las comprobaciones

​Interpretar errores comunes

​Probar emisión fiscal