API: consultar plan y consumo

GET /api/v1/contribuyente/plan-consumo — consulta el plan vigente y el consumo del ciclo del contribuyente autenticado por API key.

GET /api/v1/contribuyente/plan-consumo

Devuelve un snapshot del plan vigente y del consumo del ciclo actual.

Ruta deprecada: GET /api/v1/documento-electronico/plan-consumo sigue respondiendo lo mismo hasta el 15 de enero de 2027, cuando se remueve. Sus respuestas incluyen Deprecation: @1791590400, Sunset: Fri, 15 Jan 2027 00:00:00 GMT y Link: </api/v1/contribuyente/plan-consumo>; rel="successor-version". Cambiá la URL; la autenticación y la respuesta no cambian. Ver Versionado.

Autenticación

Authorization: Bearer {api-key} — requerido

La API key determina el contribuyente consultado. El endpoint no acepta RUC, ID de contribuyente ni suscripción en el path, query o body; una integración no puede seleccionar otro contribuyente.

Ejemplo

curl https://api.sifende.com.py/api/v1/contribuyente/plan-consumo \
  -H "Authorization: Bearer $SIFENDE_API_KEY"

Respuesta exitosa

Status: 200 OK

La respuesta es el objeto de plan y consumo directamente, sin envelope.

{
  "codigoPlan": "PRO",
  "nombrePlan": "PRO",
  "inicioPeriodo": "2026-10-02T03:00:00Z",
  "finPeriodo": "2026-11-02T03:00:00Z",
  "documentosIncluidos": 250,
  "consumoConfirmado": 262,
  "reservasActivas": 3,
  "documentosDisponibles": 0,
  "permiteAdicionales": true,
  "precioDocumentoAdicionalPyg": 400,
  "adicionalesFacturables": 12,
  "costoEstimadoPyg": 4800
}

Campos

Campo	Tipo	Descripción
`codigoPlan`	`string`	Código estable del plan vigente
`nombrePlan`	`string`	Nombre del plan apto para mostrar
`inicioPeriodo`	`string (RFC 3339)`	Inicio inclusivo del ciclo
`finPeriodo`	`string (RFC 3339)`	Fin exclusivo del ciclo
`documentosIncluidos`	`integer`	Cupo efectivo incluido en el ciclo
`consumoConfirmado`	`integer`	Documentos definitivos del ciclo
`reservasActivas`	`integer`	Documentos en proceso que conservan capacidad mientras se resuelven
`documentosDisponibles`	`integer`	Capacidad incluida restante; nunca es negativa
`permiteAdicionales`	`boolean`	Indica si el plan permite superar el cupo como adicional
`precioDocumentoAdicionalPyg`	`integer \| null`	Precio unitario efectivo en PYG; `null` si no se permiten adicionales
`adicionalesFacturables`	`integer`	Confirmados por encima del cupo que pueden facturarse
`costoEstimadoPyg`	`integer`	Costo adicional estimado en PYG

finPeriodo es exclusivo: el ciclo siguiente comienza en ese instante. Las reservas no son consumo confirmado ni adicionales cobrados. costoEstimadoPyg es una estimación calculada con los confirmados adicionales y el precio efectivo; consultar el endpoint no ejecuta un cobro ni cambia el plan.

Las emisiones en DEV y SANDBOX son ilimitadas: no consumen ni reservan cupo y no alteran estos contadores. El snapshot refleja la ocupación del ciclo de producción.

Consultá también Planes y Precios y el manejo de document-quota-exceeded.

Errores

Status	Descripción
`401`	API key ausente, inválida o revocada
`500`	Error interno al resolver el plan o el consumo

Consultar Plan y Consumo