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

Autenticación

Cada petición a la API lleva tu API Key en la cabecera X-Api-Key. En producción, además, debe salir de una IP registrada para tu integración.

Puedes llamar a nuestra API sin iniciar sesión ni renovar tokens. Cada petición se autentica por sí sola con dos comprobaciones: que traiga una API Key válida y, en producción, que llegue desde una IP pública que registraste para tu integración. En el sandbox se acepta cualquier IP. Cada ambiente usa su propia API Key.

En esta página verás cómo enviar la API Key, cómo obtenerla, guardarla y rotarla, cómo averiguar y registrar tu IP de salida y qué significa cada error de autenticación. Al terminar tendrás una llamada a GET /v1/contexto que responde 200.

Conceptos#

  • API Key. Es la credencial de tu integración. Una sola API Key cubre todos los contribuyentes y tipos de comprobante habilitados para tu integración, y dentro de la API no existen usuarios ni permisos por persona. Más detalle en API Key.
  • IP permitida. Es la dirección IP pública desde la que tu servidor sale a Internet. En producción, la API solo acepta tu API Key si la petición llega desde una IP registrada. Las IP se registran por integración, así que valen para todas tus API Key. El sandbox no exige IP registrada.
  • Ambiente. Pruebas y producción tienen URL distintas y cada uno tiene sus propias API Key. Las diferencias están en Ambientes y contribuyentes.

Si la API Key falta, no existe, está revocada o venció, la respuesta es un 401 con el codEstado 3009 (credenciales_invalidas). En producción, si la API Key es válida pero la IP no está permitida, la respuesta es un 403 con el codEstado 3010 (ip_no_autorizada). Revisa la causa que corresponda en Errores de autenticación.

Antes de empezar#

  • Una API Key de pruebas. Si todavía no tienes una, crea un sandbox; la API Key la obtienes después, en Pruebas del Portal del Cliente.
  • La IP pública de salida de tu servidor, registrada en el Portal del Cliente como se explica en Registra tu IP. Solo se exige en producción; el sandbox acepta cualquier IP.
  • La API Key guardada en la variable de entorno ECUAFACT_API_KEY, como se explica en Guarda la API Key.

Envía la API Key#

Incluye la cabecera X-Api-Key en cada petición a /v1.

Cabecera Obligatoria Valor
X-Api-Key Sí Tu API Key completa, tal como la copiaste del portal al crearla. Tiene dos partes separadas por un punto (prefijo.secreto).

El ejemplo consulta GET /v1/contexto, que es la llamada más simple para comprobar que tu API Key y tu IP funcionan.

Importante

Ambiente de pruebas: sin validez fiscal.

curl -s "https://api-sandbox.mynexusapi.com/v1/contexto" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
using System.Net.Http;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using HttpResponseMessage respuesta = await http.GetAsync("/v1/contexto");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/contexto",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contexto');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' ' . $cuerpo . PHP_EOL;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contexto"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .GET()
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
# Una sola vez: guarda tu API Key de pruebas en el CLI (te la pide sin mostrarla).
ecuafact login --entorno sandbox

# Resultado esperado: tu integración y sus contribuyentes, en tabla.
ecuafact cuenta --entorno sandbox

Resultado esperado#

Si la API Key y la IP son correctas, recibes 200 OK con tu integración y tus contribuyentes:

{
  "idCliente": "1f2e3d4c-5b6a-4789-9012-abcdef012345",
  "nombre": "Integracion de ejemplo",
  "contribuyentes": [
    {
      "identificacion": "0123456789001",
      "puedeEmitir": true,
      "puedeRecibir": true,
      "tiposComprobante": [
        "01",
        "03",
        "04",
        "05",
        "06",
        "07"
      ],
      "marcaBlanca": false
    }
  ]
}
Campo Tipo Descripción
idCliente string (UUID) Identificador de tu integración. Inclúyelo al pedir soporte.
nombre string Nombre de tu integración.
contribuyentes array Contribuyentes habilitados para tu API Key en este ambiente. Puede venir vacío si aún no tienes ninguno habilitado.
contribuyentes[].identificacion string Identificación completa del contribuyente (para un RUC, sus 13 dígitos). Es el valor que usas en la ruta {identificacion} y en infoTributaria.ruc.
contribuyentes[].puedeEmitir boolean true si puedes emitir comprobantes para este contribuyente.
contribuyentes[].puedeRecibir boolean Indica si el contribuyente tiene habilitada la recepción.
contribuyentes[].tiposComprobante array de string Tipos de comprobante habilitados (tipoDocumento): 01, 03, 04, 05, 06, 07.
contribuyentes[].marcaBlanca boolean true si el contribuyente es de marca blanca y sus comprobantes no tienen RIDE. Más detalle en Contexto.

Sabes que funcionó cuando el estado HTTP es 200 y ves tus contribuyentes. Si recibes un 401 con el codEstado 3009 (credenciales_invalidas) o un 403 con el codEstado 3010 (ip_no_autorizada), revisa Errores de autenticación.

Obtén tu API Key#

Puedes conseguir una API Key de distintas maneras, según si quieres probar, si ya tienes acceso al portal o si vas a producción.

Situación Cómo la obtienes
Quieres probar y no tienes cuenta Crea tu cuenta en https://portal.mynexusapi.com/sandbox. Al terminar el alta, ingresa al portal y sigue la fila siguiente.
Tu cuenta está en pruebas Abre Pruebas en el Portal del Cliente y pulsa Generar en "API Key de pruebas" (si ya tienes una, pulsa Rotar). La API Key se muestra una sola vez.
Necesitas producción Desde el Portal del Cliente, en Pasar a producción, como se explica en Sandbox de pruebas. La API Key de producción se muestra una sola vez.
Ya estás en producción Entra a Cuenta > API Keys y pulsa Crear API Key. Escribe un nombre que identifique su uso, por ejemplo ERP produccion.

Al crear una clave en el portal, la API Key completa se muestra una sola vez, así que cópiala en ese momento a tu gestor de secretos. Si la pierdes, no se puede recuperar; en ese caso, crea otra y revoca la anterior.

Scopes y RUC de una API Key#

Cada API Key tiene dos límites independientes:

  • Scopes: qué acciones puede hacer.
  • RUC permitidos: sobre qué contribuyentes puede actuar.

Una API Key con * en scopes puede usar todos los servicios; una API Key con una lista solo puede usar esos servicios. Lo mismo aplica a ruc: * significa todos los RUC y una lista limita la API Key a esas identificaciones. La clave que se crea con un sandbox queda limitada a su RUC y a los scopes de integración; no puede emitir ni consultar otro contribuyente.

En el Portal del Cliente, al crear una clave en Cuenta > API Keys, eliges los servicios y los RUC, y la tabla de claves muestra el alcance de cada una. Si no limitas ninguno, la clave puede usar todos los servicios y todos los RUC. Para cambiar los permisos de una clave existente, crea una nueva y revoca la anterior.

Los scopes disponibles son:

Scope Permite
cuenta:leer Consultar el contexto y el consumo.
comprobantes:leer Consultar operaciones y comprobantes emitidos, y descargar el RIDE y el XML.
comprobantes:emitir Emitir y validar comprobantes.
sri:consultar Consultar contribuyentes, establecimientos, identificaciones y claves de acceso.
perfil:leer Ver el perfil del emisor.
perfil:escribir Actualizar el perfil del emisor y su logo.
webhooks:leer Ver destinos, entregas e intentos.
webhooks:gestionar Crear, editar, rotar secreto, pausar, reanudar y deshabilitar destinos.
webhooks:probar Enviar el evento de prueba.
webhooks:reintentar Reenviar una entrega.

Una API Key limitada a un RUC no puede ver ni administrar destinos de otro RUC ni un destino para todos los RUC. Si intentas una operación fuera de su alcance, la API responde 403 con el codEstado 3011 (acceso_denegado).

Atención

La API Key permite emitir comprobantes a nombre de tus contribuyentes. No la pegues en tickets, chats, repositorios ni capturas de pantalla.

Guarda la API Key#

Te recomendamos que tu código lea la API Key desde fuera del código fuente. Todos los ejemplos de esta documentación la leen de la variable de entorno ECUAFACT_API_KEY, y la tabla muestra cómo definirla según dónde corre tu aplicación.

Dónde Cómo
Tu equipo (desarrollo) Define la variable en la sesión: export ECUAFACT_API_KEY="..." (Linux/macOS) o $env:ECUAFACT_API_KEY="..." (PowerShell). Si usas un archivo .env, agrégalo a .gitignore.
Servidor o contenedor Define una variable de entorno del servicio (systemd, Docker, Kubernetes Secret o la configuración de la aplicación en tu proveedor de nube).
Producción Usa un gestor de secretos que inyecte el valor al iniciar la aplicación, por ejemplo Azure Key Vault, AWS Secrets Manager, Google Secret Manager o HashiCorp Vault.
.NET en desarrollo Ejecuta dotnet user-secrets set "Ecuafact:ApiKey" "..." y léela desde la configuración.

Además, te recomendamos estas tres prácticas:

  • Usa la API Key solo en tu backend. Nunca la pongas en el navegador, en una app móvil ni en una aplicación de escritorio que entregues a terceros, porque cualquiera podría extraerla.
  • No la escribas en logs. Si registras cabeceras, enmascara X-Api-Key.
  • Usa una API Key distinta por sistema, por ejemplo una para el ERP y otra para la tienda en línea. Así puedes revocar una sin detener la otra.

Rota o revoca una API Key#

Rota la API Key si se filtró, si una persona con acceso deja el equipo o cuando lo pida tu política de seguridad. La rotación no corta el servicio si sigues este orden:

  1. En el portal, entra a Cuenta > API Keys, pulsa Crear API Key y copia la nueva API Key.
  2. Actualiza el secreto en tu servidor y reinicia o recarga la aplicación.
  3. Verifica con GET /v1/contexto que la nueva API Key responde 200.
  4. En Cuenta > API Keys, abre el menú de la clave anterior y pulsa Revocar.

La revocación tarda hasta 30 segundos en aplicarse. Pasado ese tiempo, la clave revocada recibe un 401 con el codEstado 3009 (credenciales_invalidas).

Atención

Si sospechas que tu API Key se filtró, revócala de inmediato aunque tu servicio se detenga unos minutos. Quien la tenga podría emitir comprobantes con validez fiscal si también controla una IP registrada.

Registra tu IP#

En producción, puedes registrar en la lista de IP permitidas de tu integración las IP desde las que llamas a la API. Si una petición llega desde una IP que no está en la lista, la API la rechaza con un 403 y el codEstado 3010 (ip_no_autorizada), aunque la API Key sea correcta. El sandbox no exige IP registrada.

Averigua tu IP pública de salida#

La IP que importa es la que ve la API, no la de tu red interna. Las direcciones que empiezan por 192.168, 10 o 172.16 a 172.31 son privadas y nunca llegan a la API. Para conocer la IP pública, ejecuta este comando desde el mismo servidor que llamará a la API:

curl -4 https://ifconfig.me   # IP publica IPv4
curl -6 https://ifconfig.me   # IP publica IPv6 (si tu servidor tiene IPv6)
Tu caso Qué IP registrar
Servidor propio con IP fija La IP pública fija que te asignó tu proveedor de Internet.
Oficina o red con NAT La IP pública del router o firewall por el que sale el tráfico. Todos los equipos detrás del NAT comparten esa IP.
Nube (máquina virtual) Asigna una IP pública estática (IP elástica o reservada). La IP dinámica por defecto puede cambiar al reiniciar.
Nube (funciones, contenedores administrados, PaaS) Estos servicios salen por IP que cambian. Configura una salida fija (NAT gateway con IP estática o la opción de IP de salida dedicada de tu proveedor) y registra esa IP.
Tu equipo de desarrollo (casa u oficina) La IP pública de tu conexión. Suele cambiar, así que vuelve a revisarla si empiezas a recibir el codEstado 3010 (ip_no_autorizada).

Formatos admitidos#

Para registrar una IP, entra en el Portal del Cliente a Cuenta > IP permitidas y pulsa Agregar. Para borrar una IP que ya no usas, pulsa Quitar. La tabla muestra qué formatos acepta la lista.

Formato Ejemplo Admitido
IPv4 exacta 203.0.113.10 Sí
IPv6 exacta 2001:db8::10 Sí
Rango IPv4 en notación CIDR 203.0.113.0/24 Sí
Rango IPv6 en notación CIDR 2001:db8::/64 Sí, con prefijo de /32 o más largo.
Cualquier dirección (0.0.0.0/0 o ::/0) 0.0.0.0/0 No
Nombre de dominio servidor.midominio.com No

Si no registras ninguna IP, en producción solo funcionan las API Key limitadas a servicios y RUC concretos (no a todos). En cuanto registras una IP, la lista se aplica a todas tus API Key.

Usa Probar en la misma pantalla para comprobar si una IP queda cubierta por tu lista. Registra solo las IP que de verdad llaman a la API, porque cada IP o rango que agregas es un punto de entrada más para tu API Key.

Nota

Si tu servidor tiene IPv4 e IPv6, la conexión puede salir por cualquiera de las dos. Registra ambas, o fuerza IPv4 en tu cliente HTTP (por ejemplo curl -4).

La API valida la IP de la conexión que recibe, así que enviar cabeceras como X-Forwarded-For no cambia la IP que se valida.

Límite de intentos fallidos#

Para proteger tu API Key de quien intenta adivinarla, limitamos por IP de origen los intentos de autenticación fallidos, es decir, las peticiones rechazadas con un 401 y el codEstado 3009 (credenciales_invalidas) o con un 403 y el codEstado 3010 (ip_no_autorizada).

Regla Valor
Intentos fallidos permitidos 20 por minuto, por IP. En IPv6 se cuentan juntas todas las direcciones del mismo prefijo /64.
Ventana El minuto de reloj, de hh:mm:00 a hh:mm:59. El contador vuelve a cero al empezar el minuto siguiente.
Al superar el límite Toda petición desde esa IP recibe un 429 con el codEstado 5005 (limite_solicitudes) hasta que termine el minuto, sin importar qué API Key envíe, aunque sea correcta.
Cuánto esperar Los segundos que indica la cabecera Retry-After.
Reinicio El contador no se reinicia con una autenticación correcta: expira al terminar el minuto.

Un bucle que reintenta con una API Key equivocada termina bloqueando tu propia IP. Si recibes el codEstado 3009 (credenciales_invalidas) o el 3010 (ip_no_autorizada), corrige la causa antes de reintentar. El detalle de los límites está en Límite de request.

Errores de autenticación#

codEstado HTTP Cuándo ocurre Qué hacer
3009 (credenciales_invalidas) 401 Falta la cabecera X-Api-Key, está mal escrita o la API Key no existe, está revocada, venció o pertenece a otro ambiente. Revisa el nombre de la cabecera y que copiaste la API Key completa, con el punto. Si la revocaste, crea otra. Si es de otro ambiente, usa la clave que corresponde a la URL.
3010 (ip_no_autorizada) 403 En producción, la API Key es válida pero la petición llega desde una IP que no está en IP permitidas, o la API no pudo identificar la IP de origen. En sandbox no ocurre por IP. Averigua tu IP pública de salida y agrégala en Cuenta > IP permitidas. Si usas un proxy, llama directo a la URL de la API. Si persiste, abre un ticket con el valor de X-Correlation-Id.
3011 (acceso_denegado) 403 La autenticación fue correcta, pero el contribuyente de la ruta o el tipo de comprobante no están habilitados. Revisa GET /v1/contexto y usa una identificacion y un tipoDocumento que aparezcan ahí; la misma identificacion va en infoTributaria.ruc.
5005 (limite_solicitudes) 429 Superaste 20 intentos fallidos por minuto desde la misma IP, o el límite de solicitudes por minuto de tu integración. Espera los segundos que indica Retry-After y corrige la API Key o la IP antes de reintentar.

Cuándo aparece 3009#

Caso Qué revisar
No enviaste X-Api-Key La cabecera debe viajar en todas las peticiones a /v1.
La clave está mal formada Debe tener las dos partes separadas por un punto (prefijo.secreto), sin espacios ni saltos de línea. Vuelve a copiarla desde Cuenta > API Keys.
La clave fue revocada, venció o se eliminó En Cuenta > API Keys la clave aparece como Revocada o Vencida. Crea una nueva.
La clave pertenece a otro ambiente Pruebas y producción usan claves distintas. Usa la clave del ambiente de la URL.
La clave no existe Revisa que hayas copiado la clave completa y que estés usando la integración correcta.

La IP no se informa con 3009. En producción, si la clave es válida y la IP no está permitida, la respuesta es 403 con el codEstado 3010 (ip_no_autorizada). El sandbox no exige IP registrada.

Cuándo aparece 3010#

Caso Qué revisar
La IP no está en IP permitidas Averigua tu IP pública de salida y agrégala en Cuenta > IP permitidas.
La IP cambió por VPN, nube o proxy Registra la IP de salida real o fuerza una salida fija.
La API no pudo identificar la IP Llama directo a la URL de la API, sin proxies que oculten el origen.

El catálogo completo de codEstado está en Errores.

Si el problema persiste, abre un ticket en soporte.ecuafact.com. También puedes consultar el centro de ayuda o escribir por WhatsApp. Horario: lunes a viernes, 09:00-18:00 GMT-5. Primera respuesta: 1 día hábil; producción caída: 4 horas.

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.