Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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-Key y claveAcceso junto a cada documento.
  • Reintentas con la misma Idempotency-Key ante 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 estado de la operación es autorizado.
  • 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/contexto con la API Key de producción responde 200 y lista tus contribuyentes con puedeEmitir: true.
  • Cambiaste en tu configuración la URL base a https://api.mynexusapi.com y la API Key a la de producción.
  • Decidiste la numeración de cada estab y ptoEmi de 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#

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.