En esta página
Ambientes y contribuyentes
Pruebas y producción comparten el mismo contrato y solo cambian la URL y la API Key; aquí ves cómo pasar a producción y qué identificación usar.
Puedes trabajar con nuestra API en dos ambientes: uno de pruebas, para desarrollar sin validez fiscal, y otro de producción, para emitir comprobantes reales. Aquí ves en qué se diferencian, qué te recomendamos comprobar antes de pasar a producción y cómo se identifica cada contribuyente en las rutas y en el cuerpo de las peticiones.
Consúltala cuando prepares tu integración para producción o cuando una petición te devuelva un 403 o un 422 por la identificación del contribuyente. Al terminar sabrás qué URL y qué API Key usar en cada ambiente, y qué valor del contexto va en cada lugar.
Conceptos#
- Ambiente. El SRI tiene dos ambientes: pruebas, donde los comprobantes no tienen validez fiscal, y producción, donde sí la tienen. Para cada uno te damos una URL de la API distinta.
- Contribuyente. Es la persona o empresa en cuyo nombre emites, y se identifica con su RUC de 13 dígitos o con la identificación con la que está registrado, de 5 a 13 dígitos. Una integración puede emitir para varios contribuyentes con la misma API Key.
- Clave de acceso. Es el número de 49 dígitos que identifica cada comprobante ante el SRI. Nosotros la asignamos por ti.
Todos los términos están en el Glosario.
Ambientes#
| Pruebas | Producción | |
|---|---|---|
| URL base del API | https://api-sandbox.mynexusapi.com |
https://api.mynexusapi.com |
| Validez fiscal | No | Sí |
Código de ambiente (ambiente en el seguimiento y dígito 24 de la clave de acceso) |
1 |
2 |
| Alta por autoservicio | Sí, con el Sandbox de pruebas. | Sí, desde Pasar a producción al cumplir las condiciones. |
| Portal del Cliente | https://portal.mynexusapi.com (alta en /sandbox; el sandbox se administra desde este portal). |
https://portal.mynexusapi.com (el mismo portal; el paso a producción se hace desde Pasar a producción). |
| API Key | Propia del ambiente de pruebas. | Propia del ambiente de producción. |
| IP de origen | Se acepta cualquier IP. | Solo las IP registradas en Cuenta > IP permitidas. Si no registraste ninguna, una API Key limitada a servicios y RUC concretos funciona desde cualquier IP. |
| Cupo | Paquete de pruebas de 3.000 documentos, sin vencimiento ni renovación automática. | Paquetes comprados, de un año desde el pago. |
| Reglas del comprobante, secuencial, idempotencia y errores | Iguales. | Iguales. |
El contrato, los campos y los códigos de error son los mismos en los dos ambientes, así que el código que funciona en pruebas funciona en producción con solo cambiar la URL base y la API Key, y registrar tu IP de salida.
Atención
Todo lo que emitas con la URL de producción se envía al SRI con validez fiscal y no se puede deshacer desde la API. Usa la URL de producción solo después de completar la lista de verificación de abajo, y guárdala en tu configuración, no en el código.
Cómo pasar a producción#
Antes de emitir el primer comprobante real, revisa que cumples cada punto de esta lista. Los primeros cinco se comprueban en pruebas; los demás, ya con la habilitación de producción.
- Ejecutaste en pruebas los casos de prueba y tu sistema reacciona bien a cada uno.
- Tu sistema guarda
idOperacion,Idempotency-KeyyclaveAccesojunto a cada documento. - Reintentas con la misma
Idempotency-Keyante timeouts y errores de red. - Recibes el resultado por webhook y verificas la firma, o haces un seguimiento con espera y un número máximo de consultas.
- Solo marcas un comprobante como válido cuando el
estadode la operación esautorizado. - Completaste Pasar a producción en el Portal del Cliente, con el RUC de cada contribuyente y las IP de salida de tus servidores de producción. La API Key de producción se muestra una sola vez al confirmar.
- Recibiste la API Key de producción y la guardaste como secreto, separada de la de pruebas.
- Las IP de salida de producción están registradas en el Portal del Cliente, en Cuenta > IP permitidas.
-
GET https://api.mynexusapi.com/v1/contextocon la API Key de producción responde 200 y lista tus contribuyentes conpuedeEmitir: true. - Cambiaste en tu configuración la URL base a
https://api.mynexusapi.comy la API Key a la de producción. - Decidiste la numeración de cada
estabyptoEmide producción: el secuencial automático o el de tu sistema.
Los secuenciales de pruebas y de producción son series independientes, así que los números que usaste en pruebas no ocupan números en producción.
Contribuyentes de tu integración#
GET /v1/contexto lista los contribuyentes para los que tu API Key puede operar
en el ambiente de la URL que llamas. Te recomendamos consultarlo al iniciar tu
sistema para saber
qué identificación usar y qué tipos de comprobante tienes habilitados; todos sus
campos están en Contexto.
| Campo | Qué es | Dónde se usa |
|---|---|---|
identificacion |
La identificación completa del contribuyente, tal como está registrada: su RUC de 13 dígitos o una identificación de 5 a 13 dígitos. | En la ruta /v1/contribuyentes/{identificacion}/... y en el cuerpo, en infoTributaria.ruc. |
puedeEmitir |
Vale true si puedes emitir para este contribuyente. |
Antes de emitir. |
puedeRecibir |
Indica si el contribuyente tiene habilitada la recepción. | Es informativo y no afecta la emisión. |
tiposComprobante |
Los códigos habilitados (01, 03, 04, 05, 06, 07). |
Antes de emitir cada tipo. |
Si un contribuyente no aparece en el contexto, no está habilitado para tu API Key en ese ambiente. Si lo necesitas, puedes solicitar su alta por el canal comercial.
Identificación en la ruta y RUC en el cuerpo#
La ruta y el cuerpo usan el mismo valor: la identificacion del contexto, que
es la identificación completa del contribuyente. Con el contribuyente de
prueba, la identificacion es 0123456789001, y la usas así:
POST /v1/contribuyentes/0123456789001/facturas
El siguiente fragmento muestra solo los campos de identificación del cuerpo; el cuerpo completo de cada comprobante está en la guía de su tipo.
{
"infoTributaria": {
"ruc": "0123456789001",
"estab": "001",
"ptoEmi": "001"
}
}
La misma identificacion va en las demás rutas del contribuyente: las
descargas del RIDE y del XML y el perfil del emisor. Si los valores no coinciden, la API responde así:
| Si envías | Respuesta | Qué hacer |
|---|---|---|
| En la ruta, una identificación que no es de ninguno de tus contribuyentes | 403 con el codEstado 3011 (acceso_denegado). |
Usa una identificacion del contexto. |
En infoTributaria.ruc, un valor distinto de la identificacion de la ruta |
422 con el codEstado 3002 (comprobante_invalido). |
Envía en infoTributaria.ruc la misma identificacion de la ruta. |
infoTributaria.ruc admite solo dígitos, de 5 a 13.
Clave de acceso#
La clave de acceso es el identificador del comprobante ante el SRI. Tiene 49
dígitos y nosotros la asignamos, por eso la solicitud de emisión no tiene un
campo claveAcceso; si lo envías, la API responde 422 con el codEstado 3002 (comprobante_invalido). La
recibes en el seguimiento (GET /v1/operaciones/{idOperacion}) y en los
webhooks, y la usas para descargar el RIDE y el XML.
La tabla desglosa la clave de ejemplo
0710202601012345678900110010010000001231234567811:
| Posición | Dígitos | Contenido | En el ejemplo |
|---|---|---|---|
| 1-8 | 8 | Fecha de emisión (ddMMyyyy) |
07102026 |
| 9-10 | 2 | Tipo de comprobante (tipoDocumento) |
01 |
| 11-23 | 13 | RUC del emisor | 0123456789001 |
| 24 | 1 | Ambiente (1 pruebas, 2 producción) |
1 |
| 25-30 | 6 | Serie: establecimiento + punto de emisión | 001001 |
| 31-39 | 9 | Secuencial | 000000123 |
| 40-47 | 8 | Código numérico | 12345678 |
| 48 | 1 | Tipo de emisión (1 normal) |
1 |
| 49 | 1 | Dígito verificador (módulo 11) | 1 |
La clave es única por ambiente: el mismo comprobante tiene claves distintas en pruebas y en producción. Si quieres revisar una clave sin emitir nada, usa Decodificar clave de acceso.
Errores de este apartado#
codEstado |
HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
3009 (credenciales_invalidas) |
401 | La API Key no es del ambiente de la URL (por ejemplo, la de pruebas contra la URL de producción). | Corrige la configuración: usa la API Key del ambiente de la URL. |
3011 (acceso_denegado) |
403 | El contribuyente de la ruta no está habilitado para tu API Key en este ambiente, o el tipo de comprobante no está habilitado. | Corrige la ruta con una identificacion del contexto de ese ambiente o solicita la habilitación. |
3002 (comprobante_invalido) |
422 | Enviaste ambiente, tipoEmision o claveAcceso, o infoTributaria.ruc es distinto de la identificacion de la ruta. |
Corrige el cuerpo: quita esos campos y envía en infoTributaria.ruc la identificacion de la ruta. |
3010 (ip_no_autorizada) |
403 | En producción, la IP no está registrada o la API no pudo identificar la IP de origen. El sandbox no exige IP registrada. | Registra tu IP de producción en el portal o llama sin proxies que oculten el origen. Si persiste, abre un ticket con el valor de X-Correlation-Id. |
El catálogo completo de codEstado está en Errores.
Siguientes pasos#
- Contexto: todos los campos de
GET /v1/contexto. - Datos de prueba: los casos que debes probar antes de producción.
- Comprobantes electrónicos: la estructura de cada tipo de comprobante.
- Buenas prácticas: reintentos, idempotencia y manejo de secretos en producción.