> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commercy.com.ar/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes y permisos

> Qué datos puede ver y modificar tu app, y cómo se piden.

Los scopes definen qué datos puede ver y modificar tu app en la tienda de un comerciante. El comerciante los ve, en lenguaje llano, en la pantalla de consentimiento y puede aceptar o rechazar la instalación.

Pedí **sólo los scopes que tu app usa**. Cada scope extra se revisa en la homologación y baja la tasa de instalación.

## Catálogo

| Scope | Qué habilita | Notas |
| - | - | - |
| `read_shops` | Ver las sucursales (nombre, dirección y horarios) y los datos básicos de la tienda. | Está **siempre incluido**: no hace falta pedirlo. |
| `read_products` | Ver productos, variantes, categorías y marcas. | Habilita los webhooks `product.*` y `products.bulk_updated`. |
| `write_products` | Crear, editar y dar de baja productos. | Incluye `read_products`. Los productos que crea la app no llevan precio ni costo: los precios van por `write_prices`. |
| `read_prices` | Ver los precios de venta resueltos por sucursal y lista de precios. | |
| `write_prices` | Cambiar los precios de venta. | Incluye `read_prices`. |
| `read_stock` | Ver el stock de cada sucursal (existencias y disponible). | Habilita el webhook `stock.changed`. |
| `write_stock` | Ajustar el stock. | Incluye `read_stock`. |
| `read_orders` | Ver las ventas, con nombre, email, teléfono y dirección de cada comprador. | Habilita los webhooks `order.*`. |
| `write_orders` | Cambiar el estado de las ventas y cargar los datos de envío. | Incluye `read_orders`. No permite cancelar, devolver ni reembolsar. |
| `read_customers` | Ver los clientes y sus datos de contacto. | Habilita los webhooks `customer.*`. |
| `write_customers` | Crear y editar clientes. | Incluye `read_customers`. |
| `read_costs` | Ver costos y márgenes: `cost` en productos y variantes, y `cogs` en las líneas de las ventas. | **Scope sensible**, ver abajo. |

## Reglas

* **`write_x` implica `read_x`.** Si pedís `write_stock` ya podés leer el stock; no hace falta pedir también `read_stock`.
* **`read_shops` siempre está.** Todas las instalaciones pueden listar las sucursales.
* **`read_costs` no va solo.** Sólo se puede pedir junto con `read_products` o `read_orders` (o sus versiones `write_`). Aparece destacado en la pantalla de consentimiento con un aviso de que se trata de información sensible, y hay que justificarlo en la revisión.
* **Los webhooks de un recurso exigen su `read_`.** Una instalación sin `read_orders` no recibe `order.created`, aunque esté suscripta. Los 4 webhooks obligatorios se entregan a todas las instalaciones.
* **Nunca se exponen datos fiscales.** Ningún recurso de la API v1 devuelve CUIT, CUIL, razón social ni condición frente al IVA. Sólo se informa un DNI cuando el comerciante lo cargó como DNI.
* **La instalación ve todas las sucursales del comercio**, no se puede acotar a algunas.
* **Los scopes no se reducen en silencio.** Si ampliás los scopes de tu app, los comerciantes ya instalados mantienen los anteriores hasta que vuelvan a autorizar.

## Qué pasa si falta un scope

Si tu token no tiene el scope que necesita un endpoint, la API responde `403 insufficient_scope` e indica cuál falta:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "La instalación no tiene el scope read_orders",
    "details": [{ "required_scope": "read_orders" }],
    "request_id": "0b6f6d3e-6c0e-4c0b-9a5a-6a8f6d1c2a10"
  }
}
```

Los scopes de una instalación están en el campo `scope` de la respuesta del token. Para pedir más, ampliá los scopes de tu app en el portal y pedile al comerciante que vuelva a autorizarla (ver [Autenticación OAuth](/oauth)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.