Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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#

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.