• 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.

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

Atenção: a versão 5.0.0+ do bling-erp-api para Javascript/TypeScript utiliza a API v3 do Bling. Caso deseja utilizar a API v2 do Bling, utilize a versão 4.0.0. A versão 6.0.0 troca new Bling(accessToken) por Bling.create({ auth }) e passa a cobrir JWT, token opaco legado e o fluxo OAuth.

Instalação

Para instalar, execute o comando:

npm i bling-erp-api

Criação de uma nova conexão

A construção é sempre 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()

bling.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.

Fluxo de autorização. Exemplo completo: projeto de demonstração.

Entidades disponíveis

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

• Borderos (.borderos)
• Campos customizados (.camposCustomizados)
• Canais de Venda (.canaisDeVenda)
• Categorias - Lojas (.categoriasLojas)
• Categorias - Produtos (.categoriasProdutos)
• Categorias - Receitas e Despesas (.categoriasReceitasDespesas)
• Contas a Pagar (.contasPagar)
• Contas a Receber (.contasReceber)
• Contas Contábeis (.contasContabeis)
• Contatos (.contatos)
• Contatos - Tipos (.contatosTipos)
• Contratos (.contratos)
• Depósitos (.depositos)
• Empresas (.empresas)
• Estoques (.estoques)
• Formas de Pagamento (.formasDePagamento)
• Grupos de Produtos (.gruposDeProdutos)
• Homologação (.homologacao)
• Logísticas (.logisticas)
• Logísticas - Etiquetas (.logisticasEtiquetas)
• Logísticas - Objetos (.logisticasObjetos)
• Logísticas - Remessas (.logisticasRemessas)
• Logísticas - Serviços (.logisticasServicos)
• Naturezas de Operações (.naturezasDeOperacoes)
• Notas Fiscais de Consumidor Eletrônicas (.nfces)
• Notas Fiscais de Serviço Eletrônicas (.nfses)
• Notas Fiscais Eletrônicas (.nfes)
• Notificações (.notificacoes)
• Ordens de Produção (.ordensDeProducao)
• Pedidos - Compras (.pedidosCompras)
• Pedidos - Vendas (.pedidosVendas)
• Produtos (.produtos)
• Produtos - Estruturas (.produtosEstruturas)
• Produtos - Fornecedores (.produtosFornecedores)
• Produtos - Lojas (.produtosLojas)
• Produtos - Variações (.produtosVariacoes)
• Propostas Comerciais (.propostasComerciais)
• Situações (.situacoes)
• Situações - Módulos (.situacoesModulos)
• Situações - Transições (.situacoesTransicoes)
• Usuários (.usuarios)
• 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