API: consultar plan y consumo

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

GET /api/v1/documento-electronico/plan-consumo

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

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/documento-electronico/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