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

# Respuestas del API

Las respuestas de la API llegan como JSON plano o como archivo, y siempre traen cabeceras que te conviene leer.

Antes de leer un campo de una respuesta necesitas saber dónde está. Las
respuestas JSON traen sus campos en el primer nivel, sin ninguna clave que los
envuelva, y las descargas traen el archivo binario. Así puedes leer cualquier
respuesta de la misma manera, sin importar el endpoint.

Aquí ves las dos formas del cuerpo, la respuesta de la emisión, la forma de los
errores, las cabeceras que acompañan a cada respuesta y el formato de los
valores. Al terminar sabrás leer cualquier respuesta de la API sin adivinar.

## Formas del cuerpo

Antes de leer una respuesta, ubica su endpoint en esta tabla.

| Forma | Endpoints | Cómo se lee |
|---|---|---|
| **JSON plano** | Todos los endpoints que responden JSON: emisión, seguimiento, contexto, cupo, perfil del emisor, consultas al SRI y errores | Los campos están en el primer nivel del JSON. |
| **Archivo** | RIDE (`GET .../comprobantes/{claveAcceso}/ride`) y XML (`GET .../comprobantes/{claveAcceso}/xml`) | El cuerpo es el archivo binario, no JSON. |

Este es un ejemplo completo de respuesta JSON, la de `GET /v1/consumo`:

```json
{
  "limiteDocumentos": 1500,
  "reservados": 5,
  "consumidos": 990,
  "disponibles": 505,
  "vigenteHasta": "2027-01-01T00:00:00Z",
  "limiteExtra": 500,
  "reservadosExtra": 0,
  "consumidosExtra": 0,
  "disponiblesExtra": 500
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| Campos del recurso | varios | Están en el primer nivel. El detalle está en [Consumo y cuotas](/v1/guias/consumo). |

### Lee una respuesta en tu código

El ejemplo consulta tu cupo y el seguimiento de una operación, e imprime un
campo de cada una. Reemplaza el `idOperacion` por uno que te haya devuelto una
emisión.

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

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

curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
```

```csharp
using System.Net.Http;
using System.Text.Json;

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 consumo = await http.GetAsync("/v1/consumo");
using JsonDocument cupo = JsonDocument.Parse(await consumo.Content.ReadAsStringAsync());
Console.WriteLine($"{(int)consumo.StatusCode} disponibles: {cupo.RootElement.GetProperty("disponibles").GetInt32()}");

using HttpResponseMessage operacion = await http.GetAsync("/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
using JsonDocument seguimiento = JsonDocument.Parse(await operacion.Content.ReadAsStringAsync());
Console.WriteLine($"{(int)operacion.StatusCode} estado: {seguimiento.RootElement.GetProperty("estado").GetString()}");
```

```python
import os
import requests

base = "https://api-sandbox.mynexusapi.com"
headers = {"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}

consumo = requests.get(f"{base}/v1/consumo", headers=headers, timeout=30)
print(consumo.status_code, "disponibles:", consumo.json()["disponibles"])

operacion = requests.get(f"{base}/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f", headers=headers, timeout=30)
print(operacion.status_code, "estado:", operacion.json()["estado"])
```

```javascript
// Node.js 18 o superior. Guarda como respuestas.mjs y ejecuta: node respuestas.mjs
const base = 'https://api-sandbox.mynexusapi.com';
const headers = { 'X-Api-Key': process.env.ECUAFACT_API_KEY };

const consumo = await fetch(`${base}/v1/consumo`, { headers });
const cupo = await consumo.json();
console.log(consumo.status, 'disponibles:', cupo.disponibles);

const operacion = await fetch(`${base}/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f`, { headers });
const seguimiento = await operacion.json();
console.log(operacion.status, 'estado:', seguimiento.estado);
```

```php
<?php
function consultar(string $ruta): array
{
    $ch = curl_init('https://api-sandbox.mynexusapi.com' . $ruta);
    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);
    return [$estado, json_decode($cuerpo, true)];
}

[$estado, $cupo] = consultar('/v1/consumo');
echo $estado . ' disponibles: ' . $cupo['disponibles'] . PHP_EOL;

[$estado, $seguimiento] = consultar('/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
echo $estado . ' estado: ' . $seguimiento['estado'] . PHP_EOL;
```

```bash-cli
# Resultado esperado: tus documentos disponibles y el estado de la operación.
ecuafact consumo --entorno sandbox --campos disponibles
ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox --campos estado
```

**Resultado esperado.** Los ejemplos HTTP imprimen `200 disponibles: ...` y
`200 estado: ...`. Si la operación no existe en tu integración, la segunda
llamada responde 404 con el `codEstado` 3013 (`no_encontrado`), como se explica en
[Respuestas de error](#respuestas-de-error).

## Respuesta de la emisión

La emisión responde `202 Accepted` con este cuerpo, que tiene la misma forma
del [seguimiento](/v1/guias/consulta-operacion):

```json
{
  "estado": "recibido",
  "codEstado": 1001,
  "errores": [],
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "ambiente": 1,
  "tipoDocumento": "01",
  "numeroDocumento": "001-001-000000123",
  "referenciaExterna": "FAC-ERP-4581",
  "claveAcceso": null,
  "fhRecibido": "2026-11-09T10:15:00-05:00",
  "fhAutorizacion": null
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | `recibido` en el 202: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. |
| `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu sistema debe aceptar los dos valores. |
| `errores` | array de string | Lista vacía cuando el comprobante se recibió sin novedades. |
| `idOperacion` | string (UUID) | Identificador de la [operación](/v1/guias/glosario#operacion). Guárdalo, porque con él consultas el resultado del SRI. |
| `urlEstado` | string | URL completa del seguimiento, por ejemplo `https://api-sandbox.mynexusapi.com/v1/operaciones/{idOperacion}`. Puedes llamarla tal como viene. |
| `ambiente` | number | `1` para pruebas y `2` para producción. |
| `tipoDocumento` | string | Tipo de comprobante: `01`, `03`, `04`, `05`, `06` o `07`. |
| `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. |
| `referenciaExterna` | string o `null` | La `referenciaExterna` que enviaste. |
| `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes después en el seguimiento o en el webhook. |
| `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. |
| `fhAutorizacion` | string o `null` | Fecha y hora de autorización; en el 202 es `null`. |

El campo `msgError` no aparece porque la emisión no tiene error. Si reintentas
con la misma `Idempotency-Key` y el mismo cuerpo, o con la misma
`referenciaExterna` y el mismo cuerpo, la API responde con la misma forma y el
mismo `idOperacion`, con el estado actual de esa operación, y no crea otro
comprobante. El resultado actual también lo ves en el
[seguimiento](/v1/guias/consulta-operacion).

> [!NOTE]
> El 202 significa que la solicitud fue recibida; la autorización del SRI llega
> después por [seguimiento](/v1/guias/consulta-operacion) o por
> [webhook](/v1/guias/webhooks).

## Respuestas de error

Todos los errores tienen la misma forma plana, con un `codEstado` numérico de
4 dígitos cuyo primer dígito coincide con el `estado`:

```json
{
  "estado": "rechazado",
  "codEstado": 3013,
  "msgError": "Recurso no encontrado.",
  "errores": []
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | Estado que corresponde al código: `rechazado` (3xxx), `rechazo_configuracion` (4xxx) o `error` (5xxx). |
| `codEstado` | number | Código estable del catálogo. Programa tus decisiones con este valor y el estado HTTP. |
| `msgError` | string | Descripción general y fija del código. |
| `errores` | array de string | Detalle específico, por ejemplo la ruta del campo en un error de validación. Viene siempre y es una lista vacía cuando no hay detalle. |

Un rechazo de la emisión, por ejemplo un 422 de validación, trae estos mismos
cuatro campos dentro de la forma completa de la respuesta de emisión, con
`idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en
`null`, porque no se creó ninguna operación. Qué significa cada código y si se
reintenta se explica en [Errores](/v1/guias/errores#catalogo-de-codestado).

## Cabeceras de respuesta

Además del cuerpo, cada respuesta trae cabeceras con información útil para tu
integración:

| Cabecera | Cuándo aparece | Qué contiene | Para qué te sirve |
|---|---|---|---|
| `X-Correlation-Id` | En toda respuesta. | El identificador de la petición. Si enviaste tu propio `X-Correlation-Id` (de 1 a 64 caracteres `A-Z`, `a-z`, `0-9`, `.`, `_`, `-`), la API usa y devuelve ese mismo valor. | Regístralo en tus logs, porque es el dato que te pedimos en soporte. |
| `X-Api-Version` | En toda respuesta de `/v1`. | La versión del contrato que respondió (`2026-11-16`). | Te permite detectar cambios de versión, como se explica en [Versionado](/v1/guias/versionado). |
| `Location` | En el 202 de la emisión. | La URL completa del seguimiento, el mismo valor que `urlEstado`. | Úsala para consultar el estado. |
| `Content-Type` | En toda respuesta con cuerpo. | `application/json` en JSON, `application/pdf` en el RIDE y `application/xml` en el XML. | Te dice cómo leer el cuerpo. |
| `Content-Disposition` | En la descarga del XML. | `attachment` con el nombre de archivo sugerido `{claveAcceso}.xml`. | Úsala para guardar el archivo con su nombre. |
| `X-RateLimit-Limit` | En las respuestas autenticadas, cuando tu API Key tiene límite. | Las solicitudes permitidas por minuto. | Te dice tu límite; más detalle en [Límite de request](/v1/guias/limite-de-request). |
| `X-RateLimit-Remaining` | Junto con `X-RateLimit-Limit`. | Las solicitudes que te quedan en el minuto. | Te permite frenar antes de recibir un 429. |
| `X-RateLimit-Reset` | En el 429 con el `codEstado` 5005 (`limite_solicitudes`). | El fin de la ventana, en segundos Unix. | Te dice cuándo vuelves a tener solicitudes. |
| `Retry-After` | En los 429 y 503. | Los segundos de espera antes de reintentar. | Úsala para programar el reintento. |
| `Cache-Control` | En toda respuesta de `/v1`. | `no-store`, salvo en `GET /v1/catalogos` y `GET /v1/catalogos/{nombre}`, que traen `private, max-age=3600`. | Con `no-store`, las respuestas no se guardan en cachés intermedias; tampoco las guardes tú sin control. Los catálogos sí puedes guardarlos hasta una hora, como se explica en [Consultar los catálogos por API](/v1/guias/catalogos#consultar-los-catalogos-por-api). |

Así se ven las cabeceras de una emisión:

```
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f
X-Correlation-Id: 0HN7A2B3C4D5E:00000001
X-Api-Version: 2026-11-16
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
Cache-Control: no-store
```

## Formatos de los valores

Los valores de las respuestas siguen estos formatos:

| Tipo de dato | Formato | Ejemplo |
|---|---|---|
| Identificadores (`idOperacion`, `idCliente`) | UUID en texto. | `"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"` |
| Códigos e identificaciones (`tipoDocumento`, `identificacion`, `claveAcceso`) | Texto, aunque solo tengan dígitos, para conservar los ceros a la izquierda. | `"01"`, `"0123456789"` |
| Códigos de resultado y de error (`codEstado`) | Número entero de 4 dígitos. El primer dígito coincide con el `estado`. | `3002` |
| Estados (`estado`) | Texto en minúsculas con guion bajo. | `"recibido"`, `"rechazo_configuracion"` |
| Importes | Número JSON con punto decimal. | `112.5` |
| Fechas del comprobante (`fechaEmision` del listado de operaciones) | Texto con el formato `dd/MM/yyyy`. | `"15/09/2026"` |
| Fechas y horas de las respuestas (`fhRecibido`, `fhAutorizacion`, `vigenteHasta`) | Texto ISO 8601 (`yyyy-MM-ddTHH:mm:ss`). Algunos campos agregan la zona horaria al final (`Z` o `-05:00`), así que usa un parser ISO 8601 que acepte las dos formas. | `"2026-09-15T14:32:10"` |
| Campos opcionales sin valor | `null`. La excepción es `msgError`, que no aparece cuando no hay error. | `"fhAutorizacion": null` |

## Siguientes pasos

- [Errores](/v1/guias/errores#catalogo-de-codestado): qué hacer ante cada `codEstado`.
- [Seguimiento de una operación](/v1/guias/consulta-operacion): los campos del estado de una emisión.
- [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar.
- [Versionado](/v1/guias/versionado): cómo cambia el contrato y qué significa `X-Api-Version`.
- [Estado del servicio](/v1/guias/estado-del-servicio): consulta sin API Key si la API está operativa cuando recibes errores 5xx.
