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

# 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](/v1/guias/ambientes#como-pasar-a-produccion).

> [!IMPORTANT]
> 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](/v1/guias/ambientes).

## 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](/v1/guias/glosario) 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](/v1/guias/sandbox). |
| Integración solicitada | Empresas que necesitan varios RUC o una configuración distinta. | Envía el [formulario de solicitud](https://www.ecuafact.com/) con tu RUC y tus IP de salida, como se explica en [Autenticación](/v1/guias/autenticacion#obten-tu-api-key). |

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](/v1/guias/primeros-pasos#paso-3.emite-la-factura)
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](/v1/guias/consumo) 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](/v1/guias/ciclo-de-vida#estados-y-que-hacer). |
| 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](/v1/guias/ciclo-de-vida#estados-y-que-hacer). |
| 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](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Primeros pasos](/v1/guias/primeros-pasos): el recorrido completo desde la API Key hasta el RIDE.
- [Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida): qué hacer con cada resultado fiscal.
- [Errores](/v1/guias/errores): todos los códigos y si se reintentan o se corrigen.
- [Ambientes y contribuyentes](/v1/guias/ambientes): la lista de verificación para pasar a producción.
