Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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 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.
  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.

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:

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.
No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.