Scopes

Cada API key tiene asociada una lista de scopes que delimitan qué endpoints puede invocar. El servidor verifica el scope requerido por cada endpoint y devuelve 403 Forbidden si la API key no lo tiene.

Scopes disponibles

Cambio incompatible desde v1.2: emitir NC o ND ya no lo habilita facturas:write. Una key con solo facturas:write recibe 403 al enviar tipo: "NotaCredito" o "NotaDebito". Ver el changelog.

Por qué NC/ND tienen su propio scope

POST /facturas es un único endpoint, pero según el tipo hace dos cosas muy distintas:

• FE/TE: registra una venta nueva. Es la operación cotidiana.
• NC/ND: modifica un comprobante ya emitido — típicamente devuelve dinero (NC) o cobra un monto adicional al cliente (ND) sobre un comprobante ya remitido a Hacienda. Es un permiso más sensible: una key comprometida que solo emite no puede anular ventas ajenas retroactivamente; una que además emite NC, sí.

Separar FE de TE, en cambio, no aportaría protección alguna: son la misma operación (registrar una venta) con o sin cliente identificado — dividir sus scopes solo agregaría fricción sin ganar seguridad.

facturas-compra:* es un par de scopes aparte porque la operación es distinta en su raíz: el comprobante se emite a nombre de un tercero (el proveedor), no de una venta propia. Mezclarlo con los scopes de venta permitiría que una key de POS normal emitiera, de forma involuntaria, comprobantes fiscales atribuidos a un proveedor. Ver Emitir factura de compra.

mensajes:* va aparte porque no corresponde a una venta: aceptar o rechazar la factura de un proveedor determina si esa compra se toma como gasto, y se emite a nombre propio contra un comprobante ajeno. Una key destinada a facturar no debería poder responder ante el fisco por las compras del comercio. Ver Aceptar o rechazar la factura de un proveedor.

catalogo:* también va aparte, y por una razón distinta: escribir aquí no emite nada fiscal, pero afecta datos maestros —precio, CABYS, impuestos— que después alimentan cada comprobante que se emita con ese producto. Una key destinada únicamente a facturar no debería poder modificar el precio ni el CABYS del catálogo del comercio. Ver Crear o actualizar producto.

Combinaciones recomendadas

Principio de menor privilegio: deben solicitarse únicamente los scopes que la integración realmente necesita. Un e-commerce que nunca realiza devoluciones por API no necesita notas:write, aunque emita cientos de tiquetes al día. Si más adelante se requieren scopes adicionales, la API key puede rotarse con scopes ampliados.