Tezora

Autenticación y alcances

Cada petición lleva la llave de una credencial en la cabecera Authorization: Bearer tzk_….

Una persona administradora de la empresa crea la credencial en el menú Empresa > Configuración, pestaña Integraciones, con el módulo Facturación por API activo. La credencial define un nombre, el punto de venta desde el que emite y sus alcances. La llave tiene la forma tzk_<prefijo>_<secreto> y se muestra una sola vez; Tezora guarda solo su hash.

El punto de venta de la credencial determina el establecimiento y el correlativo de los documentos. Cada sistema integrado usa su propia credencial y su propio correlativo.

La credencial queda atada a la sucursal de su punto de venta. Una llave ve y opera solo las ventas de su sucursal: GET /sales lista solo esas, y leer, emitir, enviar, corregir o invalidar una venta de otra sucursal responde 403 sale_of_another_branch. Lo mismo rige para los lotes: GET /sales/batches lista solo los enviados por llaves de su sucursal, y leer un lote de otra sucursal responde 403 batch_of_another_branch. Para conciliar la empresa completa se usa una llave por sucursal. Los clientes y los productos son de la empresa y cualquier llave los ve.

Alcance Permite Operaciones
customers:read Consultar los clientes de la empresa. Clientes: Listar, Clientes: Ver
customers:write Registrar y actualizar clientes. Clientes: Crear, Clientes: Actualizar, Clientes: Crear o actualizar en lote, Clientes: Crear o actualizar
catalog:read Consultar productos y servicios. Productos y servicios: Listar, Productos y servicios: Ver
catalog:write Registrar y actualizar productos y servicios. Productos y servicios: Crear, Productos y servicios: Crear o actualizar, Productos y servicios: Actualizar, Productos y servicios: Crear o actualizar en lote
sales:read Consultar ventas y sus documentos tributarios electrónicos. Ventas: Listar, Ventas: Ver, Ventas: Descargar JSON, Ventas: Descargar PDF, Ventas: Compartir, Idempotencia: Buscar por llave, Lotes de ventas: Listar, Lotes de ventas: Ver, Notas de crédito y débito: Descargar JSON, Notas de crédito y débito: Descargar PDF, Notas de crédito y débito: Compartir
sales:write Crear ventas que emiten documentos tributarios electrónicos y notas de ajuste. Ventas: Crear, Ventas: Emitir documento, Ventas: Enviar por correo, Lotes de ventas: Enviar, Notas de crédito y débito: Emitir
documents:invalidate Invalidar documentos ya emitidos ante Hacienda. No se concede por defecto. Invalidación: Invalidar venta, Invalidación: Invalidar nota
Ninguno; basta una llave válida. Autenticación: Ver la llave actual, Catálogos de Hacienda: Ver

La llave no vence. La rotación consiste en crear una credencial nueva con los mismos alcances, desplegar la llave nueva, comprobarla con GET /me y revocar la anterior. Una credencial revocada responde 401 de inmediato. Una empresa admite hasta 20 credenciales activas. Sin el módulo, todas las llaves responden 403 module_inactive; con el acceso de la empresa vencido o suspendido, 403 company_access_suspended.

Ambiente de Hacienda

Cada empresa emite en el ambiente que tiene configurado: pruebas (00) o producción (01). La llave no elige el ambiente. Lo facturado mientras la empresa está en pruebas no tiene valor fiscal.

GET /me informa el ambiente de la llave. El paso a producción se confirma cuando hacienda_environment.value es 01.