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

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 o el término que no conoces en el 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.

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.

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 o consulta GET /v1/operaciones/{idOperacion} hasta que su estado deje de ser recibido. El recorrido completo está en Ciclo de vida del comprobante.

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

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 no, porque nosotros la asignamos y ese campo no existe en la solicitud; si lo envías, la API responde 422. El 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.

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

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.

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

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.

Si no identificas la causa, pide soporte con el idOperacion y el X-Correlation-Id, como se explica en Cómo 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 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.
  • Para el XML, usa Descargar 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, que tiene marcaBlanca en true en GET /v1/contexto. Sus comprobantes se emiten y se autorizan igual que los demás, pero no tienen RIDE, así que Descargar PDF responde siempre 404 con el codEstado 3013 (no_encontrado). El XML se descarga igual.

No reintentes esas dos llamadas, porque la respuesta no va a cambiar. Descarga el XML autorizado 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.

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.

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

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.

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

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

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.

¿Cómo pido soporte?#

Abre un ticket en 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 o escribir por WhatsApp. La lista completa está en Cómo 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.

Siguientes pasos#

  • Primeros pasos: emite tu primer comprobante en pruebas.
  • Errores: todos los códigos y qué hacer ante cada uno.
  • Buenas prácticas: idempotencia y reintentos con código listo para copiar.
  • Glosario: los términos fiscales y de la API explicados.
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.