<!-- source_url: https://docs.mynexusapi.com/v1/guias/colecciones | last_updated: 2026-11-19 -->

# Colecciones

Descarga la colección de Postman y los ejemplos de la API para probar cada petición sin escribir código, también desde Bruno o Newman.

Antes de escribir código, puede servirte ver cómo responde la API a cada
petición. Con nuestra colección de Postman puedes enviar las peticiones
principales del contrato tal como vienen, con pruebas automáticas que comprueban
la respuesta, y también puedes abrirla en Bruno o ejecutarla desde la terminal
con Newman.

En esta página encontrarás todos los archivos descargables, cómo configurar la
colección con tu API Key de pruebas y cómo emitir tu primera factura desde
Postman, además de qué contiene cada carpeta y cómo usarla en Bruno y Newman.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. El environment apunta a
> `https://api-sandbox.mynexusapi.com`.

## Archivos

La colección y el environment también están publicados en el workspace público
de Postman [Ecuafact API](https://www.postman.com/ecuafact/ecuafact-api). Desde
ahí puedes hacer un *fork* a tu propio workspace y recibir las actualizaciones
sin descargar ni importar archivos.

| Archivo | Contenido |
|---|---|
| [Colección Postman](/downloads/v1/Ecuafact-API-v1.postman_collection.json) | Las peticiones del flujo de integración, agrupadas por carpeta, con pruebas automáticas y scripts que generan la fecha de emisión y la `Idempotency-Key`. Formato Postman v2.1; Bruno y Newman la importan. |
| [Environment](/downloads/v1/Ecuafact-API.postman_environment.json) | Variables `baseUrl` (pruebas), `baseUrlProduccion`, `apiKey` (vacía), `identificacion`, `ruc`, `estab`, `ptoEmi`, `claveAcceso` (de ejemplo, para decodificar), `idOperacion` más `idOperacion01` a `idOperacion07` (se llenan solas al emitir), `claveAccesoEmitida` (se llena sola cuando la operación queda autorizada), `idDestino` (se llena al crear o listar destinos) y `eventoId` (se llena al listar entregas). |
| [OpenAPI](/api/openapi.json) | Especificación OpenAPI 3.1 de la API. Importable en Postman, Bruno, Insomnia o generadores de clientes. |
| Ejemplos de solicitud | Un JSON listo por tipo de comprobante: [Factura `01`](/downloads/v1/ejemplos/example-01.json), [Liquidación de compra `03`](/downloads/v1/ejemplos/example-03.json), [Nota de crédito `04`](/downloads/v1/ejemplos/example-04.json), [Nota de débito `05`](/downloads/v1/ejemplos/example-05.json), [Guía de remisión `06`](/downloads/v1/ejemplos/example-06.json) y [Retención `07`](/downloads/v1/ejemplos/example-07.json). |
| [Emisión para asistentes](/downloads/v1/emision-factura.md) | Resumen corto del contrato de emisión para pegar en un asistente de IA. |
| [Catálogo de servicios](/.well-known/api-catalog) | Enlaces a OpenAPI, documentación y versiones (RFC 9727), para descubrimiento automático. |
| [Versiones del contrato](/.well-known/api-versions.json) | Versión vigente, fechas y retiro, en JSON. |
| [llms.txt](/llms.txt) y [llms-full.txt](/llms-full.txt) | Índice y texto completo de la documentación para asistentes de IA. |

Los ejemplos JSON usan el contribuyente 0123456789001 de
[Datos de prueba](/v1/guias/datos-de-prueba) y el `secuencial` `"000000000"`,
con el que te asignamos el siguiente. Antes de enviarlos, cambia
`infoTributaria.ruc` por tu RUC y `fechaEmision` por la fecha de hoy, en formato
`dd/MM/yyyy`. Las referencias a documentos de sustento de los tipos 04, 05 y 07
son de ejemplo, así que reemplázalas por comprobantes tuyos.

## Requisitos

- [ ] [Postman](https://www.postman.com/downloads/) o [Bruno](https://www.usebruno.com/)
      instalado. Para la terminal, instala Newman con `npm install -g newman`.
- [ ] Una API Key de pruebas. Si todavía no tienes una, [crea un sandbox](/v1/guias/sandbox).
- [ ] Tu `identificacion`, que es tu RUC de 13 dígitos. La ves en
      `GET /v1/contexto` o en el portal del cliente.
- [ ] La IP de tu equipo registrada, solo si trabajas en producción: el sandbox
      acepta llamadas desde cualquier IP, y en producción la registras en
      **Cuenta > IP permitidas**.

## Usar la colección en Postman

Sigue estos pasos para emitir tu primera factura desde Postman:

1. Descarga los dos archivos, la colección y el environment.
2. En Postman, pulsa **Import** y arrastra ambos archivos. Aparecen la colección
   `Ecuafact API — Comprobantes Electronicos SRI (v1)` y el environment
   `Ecuafact API — Plantilla`.
3. Arriba a la derecha, en el selector de environments, elige
   `Ecuafact API — Plantilla`. Sin un environment seleccionado, la colección usa
   sus propias variables, que apuntan a pruebas pero con `apiKey` vacía, así que
   las peticiones autenticadas responden 401.
4. Abre el environment con el icono del ojo y **Edit**, y completa estas
   variables:
   - `apiKey`: tu API Key. Márcala como tipo **secret** para que no se vea.
   - `identificacion`: tu `identificacion` de `GET /v1/contexto`, que es tu RUC
     de 13 dígitos.
   - `ruc`: el mismo valor de `identificacion`.
   - `estab` y `ptoEmi`: tu establecimiento y punto de emisión. La plantilla
     trae `002` y `001`; cámbialos por los de tu contribuyente.
   Guarda con **Save**.
5. Ejecuta **00 > 00.2 Contexto de la credencial**. Funcionó si la respuesta es
   200 y lista tus contribuyentes. Un 401 con el `codEstado` 3009 (`credenciales_invalidas`) indica que falta la
   API Key o no es válida. Un 403 con el `codEstado` 3010 (`ip_no_autorizada`) indica que la IP no está permitida.
6. Si quieres comprobar la factura antes de emitirla, ejecuta
   **01 > 01.0 Validar factura (sin emitir)**. Envía el mismo cuerpo que 01.1
   y responde 200 con `valido` en `true` y `errores` vacío cuando la factura es válida, o 422 con el `codEstado` 3002 (`comprobante_invalido`) y el problema en `errores` cuando no lo es. Esta petición no
   emite nada, no consume cupo ni lleva `Idempotency-Key`, así que puedes
   repetirla las veces que necesites; lo explica
   [Validar sin emitir](/v1/guias/emision#validar-sin-emitir).
7. Ejecuta **01 > 01.1 Factura**. Deberías recibir `202 Accepted` con `estado`
   `recibido`, un `codEstado` 1001 o 1002 y un `idOperacion`, que la prueba de la petición guarda en el
   environment.
8. Ejecuta **02 > 02.1 Ver operación** varias veces, con unos segundos de
   espera entre cada una, mientras `estado` sea `recibido`. Termina en
   `autorizado`, o en `rechazado` con el `codEstado` 3001 (`rechazo_sri`) si el
   SRI lo rechazó. Cuando queda `autorizado`, la prueba de la
   petición guarda la `claveAcceso` en `claveAccesoEmitida`.
9. Ejecuta **06 > 06.1 Descargar RIDE (PDF)** para bajar el PDF de esa factura.
   En Postman, guárdalo con **Save Response > Save to a file**.
10. Para conciliar lo emitido, abre **03 > 03.1 Listar operaciones** y ajusta
    `desde` y `hasta` al período. La petición usa tu `identificacion` y devuelve
    la página con `comprobantes`, `pagina`, `tamanoPagina` y `hayMas`.
11. Para administrar webhooks, usa la carpeta **08**. Empieza por **08.1 Crear
    destino** o **08.2 Listar destinos**: la prueba guarda el `publicId` en
    `idDestino` para las demás peticiones. Copia el `secretoUnaVez` de la
    respuesta a tu servidor; la colección no lo guarda ni lo imprime.

Cada petición de emisión genera con un script una `Idempotency-Key` y una
`referenciaExterna` nuevas, así que repetirla emite un comprobante nuevo con el
siguiente secuencial. Para probar el reintento idempotente, reemplaza en la
petición la cabecera `Idempotency-Key` (`{{idempotencyKey}}`) y el valor de
`referenciaExterna` del cuerpo (`{{referenciaExterna}}`) por valores fijos
tuyos, y envíala dos veces el mismo día. La segunda respuesta es igual a la primera y
trae el mismo `idOperacion`. Si fijas solo la `Idempotency-Key`, el cuerpo cambia
y la segunda respuesta es un 409 con el `codEstado` 3005 (`conflicto_idempotencia`).

Las peticiones de emisión traen deshabilitada la cabecera opcional
`X-Additional-Info`, con el valor `MiERP/4.2 sucursal=001`. Actívala y cambia el
valor por el nombre y la versión de tu sistema para que soporte encuentre tus
solicitudes; la cabecera no cambia la respuesta. Sus reglas están en
[Límites](/v1/guias/limites#cabeceras).

## Qué hay en cada carpeta

La colección agrupa las peticiones en carpetas numeradas, en el orden en que
las usarías al integrar.

| Carpeta | Peticiones | Para qué |
|---|---|---|
| `00` Inicio y diagnóstico | Salud del servicio (`GET /salud`, sin API Key), contexto, cupo, estado del servicio (`GET /estado`, sin API Key) | Comprobar conexión, API Key y cupo antes de emitir. |
| `01` Emitir comprobantes | Validar factura (sin emitir), factura, liquidación, nota de crédito, nota de débito, guía de remisión, retención | Comprobar una factura antes de emitirla y luego una emisión por tipo; cada emisión guarda su `idOperacion`. |
| `02` Seguimiento de operación | Ver operación | Consultar el resultado del SRI de la última emisión. |
| `03` Listado de operaciones | Listar operaciones | Consultar los comprobantes de un contribuyente y un período, con filtros y paginación. |
| `04` Errores y casos límite | 401 sin credencial, 400 sin `Idempotency-Key`, 422 campo no soportado, 422 XML con `codDoc` incorrecto y 429 cupo agotado | Ver la forma de cada error. El caso de cupo agotado solo responde 429 si tu cupo está realmente agotado. |
| `05` Consultas SRI | Contribuyente, búsqueda por nombre, establecimientos, validar identificación, decodificar clave | Consultas al catastro del SRI; no consumen cupo. |
| `06` Descargas | Descargar RIDE (PDF), descargar XML | Obtener los archivos de un comprobante emitido. Usan `claveAccesoEmitida`. |
| `07` Perfil del emisor | Leer perfil, actualizar perfil, cambiar logo | Ver y cambiar los datos del emisor que salen en el RIDE. La actualización y el logo cambian el perfil real del ambiente donde los ejecutes. |
| `08` Webhooks | Crear destino, listar destinos, pausar, reanudar, rotar secreto, entregas, reintentar y deshabilitar | Administrar los destinos por API. Crear y rotar devuelven el secreto una sola vez; la colección no lo guarda. |
| `09` Catálogos | Listar catálogos, leer un catálogo | Consultar los catálogos del SRI con `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}`; la variable `catalogo` elige la clave y vale `tarifas-iva` por defecto. |

Las carpetas `03`, `08` y `09` no forman parte del flujo de emisión: ejecútalas cuando
necesites conciliar comprobantes, administrar destinos o leer los catálogos. La carpeta `08` crea,
pausa o deshabilita destinos reales en el ambiente donde la ejecutes.

## Usar la colección en Bruno

Si prefieres Bruno, puedes importar en él la colección de Postman. Para usarla,
sigue estos pasos:

1. En Bruno, elige **Import Collection** > **Postman Collection** y selecciona
   el archivo de la colección. Bruno te pide una carpeta para guardarla.
2. En la colección, abre **Environments** > **Create** y crea un environment
   con las variables `baseUrl` (`https://api-sandbox.mynexusapi.com`), `apiKey`
   (márcala como secreta), `identificacion`, `ruc`, `estab` y `ptoEmi`.
3. Selecciona ese environment y sigue los pasos 5 a 9 de Postman.

Bruno ejecuta los scripts de Postman más comunes. Si una prueba automática no
corre, la petición se envía igual y puedes leer la respuesta.

## Ejecutar con Newman

Si necesitas ejecutar la colección desde la terminal, por ejemplo en un proceso
de integración continua, puedes usar Newman. Pasa la API Key por variable de
entorno, para no guardarla en el archivo:

```bash
newman run Ecuafact-API-v1.postman_collection.json \
  -e Ecuafact-API.postman_environment.json \
  --env-var "apiKey=$ECUAFACT_API_KEY" \
  --env-var "identificacion=0123456789001" \
  --env-var "ruc=0123456789001"
```

Newman imprime cada petición con su estado y las pruebas que pasaron o fallaron.
Al ejecutar la carpeta `01` se emiten comprobantes de prueba y se consume cupo
del sandbox. Si ejecutas la colección completa, ten en cuenta que **07.2** y
**07.3** cambian el perfil del emisor, y que la carpeta **08** crea, pausa,
reanuda, rota el secreto o deshabilita destinos reales del ambiente. Para
dejarlas fuera, ejecuta solo las carpetas que necesitas con `--folder`.

## Siguientes pasos

- [Primeros pasos](/v1/guias/primeros-pasos): sigue el mismo flujo paso a paso, con código.
- [Datos de prueba](/v1/guias/datos-de-prueba): usa los valores de ejemplo y los casos de prueba para provocar cada respuesta.
- [SDKs](/v1/guias/sdk): pasa de la colección a código con un cliente oficial.
