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

# Seguimiento de una operación

Consulta el resultado de una emisión: si sigue recibida, si el SRI la autorizó o la rechazó y cuál es su clave de acceso.

Cuando emites un comprobante, la API lo recibe y responde de inmediato con un
`idOperacion`, pero el resultado del [SRI](/v1/guias/glosario) llega después.
Este endpoint te dice cómo está esa [operación](/v1/guias/glosario#operacion):
si el comprobante sigue recibido y sin resultado, si el SRI lo autorizó o lo
rechazó, si no se pudo emitir y por qué, y cuál es la
[clave de acceso](/v1/guias/glosario#clave-de-acceso) que le asignamos.

Puedes usarlo para seguir cada emisión hasta su estado final. Al terminar esta
página sabrás leer el campo `estado`, junto con `codEstado`, `msgError` y
`errores`, y qué hacer en cada caso: esperar, entregar el comprobante a tu cliente o corregirlo
y emitirlo de nuevo.

```
GET /v1/operaciones/{idOperacion}
X-Api-Key: <tu API Key>
```

## Para agentes

Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.

Pega este prompt en un agente de programación con acceso a la terminal:

```text
Implementa en este proyecto el seguimiento de una operación de Ecuafact hasta un estado final. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, puedes instalarla con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/consulta-operacion.md antes de escribir código; no inventes campos. Reutiliza el SDK de Ecuafact que el proyecto ya use; si no usa ninguno, recomiéndame el SDK de su lenguaje o el CLI ecuafact, con una frase de motivo, y espera mi respuesta; HTTP directo solo si lo prefiero. Consulta GET /v1/operaciones/{idOperacion} con el idOperacion de la emisión (o usa urlEstado tal cual, que es una URL absoluta) y repite con espera creciente mientras el estado sea recibido (codEstado 1001 o 1002), con un tiempo máximo y sin saturar el límite de solicitudes; respeta Retry-After. Cualquier otro estado es final y se decide por estado y codEstado numérico: autorizado (2001) es el único con validez fiscal; en los demás casos lee errores como arreglo, explica la causa con el catálogo de la guía de errores y no reemitas ante 5001 ni 5007. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Prueba con una operación de pruebas que yo te indique o que emitas con un comprobante de prueba. Ejecuta el seguimiento e informa solo el estado final, el codEstado y la claveAcceso, y cualquier acción que yo deba hacer.
```

## Cuándo usarlo

La emisión responde `202 Accepted` con un `idOperacion`, y eso significa que el
comprobante fue **recibido**, no que esté autorizado. Puedes enterarte del
resultado de dos formas, y también combinarlas.

- **Webhook**, la forma que te recomendamos. Te avisamos con
  `document.authorized`, `document.rejected` o `document.failed` en cuanto hay
  un resultado, así que no gastas solicitudes ni tienes que decidir cada cuánto
  preguntar. El detalle está en [Webhooks](/v1/guias/webhooks).
- **Consulta**, con este endpoint. Te sirve si aún no tienes un servidor
  público para recibir webhooks, durante las pruebas, como respaldo cuando un
  webhook no llegó o para mostrar el estado cuando un usuario lo pide.

Si emites muchos comprobantes, te recomendamos el webhook, porque consultar
cada operación en bucle consume tu [límite de solicitudes](/v1/guias/limite-de-request), que por
defecto es de 200 por minuto y de 60 en un sandbox.

## 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 hacerlo, sigue
  [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip).
- [ ] El `idOperacion` que recibiste en la respuesta 202 de una
  [emisión](/v1/guias/emision). Debe ser de una emisión hecha con la misma API
  Key y en la misma URL, de pruebas o de producción.

## Parámetros

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `idOperacion` (ruta) | string (UUID) | Sí | El `idOperacion` de la respuesta 202 de la emisión, que también viene en `urlEstado` y en la cabecera `Location`. Debe tener formato UUID, por ejemplo `3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f`. |
| `X-Api-Key` (cabecera) | string | Sí | La misma API Key con la que emitiste. Una operación de otra integración responde 404. |

El campo `urlEstado` de la respuesta de emisión trae la URL completa del
seguimiento, por ejemplo
`https://api-sandbox.mynexusapi.com/v1/operaciones/{idOperacion}`, y la cabecera
`Location` trae el mismo valor. Puedes llamarla tal como viene, sin armar la
ruta por tu cuenta.

## Ejemplo

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

Reemplaza el `idOperacion` de ejemplo por el que recibiste al emitir. Todos los
ejemplos imprimen el estado HTTP y el cuerpo de la respuesta.

```bash
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;

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/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
```

```python
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
    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 operacion.mjs y ejecuta: node operacion.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f', {
  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/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
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/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"))
    .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")!
});

Operation operacion = await client.GetOperacionAsync(Guid.Parse("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"));
Console.WriteLine($"{operacion.Estado} / {operacion.CodEstado} / {operacion.ClaveAcceso}");
```

```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"],
))

operacion = client.get_operacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f")
print(operacion.estado, operacion.cod_estado, operacion.clave_acceso)
```

```javascript-sdk
// Node.js 18 o superior. Guarda como operacion-sdk.mjs y ejecuta: node operacion-sdk.mjs
import { EcuafactClient } from '@ecuafact/sdk';

const client = new EcuafactClient({
  baseAddress: 'https://api-sandbox.mynexusapi.com/',
  apiKey: process.env.ECUAFACT_API_KEY
});

const operacion = await client.getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
console.log(operacion.estado, operacion.codEstado, operacion.claveAcceso);
```

```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'),
));

$operacion = $client->getOperacion('3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f');
echo $operacion->estado . ' / ' . $operacion->codEstado . PHP_EOL;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.Operation;

// 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")));

Operation operacion = client.getOperacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
System.out.println(operacion.estado() + " / " + operacion.codEstado());
```

```bash-cli
# Resultado esperado: el estado, el codEstado y la claveAcceso de la operación.
ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f --entorno sandbox
```

## Respuesta

La API responde `200 OK` con la operación en el primer nivel del JSON. La forma
es la misma de la respuesta `202 Accepted` de la emisión, con los valores
actuales. Este ejemplo corresponde a una factura ya autorizada:

```json
{
  "estado": "autorizado",
  "codEstado": 2001,
  "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": "0911202601179999999900110010010000001231234567810",
  "fhRecibido": "2026-11-09T10:15:00-05:00",
  "fhAutorizacion": "2026-11-09T10:15:18-05:00"
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | Resultado de la operación. Sus valores están en [Valores de estado](#valores-de-estado). |
| `codEstado` | number | Código numérico de 4 dígitos que precisa el resultado. Su primer dígito coincide con el `estado`: 1 es `recibido`, 2 `autorizado`, 3 `rechazado`, 4 `rechazo_configuracion`, 5 `error` y 6 `cancelado`. Sus valores están en [Códigos de resultado](#codigos-de-resultado). |
| `msgError` | string | Descripción general y fija del código, en español. Solo viene cuando el comprobante no se autorizó; con `recibido` o `autorizado` el campo no aparece. Muéstralo o regístralo, pero decide con `estado` y `codEstado`. |
| `errores` | array de string | Detalle específico del resultado, por ejemplo el mensaje del SRI en un rechazo fiscal o la ruta del campo en un comprobante inválido. Viene siempre y es una lista vacía cuando no hay detalle. El texto es informativo, así que muéstralo o regístralo sin compararlo en tu código. |
| `idOperacion` | string (UUID) | El identificador que consultaste. |
| `urlEstado` | string | URL completa de este mismo seguimiento. |
| `ambiente` | number | `1` para pruebas y `2` para producción. Siempre coincide con la URL que llamas. |
| `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`, por ejemplo `001-001-000000123`. Si dejaste que te asignáramos el secuencial, aquí lo encuentras. |
| `referenciaExterna` | string o `null` | La `referenciaExterna` que enviaste al emitir, o `null` si no la enviaste. |
| `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos que te asignamos. Vale `null` mientras el `codEstado` es 1001 y también cuando el comprobante no se llegó a emitir. Guárdala, porque la necesitas para descargar el RIDE y el XML. |
| `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con la zona horaria de Ecuador, por ejemplo `2026-11-09T10:15:00-05:00`. |
| `fhAutorizacion` | string o `null` | Fecha y hora de autorización, en ISO 8601 con zona horaria. Puede ser `null` aunque el `estado` sea `autorizado`, porque la autorización no siempre trae fecha; por eso no la uses para decidir si el comprobante está autorizado. |

Mientras el comprobante no tiene resultado, el `estado` es `recibido` y el
`codEstado` vale 1001 si todavía no tiene clave de acceso o 1002 si ya la
tiene. Tu sistema debe aceptar los dos valores y tratar la `claveAcceso` como
opcional mientras el comprobante siga recibido:

```json
{
  "estado": "recibido",
  "codEstado": 1002,
  "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": "0911202601179999999900110010010000001231234567810",
  "fhRecibido": "2026-11-09T10:15:00-05:00",
  "fhAutorizacion": null
}
```

Así se ve, en cambio, un comprobante que el SRI rechazó. El `estado` es
`rechazado`, el `codEstado` 3001 indica que el rechazo vino del SRI, `msgError`
trae la descripción fija del código y `errores` trae el mensaje del SRI:

```json
{
  "estado": "rechazado",
  "codEstado": 3001,
  "msgError": "El SRI rechazó el comprobante.",
  "errores": [
    "CLAVE ACCESO REGISTRADA"
  ],
  "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": "0911202601179999999900110010010000001231234567810",
  "fhRecibido": "2026-11-09T10:15:00-05:00",
  "fhAutorizacion": null
}
```

### Valores de estado

El campo `estado` tiene seis valores. Solo `recibido` es provisional; los demás
son finales y ya no cambian.

| Valor | Final | Significado |
|---|---|---|
| `recibido` | No | Recibimos el comprobante, pasó nuestras validaciones y todavía no tiene un resultado final. |
| `autorizado` | Sí | El SRI autorizó el comprobante. Es el único valor con validez fiscal. |
| `rechazado` | Sí | El comprobante no se autorizó por su contenido: lo rechazó el SRI o no cumplió una regla de la validación fiscal. `codEstado` dice cuál de los dos casos es. |
| `rechazo_configuracion` | Sí | No se pudo emitir porque falta o está mal una configuración del emisor, como la firma electrónica, la suscripción o el cupo. |
| `error` | Sí | No se pudo emitir por un fallo inesperado o porque algo impidió de forma definitiva que se autorice. |
| `cancelado` | Sí | La plataforma canceló el envío de forma automática. El comprobante no se emitió y no consumió cupo. |

No llames "autorizado" a un comprobante recibido, porque el 202 de la emisión
solo indica que se **recibió**. Para uso fiscal solo cuenta que el `estado` sea
`autorizado`.

### Códigos de resultado

El `codEstado` precisa el resultado dentro de cada `estado`. Mientras el
comprobante sigue `recibido` vale 1001 o 1002, y cuando el `estado` es final y
distinto de `autorizado` dice la causa. La acción para cada código está en
[Qué hacer según el estado](#que-hacer-segun-el-estado), y el catálogo completo,
en [Errores](/v1/guias/errores#codigos-de-resultado-de-una-operacion).

| `codEstado` | Nombre | `estado` | Significado |
|---|---|---|---|
| 1001 | `comprobante_recibido` | `recibido` | Recibimos el comprobante y todavía no tiene clave de acceso ni resultado. |
| 1002 | `comprobante_enviado` | `recibido` | El comprobante ya tiene `claveAcceso` y espera el resultado del SRI. |
| 2001 | `comprobante_autorizado` | `autorizado` | El SRI autorizó el comprobante. |
| 3001 | `rechazo_sri` | `rechazado` | El SRI rechazó el comprobante. `errores` trae el mensaje del SRI. |
| 3002 | `comprobante_invalido` | `rechazado` | La validación fiscal rechazó el contenido antes de enviarlo al SRI. `errores` trae el detalle por campo cuando existe. |
| 4001 | `emisor_no_configurado` | `rechazo_configuracion` | Al emisor le falta configuración para emitir ante el SRI. |
| 4002 | `firma_no_valida` | `rechazo_configuracion` | La firma electrónica del emisor está caducada o no es válida. |
| 4003 | `suscripcion_inactiva` | `rechazo_configuracion` | La suscripción del emisor no está activa. |
| 4004 | `cupo_agotado` | `rechazo_configuracion` | No quedan documentos en tus paquetes vigentes. |
| 5001 | `error_interno` | `error` | Tuvimos un fallo inesperado y el comprobante no se completó. |
| 5006 | `entrega_no_posible` | `error` | El comprobante no se pudo emitir y confirmamos que no se creó. |
| 5007 | `resultado_no_confirmado` | `error` | No pudimos confirmar si el comprobante llegó a crearse. |
| 6001 | `operacion_cancelada` | `cancelado` | La plataforma canceló el envío antes de emitirlo. |

Los nombres de la tabla te sirven para leer la documentación y coinciden con las
constantes de nuestros SDK, pero en el JSON solo viaja el número. Si recibes un
`codEstado` que tu sistema no reconoce, decide por su primer dígito, que siempre
coincide con el `estado`. Si es final, trátalo como un rechazo que debe revisar
una persona y conserva el `idOperacion` para soporte.

## Qué hacer según el estado

Una operación está en **estado final** cuando su `estado` es cualquier valor
distinto de `recibido`. Mientras sea `recibido`, sigue esperando.

| `estado` | `codEstado` | Final | Qué hacer |
|---|---|---|---|
| `recibido` | 1001 o 1002 | No | Espera el webhook o consulta más tarde, y no reenvíes la emisión. Con 1002 ya puedes guardar la `claveAcceso`, pero el comprobante todavía no está autorizado. |
| `autorizado` | 2001 | Sí | Guarda la `claveAcceso`, descarga el [RIDE](/v1/guias/consulta-ride) y el [XML](/v1/guias/consulta-xml) y entrégalos a tu cliente. |
| `rechazado` | 3001 | Sí | Es un rechazo fiscal y el cupo se consume. Corrige el comprobante según el mensaje del SRI que viene en `errores` y emítelo como un comprobante **nuevo**, con un secuencial nuevo (o sin `secuencial`, para que te asignemos el siguiente), una `Idempotency-Key` nueva y una `referenciaExterna` nueva. Si reutilizas el número rechazado, la API responde 409 con el `codEstado` 3004 (`comprobante_duplicado`). |
| `rechazado` | 3002 | Sí | Corrige el dato que indica `errores` y reenvía el comprobante con claves nuevas. Puedes conservar el mismo número. |
| `rechazo_configuracion` | 4001 | Sí | Revisa el RUC en **Cuenta > Contribuyentes** del Portal del Cliente: en el ambiente en que emitiste, la columna **Pruebas** o **Producción** debe mostrar **Listo** o **En producción**. Si muestra **Configurando**, espera a que termine; si ya está listo, escribe a soporte con el `idOperacion`. Después reenvía con el mismo número y claves nuevas. |
| `rechazo_configuracion` | 4002 | Sí | En **Cuenta > Contribuyentes** del Portal del Cliente, pulsa **Reemplazar firma** en la fila del RUC y carga una firma electrónica vigente; si tu portal no muestra esa opción, cárgala en **Cuenta > Certificados** con **Reemplazar certificado**. Después reenvía con el mismo número y claves nuevas. |
| `rechazo_configuracion` | 4003 | Sí | Regulariza la suscripción del emisor y reenvía con el mismo número y claves nuevas. |
| `rechazo_configuracion` | 4004 | Sí | Compra un paquete de documentos y reenvía con el mismo número y claves nuevas. |
| `error` | 5006 | Sí | El comprobante no se creó. Reenvíalo con el mismo número y claves nuevas. |
| `error` | 5007 | Sí | **No reemitas**, porque el comprobante podría existir y lo duplicarías. Búscalo en el seguimiento y escribe a soporte con el `idOperacion`. |
| `error` | 5001 | Sí | Escribe a soporte con el `idOperacion` antes de reemitir, para confirmar que el comprobante no existe. |
| `cancelado` | 6001 | Sí | El comprobante no se emitió y no consumió cupo. Emítelo de nuevo con claves nuevas; puedes usar el mismo número. Con la misma `Idempotency-Key` recibirías otra vez esta operación cancelada. |

En esta tabla, "claves nuevas" significa una `Idempotency-Key` nueva y una
`referenciaExterna` nueva. Para conservar el número, envía el mismo `estab`,
`ptoEmi` y `secuencial`. Si dejaste que te asignáramos el secuencial, lo
encuentras en el `numeroDocumento` de esta misma respuesta o en el
[listado de operaciones](#listado-de-operaciones-por-contribuyente). Un reenvío
con el mismo número puede responder con el mismo `idOperacion` y no descuenta
otro documento de tu cupo.

> [!WARNING]
> No reemplaces la `Idempotency-Key` ni la `referenciaExterna` mientras la
> operación siga en `recibido`. Emitir de nuevo con datos de idempotencia
> distintos crea un segundo comprobante.

Un rechazo y una espera se manejan de forma distinta. Un **rechazo**
(`rechazado` o `rechazo_configuracion`) exige corregir el comprobante o la
configuración del emisor antes de emitir de nuevo. Una **espera** (`recibido`)
no requiere ninguna acción: consulta más tarde o espera el webhook.

## Listado de operaciones por contribuyente

Para reconciliar lo emitido en un período, usa el listado paginado por
contribuyente. No devuelve todo el historial de la cuenta: exige la
`identificacion` y limita el rango de fechas a 366 días. No consume cupo.

```text
GET /v1/operaciones?identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50
X-Api-Key: <tu API Key>
```

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `identificacion` (consulta) | string | Sí | La identificación completa que devuelve `GET /v1/contexto`, la misma de `infoTributaria.ruc`. |
| `desde` (consulta) | string (`yyyy-MM-dd`) | No | Fecha inicial, desde el 2000-01-01. Si no la envías, se usan los 30 días anteriores a `hasta`. |
| `hasta` (consulta) | string (`yyyy-MM-dd`) | No | Fecha final. Si no la envías, se usa la fecha de hoy. Entre `desde` y `hasta` puede haber como máximo 366 días. |
| `tipoDocumento` (consulta) | string | No | `01`, `03`, `04`, `05`, `06` o `07`. Sin él, devuelve todos los tipos. |
| `buscar` (consulta) | string | No | Texto libre de hasta 100 caracteres, sin caracteres de control, para filtrar por número, clave, contraparte o referencia. |
| `pagina` (consulta) | number | No | Página, de 1 a 10000. Por defecto 1. |
| `tamanoPagina` (consulta) | number | No | Filas por página, de 1 a 100. Por defecto 20. |
| `X-Api-Key` (cabecera) | string | Sí | Tu API Key. |

Los ejemplos listan las facturas de los primeros 10 días de noviembre de 2026
del contribuyente de pruebas.

```bash
curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones?identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50" \
  -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);

string consulta = "identificacion=0123456789001&desde=2026-11-01&hasta=2026-11-10&tipoDocumento=01&pagina=1&tamanoPagina=50";
using HttpResponseMessage respuesta = await http.GetAsync("/v1/operaciones?" + consulta);
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
```

```javascript
// Node.js 18 o superior. Guarda como listado.mjs y ejecuta: node listado.mjs
const consulta = new URLSearchParams({
  identificacion: '0123456789001',
  desde: '2026-11-01',
  hasta: '2026-11-10',
  tipoDocumento: '01',
  pagina: '1',
  tamanoPagina: '50'
});
const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones?${consulta}`, {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
```

```php
<?php
$consulta = http_build_query([
    'identificacion' => '0123456789001',
    'desde' => '2026-11-01',
    'hasta' => '2026-11-10',
    'tipoDocumento' => '01',
    'pagina' => 1,
    'tamanoPagina' => 50,
]);
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/operaciones?' . $consulta);
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;
```

La respuesta es una página de comprobantes:

```json
{
  "comprobantes": [
    {
      "claveAcceso": "1011202601099215640600110010010000000025469774111",
      "numeroDocumento": "001-001-000000002",
      "tipoDocumento": "01",
      "fechaEmision": "10/11/2026",
      "identificacionContraparte": "0123456789",
      "razonSocialContraparte": "CONTRIBUYENTE DE PRUEBAS",
      "total": 1.00,
      "estado": "recibido",
      "codEstado": 1002,
      "errores": [],
      "fhAutorizacion": null
    }
  ],
  "pagina": 1,
  "tamanoPagina": 50,
  "hayMas": false
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `comprobantes` | array | Comprobantes de la página; vacío si no hay ninguno en el período. |
| `comprobantes[].claveAcceso` | string | Clave de acceso de 49 dígitos. |
| `comprobantes[].numeroDocumento` | string | Número con la forma `estab-ptoEmi-secuencial`. |
| `comprobantes[].tipoDocumento` | string | Tipo de comprobante: `01`, `03`, `04`, `05`, `06` o `07`. |
| `comprobantes[].fechaEmision` | string | Fecha de emisión con formato `dd/MM/yyyy`. |
| `comprobantes[].identificacionContraparte` | string | Identificación del comprador, del proveedor o del destinatario. |
| `comprobantes[].razonSocialContraparte` | string | Razón social de la contraparte. |
| `comprobantes[].total` | number | Importe total del comprobante. |
| `comprobantes[].estado` | string | Mismo significado que en [Valores de estado](#valores-de-estado). |
| `comprobantes[].codEstado` | number | Mismo significado que en [Códigos de resultado](#codigos-de-resultado). |
| `comprobantes[].msgError` | string | Descripción fija del código. Solo viene cuando el comprobante no se autorizó. |
| `comprobantes[].errores` | array de string | Detalle del resultado; lista vacía cuando no hay detalle. |
| `comprobantes[].fhAutorizacion` | string o `null` | Fecha y hora de autorización en ISO 8601; `null` si no está autorizado. |
| `pagina` | number | Página devuelta. |
| `tamanoPagina` | number | Filas por página usadas en la consulta. |
| `hayMas` | boolean | `true` si existe una página siguiente. |

Tu API Key debe tener el scope `comprobantes:leer` y acceso al contribuyente
consultado. Si no lo tiene, la API responde 403 con el `codEstado` 3011
(`acceso_denegado`); un filtro fuera de rango, por ejemplo un período mayor de
366 días, responde 400 con el `codEstado` 3012 (`filtros_invalidos`). Para un
volumen grande, recorre las páginas con `hayMas` en lugar de pedir todo en una
sola llamada. Los estados de este listado están en
[Estados de este endpoint](#estados-de-este-endpoint).

### Listado desde el CLI

El comando `ecuafact operaciones listar` hace esta misma consulta. Si no indicas
`--identificacion`, toma el contribuyente de `GET /v1/contexto` cuando hay uno
solo; si la integración tiene varios, se detiene y te pide `--identificacion`,
sin elegir uno en silencio. `--json` y `--csv` equivalen a `--salida json` y
`--salida csv`. La tabla muestra el número, el tipo, la fecha, el estado, el
`codEstado`, el total, la identificación de la contraparte y la clave de acceso;
en JSON recibes la
página completa, con `pagina`, `tamanoPagina` y `hayMas`.

```bash-cli
# Resultado esperado: una fila por comprobante, con su estado y codEstado.
ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --tipo 01 --entorno sandbox

# La pagina completa en JSON, para guardarla o procesarla.
ecuafact operaciones listar --identificacion 0123456789001 --desde 2026-11-01 --hasta 2026-11-10 --json

# Un CSV para abrir en Excel.
ecuafact operaciones listar --identificacion 0123456789001 --desde 2026-11-01 --hasta 2026-11-10 --csv > emitidos.csv
```

Si la respuesta trae `hayMas` en `true`, repite el comando con `--pagina` una
unidad mayor. El comando te recuerda la página siguiente en el mensaje de
resumen.

### Listado en Postman

En la colección, abre **03 · Listado de operaciones > 03.1 Listar operaciones**.
Usa las variables del environment `baseUrl`, `apiKey` e `identificacion`, y
ajusta `desde` y `hasta` al período que quieras conciliar. La petición trae
ejemplos de `200` con una página de comprobantes, de `403` con el `codEstado`
3011 y de `400` con el 3012.

## Seguimiento con espera

Si no usas webhooks, puedes consultar la operación cada pocos segundos hasta
llegar a un estado final, siempre con un tope de tiempo. El resultado del SRI puede
tardar varios minutos, y consultar más seguido que cada 5 segundos no lo
acelera.

Este ejemplo consulta cada 10 segundos durante un máximo de 10 minutos. Si
llega al tope sin un estado final, no es un error. Deja el comprobante como
pendiente en tu sistema y vuelve a consultarlo más tarde, o espera el webhook.

```bash
# Requiere jq. Uso: ./seguir.sh 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f
ID="$1"
for intento in $(seq 1 60); do
  CUERPO=$(curl -s "https://api-sandbox.mynexusapi.com/v1/operaciones/$ID" -H "X-Api-Key: $ECUAFACT_API_KEY")
  ESTADO=$(echo "$CUERPO" | jq -r '.estado')
  echo "Intento $intento: $ESTADO"
  if [ "$ESTADO" != "recibido" ]; then echo "$CUERPO"; exit 0; fi
  sleep 10
done
echo "Sin estado final tras 10 minutos: consulta mas tarde."
```

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

string idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f";
DateTime limite = DateTime.UtcNow.AddMinutes(10);
while (DateTime.UtcNow < limite)
{
    using HttpResponseMessage respuesta = await http.GetAsync($"/v1/operaciones/{idOperacion}");
    string cuerpo = await respuesta.Content.ReadAsStringAsync();
    if (!respuesta.IsSuccessStatusCode)
    {
        Console.WriteLine($"{(int)respuesta.StatusCode} {cuerpo}");
        return;
    }
    using JsonDocument json = JsonDocument.Parse(cuerpo);
    string estado = json.RootElement.GetProperty("estado").GetString()!;
    Console.WriteLine(estado);
    if (estado != "recibido")
    {
        Console.WriteLine(cuerpo);
        return;
    }
    await Task.Delay(TimeSpan.FromSeconds(10));
}
Console.WriteLine("Sin estado final tras 10 minutos: consulta mas tarde.");
```

```python
import os
import time
import requests

id_operacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"
url = f"https://api-sandbox.mynexusapi.com/v1/operaciones/{id_operacion}"
headers = {"X-Api-Key": os.environ["ECUAFACT_API_KEY"]}
limite = time.monotonic() + 600

while time.monotonic() < limite:
    r = requests.get(url, headers=headers, timeout=30)
    if r.status_code != 200:
        print(r.status_code, r.text)
        break
    operacion = r.json()
    print(operacion["estado"], "/", operacion["codEstado"])
    if operacion["estado"] != "recibido":
        print(r.text)
        break
    time.sleep(10)
else:
    print("Sin estado final tras 10 minutos: consulta mas tarde.")
```

```javascript
// Node.js 18 o superior. Guarda como seguir.mjs y ejecuta: node seguir.mjs
const idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f';
const limite = Date.now() + 10 * 60 * 1000;
const esperar = (ms) => new Promise((resolver) => setTimeout(resolver, ms));

let terminado = false;
while (!terminado && Date.now() < limite) {
  const res = await fetch(`https://api-sandbox.mynexusapi.com/v1/operaciones/${idOperacion}`, {
    headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
  });
  if (res.status !== 200) {
    console.log(res.status, await res.text());
    break;
  }
  const operacion = await res.json();
  console.log(operacion.estado, '/', operacion.codEstado);
  terminado = operacion.estado !== 'recibido';
  if (terminado) {
    console.log(JSON.stringify(operacion));
  } else {
    await esperar(10000);
  }
}
if (!terminado) {
  console.log('Sin estado final: consulta mas tarde.');
}
```

```php
<?php
$idOperacion = '3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f';
$limite = time() + 600;
$terminado = false;
while (!$terminado && time() < $limite) {
    $ch = curl_init('https://api-sandbox.mynexusapi.com/v1/operaciones/' . $idOperacion);
    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);
    if ($estado !== 200) {
        echo $estado . ' ' . $cuerpo . PHP_EOL;
        break;
    }
    $operacion = json_decode($cuerpo, true);
    echo $operacion['estado'] . ' / ' . $operacion['codEstado'] . PHP_EOL;
    $terminado = $operacion['estado'] !== 'recibido';
    if ($terminado) {
        echo $cuerpo . PHP_EOL;
    } else {
        sleep(10);
    }
}
if (!$terminado) {
    echo 'Sin estado final: consulta mas tarde.' . PHP_EOL;
}
```

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

// Dentro de: public static void main(String[] args) throws Exception
String idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f";
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/operaciones/" + idOperacion))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .GET()
    .build();
Pattern patronEstado = Pattern.compile("\"estado\"\\s*:\\s*\"([a-z_]+)\"");
long limite = System.currentTimeMillis() + 10 * 60 * 1000;
boolean terminado = false;
while (!terminado && System.currentTimeMillis() < limite) {
    HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
    if (respuesta.statusCode() != 200) {
        System.out.println(respuesta.statusCode() + " " + respuesta.body());
        break;
    }
    Matcher estado = patronEstado.matcher(respuesta.body());
    String valorEstado = estado.find() ? estado.group(1) : "";
    System.out.println(valorEstado);
    terminado = !valorEstado.isEmpty() && !valorEstado.equals("recibido");
    if (terminado) {
        System.out.println(respuesta.body());
    } else {
        Thread.sleep(10_000);
    }
}
if (!terminado) {
    System.out.println("Sin estado final: consulta mas tarde.");
}
```

Sabrás que funcionó si el bucle termina con el `estado` en `autorizado` y te
muestra la `claveAcceso`. En pruebas, eso ocurre cuando emitiste un comprobante válido.

## Estados de este endpoint

Cuando la consulta falla, el cuerpo trae la forma de error de toda la API, con
`estado`, `codEstado`, `msgError` y `errores`, que se explica en
[Errores](/v1/guias/errores#forma-del-error).

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | La API encontró la operación. | Lee el `estado` y el `codEstado` como se explica en [Qué hacer según el estado](#que-hacer-segun-el-estado). |
| 3013 (`no_encontrado`) | 404 | No existe una operación con ese `idOperacion` para tu integración, porque el valor está mal copiado, pertenece a otra integración o se emitió en el otro ambiente. | Revisa el `idOperacion` y confirma que llamas a la misma URL, de pruebas o de producción, donde emitiste. |
| 3013 (`no_encontrado`) | 404 | El `idOperacion` de la ruta no tiene formato UUID. | Copia el `idOperacion` tal como vino en la respuesta 202. |
| 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa la API Key, como se explica en [Autenticación](/v1/guias/autenticacion). |
| 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** o llama sin proxies que oculten el origen. |
| 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes. | Espera lo que indica `Retry-After`, consulta con menos frecuencia o usa webhooks. |
| 5002 (`servicio_no_disponible`) | 503 | El servicio no está disponible temporalmente. | Reintenta con una espera creciente. |

Para el listado de operaciones, los estados propios son estos, además de los
de autenticación y límite de la tabla anterior:

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | La API devuelve la página de comprobantes, que puede venir vacía. | Si `hayMas` es `true`, pide la página siguiente. |
| 3003 (`solicitud_invalida`) | 400 | Falta `identificacion` o una fecha no tiene el formato `yyyy-MM-dd`. | Envía `identificacion` y fechas con formato `2026-11-01`. |
| 3012 (`filtros_invalidos`) | 400 | Un filtro está fuera de rango: fecha anterior al 2000-01-01, `hasta` menor que `desde`, más de 366 días entre ambas, `pagina` fuera de 1 a 10000, `tamanoPagina` fuera de 1 a 100, `buscar` de más de 100 caracteres o `tipoDocumento` distinto de `01`, `03`, `04`, `05`, `06` o `07`. | Corrige el filtro que indica `errores` y repite la consulta. |
| 3002 (`comprobante_invalido`) | 422 | La `identificacion` no tiene entre 5 y 13 dígitos numéricos. | Usa la `identificacion` que devuelve `GET /v1/contexto`. |
| 3011 (`acceso_denegado`) | 403 | La `identificacion` no es de un contribuyente habilitado para tu API Key en este ambiente, o no puede emitir el `tipoDocumento` que pediste. | Revisa `GET /v1/contexto` y usa un contribuyente y un tipo habilitados. |

El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar en bucle.
- [Descargar PDF](/v1/guias/consulta-ride): obtén el RIDE cuando el comprobante esté `autorizado`.
- [Buenas prácticas](/v1/guias/buenas-practicas): reintentos e idempotencia sin duplicar comprobantes.
