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

# Consumo y cuotas

Devuelve cuántos documentos te quedan para emitir en el ambiente de la URL que llamas, sumando tus paquetes vigentes.

Cada comprobante que envías descuenta un documento de tu cupo, que es la suma de
tus paquetes de documentos pagados y vigentes en ese ambiente. Con
`GET /v1/consumo` puedes saber cuántos documentos tienes en paquetes, cuántos están
reservados por emisiones que aún esperan resultado, cuántos ya se consumieron,
cuántos te quedan y cuándo vence el próximo paquete.

En esta página verás cómo consultarlo, qué significa cada campo de la respuesta
con un ejemplo numérico, y en qué momento de una emisión se reserva, se consume o
se libera un documento.

```
GET /v1/consumo
X-Api-Key: <tu API Key>
```

## Cuándo usarlo

Te recomendamos consultarlo antes de enviar un lote grande de comprobantes, para
no quedarte sin [cupo](/v1/guias/glosario) a mitad del lote. También puedes
usarlo desde un tablero o una alerta interna que avise cuando queden pocos
documentos. Es el mismo saldo que ves en
el Portal del Cliente, y cada ambiente tiene su propio cupo.

## Antes de empezar

- [ ] Una API Key de pruebas guardada en la variable de entorno
      `ECUAFACT_API_KEY`, como se explica en
      [Autenticación](/v1/guias/autenticacion). Si todavía no tienes una,
      [crea un sandbox](/v1/guias/sandbox).
- [ ] Solo en producción, la IP pública de salida de tu servidor registrada para
      tu integración, como se explica en
      [Registra tu IP](/v1/guias/autenticacion#registra-tu-ip). El sandbox acepta
      cualquier IP.
- [ ] Un paquete de documentos pagado y vigente en el ambiente de la URL que
      llamas. El [sandbox](/v1/guias/sandbox) ya incluye un paquete de pruebas.

## Parámetros

Este endpoint no tiene parámetros de ruta ni de consulta; solo necesita tu API
Key.

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `X-Api-Key` (cabecera) | string | Sí | Tu API Key. |

## Ejemplo

Los ejemplos consultan el cupo de tu integración en el ambiente de pruebas e
imprimen la respuesta.

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

```bash
curl -s "https://api-sandbox.mynexusapi.com/v1/consumo" \
  -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/consumo");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
```

```python
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/consumo",
    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 consumo.mjs y ejecuta: node consumo.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consumo', {
  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/consumo');
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/consumo"))
    .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")!
});

QuotaBucket cupo = await client.GetConsumoAsync();
Console.WriteLine($"Disponibles {cupo.Disponibles} de {cupo.LimiteDocumentos}; próximo vencimiento {cupo.VigenteHasta:yyyy-MM-dd}");
```

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

cupo = client.get_consumo()
print("Disponibles", cupo.disponibles, "de", cupo.limite_documentos, "- próximo vencimiento", cupo.vigente_hasta)
```

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

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

const cupo = await client.getConsumo();
console.log('Disponibles', cupo.disponibles, 'de', cupo.limiteDocumentos, '- próximo vencimiento', cupo.vigenteHasta);
```

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

$cupo = $client->getConsumo();
echo 'Disponibles ' . $cupo->disponibles . ' de ' . $cupo->limiteDocumentos . PHP_EOL;
```

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

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

QuotaBucket cupo = client.getConsumo();
System.out.println("Disponibles " + cupo.disponibles() + " de " + cupo.limiteDocumentos());
```

```bash-cli
# Resultado esperado: límite, reservados, consumidos y disponibles, en tabla.
ecuafact consumo --entorno sandbox
```

## Respuesta

La API responde `200 OK` con este objeto JSON:

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

Los cuatro primeros campos suman todos tus paquetes pagados y vigentes del
ambiente. Un paquete vencido, sin pagar o anulado no cuenta.

| Campo | Tipo | Descripción |
|---|---|---|
| `limiteDocumentos` | number | Documentos de todos tus paquetes vigentes. |
| `reservados` | number | Documentos apartados por emisiones recibidas que aún no tienen resultado final. |
| `consumidos` | number | Documentos ya descontados: emisiones con resultado final (autorizadas, rechazadas o con rechazo de configuración), intentos con 422 y reenvíos con cambios. |
| `disponibles` | number | Documentos que aún puedes emitir: `limiteDocumentos - reservados - consumidos`. |
| `vigenteHasta` | string | Fecha y hora, en UTC e ISO 8601, en que vence el próximo paquete con saldo. `9999-12-31T00:00:00Z` significa que tus paquetes con saldo no vencen, como el paquete de pruebas. |
| `limiteExtra`, `reservadosExtra`, `consumidosExtra`, `disponiblesExtra` | number | Se mantienen por compatibilidad y valen 0: todo el saldo está en los cuatro primeros campos. |

## Paquetes

Cada paquete es de un ambiente, tiene una cantidad de documentos y una vigencia:

- **Producción.** Dura un año desde el pago. Lo compras en **Consumo**, con **Comprar
  documentos**, en el Portal del Cliente; con transferencia o depósito, el paquete se activa cuando
  se confirma el pago. El precio se muestra sin IVA y el IVA se suma al pagar.
- **Pruebas.** El [sandbox](/v1/guias/sandbox) incluye 3.000 documentos que no vencen.

Al emitir, el documento se descuenta del paquete vigente que vence primero; los
paquetes sin vencimiento se usan al final. El saldo de un paquete vencido se pierde.

## Ejemplo numérico

Supón que en producción tienes un paquete de 1.000 documentos que vence el 1 de
marzo de 2027 y otro de 500 que vence el 1 de junio de 2027. Así cambian los
valores a medida que emites:

1. **Al inicio** no has emitido nada, así que `limiteDocumentos` vale 1500,
   `reservados` 0, `consumidos` 0, `disponibles` 1500 y `vigenteHasta` es el 1
   de marzo de 2027.
2. **Emites 995 comprobantes.** Cada emisión aceptada con un 202 aparta 1
   documento del paquete que vence primero. Cuando 990 ya tienen resultado del
   SRI y 5 siguen esperando, `reservados` vale 5, `consumidos` 990 y
   `disponibles` 505. Es la respuesta de ejemplo de arriba.
3. **Llegan los 5 resultados pendientes**, que pasan de reservados a
   consumidos: `reservados` vale 0, `consumidos` 995 y `disponibles` 505.
4. **Emites 10 más.** Los 5 primeros salen del primer paquete, al que le
   quedaban 5, y los 5 siguientes, del segundo. El primer paquete queda sin saldo,
   así que `vigenteHasta` pasa al 1 de junio de 2027.
5. **Una de esas 10 operaciones queda `cancelado`.** Su documento se libera y
   vuelve a estar disponible, así que `disponibles` sube 1.

## Cuándo se reserva, consume o libera

La tabla muestra el efecto de cada momento de una emisión sobre el cupo:

| Momento | Efecto en el cupo |
|---|---|
| La emisión se rechaza por acceso (401 o 403), por cupo (429) o por una solicitud mal formada (400) | Ninguno. |
| La emisión se rechaza con 422 por formato o validación del comprobante | Consume 1 como intento, aunque no se emita nada. Repetir la misma `Idempotency-Key` con el mismo cuerpo devuelve el mismo 422 sin consumir otro. |
| Validas con `/validar` | Ninguno. |
| La emisión se acepta con un 202 y `estado` en `recibido` | Aparta 1: `reservados` sube 1 y `disponibles` baja 1. |
| Llega un reintento idempotente (misma `Idempotency-Key` y mismo cuerpo), que responde con el mismo `idOperacion` y el estado actual de la operación | Ninguno, porque es la misma operación. |
| La operación termina en `autorizado` o en `rechazado` con el `codEstado` 3001 (`rechazo_sri`) | Consume: `reservados` baja 1 y `consumidos` sube 1. Un rechazo del SRI también consume, porque el comprobante sí llegó al SRI. |
| La operación termina en `rechazado` con 3002 (`comprobante_invalido`) o en `rechazo_configuracion` | Consume: `reservados` baja 1 y `consumidos` sube 1. |
| Reenvías un comprobante rechazado con el mismo número y el mismo contenido | Ninguno, aunque hayas cambiado la firma electrónica o la modalidad del contribuyente. |
| Reenvías un comprobante rechazado con el mismo número y otro contenido (por ejemplo, otro comprador) | Consume 1: es otro envío. Sin saldo, el reenvío responde 429. |
| El contribuyente no tiene firma electrónica configurada | Ninguno: la emisión se rechaza sin consumir. |
| La operación termina en `error` con 5006 (`entrega_no_posible`) o 5007 (`resultado_no_confirmado`) | Sigue reservado: `reservados` y `disponibles` no cambian. Si reenvías el mismo número, el reenvío usa ese mismo documento y no reserva otro; el documento se consume cuando el reenvío obtiene su resultado. |
| La operación termina en `error` con 5001 (`error_interno`) | Según el caso, el documento queda consumido o sigue reservado. Al revisar la operación, soporte te confirma cómo quedó. |
| La operación termina en `cancelado` | Libera: `reservados` baja 1 y `disponibles` sube 1. Es el único caso que devuelve el documento. |

Cada comprobante descuenta un solo documento, aunque lo consultes, lo descargues
o lo reenvíes por correo muchas veces. Las consultas, incluidas las del SRI, no
consumen cupo.

> [!WARNING]
> Sin un paquete vigente con saldo, la emisión responde 429 con el `codEstado`
> 4004 (`cupo_agotado`). Compra un paquete antes de enviar lotes grandes.

## Estados de este endpoint

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | La API devuelve el cupo. | Compara `disponibles` con el tamaño de tu próximo lote. |
| 3013 (`no_encontrado`) | 404 | Tu integración no tiene paquetes en este ambiente. | Compra un paquete para ese ambiente o, en pruebas, crea un [sandbox](/v1/guias/sandbox). |
| 3009 (`credenciales_invalidas`) | 401 | La API Key falta 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` y reintenta. |
| 5002 (`servicio_no_disponible`) | 503 | Nuestro servicio no está disponible por un momento. | Reintenta con espera creciente. |

El 429 con el `codEstado` 4004 (`cupo_agotado`), que indica cupo agotado, lo
devuelve la emisión y no esta consulta. El catálogo
completo está en [Errores](/v1/guias/errores).

## Siguientes pasos

- [Límite de request](/v1/guias/limite-de-request): no confundas el cupo de documentos con el límite de solicitudes por minuto.
- [Seguimiento de una operación](/v1/guias/consulta-operacion): revisa qué operaciones siguen reservando cupo.
- [Buenas prácticas](/v1/guias/buenas-practicas#cupo): planifica lotes grandes sin quedarte sin cupo.
