• Versão em PHP
• Versão em C# (em breve)

Bling ERP API - Javascript/Typescript

Pacote de integração com a API v3 do ERP Bling para Javascript/TypeScript. O mais completo existente.

Cobre autenticações JWT, fluxo OAuth e token opaco (legado).

Atualizado com a versão v354 da API (veja o registro de alterações).

Instalação

Para instalar, execute o comando:

npm i bling-erp-api

Criação de uma nova conexão

Instancie via Bling.create({ auth }). O campo auth.method escolhe como o token será usado ou obtido.

JWT (recomendado)

Use quando você já possui um access token JWT (emitido com o header enable-jwt: 1 no /oauth/token). A biblioteca envia Authorization: Bearer e enable-jwt: 1 em todas as chamadas de recurso.

import Bling from 'bling-erp-api'

const blingConnection = Bling.create({
  auth: {
    method: 'jwt',
    accessToken: 'seu-jwt'
  }
})

Guia de migração JWT.

Token opaco (legado)

Use apenas se o token que você já tem não é JWT. Tokens opacos estão descontinuados no Bling.

const blingConnection = Bling.create({
  auth: {
    method: 'opaque',
    accessToken: 'token-opaco'
  }
})

OAuth (authorization_code)

A biblioteca cobre authorize, troca do code, refresh e revoke. O Bling não implementa client credentials, password nem implicit. clientSecret é somente no servidor — não use method: 'oauth' no navegador.

A troca e o refresh sempre enviam enable-jwt: 1. Persista o JSON através de um listener registrado via onTokens.

import Bling from 'bling-erp-api'

const blingConnection = Bling.create({
  auth: {
    method: 'oauth',
    clientId: 'seu-client-id',
    clientSecret: 'seu-client-secret',
    refreshToken: 'opcional-se-ja-autorizado',
    onTokens: async (tokens) => {
      // persista access_token e refresh_token
    }
  }
})

const authorizationUrl = blingConnection.auth.getAuthorizationUrl({
  state: 'csrf-aleatorio'
})
// redirecione o usuário; no callback (code expira em 1 minuto):
await blingConnection.auth.exchangeAuthorizationCode(code)

const products = await blingConnection.produtos.get()

blingConnection.auth existe somente no cliente OAuth (BlingOAuthClient). Clientes JWT e opacos não têm essa propriedade.

Refresh: o access token é renovado com POST /oauth/token e grant_type=refresh_token (refresh vale 30 dias). Com autoRefresh (padrão quando há refreshToken), um 401 nas chamadas de recurso dispara o refresh e uma nova tentativa.

Entenda o fluxo de autorização e como aplicá-lo neste projeto de demonstração.

Entidades disponíveis

Todas as entidades do Bling atualmente são permitidas para interação. São elas:

• [x] Anúncios (.anuncios)
• [x] Anúncios - Categorias (.anunciosCategorias)
• [x] Borderos (.borderos)
• [x] Caixas e Bancos (.caixas)
• [x] Campos customizados (.camposCustomizados)
• [x] Canais de Venda (.canaisDeVenda)
• [x] Categorias - Lojas (.categoriasLojas)
• [x] Categorias - Produtos (.categoriasProdutos)
• [x] Categorias - Receitas e Despesas (.categoriasReceitasDespesas)
• [x] Contas a Pagar (.contasPagar)
• [x] Contas a Receber (.contasReceber)
• [x] Contas Contábeis (.contasContabeis)
• [x] Contatos (.contatos)
• [x] Contatos - Tipos (.contatosTipos)
• [x] Contratos (.contratos)
• [x] Depósitos (.depositos)
• [x] Documentos Compartilhados (.documentosCompartilhados)
• [x] Empresas (.empresas)
• [x] Estoques (.estoques)
• [x] Formas de Pagamento (.formasDePagamento)
• [x] Grupos de Produtos (.gruposDeProdutos)
• [x] Homologação (.homologacao)
• [x] Listas de Preços (.listasPrecos)
• [x] Logísticas (.logisticas)
• [x] Logísticas - Etiquetas (.logisticasEtiquetas)
• [x] Logísticas - Objetos (.logisticasObjetos)
• [x] Logísticas - Remessas (.logisticasRemessas)
• [x] Logísticas - Serviços (.logisticasServicos)
• [x] Naturezas de Operações (.naturezasDeOperacoes)
• [x] Notas Fiscais de Consumidor Eletrônicas (.nfces)
• [x] Notas Fiscais de Serviço Eletrônicas (.nfses)
• [x] Notas Fiscais Eletrônicas (.nfes)
• [x] Notificações (.notificacoes)
• [x] Ordens de Produção (.ordensDeProducao)
• [x] Ordens de Serviço (.ordensServico)
• [x] Pedidos - Compras (.pedidosCompras)
• [x] Pedidos - Vendas (.pedidosVendas)
• [x] Produtos (.produtos)
• [x] Produtos - Estruturas (.produtosEstruturas)
• [x] Produtos - Fornecedores (.produtosFornecedores)
• [x] Produtos - Lojas (.produtosLojas)
• [x] Produtos - Lotes (.produtosLotes)
• [x] Produtos - Lotes Lançamentos (.produtosLotesLancamentos)
• [x] Produtos - Variações (.produtosVariacoes)
• [x] Propostas Comerciais (.propostasComerciais)
• [x] Situações (.situacoes)
• [x] Situações - Módulos (.situacoesModulos)
• [x] Situações - Transições (.situacoesTransicoes)
• [x] Usuários (.usuarios)
• [x] Vendedores (.vendedores)

Exemplo de uso

Para listar seus produtos, basta executar:

import Bling from 'bling-erp-api'

const blingConnection = Bling.create({
  auth: {
    method: 'jwt',
    accessToken: 'seu-jwt'
  }
})

const products = await blingConnection.produtos.get()

console.log(products)

Executando os testes do projeto

Faça o clone do projeto, instale as dependências e execute:

npm run test

Contribuindo ao projeto

• Guia de contribuição
• Apoie o projeto