En esta página
Contexto GET
Devuelve tu integración y los contribuyentes que puedes operar con tu API Key, junto con la identificación que usas en las rutas.
Este endpoint te dice con quién puedes trabajar. Responde con el nombre de tu integración y la lista de contribuyentes habilitados para tu API Key en el ambiente al que llamas, y para cada uno indica qué tipos de comprobante puede emitir y qué identificación debes usar en las demás rutas de la API.
Te recomendamos hacerla como primera llamada de tu integración. Además de darte los datos que necesitas para emitir y consultar, te confirma que tu API Key funciona (y, en producción, que tu IP de salida está registrada), así que también puedes usarla como prueba de conexión cada vez que cambias de servidor o de credencial.
GET /v1/contexto
X-Api-Key: <tu API Key>
Cuándo usarlo#
Llámalo antes de emitir o consultar, porque el valor identificacion de cada
contribuyente es el que va en las rutas /v1/contribuyentes/{identificacion}/....
Antes de empezar#
- Una API Key de pruebas guardada en la variable de entorno
ECUAFACT_API_KEY. Si todavía no tienes una, crea un sandbox; cómo viaja la API Key se explica en Autenticación. - Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo registrarla, sigue Registra tu IP.
Parámetros#
Este endpoint no tiene parámetros de ruta ni de consulta; solo usa cabeceras.
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
X-Api-Key (cabecera) |
string | Sí | Tu API Key. Ve Autenticación. |
X-Api-Version (cabecera) |
string | No | Versión del contrato. Si no la envías, se usa la vigente. Ve Versionado. |
Ejemplo#
Importante
Ambiente de pruebas: sin validez fiscal.
Todos los ejemplos imprimen el estado HTTP y el cuerpo de la respuesta.
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 contexto.mjs y ejecuta: node contexto.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());
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;
using var client = EcuafactClient.Create(new EcuafactClientOptions
{
BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});
Contexto contexto = await client.GetContextoAsync();
foreach (Contribuyente contribuyente in contexto.Contribuyentes ?? [])
{
Console.WriteLine($"{contribuyente.Identificacion} emite: {string.Join(",", contribuyente.TiposComprobante ?? [])}");
}
import os
from ecuafact import EcuafactClient, EcuafactClientOptions
client = EcuafactClient(EcuafactClientOptions(
base_address="https://api-sandbox.mynexusapi.com/",
api_key=os.environ["ECUAFACT_API_KEY"],
))
contexto = client.get_contexto()
for contribuyente in contexto.contribuyentes or []:
print(contribuyente.identificacion, contribuyente.tipos_comprobante)
// Node.js 18 o superior. Guarda como contexto-sdk.mjs y ejecuta: node contexto-sdk.mjs
import { EcuafactClient } from '@ecuafact/sdk';
const client = new EcuafactClient({
baseAddress: 'https://api-sandbox.mynexusapi.com/',
apiKey: process.env.ECUAFACT_API_KEY
});
const contexto = await client.getContexto();
for (const contribuyente of contexto.contribuyentes ?? []) {
console.log(contribuyente.identificacion, contribuyente.tiposComprobante);
}
<?php
require 'vendor/autoload.php';
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;
$client = new EcuafactClient(new EcuafactClientOptions(
baseAddress: 'https://api-sandbox.mynexusapi.com/',
apiKey: getenv('ECUAFACT_API_KEY'),
));
$contexto = $client->getContexto();
foreach ($contexto->contribuyentes ?? [] as $contribuyente) {
echo $contribuyente->identificacion . PHP_EOL;
}
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.Contexto;
import com.ecuafact.sdk.contracts.Contribuyente;
// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));
Contexto contexto = client.getContexto();
for (Contribuyente contribuyente : contexto.contribuyentes()) {
System.out.println(contribuyente.identificacion() + " " + contribuyente.tiposComprobante());
}
# Resultado esperado: tu integración y sus contribuyentes habilitados, en tabla.
ecuafact cuenta --entorno sandbox
Sabrás que funcionó si el estado es 200 y la lista contribuyentes trae al
menos un contribuyente.
Respuesta#
La API responde 200 OK con este objeto JSON:
{
"idCliente": "1f2e3d4c-5b6a-4789-9012-abcdef012345",
"nombre": "Integracion de ejemplo",
"contribuyentes": [
{
"identificacion": "0123456789001",
"puedeEmitir": true,
"puedeRecibir": false,
"tiposComprobante": [
"01",
"03",
"04",
"05",
"06",
"07"
],
"marcaBlanca": false
}
]
}
| Campo | Tipo | Descripción |
|---|---|---|
idCliente |
string (UUID) | Identificador de tu integración. Inclúyelo cuando pidas soporte. |
nombre |
string | Nombre de tu integración. Si contribuyentes viene vacío, vale Cliente API. |
contribuyentes |
array | Contribuyentes habilitados para tu API Key en el ambiente de la URL que llamaste. Viene vacío ([]) si aún no tienes ninguno habilitado en ese ambiente. |
contribuyentes[].identificacion |
string | 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. Es el valor que pones en {identificacion} en todas las rutas /v1/contribuyentes/{identificacion}/... y en infoTributaria.ruc al emitir. |
contribuyentes[].puedeEmitir |
boolean | true si el contribuyente tiene al menos un tipo de comprobante habilitado para emitir. |
contribuyentes[].puedeRecibir |
boolean | true si el contribuyente tiene habilitado el servicio de recepción. No afecta la emisión. |
contribuyentes[].tiposComprobante |
array de string | Códigos de tipo de comprobante (tipoDocumento) que puede emitir, en orden: 01 factura, 03 liquidación de compra, 04 nota de crédito, 05 nota de débito, 06 guía de remisión y 07 comprobante de retención. Viene vacío si no puede emitir. |
contribuyentes[].marcaBlanca |
boolean | true si el contribuyente es un emisor de marca blanca: sus comprobantes se emiten y se autorizan igual, pero no tienen RIDE. Para ese contribuyente, Descargar PDF responde 404 con el codEstado 3013 (no_encontrado); el XML autorizado se descarga igual. Lo configuramos nosotros por contribuyente; no lo cambias desde la API. |
Si te habilitan un contribuyente o un tipo de comprobante, puede tardar un par de minutos en aparecer en esta respuesta.
Estados de este endpoint#
codEstado |
HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | La API devuelve el contexto. | Guarda la identificacion de cada contribuyente y úsala en las rutas. |
3009 (credenciales_invalidas) |
401 | Falta la cabecera X-Api-Key, la API Key es inválida o está revocada. |
Revisa la API Key, como se explica en Autenticación. No reintentes sin cambiar nada. |
3010 (ip_no_autorizada) |
403 | En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. | Registra tu IP en Cuenta > IP permitidas y revisa que tu proxy o balanceador no oculte la IP de salida. |
5005 (limite_solicitudes) |
429 | Superaste el límite de solicitudes por minuto o de autenticaciones fallidas desde tu IP. | Espera los segundos que indica la cabecera Retry-After y reintenta. El detalle está en Límite de request. |
3007 (version_no_soportada) |
400 | Enviaste X-Api-Version con una versión que no existe. |
Quita la cabecera o usa la versión vigente, 2026-11-16. |
5002 (servicio_no_disponible) |
503 | El servicio no está disponible temporalmente. | Espera lo que indica Retry-After y reintenta con una espera creciente. |
Si un contribuyente que esperas no aparece en contribuyentes, todavía no está
habilitado para tu integración en ese ambiente, y puedes solicitar su alta.
El catálogo completo de códigos está en Errores.
Siguientes pasos#
- Primeros pasos: emite tu primer comprobante con la
identificacionque acabas de obtener. - Ambientes y contribuyentes: entiende por qué un contribuyente aparece en pruebas y no en producción.
- Seguimiento de una operación: lista lo que ya emitió un contribuyente.