En esta página
Consumo y cuotas GET
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 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. Si todavía no tienes una, crea un 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. El sandbox acepta cualquier IP.
- Un paquete de documentos pagado y vigente en el ambiente de la URL que llamas. El 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.
Importante
Ambiente de pruebas: sin validez fiscal.
curl -s "https://api-sandbox.mynexusapi.com/v1/consumo" \
-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/consumo");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
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)
// 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
$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;
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());
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}");
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)
// 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
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;
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());
# Resultado esperado: límite, reservados, consumidos y disponibles, en tabla.
ecuafact consumo --entorno sandbox
Respuesta#
La API responde 200 OK con este objeto 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 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:
- Al inicio no has emitido nada, así que
limiteDocumentosvale 1500,reservados0,consumidos0,disponibles1500 yvigenteHastaes el 1 de marzo de 2027. - 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,
reservadosvale 5,consumidos990 ydisponibles505. Es la respuesta de ejemplo de arriba. - Llegan los 5 resultados pendientes, que pasan de reservados a
consumidos:
reservadosvale 0,consumidos995 ydisponibles505. - 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
vigenteHastapasa al 1 de junio de 2027. - Una de esas 10 operaciones queda
cancelado. Su documento se libera y vuelve a estar disponible, así quedisponiblessube 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.
Atención
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. |
3009 (credenciales_invalidas) |
401 | La API Key falta o es inválida. | Revisa la API Key, como se explica en Autenticación. |
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.
Siguientes pasos#
- Límite de request: no confundas el cupo de documentos con el límite de solicitudes por minuto.
- Seguimiento de una operación: revisa qué operaciones siguen reservando cupo.
- Buenas prácticas: planifica lotes grandes sin quedarte sin cupo.