En esta página
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.
Importante
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. Desde ahí puedes hacer un fork a tu propio workspace y recibir las actualizaciones sin descargar ni importar archivos.
| Archivo | Contenido |
|---|---|
| Colección Postman | 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 | 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 | 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, Liquidación de compra 03, Nota de crédito 04, Nota de débito 05, Guía de remisión 06 y Retención 07. |
| Emisión para asistentes | Resumen corto del contrato de emisión para pegar en un asistente de IA. |
| Catálogo de servicios | Enlaces a OpenAPI, documentación y versiones (RFC 9727), para descubrimiento automático. |
| Versiones del contrato | Versión vigente, fechas y retiro, en JSON. |
| llms.txt y 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 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 o Bruno
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.
- Tu
identificacion, que es tu RUC de 13 dígitos. La ves enGET /v1/contextoo 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:
- Descarga los dos archivos, la colección y el environment.
- En Postman, pulsa Import y arrastra ambos archivos. Aparecen la colección
Ecuafact API — Comprobantes Electronicos SRI (v1)y el environmentEcuafact API — Plantilla. - 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 conapiKeyvacía, así que las peticiones autenticadas responden 401. - 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: tuidentificaciondeGET /v1/contexto, que es tu RUC de 13 dígitos.ruc: el mismo valor deidentificacion.estabyptoEmi: tu establecimiento y punto de emisión. La plantilla trae002y001; cámbialos por los de tu contribuyente. Guarda con Save.
- Ejecuta 00 > 00.2 Contexto de la credencial. Funcionó si la respuesta es
200 y lista tus contribuyentes. Un 401 con el
codEstado3009 (credenciales_invalidas) indica que falta la API Key o no es válida. Un 403 con elcodEstado3010 (ip_no_autorizada) indica que la IP no está permitida. - 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
validoentrueyerroresvacío cuando la factura es válida, o 422 con elcodEstado3002 (comprobante_invalido) y el problema enerrorescuando no lo es. Esta petición no emite nada, no consume cupo ni llevaIdempotency-Key, así que puedes repetirla las veces que necesites; lo explica Validar sin emitir. - Ejecuta 01 > 01.1 Factura. Deberías recibir
202 Acceptedconestadorecibido, uncodEstado1001 o 1002 y unidOperacion, que la prueba de la petición guarda en el environment. - Ejecuta 02 > 02.1 Ver operación varias veces, con unos segundos de
espera entre cada una, mientras
estadosearecibido. Termina enautorizado, o enrechazadocon elcodEstado3001 (rechazo_sri) si el SRI lo rechazó. Cuando quedaautorizado, la prueba de la petición guarda laclaveAccesoenclaveAccesoEmitida. - 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.
- Para conciliar lo emitido, abre 03 > 03.1 Listar operaciones y ajusta
desdeyhastaal período. La petición usa tuidentificaciony devuelve la página concomprobantes,pagina,tamanoPaginayhayMas. - Para administrar webhooks, usa la carpeta 08. Empieza por 08.1 Crear
destino o 08.2 Listar destinos: la prueba guarda el
publicIdenidDestinopara las demás peticiones. Copia elsecretoUnaVezde 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.
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:
- En Bruno, elige Import Collection > Postman Collection y selecciona el archivo de la colección. Bruno te pide una carpeta para guardarla.
- 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,estabyptoEmi. - 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:
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: sigue el mismo flujo paso a paso, con código.
- Datos de prueba: usa los valores de ejemplo y los casos de prueba para provocar cada respuesta.
- SDKs: pasa de la colección a código con un cliente oficial.