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

# 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](/v1/guias/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](/v1/guias/sandbox). | 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.

> [!WARNING]
> 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](/v1/guias/datos-de-prueba#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](/v1/guias/webhooks) y verificas la
      [firma](/v1/guias/webhooks-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](/v1/guias/consulta-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.

```json
{
  "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](/v1/guias/consulta-clave-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](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Contexto](/v1/guias/consulta-contexto): todos los campos de `GET /v1/contexto`.
- [Datos de prueba](/v1/guias/datos-de-prueba): los casos que debes probar antes de producción.
- [Comprobantes electrónicos](/v1/guias/emision): la estructura de cada tipo de comprobante.
- [Buenas prácticas](/v1/guias/buenas-practicas): reintentos, idempotencia y manejo de secretos en producción.
