Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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:

  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.

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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.