Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Datos de prueba

Datos ficticios que usan todos los ejemplos y casos para provocar cada respuesta de la API antes de pasar a producción.

Antes de pasar a producción te recomendamos comprobar que tu integración reacciona bien a cada respuesta posible: una factura autorizada, un reintento, un duplicado, un error de validación o un límite superado. Aquí tienes los datos ficticios que usan todos los ejemplos de la documentación, cómo conseguir una credencial de pruebas y, caso por caso, cómo provocar cada respuesta y qué debería hacer tu sistema con ella.

Úsala como lista de verificación: si tu integración maneja bien todos los casos de las tablas, está lista para el paso a producción.

Importante

Ambiente de pruebas: sin validez fiscal. Todo lo de esta página se ejecuta contra https://api-sandbox.mynexusapi.com. Nunca uses RUC, cédulas, certificados ni datos fiscales reales en ejemplos, capturas o tickets de soporte. El certificado del RUC sí se carga en el Portal del Cliente para firmar los comprobantes; no lo compartas fuera de ese formulario.

URL base#

Ambiente URL base de la API Portal del Cliente
Pruebas https://api-sandbox.mynexusapi.com https://portal.mynexusapi.com
Producción https://api.mynexusapi.com https://portal.mynexusapi.com

Las diferencias entre los dos ambientes y cómo pasar de uno a otro están en Ambientes y contribuyentes.

Valores de ejemplo#

Todos los ejemplos de esta documentación usan estos valores. Son ficticios, así que si creaste tu propio sandbox, reemplaza la identificación y el RUC por los tuyos; los ves en la respuesta de GET /v1/contexto.

Dato Valor Dónde se usa
Identificación del emisor 0123456789001 En la ruta /v1/contribuyentes/{identificacion}/... y en infoTributaria.ruc. Es el RUC del emisor, de 13 dígitos.
Establecimiento 001 o 002 En infoTributaria.estab.
Punto de emisión 001 En infoTributaria.ptoEmi.
Comprador con cédula Tipo 05, identificación 0123456789 En info.tipoIdentificacionComprador e info.identificacionComprador.
Comprador con RUC Tipo 04, identificación 0123456789001 En los mismos campos que el anterior.
Consumidor final Tipo 07, identificación 9999999999999 Solo en facturas de hasta 50.00.
Idempotency-Key FACTURA-2026-0001 En la cabecera de la emisión.
idOperacion 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f En GET /v1/operaciones/{idOperacion}.
Clave de acceso de ejemplo 0710202601012345678900110010010000001231234567811 En la descarga del RIDE y del XML. Tiene 49 dígitos y un dígito verificador válido, pero no corresponde a ningún comprobante real.

El secuencial en pruebas#

El secuencial es el número del comprobante dentro de su serie, que se forma con el establecimiento, el punto de emisión, el tipo de comprobante y el ambiente. Si quieres probar rápido, te recomendamos dejar que nosotros lo asignemos.

Qué envías en infoTributaria.secuencial Qué pasa
Nada (omites el campo) Asignamos el siguiente número libre de la serie.
"000000000" (solo ceros) Lo mismo que si lo omites: el número se asigna automáticamente.
Un número de 1 a 999999999, solo dígitos y máximo 9 (por ejemplo "124" o "000000124") Se usa ese número. Si ya existe un comprobante autorizado o pendiente con ese número, la API responde 409 con el codEstado 3004 (comprobante_duplicado).

Esta regla es la misma en pruebas y en producción. Tampoco envíes claveAcceso: nosotros la asignamos y la recibes en el seguimiento o en el webhook. Si la envías, la API responde 422 con el codEstado 3002 (comprobante_invalido).

Cómo obtener una credencial de pruebas#

Puedes obtenerla de dos maneras, según lo que necesites probar.

Camino Para qué sirve Cómo
Sandbox por autoservicio (recomendado) Integrar tu sistema con tu propio RUC y tu certificado. Crea tu cuenta en https://portal.mynexusapi.com/sandbox. Al terminar el alta, obtienes la API Key de pruebas en Pruebas del Portal del Cliente, donde se muestra una sola vez; el paso a paso está en Sandbox de pruebas.
Integración solicitada Empresas que necesitan varios RUC o una configuración distinta. Envía el formulario de solicitud con tu RUC y tus IP de salida, como se explica en Autenticación.

Con una integración activa, puedes crear y rotar tus API Key en el Portal del Cliente, en Cuenta > API Keys, y administrar tus IP en Cuenta > IP permitidas.

Casos de prueba#

Ejecuta estos casos antes de pasar a producción. Parte del archivo comprobante.json de Primeros pasos y cambia solo lo que indica la columna "Cómo provocarlo". Cada fila dice qué responde la API (el estado HTTP y el codEstado del cuerpo) y qué debería hacer tu sistema. Los errores traen además msgError, con la descripción del código, y errores, con el detalle.

Emisión y admisión#

Caso Cómo provocarlo Qué responde la API Qué debe hacer tu sistema
Emisión exitosa Envía comprobante.json sin cambios, con una Idempotency-Key nueva. 202 con estado en recibido, el codEstado 1001 o 1002 y un idOperacion. Guardar el idOperacion y seguir la operación; aceptar los dos códigos y tratar la claveAcceso como opcional.
Reintento idempotente Repite exactamente la misma petición, con la misma Idempotency-Key y el mismo cuerpo. Un 202 con el mismo idOperacion y el estado actual de la operación. Tratarlo como un éxito, sin crear otro registro.
Conflicto de idempotencia Repite la misma Idempotency-Key, pero cambia el cuerpo (por ejemplo detalles[0].descripcion). 409 con el codEstado 3005 (conflicto_idempotencia). No reintentar; para un comprobante nuevo, usar una clave nueva.
Conflicto de referencia Usa una Idempotency-Key nueva, deja la misma referenciaExterna y cambia el cuerpo. 409 con el codEstado 3005 (conflicto_idempotencia). Usar una referenciaExterna nueva para cada documento nuevo.
Sin Idempotency-Key Quita la cabecera Idempotency-Key. 400 con el codEstado 3003 (solicitud_invalida); errores menciona la cabecera. Corregir el cliente HTTP.
JSON mal formado Borra una coma o una llave de comprobante.json. 400 con el codEstado 3003 (solicitud_invalida). Corregir la serialización.
Campo obligatorio ausente Borra origenReferencia. 422 con el codEstado 3002 (comprobante_invalido) y, en errores, $.origenReferencia: Campo obligatorio. Corregir el dato y reenviar con la misma Idempotency-Key.
Campo con formato inválido Cambia infoTributaria.estab a "0A1". 422 con el codEstado 3002 (comprobante_invalido) y, en errores, $.infoTributaria.estab: Solo se admiten digitos. Corregir el dato.
Totales que no cuadran Cambia info.pagos[0].total a 100.00 (el importeTotal es 115.00). 422 con el codEstado 3002 (comprobante_invalido). Recalcular los totales. Un 422 consume 1 documento como intento.
Campo que no se envía Agrega "ambiente": "1" dentro de infoTributaria. 422 con el codEstado 3002 (comprobante_invalido). Quitar el campo, porque el ambiente lo define la URL.
Consumidor final sobre el tope Cambia el comprador al tipo 07 con 9999999999999, sin cambiar el importeTotal de 115.00. 422 con el codEstado 3002 (comprobante_invalido). Identificar al comprador cuando la factura supera 50.00.
RUC de otro contribuyente Cambia infoTributaria.ruc por un valor distinto de la identificación de la ruta (por ejemplo 1111111111001 o 0123456789002). 422 con el codEstado 3002 (comprobante_invalido) y, en errores, $.infoTributaria.ruc: El RUC no corresponde al contribuyente del contexto. Usar en infoTributaria.ruc la misma identificacion de la ruta.
Contribuyente no habilitado Pide el RIDE con una identificación que no es tuya: GET /v1/contribuyentes/0000000000001/comprobantes/0710202601012345678900110010010000001231234567811/ride. 403 con el codEstado 3011 (acceso_denegado). Usar la identificacion del contexto.
Duplicado Emite con un secuencial explícito que no hayas usado (por ejemplo "000000777") y espera a que se autorice. Luego envía otro comprobante con el mismo secuencial, una Idempotency-Key nueva y una referenciaExterna nueva. 409 con el codEstado 3004 (comprobante_duplicado). Omitir el secuencial o usar el siguiente número.
XML con codDoc de otro tipo Envía una factura en XML con <codDoc>04</codDoc> y Content-Type: application/xml. 422 con el codEstado 3002 (comprobante_invalido). Corregir codDoc o usar la ruta del tipo correcto.
Cuerpo demasiado grande Envía una emisión de más de 2 MiB. 413 con el codEstado 3006 (cuerpo_excedido). Reducir el comprobante.

Acceso y límites#

Caso Cómo provocarlo Qué responde la API Qué debe hacer tu sistema
API Key inválida Cambia un carácter de la API Key en X-Api-Key. 401 con el codEstado 3009 (credenciales_invalidas). No reintentar y revisar la configuración.
IP no registrada Llama desde otra red (por ejemplo, datos móviles) sin agregar esa IP. 403 con el codEstado 3010 (ip_no_autorizada). Registrar la IP en Cuenta > IP permitidas.
Límite de solicitudes Desde un sandbox, envía más de 60 consultas en un minuto (por ejemplo, GET /v1/contexto en un bucle sin espera). 429 con el codEstado 5005 (limite_solicitudes) y la cabecera Retry-After. Esperar los segundos que indica Retry-After y reducir la frecuencia.
Cupo agotado Ocurre cuando disponibles llega a 0 en GET /v1/consumo. No lo provoques gastando el cupo del sandbox. 429 con el codEstado 4004 (cupo_agotado). Ampliar el cupo como se explica en Consumo y cuotas y no reintentar en bucle.

Resultado fiscal (seguimiento y webhooks)#

Caso Cómo provocarlo Qué ves Qué debe hacer tu sistema
Autorizado Haz una emisión exitosa y síguela hasta el final. estado en autorizado con el codEstado 2001 y el webhook document.authorized. Marcar el documento como autorizado y descargar el RIDE.
Rechazo del SRI No hay un dato que garantice el rechazo en pruebas, porque depende de las validaciones del SRI. estado en rechazado con el codEstado 3001 (rechazo_sri), el mensaje del SRI en errores y el webhook document.rejected. Corregir y emitir de nuevo con un número nuevo, como se explica en Ciclo de vida.
Comprobante no emitido No se puede provocar a voluntad. El webhook document.failed, con estado en rechazado, rechazo_configuracion o error, la causa en codEstado y el detalle en errores. Actuar según el codEstado, como se explica en Ciclo de vida.
RIDE no disponible Pide /ride con una claveAcceso válida que no emitiste (por ejemplo, la clave de ejemplo de esta página). 404 con el codEstado 3013 (no_encontrado). Comprobar la clave y esperar a que el comprobante esté autorizado.
Clave de acceso inválida Pide /ride con una clave de 49 dígitos a la que le cambiaste el último dígito. 400 con el codEstado 3003 (solicitud_invalida). Usar la claveAcceso del seguimiento sin modificarla.

El catálogo completo de códigos está en Errores.

Siguientes pasos#

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.