Pular para conteúdo

Permissões dos apps

Todo app OAuth2 declara no cadastro as permissões (escopos) de que precisa. O seller vê essa lista ao autorizar, e o access_token carrega só o que foi autorizado. Uma chamada sem a permissão que a operação exige recebe 403 com o campo required_scope.

Ações sensíveis ganharam permissão própria — corte em 26/12/2026

Emitir nota fiscal, cancelar nota fiscal, cancelar pedido e ver dados pessoais do comprador passaram a ter permissão própria em 27/09/2026. Até 26/12/2026 a permissão antiga continua valendo. A partir de 26/12/2026, só a nova. Veja o que fazer antes do corte.

Permissão O que libera
ad:view Ver anúncios
ad:edit Alterar anúncios
erp:view Ver jobs de importação do ERP (Bling)
erp:edit Reprocessar e cancelar jobs de importação do ERP (Bling)
freight:view Cotar frete
freight:edit Reservada: sem operação de parceiro hoje
invoice:view Ver notas fiscais e baixar DANFE e XML
invoice:edit Alterar notas fiscais. Até 26/12/2026 também emite e cancela
invoice:issue Emitir nota fiscal: gerar, autorizar, carta de correção, estorno, complementar e devolução
invoice:cancel Cancelar nota fiscal
notification:view Ver webhooks de notificação
notification:edit Configurar webhooks de notificação
order:view Ver pedidos. A partir de 26/12/2026, sem order:customer-data, os dados pessoais do comprador vêm mascarados
order:edit Criar pedido e alterar situação (faturado, enviado, entregue, pago, devolvido) e notas. Até 26/12/2026 também cancela
order:cancel Cancelar pedido
order:customer-data Ver documento, e-mail, telefones, data de nascimento e endereço do comprador sem máscara
platform:view Ver plataformas
price:view Ver preços
price:edit Alterar preços
product:view Ver produtos, SKUs, marcas, categorias e atributos
product:edit Criar e alterar produtos, SKUs, marcas, categorias e atributos
promotion:view Ver promoções
promotion:edit Criar e alterar promoções
stock:view Ver estoque
stock:edit Alterar estoque
tag:view Ver etiquetas
tag:edit Gerar e alterar etiquetas

O que muda em 26/12/2026

Operação Chamada Até 26/12/2026 A partir de 26/12/2026
Emitir nota de venda POST /integration/invoicer/invoices/sale invoice:edit ou invoice:issue invoice:issue
Gerar nota do pedido GET /integration/invoicer/invoices/invoice-order/{id} invoice:edit ou invoice:issue invoice:issue
Autorizar nota GET /integration/invoicer/invoices/authorize/{id} invoice:edit ou invoice:issue invoice:issue
Carta de correção POST /integration/invoicer/invoices/correction-letter/{id} invoice:edit ou invoice:issue invoice:issue
Estorno POST /integration/invoicer/invoices/reversal invoice:edit ou invoice:issue invoice:issue
Nota complementar POST /integration/invoicer/invoices/complementary invoice:edit ou invoice:issue invoice:issue
Devolução POST /integration/invoicer/invoices/devolution invoice:edit ou invoice:issue invoice:issue
Cancelar nota DELETE /integration/invoicer/invoices/cancel-invoice/{id} invoice:edit ou invoice:cancel invoice:cancel
Cancelar pedido PUT /integration/orders/cancel/{orderId} order:edit ou order:cancel order:cancel
Dados do comprador GET /integration/orders/{orderId} e POST /integration/orders/list/search completos com order:view completos só com order:customer-data; sem ela, mascarados

Como o comprador vem mascarado

Campo Sem order:customer-data Exemplo
Documento (CPF/CNPJ/IE) no JSON, o campo number guarda só os dígitos que sobrevivem (2 últimos); o type continua declarado CPF 123.456.789-01 → documents[].number: "01"
E-mail primeiro caractere + *** + @ + domínio joao@ex.com → j***@ex.com
Telefone no JSON, o campo ddd não aparece e number guarda só os 4 últimos dígitos (sem pontuação) (11) 98765-4321 → phones[].number: "4321", sem ddd
Data de nascimento campo dateOfBirth ausente do JSON (não é enviado como null) —
Logradouro, número, complemento "***" —
Nome, cidade, UF, CEP inalterados —

O que fazer antes do corte

  1. Não edite as permissões do app para acrescentar as novas. Em 27/09/2026 a Gubee acrescentou ao cadastro de todo app a permissão nova correspondente à antiga que ele já tinha: invoice:edit → invoice:issue e invoice:cancel; order:edit → order:cancel e order:customer-data; order:view → order:customer-data. Editar as permissões de um app revoga na hora a autorização de todos os sellers conectados (ver Criar e gerenciar apps). Se o app não precisa de uma das novas, remova-a sabendo desse efeito.
  2. Peça a cada seller conectado que autorize o app de novo antes de 26/12/2026. A renovação com refresh_token mantém as permissões da autorização original; só uma nova autorização traz as novas.
  3. Trate o 403 com required_scope (abaixo).

Resposta 403

{
  "status": 403,
  "required_scope": "invoice:issue"
}

O corpo pode trazer outros campos. required_scope lista as permissões aceitas pela operação, separadas por vírgula — durante a convivência, por exemplo, invoice:edit,invoice:issue.