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

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 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.

Importante

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.

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:

Prompt para agentes

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.
  • 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.

1. Tus datos

2. Código de WhatsApp

3. Correo y clave

4. RUC y certificado

5. API Key de pruebas

1. Tus datos

2. Código de WhatsApp

3. Correo y clave

4. RUC y certificado

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.
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. El emisor de pruebas puede tardar unos minutos en quedar listo para emitir.

Atención

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.
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.
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.
Identificación para las rutas Tu RUC completo, de 13 dígitos. Puedes confirmarla con 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.

Nota

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 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.

Atención

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.
- 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 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; 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.

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.