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

# Sandbox de pruebas

Crea tu cuenta de pruebas, agrega tu RUC y emite sin validez fiscal; cuando estés listo, pasas a producción desde el mismo portal.

Puedes crear tú mismo tu cuenta desde el Portal del Cliente, sin contratos y
sin esperar a que alguien te dé acceso. El alta de la cuenta pide solo tus
datos, tu correo y tu celular; el RUC y el certificado se agregan después,
dentro del portal. El portal puede mostrar la IP desde la que te conectas como
referencia para producción; el sandbox no la exige ni la bloquea. Al terminar
tienes tu cuenta, una API Key de pruebas y un cupo único de 3.000 documentos,
sin renovación automática: todo lo que necesitas para seguir
[Primeros pasos](/v1/guias/primeros-pasos) y emitir tu primera factura.

El alta de la cuenta tarda unos minutos; agregar el RUC y el certificado, unos
pocos más. Lo que emitas en el sandbox se firma y se envía al ambiente de
pruebas del SRI, así que se comporta como en producción, pero no tiene validez
fiscal.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. El alta está en
> `https://portal.mynexusapi.com/sandbox`. Cuando termines de probar, pasas a
> producción desde el portal, como se explica en
> [Pasar a producción](#pasar-a-produccion).

## Para agentes

Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.

Pega este prompt en un agente de programación con acceso a la terminal:

```text
Prepara este proyecto para trabajar con mi sandbox de Ecuafact y comprueba que responde. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, puedes instalarla con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/sandbox.md antes de escribir código; no inventes campos. El alta de la cuenta, la carga del RUC y la del certificado las hago yo en el Portal del Cliente; no intentes crearlas ni me pidas el certificado o su password en el chat. Reutiliza el SDK de Ecuafact del proyecto; si no usa ninguno, recomiéndame el SDK de su lenguaje o el CLI ecuafact, con una frase de motivo, y espera mi respuesta; cURL o HTTP directo solo si lo prefiero. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. El sandbox no exige IP registrada: no me pidas registrar la IP. Si la API responde 401 con codEstado 3009, revisa la clave; si aparece un 403 con codEstado 3010 en pruebas, repórtalo como anomalía en lugar de reintentar. Con la clave configurada, consulta el contexto (GET /v1/contexto) con la cabecera X-Api-Key para comprobar que el emisor de pruebas responde y consulta GET /v1/consumo para ver el cupo restante. No emitas nada en este paso y no cambies a producción: ese cambio lo hago yo desde el portal. Ejecuta las consultas e informa solo el RUC del emisor de pruebas, el cupo restante y cualquier acción que yo deba hacer.
```

## Antes de empezar

- [ ] Tus nombres y apellidos, y un correo que puedas revisar, porque ahí
      llega el enlace para crear tu clave del portal.
- [ ] Un celular de Ecuador con WhatsApp que tengas a mano. Ahí llega el
      código de 6 dígitos con el que confirmas el número, y vence en 10
      minutos.
- [ ] Una conexión a internet. En el sandbox puedes llamar desde cualquier IP;
      la lista de IP permitidas se exige al pasar a producción, como se explica
      en [IP en sandbox y producción](#ip-en-sandbox-y-produccion).
- [ ] Para emitir, el RUC de 13 dígitos del emisor con el que vas a probar y su
      certificado de firma electrónica (`.p12` o `.pfx`) con su password. No
      hacen falta para crear la cuenta: se piden al agregar el RUC, dentro del
      portal.

## Cómo funciona

El alta tiene tres pasos, que el portal llama Datos, Celular y Clave. Primero
escribes tus datos, después confirmas tu celular con un código que llega por
WhatsApp y al final creas tu clave con el enlace que te enviamos por correo. La
cuenta se crea en el momento en que creas la clave. Después agregas el RUC y el
certificado dentro del Portal del Cliente y copias tu API Key de pruebas.

```mermaid
flowchart LR
    A[1. Tus datos] --> B[2. Código de WhatsApp] --> C[3. Correo y clave]
    C --> D[4. RUC y certificado] --> E[5. API Key de pruebas]
```

### 1. Tus datos

Abre `https://portal.mynexusapi.com/sandbox`. En la pantalla "Crea tu cuenta",
completa:

| Campo | Obligatorio | Regla |
|---|---|---|
| Nombres | Sí | De 2 a 100 caracteres. Solo letras, espacios, apóstrofo, guion y punto. |
| Apellidos | Sí | De 2 a 100 caracteres. Solo letras, espacios, apóstrofo, guion y punto. |
| Correo | Sí | Un correo tuyo o de tu empresa que puedas abrir, escrito sin espacios. No se aceptan correos temporales. |
| Celular con WhatsApp | Sí | Celular de Ecuador con WhatsApp: `0991234567`, `+593 99 123 4567` o `593991234567`. Un mismo celular admite hasta 3 cuentas. |
| Términos y datos | Sí | Acepta los [Términos y Condiciones y la Política de Protección de Datos Personales](https://legal.ecuafact.com/). |
| Comunicaciones | No | Casilla opcional para recibir información sobre nuevos productos y servicios, ofertas o recomendaciones por e-mail/teléfono. |
| Verificación de seguridad | Si aparece | Resuélvela antes de continuar. |

Pulsa **Continuar**. No se pide RUC, certificado, dirección ni punto de emisión
en esta pantalla. Al enviar el formulario te enviamos un código de 6 dígitos
por WhatsApp al celular que escribiste.

### 2. Confirma tu celular

La pantalla "Ingresa el código" muestra el celular al que enviamos el mensaje.
Escribe el código de 6 dígitos y pulsa **Confirmar**. El código vence en 10
minutos y admite 5 intentos; si te equivocas, la misma pantalla te deja
corregirlo.

Si el código no llega, venció o agotaste los intentos, pulsa **Reenviar
código**. El botón se habilita 60 segundos después del último envío, y el código
nuevo reemplaza al anterior. Un mismo celular admite hasta 5 códigos en 24
horas. Cada código que pides cuenta para ese máximo, también el que sale al
enviar el formulario y el que no llegó a tu celular.

Si escribiste mal el número, usa **Cambiar número** para volver al formulario
con tus datos ya cargados. Al enviarlo de nuevo te llega otro código.

Confirmar el celular todavía no crea la cuenta. Si pasan 24 horas sin que
avances en el alta, o 48 horas desde que la empezaste, los datos del formulario
se eliminan y empiezas de nuevo.

### 3. Crea tu clave

Con el celular confirmado, la pantalla "Revisa tu correo" te avisa que enviamos
un correo a tu dirección. El correo se llama "Crea tu clave de Ecuafact" y trae
el botón **Crear mi clave**. El enlace vence en 7 días y se usa una sola vez;
puedes abrirlo desde cualquier equipo o navegador.

Si el correo no llega, revisa la carpeta de correo no deseado y, pasados 60
segundos, pulsa **Reenviar correo**; el enlace nuevo reemplaza al anterior. Un
mismo celular admite hasta 5 correos del alta en 24 horas, contando el primero.

Si escribiste mal la dirección, usa **Corregir correo** para volver al
formulario. Al enviarlo de nuevo, el enlace anterior deja de servir y confirmas
otra vez tu celular con un código nuevo, aunque el número sea el mismo.

El enlace abre la pantalla "Crea tu clave", que muestra tu correo y pide la
clave dos veces. La clave debe tener entre 8 y 128 caracteres, con letras y
números. Pulsa **Crear cuenta**. La cuenta se crea en ese momento y la pantalla
"Tu cuenta está creada" te ofrece **Ingresar**; entras al Portal del Cliente
con tu correo y la clave que acabas de crear.

Tienes 7 días desde que confirmaste tu celular para crear la clave, y reenviar
el correo no alarga ese plazo. Pasado ese tiempo, los datos del alta se
eliminan y empiezas de nuevo.

Si tu correo ya tiene una cuenta de Ecuafact, en lugar del enlace recibes el
correo "Ya tienes una cuenta de Ecuafact", con el botón **Ingresar**. Entra con
tu correo y tu clave; si no la recuerdas, usa **¿Olvidaste tu clave?** en la
pantalla de ingreso.

### 4. Agrega tu RUC y tu certificado

Entra al Portal del Cliente con tu correo y tu clave, abre **Contribuyentes** y
pulsa **Agregar RUC**. Completa:

| Campo | Obligatorio | Regla |
|---|---|---|
| RUC | Sí | Exactamente 13 dígitos. |
| Razón social | Sí | Hasta 300 caracteres. |
| Teléfono | No | Hasta 40 caracteres. |
| Nombre comercial | No | Hasta 300 caracteres. |
| Dirección | No | Hasta 400 caracteres. |
| Certificado | Sí | Archivo `.p12` o `.pfx` con clave privada. |
| Clave del certificado | Sí | La password que abre el archivo. |

El certificado debe contener la clave privada. El portal comprueba que la
password lo abre y no compara el titular del certificado con el RUC. Con ese
certificado firmaremos tus comprobantes de prueba; para pasar a producción debe
estar vigente.

El alta crea la primera serie del RUC: establecimiento `001` y punto de emisión
`001`. Envías esos dos valores en `infoTributaria.estab` e
`infoTributaria.ptoEmi` de cada comprobante; si usas otros establecimientos o
puntos de emisión, los indicas en la misma solicitud. El secuencial es por RUC,
tipo de comprobante, establecimiento, punto de emisión y ambiente: si lo omites,
la API asigna el siguiente. En **Pruebas > Emitir prueba** escribes el número
con el que quieres probar.

Al pulsar **Agregar RUC**, el portal configura el ambiente de pruebas de ese RUC y
muestra el mensaje "Espera un momento..." hasta que termina; normalmente tarda
unos segundos. Si pasa un minuto sin terminar, el mensaje se cierra y te avisa que
recibirás un correo cuando el ambiente esté listo. También recibes un correo al
agregar el RUC y otro cuando termina la configuración. La modalidad llega
preseleccionada en **Normal**.

### 5. Copia tu API Key de pruebas

La API Key de pruebas no se muestra durante el alta: la obtienes dentro del
portal. La primera vez que entras, el portal te da la bienvenida y te pregunta
si quieres generarla ahora. Si eliges **Generar mi API Key**, se abre la ventana
con la clave completa. Si eliges **Ahora no** o cierras el mensaje, no vuelve a
aparecer; abre **Pruebas** y pulsa **Generar** en la tarjeta "API Key de
pruebas".

Cuando ya tienes una clave, esa tarjeta muestra su prefijo y el botón
**Rotar**: pulsa **Rotar** y confirma para obtener una nueva. En ambos casos la
ventana muestra la API Key completa una sola vez, así que usa **Copiar** y
guárdala en la variable `ECUAFACT_API_KEY` o en tu gestor de secretos antes de
pulsar **Listo**.

Si en **Pruebas** aparece el aviso "Preparando tu ambiente de pruebas", espera
unos minutos y vuelve a abrir la página.

Para saber si todo funcionó, comprueba que `GET /v1/contexto` con tu API Key
responde 200 con tu RUC en `identificacion` y que `tiposComprobante` incluye el
tipo que vas a emitir. Esa llamada es el paso 2 de
[Primeros pasos](/v1/guias/primeros-pasos). El emisor de pruebas puede tardar
unos minutos en quedar listo para emitir.

> [!WARNING]
> La API Key de pruebas permite emitir comprobantes con tu certificado. Guárdala
> en la variable `ECUAFACT_API_KEY` o en tu gestor de secretos. No la volverás a
> ver: si la pierdes o crees que se filtró, rótala de nuevo en **Pruebas** del
> Portal del Cliente. Al rotarla, la clave anterior deja de funcionar en unos
> minutos.

## Qué recibes

Este es el resumen de lo que tienes al terminar el alta y dónde encontrar cada
dato.

| Dato | Valor o dónde llega |
|---|---|
| API Key de pruebas | En **Pruebas** del Portal del Cliente, con **Generar** la primera vez y **Rotar** después. Se muestra una sola vez, como se explica en [Copia tu API Key de pruebas](#api-key-de-pruebas). |
| URL de la API de pruebas | `https://api-sandbox.mynexusapi.com` |
| Portal del Cliente | `https://portal.mynexusapi.com`, con tu correo y la clave que creaste. La sección **Pruebas** muestra tu cupo, tus comprobantes de prueba y tus bots MCP de pruebas. |
| Paquete de pruebas | 3.000 documentos en total, sin vencimiento ni renovación automática. Lo que te queda lo consultas en [Consumo y cuotas](/v1/guias/consumo). |
| Correos de los comprobantes | Se envían solo al correo del titular de tu cuenta, sea cual sea el comprador. |
| Límite de solicitudes | 60 por minuto para toda la integración. Cada respuesta trae las cabeceras `X-RateLimit-Limit` y `X-RateLimit-Remaining`; el detalle está en [Límite de request](/v1/guias/limite-de-request). |
| Identificación para las rutas | Tu RUC completo, de 13 dígitos. Puedes confirmarla con [Contexto](/v1/guias/consulta-contexto). |

## IP en sandbox y producción

En el sandbox, la API acepta la API Key desde cualquier IP. No tienes que
registrar la IP de tu equipo, de tu VPN ni la de tu servidor de pruebas. Si la
API Key es incorrecta, la respuesta es un 401 con el `codEstado` 3009
(`credenciales_invalidas`).

La lista de IP permitidas se aplica en producción. Cuando pases a producción,
registra la IP pública de salida de tu servidor antes de llamar a la API. Si
llamas desde otra IP, la respuesta es un 403 con el `codEstado` 3010
(`ip_no_autorizada`).

### Si tu IP cambia en producción

Tu IP pública cambia, por ejemplo, cuando trabajas desde casa en lugar de la
oficina, cuando usas una VPN o cambias de proveedor de internet, y cuando
despliegas tu código en un servidor o en la nube. Para seguir llamando a la API
desde la red nueva:

1. Entra al Portal del Cliente (`https://portal.mynexusapi.com`) con tu correo
   y tu clave.
2. Abre **Cuenta > IP permitidas**. Arriba, junto a "Este navegador:", ves la IP
   desde la que estás conectado al portal.
3. Pulsa **Agregar** y escribe la IP nueva (por ejemplo 190.10.20.30) o un rango
   en notación CIDR (por ejemplo 190.10.20.0/24).
4. Si quieres comprobar si una IP o un rango ya queda permitido, pulsa
   **Probar**.
5. Quita con **Quitar** las IP que ya no uses.

Ten en cuenta que la IP que muestra el portal es la de tu navegador. Si tu
código corre en otro equipo o en un servidor, registra la IP de salida de ese
equipo. Los cambios pueden tardar hasta un minuto en aplicarse; sabrás que
funcionó cuando `GET /v1/contexto` desde la red nueva responda 200 en lugar de
403.

> [!NOTE]
> Si quitas todas las IP de producción, la API rechaza todas las peticiones con
> un 403. Agrega siempre la IP nueva antes de quitar la anterior.

## Vencimiento

El paquete de pruebas no tiene fecha de vencimiento: recibes 3.000 documentos
una sola vez. El saldo no se repone al cambiar de mes ni al repetir el alta.
Si necesitas más documentos, abre un ticket en
[soporte.ecuafact.com](https://soporte.ecuafact.com/) y nuestro equipo de
soporte amplía tu cupo de pruebas. No puedes aumentarlo por tu cuenta.

## El ambiente lo define la URL

El ambiente lo define la URL. Si envías `ambiente` en la raíz o en
`infoTributaria`, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`).

## Pasar a producción

Cuando estés listo para emitir con validez fiscal, entra al Portal del Cliente
y abre **Pasar a producción**. Antes de llamar a la API de producción, registra
la IP de salida de tu servidor en **Cuenta > IP permitidas**. El botón se
habilita cuando se cumplen las tres condiciones:

| Condición | Cómo la cumples |
|---|---|
| Correo verificado | Ya la cumples al crear tu clave con el enlace del correo. |
| Firma electrónica vigente | El certificado que cargaste al agregar el RUC debe seguir vigente. |
| Al menos 5 comprobantes de prueba aceptados | Emítelos con tu API Key de pruebas; la sección **Pruebas** muestra cuántos llevas. |

Al confirmar, tu cuenta de producción incluye **20 documentos** con vigencia de
un año. No necesitas comprar un paquete para pasar; cuando uses
esos 20, compra el paquete que necesites en **Consumo**.

La pantalla muestra tu **API Key de producción una sola vez**:
cópiala y guárdala antes de cerrar. Llamas a la API de producción en
`https://api.mynexusapi.com`, con las mismas IP permitidas.

> [!WARNING]
> El paso a producción no se puede deshacer. El ambiente de pruebas sigue
> funcionando: tu API Key de pruebas, tus bots de pruebas y el portal de pruebas
> siguen activos con el saldo que te quede del paquete de pruebas.

## Estados de este flujo

Los problemas del alta y de la carga del RUC aparecen junto al campo
correspondiente; los de la API llegan con un `codEstado` en el cuerpo del error.
Esta tabla reúne los dos.

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | Formulario | Falta el correo o el celular, o no tienen el formato esperado. | Corrige el dato en la pantalla "Crea tu cuenta". |
| - | Formulario | Aparece "Escribe tus nombres solo con letras (de 2 a 100 caracteres)." o "Escribe tus apellidos solo con letras (de 2 a 100 caracteres)." | Escribe el dato solo con letras, espacios, apóstrofo, guion o punto, sin números ni otros signos. |
| - | Formulario | Aparece "No pudimos validar la verificación de seguridad. Inténtalo de nuevo." | Resuelve la verificación de nuevo y pulsa **Continuar**. |
| - | Formulario | Aparece "Ese celular ya tiene el máximo de cuentas. Usa otro número o escribe a soporte." porque el celular ya tiene 3 cuentas. | Usa otro celular o abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/). |
| - | Formulario o pantalla | Aparece "Ya enviamos el máximo de códigos por hoy. Inténtalo mañana o escribe a soporte." | Espera 24 horas para pedir otro código o abre un ticket de soporte. |
| - | Pantalla | Aparece "Ya enviamos el máximo de correos por hoy. Inténtalo mañana o escribe a soporte." | Busca en tu buzón el último correo "Crea tu clave de Ecuafact", que sigue sirviendo. Si no lo tienes, espera 24 horas o abre un ticket de soporte. |
| - | Pantalla | Aparece "Espera 60 segundos para enviarlo de nuevo.", con los segundos que faltan. | Espera ese tiempo y pulsa de nuevo **Reenviar código** o **Reenviar correo**. |
| - | Pantalla | Aparece "El código no coincide. Revisa el mensaje de WhatsApp." | Escribe de nuevo el código del último mensaje que recibiste. |
| - | Pantalla | Aparece "Demasiados intentos con este código. Reenvía uno nuevo." o "El código venció. Reenvía uno nuevo." | Pulsa **Reenviar código** y usa el código nuevo. |
| - | Pantalla | Aparece "No pudimos enviar el código por WhatsApp. Reenvíalo en un momento." o "No pudimos enviar el correo. Reenvíalo en un momento." | Espera 60 segundos y pulsa **Reenviar código** o **Reenviar correo**. |
| - | Pantalla | Al crear la clave, el portal indica que no cumple la regla o que las dos claves no coinciden. | Escribe una clave de entre 8 y 128 caracteres, con letras y números, y repítela igual. El enlace sigue sirviendo. |
| - | Pantalla | Aparece "Enlace usado o vencido" porque el enlace ya se usó, venció o pediste uno más reciente. | Si ya creaste tu clave, pulsa **Ingresar**; si no la recuerdas, usa **¿Olvidaste tu clave?** en la pantalla de ingreso. Si no, pulsa **Volver al registro** para recibir un enlace nuevo. |
| - | Correo | Recibes "Ya tienes una cuenta de Ecuafact" en lugar del enlace para crear la clave. | Ingresa con tu correo y tu clave, o recupérala con **¿Olvidaste tu clave?**. |
| - | Formulario | Al agregar el RUC aparece "El RUC debe tener 13 dígitos", falta la razón social o el certificado no se puede abrir. | Corrige el dato o el archivo en **Contribuyentes > Agregar RUC**. |
| 3009 (`credenciales_invalidas`) | 401 | Llamas a la API con una API Key ausente o incorrecta. | Revisa `ECUAFACT_API_KEY` y que hayas copiado la clave completa. |
| 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está en **IP permitidas**, o la API no pudo identificar la IP de origen. En sandbox no ocurre por IP. | Revisa tu IP como se explica en [Si tu IP cambia en producción](#si-tu-ip-cambia). Si usas un proxy, llama directamente. Si persiste, abre un ticket con el valor de la cabecera `X-Correlation-Id`. |
| 3011 (`acceso_denegado`) | 403 | Llamas con una identificación que no es la de tu sandbox, o con un tipo de comprobante que no está habilitado. | Usa la `identificacion` que devuelve `GET /v1/contexto`. |
| 4004 (`cupo_agotado`) | 429 | Usaste los 3.000 documentos del paquete de pruebas. | Abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/); nuestro equipo de soporte amplía tu cupo. Volver a hacer el alta con el mismo RUC no repone los documentos usados. |

El catálogo completo de códigos de la API está en [Errores](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Primeros pasos](/v1/guias/primeros-pasos): emite tu primera factura con la API Key que acabas de copiar.
- [Datos de prueba](/v1/guias/datos-de-prueba): los casos que conviene probar antes de pasar a producción.
- [Autenticación](/v1/guias/autenticacion): cómo viaja la API Key en cada petición y cómo se valida la IP.
- [Ambientes y contribuyentes](/v1/guias/ambientes): qué cambia al pasar de pruebas a producción.
