Escopos

Cada token e cada app tem uma lista de escopos. Peça só o necessário: a TF recusa apps com escopos além do que a função exige.

Escopo	Permite	Endpoints	Eventos
store:read	Ver dados da loja	GET /store	—
products:read	Ler produtos, variantes, SKUs e preços.	GET /products GET /products/{product_id} GET /variants	product.created product.updated product.deleted
products:write	Criar, editar e arquivar produtos; definir preços por SKU.Inclui `products:read`.	POST /products PATCH /products/{product_id} DELETE /products/{product_id} POST /prices/batch	—
inventory:read	Ler o estoque por SKU (em mãos, reservado, disponível).	GET /inventory_levels	inventory.updated
inventory:write	Definir ou ajustar o estoque por SKU.Inclui `inventory:read`.	POST /inventory_levels/set POST /inventory_levels/adjust	—
orders:read	Ler pedidos, itens, pagamento, NF-e e envios, com os dados do comprador mascarados. Ler a fila de eventos.	GET /orders GET /orders/{order_id} GET /events	order.created order.paid order.updated order.cancelled refund.completed invoice.authorized invoice.cancelled fulfillment.shipped fulfillment.delivered app.uninstalled
orders:write	Confirmar a importação (acknowledge) e cancelar ou pedir o cancelamento.Inclui `orders:read`.	POST /orders/{order_id}/acknowledge POST /orders/{order_id}/cancel	—
orders.pii:readDados pessoais	Ver nome, CPF/CNPJ, IE, e-mail, telefone e endereços do comprador. Necessário para emitir NF-e e etiquetas.	—	—
invoices:write	Enviar a NF-e emitida no ERP e informar o cancelamento dela.Inclui `orders:read`.	POST /orders/{order_id}/invoices POST /orders/{order_id}/invoices/{access_key}/cancel	—
fulfillments:write	Informar o envio (transportadora, rastreio) e a entrega.Inclui `orders:read`.	POST /orders/{order_id}/fulfillments POST /orders/{order_id}/fulfillments/delivered	—
webhooks:manage	Criar, listar e excluir os próprios endpoints de webhook.	GET /webhook_endpoints POST /webhook_endpoints DELETE /webhook_endpoints/{endpoint_id}	—

Dados pessoais (LGPD)

orders.pii:read é o único escopo com dados pessoais. Sem ele, GET /orders/{order_id} devolve nome, documento, e-mail, telefone e endereço mascarados. A tela de consentimento destaca esse escopo e, para apps parceiros, a TF exige a justificativa de uso. Webhooks nunca carregam dados pessoais.

Boas práticas

Um app de relatórios precisa de leitura (orders:read, products:read, inventory:read), não de escrita.
Só peça orders.pii:read se você emite NF-e, etiquetas ou faz atendimento ao comprador.
Faltando um escopo, a API responde 403 insufficient_scope; a resposta diz qual escopo falta.

Escopos

Cada token e cada app tem uma lista de escopos. Peça só o necessário: a TF recusa apps com escopos além do que a função exige.

Escopo	Permite	Endpoints	Eventos
store:read	Ver dados da loja	GET /store	—
products:read	Ler produtos, variantes, SKUs e preços.	GET /products GET /products/{product_id} GET /variants	product.created product.updated product.deleted
products:write	Criar, editar e arquivar produtos; definir preços por SKU.Inclui `products:read`.	POST /products PATCH /products/{product_id} DELETE /products/{product_id} POST /prices/batch	—
inventory:read	Ler o estoque por SKU (em mãos, reservado, disponível).	GET /inventory_levels	inventory.updated
inventory:write	Definir ou ajustar o estoque por SKU.Inclui `inventory:read`.	POST /inventory_levels/set POST /inventory_levels/adjust	—
orders:read	Ler pedidos, itens, pagamento, NF-e e envios, com os dados do comprador mascarados. Ler a fila de eventos.	GET /orders GET /orders/{order_id} GET /events	order.created order.paid order.updated order.cancelled refund.completed invoice.authorized invoice.cancelled fulfillment.shipped fulfillment.delivered app.uninstalled
orders:write	Confirmar a importação (acknowledge) e cancelar ou pedir o cancelamento.Inclui `orders:read`.	POST /orders/{order_id}/acknowledge POST /orders/{order_id}/cancel	—
orders.pii:readDados pessoais	Ver nome, CPF/CNPJ, IE, e-mail, telefone e endereços do comprador. Necessário para emitir NF-e e etiquetas.	—	—
invoices:write	Enviar a NF-e emitida no ERP e informar o cancelamento dela.Inclui `orders:read`.	POST /orders/{order_id}/invoices POST /orders/{order_id}/invoices/{access_key}/cancel	—
fulfillments:write	Informar o envio (transportadora, rastreio) e a entrega.Inclui `orders:read`.	POST /orders/{order_id}/fulfillments POST /orders/{order_id}/fulfillments/delivered	—
webhooks:manage	Criar, listar e excluir os próprios endpoints de webhook.	GET /webhook_endpoints POST /webhook_endpoints DELETE /webhook_endpoints/{endpoint_id}	—

Dados pessoais (LGPD)

Boas práticas

Um app de relatórios precisa de leitura (orders:read, products:read, inventory:read), não de escrita.
Só peça orders.pii:read se você emite NF-e, etiquetas ou faz atendimento ao comprador.
Faltando um escopo, a API responde 403 insufficient_scope; a resposta diz qual escopo falta.