Manual del backoffice

El backoffice (base /v1/imprenta/backoffice) es la consola de administración de la imprenta. Hay dos roles:

Rol	Puede
ZENTTO_SUPERADMIN (dueño)	Generar series, definir tarifas, reasignar/extender series, administrar distribuidores y comisiones, ver el metering global.
DISTRIBUIDOR (revendedor)	Consultar/asignar series ya generadas y ver el consumo de su cartera. No genera series ni define tarifas (protección anti-IDOR: solo ve su cartera).

Series propias de números de control

Pantalla Backoffice → Series.

Acción	Endpoint	Rol
Listar series	GET /series (filtro companyId, q)	Ambos
Generar serie	POST /series	Solo SUPERADMIN
Actualizar (nombre, prefijo, estado)	PUT /series/{id}	Ambos (distribuidor solo su cartera)
Reasignar a otra empresa	POST /series/{id}/reasignar	Solo SUPERADMIN
Extender el tope del rango	POST /series/{id}/extender	Solo SUPERADMIN

Cada serie tiene Serie, TipoDocumento, Prefijo, rango [Desde, Hasta], Correlativo (último consumido), Restantes y Estado (ACTIVA · AGOTADA · SUSPENDIDA).

Generar serie (solo superadmin): elige la empresa-cliente, el tipo de documento, la serie, el prefijo y el rango. El correlativo arranca en Desde con la primera emisión.

Asignación a clientes

Las series se asignan a una empresa-cliente (CompanyId). Con reasignar se traspasa una serie a otra empresa; con extender se aumenta el tope (Hasta) sin reasignar ni recrear.

Consumo / metering

Pantalla Backoffice → Consumo. Cada número de control emitido genera un evento facturable en imprenta."ConsumoControl".

Vista	Endpoint
Detalle de eventos	GET /consumo (filtros companyId, desde, hasta)
Resumen por cliente (para facturar)	GET /consumo/resumen

El resumen muestra por empresa: Emitidos, Restantes, PrecioPorControl, IncluidoGratis y MontoEstimado = (Emitidos − IncluidoGratis) × PrecioPorControl, más KPIs globales (clientes, total emitidos, ingreso estimado).

Tarifas

Pantalla Backoffice → Tarifas (GET/POST /tarifas). Cada plan (TarifaPlan) define:

• Moneda, PrecioPorControl (precio por número de control).
• TamanoBloque + PrecioBloque (precio por volumen).
• IncluidoGratis (números de control gratis por periodo).

CompanyId = 0 es la tarifa por defecto global; las empresas sin plan propio caen a esta. Crear/actualizar tarifas es solo SUPERADMIN.

Integradores y tokens

Pantalla Backoffice → Integradores. Un integrador es una empresa-cliente que consume la API de terceros (/api/*).

Acción	Endpoint
Listar / crear	GET/POST /integradores
Detalle / actualizar / suspender	GET/PUT/DELETE /integradores/{id}
Listar tokens	GET /integradores/{id}/tokens
Emitir token (devuelve el secret una sola vez)	POST /integradores/{id}/tokens
Revocar token	POST /integradores/{id}/tokens/{tid}/revocar
Usuarios del integrador	GET/POST /integradores/{id}/usuarios

Cada token tiene TokenUsuario (público), Ambiente (demo/production) y Estado (ACTIVO/REVOCADO). El secret se muestra una sola vez al emitirlo y nunca se vuelve a recuperar.

Distribuidores y cartera

Pantalla Backoffice → Distribuidores (solo SUPERADMIN administra; el distribuidor consulta su cartera).

Acción	Endpoint
Listar / alta de distribuidor	GET/POST /distribuidores
Suspender distribuidor	DELETE /distribuidores/{userId}
Ver cartera	GET /distribuidores/{userId}/cartera
Asignar empresa a la cartera	POST /distribuidores/{userId}/cartera
Quitar empresa de la cartera	DELETE /distribuidores/{userId}/cartera/{companyId}

La cartera es el conjunto de empresas-cliente de un distribuidor; sus permisos quedan acotados a esas empresas.

Comisiones

Pantalla Backoffice → Comisiones. Las comisiones se calculan sobre los números de control emitidos por la cartera del distribuidor.

Acción	Endpoint	Rol
Listar planes	GET /comisiones/planes	Ambos (distribuidor solo el suyo)
Definir plan	POST /comisiones/planes	Solo SUPERADMIN
Resumen devengado	GET /comisiones/resumen (distribuidor, periodo)	Ambos
Liquidaciones	GET /comisiones/liquidaciones	Ambos
Liquidar (marcar PAGADA)	POST /comisiones/liquidar	Solo SUPERADMIN

El plan (ComisionPlan) tiene Modo (PORCENTAJE o MONTO), Porcentaje, MontoPorControl/MontoPorBloque. Las liquidaciones pasan por estados DEVENGADA → PENDIENTE → PAGADA.