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#
- Primeros pasos: el recorrido completo desde la API Key hasta el RIDE.
- Ciclo de vida del comprobante: qué hacer con cada resultado fiscal.
- Errores: todos los códigos y si se reintentan o se corrigen.
- Ambientes y contribuyentes: la lista de verificación para pasar a producción.