bling-docs-mcp 1.0.0

package/docs/changelogs_full.md

@@ -0,0 +1,90 @@
+# Changelogs de API
+
+> **Seção:** changelogs
+> **Atualizado:** 2026-03-07
+
+---
+## 2026
+v339
+### Ajuste no retorno do campo de documento referenciado em itens de notas fiscais
+Lançamento: 11/02/2026 | Publicação: 11/02/2026
+O campo `documentoReferenciado` foi removido do retorno de itens de notas fiscais nos _endpoints_ `GET /nfe` e `GET /nfe/{idNotaFiscal}`.
+v339
+### Adicionada validação de campos IBS/CBS na criação de uma NFS-e
+Lançamento: 11/02/2026 | Publicação: 11/02/2026
+Adicionada validação dos campos de tributação IBS/CBS (Reforma Tributária) no _endpoint_ `POST /nfse`, garantindo compatibilidade entre código NBS, indicador de operação, CST e classificação tributária.
+v339
+### Adicionado filtro por ID da unidade de negócio na obtenção múltipla de pedidos de venda
+Lançamento: 11/02/2026 | Publicação: 11/02/2026
+Adicionado filtro por `idUnidadeNegocio` referente à filial na obtenção múltipla de pedidos de venda por meio do _endpoint_ `GET /pedidos/vendas`.
+* * *
+v338
+### Removida a formatação do CEP nos endpoints de notas fiscais
+Lançamento: 28/01/2026 | Publicação: 28/01/2026
+Removida a formatação dos campos CEP no retorno dos _endpoints_ `GET /nfe`, `GET /nfce`, `GET /nfe/{idNotaFiscal}` e `GET /nfce/{idNotaFiscalConsumidor}`.
+v338
+### Adicionado parâmetro accessKey nos campos linkDanfe e linkPDF na obtenção de NF-e
+Lançamento: 06/02/2026 | Publicação: 09/02/2026
+Os campos `linkDanfe` e `linkPDF` retornados no _endpoint_ `GET /nfe/{idNotaFiscal}` passam a incluir o parâmetro de _query_ `accessKey` na URL. Com isso, o tamanho dos links pode aumentar em até 200 caracteres. O parâmetro permite acesso seguro à visualização do documento.
+* * *
+v337
+### Adicionado campo indicador de operação na API de configurações de NFS-e
+Lançamento: 14/01/2026 | Publicação: 14/01/2026
+Os _endpoints_ `GET /nfse/configuracoes` e `PUT /nfse/configuracoes` agora possuem o campo **indicadorOperacao** (Indicador de Operação da Reforma Tributária) para cada tributo configurado no objeto `ISS.tributos`.
+v337
+### Adicionados campos de tributação IBS/CBS para notas fiscais de serviço
+Lançamento: 14/01/2026 | Publicação: 14/01/2026
+Adicionado suporte ao objeto `tributacaoIbsCbs` no endpoint `POST /nfse`, permitindo informar os dados de Tributação IBS/CBS (Imposto sobre Bens e Serviços e Contribuição sobre Bens e Serviços) conforme a nova legislação tributária.
+### Novo objeto disponível
+O objeto `tributacaoIbsCbs` é **opcional** e deve ser informado apenas quando o município do prestador exigir conformidade com IBS/CBS.
+**Exemplo de uso:**
+### Principais campos
+Campo | Descrição  
+---|---  
+`indicadorOperacao` | Código que indica onde a operação será realizada (ex: "20201" para operações nacionais)  
+`tipoOperacao` | Tipo de operação (1 = Tributado, 2 = Não Tributado, 3 = Imune)  
+`tipoEnteGovernamental` | Tipo de ente governamental quando aplicável (1 = Federal, 2 = Estadual, 3 = Distrito Federal, 4 = Municipal)  
+`codigoSituacaoTributaria` | CST - Código de Situação Tributária (ex: "000" = Tributação integral, "200" = Alíquota reduzida)  
+`classificacaoTributaria` | Classificação específica dentro do CST (ex: "000001", "200029")  
+### Campos adicionais para situações específicas
+  * **Diferimento** (CST 515): `percentualDiferimentoEstadual`, `percentualDiferimentoMunicipal`, `percentualDiferimentoCBS`
+  * **Suspensão com regime regular** (CST 550): `cstRegimeRegular`, `classificacaoTributariaRegular`
+
+
+Consulte a Referência da API para a lista completa de campos e suas descrições.
+v337
+### Permite enviar o ID da unidade de negócio ao salvar ou editar um pedido de venda
+Lançamento: 14/01/2026 | Publicação: 14/01/2026
+O campo `unidadeNegocio.id` foi adicionado nos _endpoints_ `GET /pedidos/vendas/:idPedidoVenda`, `POST /pedidos/vendas` e `PUT /pedidos/vendas/:idPedidoVenda`.
+v337
+### Permite enviar o ID da unidade de negócio ao salvar uma proposta comercial
+Lançamento: 14/01/2026 | Publicação: 14/01/2026
+O campo `unidadeNegocio.id` foi adicionado nos _endpoints_ `GET /propostas-comerciais/:idOrcamento` e `POST /propostas-comerciais`.
+v337
+### Alterado filtro de situação da conciliação na obtenção múltipla de caixas
+Lançamento: 14/01/2026 | Publicação: 14/01/2026
+O parâmetro `conciliados` foi alterado para `situacaoConciliacao` e agora permite o filtro por todas situações de conciliação.
+v337
+### Adicionado o ID da unidade de negócio na obtenção de um canal de venda
+Lançamento: 16/01/2026 | Publicação: 16/01/2026
+O campo `idUnidadeNegocio` referente à filial foi adicionado na obtenção dos detalhes de um canal de venda pelo endpoint `GET /canais-venda/{idCanalVenda}`.
+* * *
+v336
+### Adicionado parâmetro para controlar envio de e-mail no envio de NF-e
+Lançamento: 05/01/2026 | Publicação: 05/01/2026
+O _endpoint_ `POST /nfe/{idNotaFiscal}/enviar` agora aceita o parâmetro **enviarEmail** (query), permitindo controlar se o e-mail deve ser enviado ao destinatário após a emissão da nota fiscal.
+### Parâmetro
+Campo | Tipo | Descrição  
+---|---|---  
+`enviarEmail` | boolean | Define se deve enviar e-mail após a emissão da nota fiscal  
+**Valores:**
+  * `true`: Envia e-mail ao destinatário
+  * `false`: Não envia e-mail
+  * Não informado: Utiliza a configuração padrão do sistema
+
+
+### Exemplo de uso
+**Enviar nota fiscal COM envio de e-mail:**
+**Enviar nota fiscal SEM envio de e-mail:**
+**Enviar nota fiscal usando configuração padrão:**
+© 2026 Bling - [Política de privacidade](https://www.bling.com.br/politicas) - [Termos de serviço](https://www.bling.com.br/termos-de-uso)

package/docs/guias_como_utilizar_os_tokens.md

@@ -0,0 +1,20 @@
+# Como utilizar os tokens
+
+> **Seção:** Guia
+> **Atualizado:** 2026-03-07
+
+---
+## Como utilizar os tokens
+O tipo de token fornecido pelo protocolo OAuth é o Bearer, portanto, utilize o esquema "Bearer" de autenticação HTTP, inserindo a chave de acesso no cabeçalho da requisição, veja o formato abaixo.
+`GET /Api/v3/[caminho_da_api_desejada]`
+**Host** : [https://api.bling.com.br](https://api.bling.com.br)  
+**Header** : `Authorization: Bearer [access_token]`
+Abaixo contempla um exemplo de uma requisição cURL para a API de contatos.
+```bash
+curl --location --request GET 'https://api.bling.com.br/Api/v3/contatos'
+	--header 'Authorization: Bearer 4a9de71b8aaf91c8ebbf830888354d5479e83a01'
+
+```
+
+Possíveis erros e exceções com relação ao uso destes _tokens_ são tratados [aqui](https://developer.bling.com.br/aplicativos#token-expirou).
+© 2026 Bling - [Política de privacidade](https://www.bling.com.br/politicas) - [Termos de serviço](https://www.bling.com.br/termos-de-uso)

package/docs/guias_full.md

@@ -0,0 +1,72 @@
+# Guia
+
+> **Seção:** guias
+> **Atualizado:** 2026-03-07
+
+---
+## Introdução
+Bem-vindo ao Bling Developers!
+Neste repositório você irá encontrar toda a documentação necessária para integrar com o Bling. Por meio da nossa API é possível consumir recursos do Bling para atender as necessidades da sua empresa/clientes. Estruturada no padrão REST, onde você poderá utilizar métodos GET, POST, PUT, PATCH e DELETE, por meio de autenticação OAuth 2.0. A organização dessa documentação contempla informações sobre o Bling, o conceito de API e como utilizá-la.
+## Sobre o Bling
+O Bling é um ERP que facilita a emissão de notas fiscais e boletos, além de realizar integrações nativas com plataformas de e-commerce, marketplaces e logísticas, tais como por API.
+Com o Bling é possível gerenciar todo o processo de compra e venda dos produtos de maneira facilitada, bem como possuir relatórios que auxiliam na análise e gestão empresarial.
+## O que é API
+API (_Application Programming Interface_) é um conjunto de protocolos e ferramentas que facilitam a integração entre softwares e permitem que uma solução se comunique com outros produtos e serviços sem precisar acessar a interface gráfica da solução diretamente, tudo isso através do que chamamos de interface.
+O intuito de uma API é a troca de dados entre sistemas implementados em diferentes tecnologias que utilizam o mesmo protocolo de comunicação.
+No Bling, usamos a API para integrar as nossas soluções com nossos parceiros, sendo possível criar processos de automatização, atualização ou análise de registros, criação de novos aplicativos e uma vasta gama de soluções podem ser criadas para facilitar a vida dos nossos clientes.
+## Para quem é destinada a API
+A API é pública e está disponível para quem deseja estender as funcionalidades já existentes no Bling, podendo criar plugins ou componentes em sistemas próprios.
+A utilização da API permite a realização de operações de forma independente, visto que os recursos do Bling serão controlados pelo cliente da API, podendo utilizar a API para implementar soluções próprias.
+## Padrão REST
+No Bling, usamos um padrão de arquitetura para a API chamado de REST (_Representational State Transfer_).
+O REST ignora os detalhes da implementação do componente e a sintaxe de protocolo visando focar nos papéis dos componentes, nas restrições sobre sua interação e na sua interpretação de elementos de dados significativos. Ou seja, o usuário deve fazer uma requisição HTTP para algum _endpoint_ disponível para solicitar, enviar ou modificar dados do sistema, então o _endpoint_ de API transfere uma informação do estado do recurso ao solicitante. Essa informação é entregue via HTTP utilizando um formato de mensagem do tipo JSON.
+Exemplo de requisição, abaixo:
+`GET https://api.bling.com.br/Api/v3/produtos`
+Resposta do servidor:
+```json
+{
+	"data": {
+		"id": 1,
+		"nome": "Caderno universitário, 100 Folhas"
+	}
+}
+
+```
+
+Cada requisição consiste em um método HTTP, um Header, uma URI e um Body que são explicados a seguir:
+O método HTTP diferencia a ação que o usuário deseja realizar pela API, sendo eles:
+  * **GET** : Ação para obter uma ou mais entidades
+  * **POST** : Ação para criar uma entidade ou executar uma ação
+  * **PUT** : Ação para atualizar todos os dados de uma entidade
+  * **PATCH** : Ação para atualizar parcialmente os dados de uma entidade
+  * **DELETE** : Ação para remover uma entidade
+
+
+**Header** : É o cabeçalho da requisição, as informações enviadas no _header_ podem ser utilizadas para o servidor interpretar a requisição. Exemplo: `Content-Type: application/json`.   
+**URI** : Define o caminho onde a requisição irá ocorrer, por exemplo, em uma requisição para obtenção dos dados de produtos, a URI seria: `/Api/v3/produtos`.   
+**Body** : É o corpo da requisição, nele são informados os dados que serão enviados para o sistema e também são retornadas as informações da resposta de uma requisição.
+# Autenticação
+## Fundamentos
+Dentro dos fundamentos da segurança entre redes, a API dispõe de regras que assegurem a confidencialidade, a integridade e a acessibilidade das informações disponíveis:
+  * **Confidencialidade** : É a estrita regra de manter uma autorização através de uma autenticação de acesso ao recurso.
+  * **Integridade** : Assegura que os dados não poderão ser alterados sem as devidas permissões, ou que os dados não sejam visualizados em conta diferente a qual está solicitando o uso ao recurso.
+  * **Acessibilidade** : Permite a cada usuário uma disponibilidade de acesso sem prejudicar o serviço que por consequência afeta todos os outros usuários dos nossos recursos. Mantemos as informações dos nossos usuários seguras pela utilização de HTTPS e por _tokens_ gerados por aplicativos OAuth.
+
+
+## OAuth e tokens de acesso
+OAuth 2.0 é um protocolo de autorização utilizado para permitir que aplicativos de terceiros tenham acesso limitado aos recursos dos usuários do sistema, no qual o sistema detentor dos dados do usuário fica encarregado de realizar a autenticação e, por fim, após a aprovação deste usuário, conceder a autorização para o aplicativo acessar os seus recursos.
+Descubra como criar seus aplicativos e gerar os _tokens_ de acesso através do [fluxo de autorização](https://developer.bling.com.br/aplicativos#fluxo-de-autoriza%C3%A7%C3%A3o). Em resumo, quando um usuário autoriza determinado aplicativo a acessar os seus recursos, este aplicativo conseguirá obter os _tokens_ necessários para realizar as requisições e acessar o recurso. Veja abaixo como utilizar o Bearer _token_ gerado pelos aplicativos OAuth.
+## Como utilizar os tokens
+O tipo de token fornecido pelo protocolo OAuth é o Bearer, portanto, utilize o esquema "Bearer" de autenticação HTTP, inserindo a chave de acesso no cabeçalho da requisição, veja o formato abaixo.
+`GET /Api/v3/[caminho_da_api_desejada]`
+**Host** : [https://api.bling.com.br](https://api.bling.com.br)  
+**Header** : `Authorization: Bearer [access_token]`
+Abaixo contempla um exemplo de uma requisição cURL para a API de contatos.
+```bash
+curl --location --request GET 'https://api.bling.com.br/Api/v3/contatos'
+	--header 'Authorization: Bearer 4a9de71b8aaf91c8ebbf830888354d5479e83a01'
+
+```
+
+Possíveis erros e exceções com relação ao uso destes _tokens_ são tratados [aqui](https://developer.bling.com.br/aplicativos#token-expirou).
+© 2026 Bling - [Política de privacidade](https://www.bling.com.br/politicas) - [Termos de serviço](https://www.bling.com.br/termos-de-uso)

package/docs/guias_fundamentos.md

@@ -0,0 +1,11 @@
+# Fundamentos
+
+> **Seção:** Guia
+> **Atualizado:** 2026-03-07
+
+---
+## Fundamentos
+Dentro dos fundamentos da segurança entre redes, a API dispõe de regras que assegurem a confidencialidade, a integridade e a acessibilidade das informações disponíveis:
+  * **Confidencialidade** : É a estrita regra de manter uma autorização através de uma autenticação de acesso ao recurso.
+  * **Integridade** : Assegura que os dados não poderão ser alterados sem as devidas permissões, ou que os dados não sejam visualizados em conta diferente a qual está solicitando o uso ao recurso.
+  * **Acessibilidade** : Permite a cada usuário uma disponibilidade de acesso sem prejudicar o serviço que por consequência afeta todos os outros usuários dos nossos recursos. Mantemos as informações dos nossos usuários seguras pela utilização de HTTPS e por _tokens_ gerados por aplicativos OAuth.

package/docs/guias_introducao.md

@@ -0,0 +1,9 @@
+# Introdução
+
+> **Seção:** Guia
+> **Atualizado:** 2026-03-07
+
+---
+## Introdução
+Bem-vindo ao Bling Developers!
+Neste repositório você irá encontrar toda a documentação necessária para integrar com o Bling. Por meio da nossa API é possível consumir recursos do Bling para atender as necessidades da sua empresa/clientes. Estruturada no padrão REST, onde você poderá utilizar métodos GET, POST, PUT, PATCH e DELETE, por meio de autenticação OAuth 2.0. A organização dessa documentação contempla informações sobre o Bling, o conceito de API e como utilizá-la.

package/docs/guias_o_que_e_api.md

@@ -0,0 +1,10 @@
+# O que é API
+
+> **Seção:** Guia
+> **Atualizado:** 2026-03-07
+
+---
+## O que é API
+API (_Application Programming Interface_) é um conjunto de protocolos e ferramentas que facilitam a integração entre softwares e permitem que uma solução se comunique com outros produtos e serviços sem precisar acessar a interface gráfica da solução diretamente, tudo isso através do que chamamos de interface.
+O intuito de uma API é a troca de dados entre sistemas implementados em diferentes tecnologias que utilizam o mesmo protocolo de comunicação.
+No Bling, usamos a API para integrar as nossas soluções com nossos parceiros, sendo possível criar processos de automatização, atualização ou análise de registros, criação de novos aplicativos e uma vasta gama de soluções podem ser criadas para facilitar a vida dos nossos clientes.

package/docs/guias_oauth_e_tokens_de_acesso.md

@@ -0,0 +1,9 @@
+# OAuth e tokens de acesso
+
+> **Seção:** Guia
+> **Atualizado:** 2026-03-07
+
+---
+## OAuth e tokens de acesso
+OAuth 2.0 é um protocolo de autorização utilizado para permitir que aplicativos de terceiros tenham acesso limitado aos recursos dos usuários do sistema, no qual o sistema detentor dos dados do usuário fica encarregado de realizar a autenticação e, por fim, após a aprovação deste usuário, conceder a autorização para o aplicativo acessar os seus recursos.
+Descubra como criar seus aplicativos e gerar os _tokens_ de acesso através do [fluxo de autorização](https://developer.bling.com.br/aplicativos#fluxo-de-autoriza%C3%A7%C3%A3o). Em resumo, quando um usuário autoriza determinado aplicativo a acessar os seus recursos, este aplicativo conseguirá obter os _tokens_ necessários para realizar as requisições e acessar o recurso. Veja abaixo como utilizar o Bearer _token_ gerado pelos aplicativos OAuth.

package/docs/guias_padrao_rest.md

@@ -0,0 +1,34 @@
+# Padrão REST
+
+> **Seção:** Guia
+> **Atualizado:** 2026-03-07
+
+---
+## Padrão REST
+No Bling, usamos um padrão de arquitetura para a API chamado de REST (_Representational State Transfer_).
+O REST ignora os detalhes da implementação do componente e a sintaxe de protocolo visando focar nos papéis dos componentes, nas restrições sobre sua interação e na sua interpretação de elementos de dados significativos. Ou seja, o usuário deve fazer uma requisição HTTP para algum _endpoint_ disponível para solicitar, enviar ou modificar dados do sistema, então o _endpoint_ de API transfere uma informação do estado do recurso ao solicitante. Essa informação é entregue via HTTP utilizando um formato de mensagem do tipo JSON.
+Exemplo de requisição, abaixo:
+`GET https://api.bling.com.br/Api/v3/produtos`
+Resposta do servidor:
+```json
+{
+	"data": {
+		"id": 1,
+		"nome": "Caderno universitário, 100 Folhas"
+	}
+}
+
+```
+
+Cada requisição consiste em um método HTTP, um Header, uma URI e um Body que são explicados a seguir:
+O método HTTP diferencia a ação que o usuário deseja realizar pela API, sendo eles:
+  * **GET** : Ação para obter uma ou mais entidades
+  * **POST** : Ação para criar uma entidade ou executar uma ação
+  * **PUT** : Ação para atualizar todos os dados de uma entidade
+  * **PATCH** : Ação para atualizar parcialmente os dados de uma entidade
+  * **DELETE** : Ação para remover uma entidade
+
+**Header** : É o cabeçalho da requisição, as informações enviadas no _header_ podem ser utilizadas para o servidor interpretar a requisição. Exemplo: `Content-Type: application/json`.   
+**URI** : Define o caminho onde a requisição irá ocorrer, por exemplo, em uma requisição para obtenção dos dados de produtos, a URI seria: `/Api/v3/produtos`.   
+**Body** : É o corpo da requisição, nele são informados os dados que serão enviados para o sistema e também são retornadas as informações da resposta de uma requisição.
+# Autenticação

package/docs/guias_para_quem_e_destinada_a_api.md

@@ -0,0 +1,9 @@
+# Para quem é destinada a API
+
+> **Seção:** Guia
+> **Atualizado:** 2026-03-07
+
+---
+## Para quem é destinada a API
+A API é pública e está disponível para quem deseja estender as funcionalidades já existentes no Bling, podendo criar plugins ou componentes em sistemas próprios.
+A utilização da API permite a realização de operações de forma independente, visto que os recursos do Bling serão controlados pelo cliente da API, podendo utilizar a API para implementar soluções próprias.

package/docs/guias_sobre_o_bling.md

@@ -0,0 +1,9 @@
+# Sobre o Bling
+
+> **Seção:** Guia
+> **Atualizado:** 2026-03-07
+
+---
+## Sobre o Bling
+O Bling é um ERP que facilita a emissão de notas fiscais e boletos, além de realizar integrações nativas com plataformas de e-commerce, marketplaces e logísticas, tais como por API.
+Com o Bling é possível gerenciar todo o processo de compra e venda dos produtos de maneira facilitada, bem como possuir relatórios que auxiliam na análise e gestão empresarial.

package/docs/limites_filtros.md

@@ -0,0 +1,9 @@
+# Filtros
+
+> **Seção:** Limites
+> **Atualizado:** 2026-03-07
+
+---
+## Filtros
+_Requests_ GET com filtros por período com intervalo superior a um ano retornarão o _status code_ `400`.
+Filtros por período possuem os sufixos "Inicial" ou "Final", ex: `dataInicial`, `dataFinal`, `dataAlteracaoInicial` e `dataAlteracaoFinal`.

package/docs/limites_full.md

@@ -0,0 +1,56 @@
+# Limites
+
+> **Seção:** limites
+> **Atualizado:** 2026-03-07
+
+---
+# Limites
+## Filtros
+_Requests_ GET com filtros por período com intervalo superior a um ano retornarão o _status code_ `400`.
+Filtros por período possuem os sufixos "Inicial" ou "Final", ex: `dataInicial`, `dataFinal`, `dataAlteracaoInicial` e `dataAlteracaoFinal`.
+## Requisições
+A API do Bling possui uma política de segurança para evitar prejudicar o usuário e assegurar a disponibilidade dos nossos recursos.
+Existem limites sobre as requisições de cada conta Bling, não específicas por _endpoints_ , mas sim para todas. Isso significa que em quaisquer módulos que estejam sendo operados, o limite é aplicado para toda a conta.
+Caso um limite seja atingido, os próximos _requests_ não serão processados.
+Os limites por requisições são determinados pelas regras abaixo:
+  * 3 requisições por segundo
+  * 120.000 requisições por dia
+
+
+Exemplos de retornos quando um limite é atingido:
+HTTP Status code: `429` Too Many Requests
+```
+{
+	"error": {
+		"type": "TOO_MANY_REQUESTS",
+		"message": "Limite de requisições atingido.",
+		"description": "O limite de requisições por segundo foi atingido, tente novamente mais tarde.",
+		"limit": 3,
+		"period": "second"
+	}
+}
+
+```
+
+HTTP Status code: `429` Too Many Requests
+```
+{
+	"error": {
+		"type": "TOO_MANY_REQUESTS",
+		"message": "Limite de requisições atingido.",
+		"description": "O limite de requisições por dia foi atingido, tente novamente amanhã.",
+		"limit": 120000,
+		"period": "day"
+	}
+}
+
+```
+
+Também existem cenários aos quais o IP de origem da requisição pode ser bloqueado.
+As regras de bloqueios por IP são especificadas abaixo:
+  * 300 erros em 10 segundos, com duração de 10 minutos.
+  * 600 _requests_ em 10 segundos, com duração de 10 minutos.
+  * 20 _requests_ (`/oauth/token`) em 60 segundos, com duração de 60 minutos.
+
+
+Com o objetivo de manter a integridade do sistema, se uma aplicação continuar ultrapassando os limites definidos, o IP poderá ser bloqueado por tempo indeterminado.

package/docs/limites_requisicoes.md

@@ -0,0 +1,50 @@
+# Requisições
+
+> **Seção:** Limites
+> **Atualizado:** 2026-03-07
+
+---
+## Requisições
+A API do Bling possui uma política de segurança para evitar prejudicar o usuário e assegurar a disponibilidade dos nossos recursos.
+Existem limites sobre as requisições de cada conta Bling, não específicas por _endpoints_ , mas sim para todas. Isso significa que em quaisquer módulos que estejam sendo operados, o limite é aplicado para toda a conta.
+Caso um limite seja atingido, os próximos _requests_ não serão processados.
+Os limites por requisições são determinados pelas regras abaixo:
+  * 3 requisições por segundo
+  * 120.000 requisições por dia
+
+Exemplos de retornos quando um limite é atingido:
+HTTP Status code: `429` Too Many Requests
+```
+{
+	"error": {
+		"type": "TOO_MANY_REQUESTS",
+		"message": "Limite de requisições atingido.",
+		"description": "O limite de requisições por segundo foi atingido, tente novamente mais tarde.",
+		"limit": 3,
+		"period": "second"
+	}
+}
+
+```
+
+HTTP Status code: `429` Too Many Requests
+```
+{
+	"error": {
+		"type": "TOO_MANY_REQUESTS",
+		"message": "Limite de requisições atingido.",
+		"description": "O limite de requisições por dia foi atingido, tente novamente amanhã.",
+		"limit": 120000,
+		"period": "day"
+	}
+}
+
+```
+
+Também existem cenários aos quais o IP de origem da requisição pode ser bloqueado.
+As regras de bloqueios por IP são especificadas abaixo:
+  * 300 erros em 10 segundos, com duração de 10 minutos.
+  * 600 _requests_ em 10 segundos, com duração de 10 minutos.
+  * 20 _requests_ (`/oauth/token`) em 60 segundos, com duração de 60 minutos.
+
+Com o objetivo de manter a integridade do sistema, se uma aplicação continuar ultrapassando os limites definidos, o IP poderá ser bloqueado por tempo indeterminado.

package/docs/migracao-jwt_estrutura_e_tamanho_do_token.md

@@ -0,0 +1,9 @@
+# Estrutura e tamanho do token
+
+> **Seção:** Migração para autenticação JWT
+> **Atualizado:** 2026-03-07
+
+---
+## Estrutura e tamanho do token
+Diferente dos tokens opacos curtos, o JWT carrega um _payload_ de dados em Base64. Com base na estrutura atual de informações contidas (_claims_), o tamanho de um **_token_ JWT** pode variar aproximadamente de **1.500 a 3.000 caracteres**.
+**Atenção: É essencial que sua aplicação esteja preparada para armazenar e trafegar _strings_ desse tamanho nos _headers_ de autorização.**

package/docs/migracao-jwt_full.md

@@ -0,0 +1,107 @@
+# Migração para autenticação JWT
+
+> **Seção:** migracao-jwt
+> **Atualizado:** 2026-03-07
+
+---
+# Migração para autenticação JWT
+## Introdução
+Este guia aborda detalhadamente a ativação e o uso de [JSON Web Tokens](https://www.jwt.io/introduction#what-is-json-web-token) (JWT) na API do Bling além de apresentar as instruções necessárias para a implementação dessa evolução em nossa arquitetura tecnológica e destacar os principais benefícios proporcionados por essa mudança.
+Os principais tópicos da alteração que serão explicados detalhadamente nas seções subsequentes:
+  * A data de bloqueio do uso de _tokens_ opacos está em definição.
+  * A autenticação utilizando _tokens_ opacos está descontinuada.
+  * Alteração no tamanho do token gerado.
+  * Para obter JWT: Inclua o _header_ `enable-jwt: 1` ao obter um _token_ por meio do _endpoint_ `POST /oauth/token`. É fundamental manter este _header_ em todas as requisições subsequentes para garantir que os _tokens_ JWT continuem sendo emitidos após renovações.
+  * Para renovar JWT: Inclua o _header_ `enable-jwt: 1` também na requisição de renovação do _token_ para continuar recebendo _tokens_ JWT.
+  * Para usar JWT: Envie o _header_ `Authorization: Bearer {token}` em todas as requisições à API que exigem autenticação.
+
+
+## Motivação da alteração
+Antes dessa evolução, a API do Bling somente utilizava _tokens_ opacos para autenticação. Esse tipo de _token_ é apenas uma referência, um identificador aleatório. Quando a API recebe um _token_ opaco, o sistema precisa consultar um banco de dados ou mecanismo de _cache_ centralizado para validar quem é o usuário e quais são suas permissões.
+Com o JWT essa abordagem mudou. Trata-se de um _token_ estruturado e auto contido, ou seja, as informações sobre o usuário, a empresa e os escopos de permissão ficam codificadas no próprio _token_.
+## Ganhos computacionais e de infraestrutura
+A adoção do JWT traz benefícios imediatos para a latência das requisições e uso de recursos computacionais:
+  * Redução de I/O (Stateless): Ao usar JWT, a API não precisa necessariamente consultar o banco de dados para validar o _token_ a cada requisição. A validação é feita criptograficamente (CPU), sendo computacionalmente mais eficiente do que operações de entrada/saída (I/O) em disco ou rede para buscar sessões em banco de dados.
+  * Escalabilidade: Como o _token_ carrega os dados necessários, a arquitetura torna-se _stateless_ (sem estado). Isso facilita a escala horizontal dos serviços, pois qualquer servidor pode validar o _token_ sem depender de uma central de sessões.
+  * Eficiência de Rede: Embora o JWT seja maior do que um _token_ opaco, a eliminação da necessidade de consultas adicionais ao banco de dados (_round-trips_) compensa o aumento do _payload_ , especialmente em cenários de alta concorrência.
+
+
+## Estrutura e tamanho do token
+Diferente dos tokens opacos curtos, o JWT carrega um _payload_ de dados em Base64. Com base na estrutura atual de informações contidas (_claims_), o tamanho de um **_token_ JWT** pode variar aproximadamente de **1.500 a 3.000 caracteres**.
+**Atenção: É essencial que sua aplicação esteja preparada para armazenar e trafegar _strings_ desse tamanho nos _headers_ de autorização.**
+## Utilizando JWT no Bling
+Por padrão, a API do Bling retorna _tokens_ opacos, contudo, esse modelo de autenticação está descontinuado. Para receber um _token_ JWT ao invés de um _token_ opaco, você deve incluir o _header_ `enable-jwt` com o valor `1` na requisição ao _endpoint_ `POST /oauth/token`.
+**Importante:** Sem o _header_ `enable-jwt`, você receberá um _token_ opaco que continuará funcionando até a migração total para o JWT.
+**Migre o quanto antes, não deixe para o último momento.**
+### Exemplo de obtenção de token JWT
+```
+POST /Api/v3/oauth/token? HTTP/1.1
+Host: https://api.bling.com.br
+Content-Type: application/x-www-form-urlencoded
+Accept: 1.0
+Authorization: Basic [base64_das_credenciais_do_client_app]
+enable-jwt: 1
+
+grant_type=authorization_code&code=[authorization_code]
+
+```
+
+```
+curl -X POST "https://api.bling.com.br/oauth/token" \
+-H "Content-Type: application/x-www-form-urlencoded" \
+-H "Authorization: Basic [base64_das_credenciais_do_client_app]" \
+-H "enable-jwt: 1" \
+-d "grant_type=authorization_code&code=[authorization_code]"
+
+```
+
+### Exemplo de renovação de token JWT
+```
+POST /Api/v3/oauth/token? HTTP/1.1
+Host: https://api.bling.com.br
+Content-Type: application/x-www-form-urlencoded
+Accept: 1.0
+Authorization: Basic [base64_das_credenciais_do_client_app]
+enable-jwt: 1
+
+grant_type=refresh_token&refresh_token=[refresh_token]
+
+```
+
+```
+curl -X POST "https://api.bling.com.br/oauth/token" \
+-H "Content-Type: application/x-www-form-urlencoded" \
+-H "Authorization: Basic [base64_das_credenciais_do_client_app]" \
+-H "enable-jwt: 1" \
+-d "grant_type=refresh_token&refresh_token=[refresh_token]"
+
+```
+
+### Usando o token JWT nas requisições
+Após obter o _token_ JWT através do _endpoint_ `POST /oauth/token`, você deve incluí-lo em todas as requisições subsequentes à API.
+É fundamental que o _header_ `enable-jwt: 1` seja mantido em todas as requisições para garantir a compatibilidade e o processamento correto da autenticação JWT pela API.
+Este _header_ deve ser incluído em todas as requisições que exigem autenticação, como consultar produtos, criar pedidos, etc.
+Exemplo de requisição para a API de produtos:
+```
+GET /Api/v3/produtos HTTP/1.1
+Host: https://api.bling.com.br
+Authorization: Bearer [access_token]
+enable-jwt: 1
+
+```
+
+```
+curl --location --request GET 'https://api.bling.com.br/Api/v3/produtos' \
+--header 'Authorization: Bearer [access_token]' \
+--header 'Content-Type: application/json' \
+--header 'enable-jwt: 1'
+
+```
+
+## Tratamento de erros comuns
+Ao implementar o uso do JWT, atente-se aos seguintes códigos de retorno:
+`401 Unauthorized`: Indica que o _token_ expirou ou é inválido.
+**Solução:** Renove o _token_ usando o `refresh_token` (lembrando do _header_ `enable-jwt: 1`) ou refaça o fluxo de autorização OAuth.
+`400 Bad Request`: Geralmente indica _token_ malformado ou erro na sintaxe do _header_.
+**Solução:** Verifique se o _header_ segue estritamente o formato: `Authorization: Bearer {token}`.
+Dúvidas? [Entre em contato](https://www.bling.com.br/contato) com nossa equipe de atendimento.

package/docs/migracao-jwt_ganhos_computacionais_e_de_infraestrutura.md

@@ -0,0 +1,11 @@
+# Ganhos computacionais e de infraestrutura
+
+> **Seção:** Migração para autenticação JWT
+> **Atualizado:** 2026-03-07
+
+---
+## Ganhos computacionais e de infraestrutura
+A adoção do JWT traz benefícios imediatos para a latência das requisições e uso de recursos computacionais:
+  * Redução de I/O (Stateless): Ao usar JWT, a API não precisa necessariamente consultar o banco de dados para validar o _token_ a cada requisição. A validação é feita criptograficamente (CPU), sendo computacionalmente mais eficiente do que operações de entrada/saída (I/O) em disco ou rede para buscar sessões em banco de dados.
+  * Escalabilidade: Como o _token_ carrega os dados necessários, a arquitetura torna-se _stateless_ (sem estado). Isso facilita a escala horizontal dos serviços, pois qualquer servidor pode validar o _token_ sem depender de uma central de sessões.
+  * Eficiência de Rede: Embora o JWT seja maior do que um _token_ opaco, a eliminação da necessidade de consultas adicionais ao banco de dados (_round-trips_) compensa o aumento do _payload_ , especialmente em cenários de alta concorrência.

package/docs/migracao-jwt_introducao.md

@@ -0,0 +1,15 @@
+# Introdução
+
+> **Seção:** Migração para autenticação JWT
+> **Atualizado:** 2026-03-07
+
+---
+## Introdução
+Este guia aborda detalhadamente a ativação e o uso de [JSON Web Tokens](https://www.jwt.io/introduction#what-is-json-web-token) (JWT) na API do Bling além de apresentar as instruções necessárias para a implementação dessa evolução em nossa arquitetura tecnológica e destacar os principais benefícios proporcionados por essa mudança.
+Os principais tópicos da alteração que serão explicados detalhadamente nas seções subsequentes:
+  * A data de bloqueio do uso de _tokens_ opacos está em definição.
+  * A autenticação utilizando _tokens_ opacos está descontinuada.
+  * Alteração no tamanho do token gerado.
+  * Para obter JWT: Inclua o _header_ `enable-jwt: 1` ao obter um _token_ por meio do _endpoint_ `POST /oauth/token`. É fundamental manter este _header_ em todas as requisições subsequentes para garantir que os _tokens_ JWT continuem sendo emitidos após renovações.
+  * Para renovar JWT: Inclua o _header_ `enable-jwt: 1` também na requisição de renovação do _token_ para continuar recebendo _tokens_ JWT.
+  * Para usar JWT: Envie o _header_ `Authorization: Bearer {token}` em todas as requisições à API que exigem autenticação.

package/docs/migracao-jwt_motivacao_da_alteracao.md

@@ -0,0 +1,9 @@
+# Motivação da alteração
+
+> **Seção:** Migração para autenticação JWT
+> **Atualizado:** 2026-03-07
+
+---
+## Motivação da alteração
+Antes dessa evolução, a API do Bling somente utilizava _tokens_ opacos para autenticação. Esse tipo de _token_ é apenas uma referência, um identificador aleatório. Quando a API recebe um _token_ opaco, o sistema precisa consultar um banco de dados ou mecanismo de _cache_ centralizado para validar quem é o usuário e quais são suas permissões.
+Com o JWT essa abordagem mudou. Trata-se de um _token_ estruturado e auto contido, ou seja, as informações sobre o usuário, a empresa e os escopos de permissão ficam codificadas no próprio _token_.

package/docs/migracao-jwt_tratamento_de_erros_comuns.md

@@ -0,0 +1,13 @@
+# Tratamento de erros comuns
+
+> **Seção:** Migração para autenticação JWT
+> **Atualizado:** 2026-03-07
+
+---
+## Tratamento de erros comuns
+Ao implementar o uso do JWT, atente-se aos seguintes códigos de retorno:
+`401 Unauthorized`: Indica que o _token_ expirou ou é inválido.
+**Solução:** Renove o _token_ usando o `refresh_token` (lembrando do _header_ `enable-jwt: 1`) ou refaça o fluxo de autorização OAuth.
+`400 Bad Request`: Geralmente indica _token_ malformado ou erro na sintaxe do _header_.
+**Solução:** Verifique se o _header_ segue estritamente o formato: `Authorization: Bearer {token}`.
+Dúvidas? [Entre em contato](https://www.bling.com.br/contato) com nossa equipe de atendimento.