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

# Preguntas frecuentes

Respuestas a las dudas más comunes al integrar la API, desde un 401 inesperado hasta el paso a producción.

Aquí respondemos las preguntas que más se repiten durante una integración: por
qué una API Key correcta responde 401, si un 202 significa que el comprobante
está autorizado, cómo continuar la numeración de otro sistema o qué hacer cuando
el SRI rechaza un comprobante. Cada respuesta es breve y enlaza a la guía donde
está el detalle.

Si tu duda no aparece aquí, puedes buscar el código que recibiste en
[Errores](/v1/guias/errores) o el término que no conoces en el
[Glosario](/v1/guias/glosario).

## Acceso

### ¿Por qué mi API Key responde 401 o 403 si la copié bien?

En producción, la API también valida la IP de origen; el sandbox acepta cualquier
IP. Si la API Key es correcta pero tu
servidor sale a Internet por una IP que no está en **Cuenta > IP permitidas**,
la respuesta es un 403 con el `codEstado` 3010 (`ip_no_autorizada`). Si la API
Key está ausente, es inválida o fue revocada, la respuesta es un 401 con el
`codEstado` 3009 (`credenciales_invalidas`).

Revisa estos puntos en orden:

1. Comprueba que la cabecera se llame exactamente `X-Api-Key` y que el valor sea
   la API Key completa, con el punto en medio.
2. Comprueba en el Portal del Cliente, en **Cuenta > API Keys**, que la API Key no
   esté revocada.
3. Comprueba que la IP pública de tu servidor esté registrada. Para averiguarla,
   ejecuta `curl -4 https://ifconfig.me` desde ese mismo servidor.
4. Si tu servidor tiene IPv6, ten en cuenta que la conexión puede salir por
   IPv6; registra también esa IP o fuerza IPv4.

El detalle está en [Autenticación](/v1/guias/autenticacion#registra-tu-ip).

### Mi IP cambia (nube, oficina, casa). ¿Qué hago?

La API solo acepta IP exactas, IPv4 o IPv6, o rangos IPv4 en notación CIDR como
203.0.113.0/24. Si tu IP cambia, la solución depende de dónde corre tu código:

- En la nube, asigna una IP pública estática a la máquina o configura una salida
  fija (un NAT gateway) y registra esa IP.
- En una oficina con varias IP de un mismo proveedor, registra el rango CIDR que
  te asignó el proveedor.
- En desarrollo desde casa, vuelve a registrar tu IP cuando cambie.

No registres rangos amplios "por si acaso", porque cada IP permitida es un punto
de entrada más para tu API Key.

### ¿Puedo llamar a la API desde el navegador o desde una app móvil?

No. La API Key daría acceso a emitir comprobantes a cualquiera que abra las
herramientas del navegador o descompile la app. Además, la API no habilita CORS,
así que el navegador bloquea la respuesta, y solo acepta las IP registradas,
mientras que cada usuario final tiene la suya. Llama a la API desde tu backend y
haz que tu frontend hable con tu backend.

### Recibo 429 aunque hago pocas peticiones. ¿Por qué?

Un 429 puede tener dos causas distintas, y el `codEstado` del cuerpo te dice
cuál es:

| `codEstado` | Causa | Qué hacer |
|---|---|---|
| 5005 (`limite_solicitudes`) | Tu IP acumuló 20 autenticaciones fallidas en el minuto, por ejemplo por un proceso que reintenta con una API Key equivocada, o superaste las solicitudes por minuto de tu integración. | Corrige la API Key o la IP y espera los segundos que indica `Retry-After`. |
| 4004 (`cupo_agotado`) | Se agotó tu cupo de documentos. | Amplía tu cupo, porque esperar no lo repone. |

El detalle está en [Límite de request](/v1/guias/limite-de-request).

## Emisión

### La emisión respondió 202: ¿el comprobante ya está autorizado?

No. `202 Accepted` significa que **recibimos** el comprobante, y la
autorización del SRI llega después. Espera el [webhook](/v1/guias/webhooks) o
consulta `GET /v1/operaciones/{idOperacion}` hasta que su `estado` deje de ser
`recibido`. El recorrido completo está en
[Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida).

### ¿Qué responde la API si reenvío la misma emisión?

Responde con la misma operación: un 202 con `estado` en `recibido` y el
mismo `idOperacion`, sin crear otro comprobante. Eso ocurre cuando repites la
misma `Idempotency-Key` con el mismo cuerpo, o la misma `referenciaExterna` con
el mismo cuerpo. El resultado actual de esa operación lo ves en el
[seguimiento](/v1/guias/consulta-operacion).

Si esa operación terminó en `cancelado`, el reenvío te devuelve la misma
operación y **no** emite. Para emitir, envía una `Idempotency-Key` y una
`referenciaExterna` nuevas.

### ¿Tengo que enviar la clave de acceso o el secuencial?

La [clave de acceso](/v1/guias/glosario#clave-de-acceso) no, porque nosotros la
asignamos y ese campo no existe en la solicitud; si lo envías, la API responde
422. El [secuencial](/v1/guias/glosario#secuencial) es opcional: si lo omites o
lo envías en ceros, asignamos el siguiente de la serie, y si envías un número,
se usa ese. La clave de acceso la recibes en el seguimiento o en el
webhook, y el número asignado lo ves en sus dígitos 31 a 39 o en
`numeroDocumento` del seguimiento.

### Ya facturaba con otro sistema. ¿Cómo continúo la numeración?

Envía el primer comprobante de cada serie (establecimiento, punto de emisión y
tipo) con el siguiente secuencial de tu sistema anterior, por ejemplo `"1251"`
si el último fue el 1250. Desde ahí puedes omitir el secuencial, porque
continuamos desde el mayor número registrado en esa serie.

### Mi servidor se cayó justo después de enviar. ¿Se emitió o no?

No lo sabes hasta preguntar, y para eso existe la `Idempotency-Key`. Reenvía el
**mismo cuerpo** con la **misma** `Idempotency-Key`:

- Si la primera petición llegó, recibes un 202 con el `idOperacion` original,
  y no se duplica nada.
- Si no llegó, recibes un 202 con un `idOperacion` nuevo, que es la emisión que
  no se había hecho.

Para que esto funcione, guarda la `Idempotency-Key` y la `referenciaExterna` en
tu base de datos **antes** de enviar. La clave se recuerda 7 días; el detalle
está en [Buenas prácticas](/v1/guias/buenas-practicas#idempotencia).

### ¿Por qué recibo 409?

Un 409 indica un conflicto con algo que ya existe, y el `codEstado` te dice
cuál:

| `codEstado` | Causa | Qué hacer |
|---|---|---|
| 3004 (`comprobante_duplicado`) | Ya existe un comprobante con ese número (`estab` + `ptoEmi` + `secuencial`) en proceso, autorizado o rechazado por el SRI. | No lo reenvíes. Si querías otro comprobante, usa otro secuencial u omítelo. |
| 3005 (`conflicto_idempotencia`) | Reutilizaste una `Idempotency-Key`, o una `referenciaExterna`, con un cuerpo distinto, o la `referenciaExterna` ya pertenece a otro comprobante. | Si es un reintento, envía el cuerpo original sin cambios. Si es otra emisión, usa una clave y una referencia nuevas. |

El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado).

### Recibo 422. ¿Cómo sé qué campo está mal?

Lee el arreglo `errores` del cuerpo: en un 422 de comprobante trae hasta 20
problemas, cada uno con la ruta del campo cuando aplica, por ejemplo
`$.infoTributaria.ruc: Campo obligatorio.` Corrige todos los que puedas y vuelve
a enviar; los que no se hayan podido validar aparecerán en la siguiente
respuesta. Un 422 de validación consume 1 documento como intento, pero no usa un número
de la serie, así que puedes corregir y reenviar con la misma `Idempotency-Key`. Las reglas de cada comprobante están en
[Comprobantes electrónicos](/v1/guias/emision).

### ¿Puedo enviar el comprobante en XML?

Sí. Puedes enviar el XML del SRI con `Content-Type: application/xml` o
`text/xml` en los seis endpoints de emisión y en sus validaciones. La API aplica
las mismas reglas que al JSON y la firma que traiga el XML se ignora. También puedes seguir enviando JSON. El detalle está en
[Cuerpo JSON o XML](/v1/guias/emision#cuerpo-json-o-xml).

## Después de emitir

### ¿Cuánto tarda la autorización del SRI?

No hay un tiempo garantizado, porque depende del SRI. Nosotros obtenemos el
resultado por ti y te avisamos por webhook cuando lo tenemos. Mientras tanto, la
operación se mantiene con `estado` en `recibido`, que no es un resultado final.

Si la operación termina en `error` con el `codEstado` 5007 (`resultado_no_confirmado`), no
pudimos confirmar si el comprobante llegó a crearse; escribe a soporte con el
`idOperacion`. Mientras la operación esté en `recibido`, y también en ese caso,
no reenvíes el comprobante con otra `Idempotency-Key`, porque podrías
duplicarlo; con el secuencial automático, además, recibiría un número nuevo.

### ¿Qué hago si el SRI rechaza mi comprobante?

Sabes que el SRI lo rechazó porque la operación tiene `estado` en `rechazado` y
`codEstado` en 3001 (`rechazo_sri`), o porque recibes el evento
`document.rejected`. El campo `errores` trae el mensaje del SRI. El comprobante rechazado no tiene validez
fiscal, así que corrígelo con estos pasos:

1. Revisa los datos del comprobante contra la guía de su tipo: los totales, los
   impuestos, la identificación del receptor y el documento de sustento.
2. Corrige el cuerpo.
3. Envíalo como un comprobante nuevo, con un secuencial **nuevo** (u omítelo
   para que asignemos el siguiente) y con una `Idempotency-Key` y una
   `referenciaExterna` **nuevas**. Si reutilizas el número rechazado por el
   SRI, la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`).

Si en cambio el comprobante no llegó a emitirse, porque la operación terminó
en `rechazado` con 3002 (`comprobante_invalido`), en `rechazo_configuracion` o
en `error` con 5006 (`entrega_no_posible`), corrige la causa que indican
`codEstado` y `errores` y reenvíalo con el **mismo** número. Para eso, envía el mismo
`estab`, `ptoEmi` y `secuencial`, con una `Idempotency-Key` y una
`referenciaExterna` nuevas. La API reutiliza la misma operación, responde 202
con el mismo `idOperacion` y no descuenta otro documento. Confirma después el
resultado con el seguimiento, como se explica en
[Webhooks](/v1/guias/webhooks#que-hacer-ante-cada-evento).

Si no identificas la causa, pide soporte con el `idOperacion` y el
`X-Correlation-Id`, como se explica en
[Cómo pedir soporte](/v1/guias/errores#como-pedir-soporte).

### ¿Puedo anular una factura autorizada?

La API no tiene una operación de anulación. Para revertir total o parcialmente
una factura autorizada, emite una [nota de crédito](/v1/guias/emision-04) que la
referencie. La anulación formal de un comprobante ante el SRI se gestiona fuera
de la API, con los procedimientos del SRI.

### ¿Cómo obtengo el PDF (RIDE) y el XML?

Cuando el comprobante esté autorizado, usa su `claveAcceso` con estas guías:

- Para el RIDE, el PDF del comprobante, usa [Descargar PDF](/v1/guias/consulta-ride).
- Para el XML, usa [Descargar XML](/v1/guias/consulta-xml). Mientras falta la
  autorización o el archivo, recibes HTTP `404`, `codEstado` 3013 (`no_encontrado`); reintenta la descarga.
- El envío por correo lo haces desde tu sistema, con el RIDE o el XML descargado.

### ¿Por qué el RIDE responde 404 si el comprobante está autorizado?

Es lo que ocurre con un contribuyente de
[marca blanca](/v1/guias/glosario#marca-blanca), que tiene `marcaBlanca` en
`true` en [`GET /v1/contexto`](/v1/guias/consulta-contexto). Sus comprobantes se
emiten y se autorizan igual que los demás, pero no tienen RIDE, así que
[Descargar PDF](/v1/guias/consulta-ride) responde siempre 404 con el `codEstado`
3013 (`no_encontrado`). El [XML](/v1/guias/consulta-xml) se descarga igual.

No reintentes esas dos llamadas, porque la respuesta no va a cambiar. Descarga el
[XML autorizado](/v1/guias/consulta-xml) y entrégalo a tu cliente desde tu
sistema; si necesitas una representación impresa, genérala a partir de ese XML.
Revisa `marcaBlanca` antes de pedir el RIDE o el correo para evitar las dos
llamadas.

### ¿Un comprobante rechazado consume cupo?

Sí. Cada comprobante que el SRI autoriza o rechaza consume un documento de tu
cupo, y uno cancelado no consume. Las solicitudes que rechaza la propia API
(400, 403, 409 o 429) no consumen nada, un 422 de validación consume 1 documento
como intento, y reenviar corregido el mismo
número de un comprobante que no llegó a emitirse no descuenta un documento
adicional. El detalle está en
[Consumo y cuotas](/v1/guias/consumo).

## Webhooks

### ¿Cómo pruebo los webhooks en mi computadora?

La URL del webhook debe usar `https://`, estar en el puerto 443 y resolver a una
IP pública, así que `localhost` y las IP privadas se rechazan. Para recibir los
webhooks en tu computadora, sigue estos pasos:

1. Levanta tu receptor local, por ejemplo en `http://localhost:3000/webhooks/ecuafact`.
2. Exponlo con un túnel HTTPS público, por ejemplo con `ngrok http 3000` o
   `cloudflared tunnel --url http://localhost:3000`.
3. Registra la URL pública del túnel (por ejemplo
   `https://abc123.ngrok-free.app/webhooks/ecuafact`) en el Portal del Cliente,
   en **Integración > Eventos**, y guarda el secreto.
4. Pulsa **Probar**. Te enviamos un evento de prueba firmado, con
   `eventType` en `operation.requires_attention` y `probe` en `true`. Verifica la
   firma y responde con un 2xx.
5. Emite un comprobante en pruebas y espera `document.authorized` o
   `document.rejected`.

La URL de un destino no se edita, así que cada vez que el túnel cambie de URL,
crea un **Nuevo destino** con la URL nueva y deshabilita el anterior. Tu
receptor debe responder en menos de 15 segundos. Si quieres probar la
verificación de la firma sin túnel, usa la prueba local de entrega firmada de
[Webhooks](/v1/guias/webhooks).

### ¿Cómo verifico que un webhook lo enviamos nosotros?

Con la firma de la cabecera `Ecuafact-Signature: t=<epoch>,v1=<firma>`. Calcula
el HMAC-SHA256 de `t + "." + cuerpo crudo` con tu secreto y compáralo con `v1`,
usando el cuerpo tal como llegó, sin volver a serializarlo. El procedimiento
completo está en [Verificación de firma](/v1/guias/webhooks-firma).

## Pruebas y producción

### ¿Los comprobantes de pruebas tienen validez fiscal?

No. Todo lo que emites en `https://api-sandbox.mynexusapi.com` va al ambiente de
pruebas del SRI y no tiene validez fiscal. Usa solo los
[Datos de prueba](/v1/guias/datos-de-prueba).

### ¿Necesito un certificado digital?

Sí. El SRI exige que cada comprobante vaya firmado con el certificado digital
del emisor, un archivo `.p12` o `.pfx`. Al crear el [sandbox](/v1/guias/sandbox)
cargas el certificado y su contraseña, y desde ahí firmamos por ti, así
que tu código nunca maneja el certificado.

### ¿Cómo paso a producción?

El paso a producción tiene cinco pasos:

1. Completa en pruebas tu flujo de emisión, reintentos, webhook y descarga del
   RIDE, con la lista de [Buenas prácticas](/v1/guias/buenas-practicas#checklist-antes-de-produccion).
2. Entra al Portal del Cliente y usa **Pasar a producción** cuando se cumplan
   las condiciones (correo verificado, firma vigente y 5 comprobantes
   aceptados). Al confirmar, tu cuenta recibe 20 documentos de producción por
   un año.
3. Guarda la API Key de producción en tu gestor de secretos y registra las IP de
   salida de tu servidor de producción.
4. Cambia la URL base a `https://api.mynexusapi.com`.
5. Verifica con `GET /v1/contexto` que ves tus contribuyentes y emite un primer
   comprobante real.

La lista de verificación completa está en
[Ambientes y contribuyentes](/v1/guias/ambientes).

### ¿Qué pasa cuando vence mi sandbox?

El sandbox no vence: recibes 3.000 documentos una sola vez, sin renovación
automática. El saldo no se repone al cambiar de mes ni al repetir el alta; si
necesitas más, abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/)
y un administrador agrega la ampliación. Para emitir con validez fiscal,
completa **Pasar a producción** en el portal. El detalle está en
[Sandbox de pruebas](/v1/guias/sandbox#vencimiento).

## Otros

### ¿Hay SDK oficiales?

Sí, puedes integrarte con nuestros SDK oficiales para .NET, Node.js, Python,
Java y PHP. Manejan por ti la API Key y la
`Idempotency-Key`, y reintentan con la misma clave los cortes de red y los
estados 408, 425, 500, 502, 503 y 504, hasta 3 intentos y respetando
`Retry-After`. El SDK reintenta por defecto el 429 con el `codEstado` 5005
(`limite_solicitudes`); el 429 con el `codEstado` 4004 (`cupo_agotado`) no se
reintenta nunca.
El detalle está en [SDKs](/v1/guias/sdk).

### ¿Cómo pido soporte?

Abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/) con el `X-Correlation-Id` de la respuesta, la URL, el estado HTTP, el `codEstado`
y el cuerpo que enviaste, sin la API Key. También puedes consultar el [centro de ayuda](https://ecuafact.com/ayuda/) o escribir por [WhatsApp](https://wa.me/593988315544). La lista completa está en
[Cómo pedir soporte](/v1/guias/errores#como-pedir-soporte).

### ¿Cómo encuentra soporte mi solicitud?

La encontramos por el `X-Correlation-Id` que devuelve cada respuesta. Si no lo
guardaste, podemos buscarla por el texto que enviaste en la cabecera opcional
`X-Additional-Info` (por ejemplo `MiERP/4.2 sucursal=norte lote=42`). Te recomendamos enviar las dos cabeceras desde el inicio, sin datos personales ni secretos, como se explica en
[Identifica tus solicitudes](/v1/guias/buenas-practicas#identifica-tus-solicitudes).

## Siguientes pasos

- [Primeros pasos](/v1/guias/primeros-pasos): emite tu primer comprobante en pruebas.
- [Errores](/v1/guias/errores): todos los códigos y qué hacer ante cada uno.
- [Buenas prácticas](/v1/guias/buenas-practicas): idempotencia y reintentos con código listo para copiar.
- [Glosario](/v1/guias/glosario): los términos fiscales y de la API explicados.
