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

# Probar FactrAPI con Postman

> Importa la colección de pruebas y comprueba FactrAPI paso a paso.

# 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

* [Descargar la colección de FactrAPI](/postman/FactrAPI-Pruebas.postman_collection.json)
* [Descargar el entorno local de FactrAPI](/postman/FactrAPI-Local.postman_environment.json)

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**:

1. **Comprobar que la API está activa** espera `HTTP 200` y `{"status":"ok"}`.
2. **Comprobar dependencias listas** espera `HTTP 200` y `{"status":"ready"}` con PostgreSQL, Redis y almacenamiento en estado `up`.
3. **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.


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