<!-- source_url: https://docs.mynexusapi.com/v1/guias/consulta-contexto | last_updated: 2026-11-17 -->

# Contexto

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](/v1/guias/glosario) 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](/v1/guias/sandbox);
  cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion).
- [ ] 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](/v1/guias/autenticacion#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](/v1/guias/autenticacion). |
| `X-Api-Version` (cabecera) | string | No | Versión del contrato. Si no la envías, se usa la vigente. Ve [Versionado](/v1/guias/versionado). |

## Ejemplo

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal.

Todos los ejemplos imprimen el estado HTTP y el cuerpo de la respuesta.

```bash
curl -s "https://api-sandbox.mynexusapi.com/v1/contexto" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
```

```csharp
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()}");
```

```python
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)
```

```javascript
// 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
<?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;
```

```java
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());
```

```csharp-sdk
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 ?? [])}");
}
```

```python-sdk
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)
```

```javascript-sdk
// 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-sdk
<?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;
}
```

```java-sdk
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());
}
```

```bash-cli
# 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:

```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](/v1/guias/glosario) 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](/v1/guias/consulta-ride) responde 404 con el `codEstado` 3013 (`no_encontrado`); el [XML autorizado](/v1/guias/consulta-xml) 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](/v1/guias/autenticacion). 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](/v1/guias/limite-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](/v1/guias/errores).

## Siguientes pasos

- [Primeros pasos](/v1/guias/primeros-pasos): emite tu primer comprobante con la `identificacion` que acabas de obtener.
- [Ambientes y contribuyentes](/v1/guias/ambientes): entiende por qué un contribuyente aparece en pruebas y no en producción.
- [Seguimiento de una operación](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente): lista lo que ya emitió un contribuyente.
