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:
- En el portal, entra a Cuenta > API Keys, pulsa Crear API Key y copia la nueva API Key.
- Actualiza el secreto en tu servidor y reinicia o recarga la aplicación.
- Verifica con
GET /v1/contextoque la nueva API Key responde 200. - 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#
- Ambientes y contribuyentes: elige la URL correcta y la
identificacionque usarás en las rutas. - Primeros pasos: emite tu primer comprobante en pruebas.
- Límite de request: cuántas solicitudes por minuto puedes hacer y cómo leer
Retry-After. - Errores: todos los códigos y qué hacer ante cada uno.