Bling ERP API SDK

Português (BR) | English

SDK Python não oficial para a API v3 do Bling ERP.

Acesso tipado e idiomático a mais de 40 recursos do Bling ERP, com transporte síncrono e assíncrono, autenticação OAuth2, limite de taxa, retry automático e modelos Pydantic.

Descrição

O Bling ERP API SDK é uma biblioteca Python que simplifica a integração com a API v3 do Bling ERP. Ela oferece uma interface canônica em português (com aliases em inglês para compatibilidade), modelos tipados com Pydantic v2, validação de contratos OpenAPI, e tratamento robusto de erros e rate limiting — tudo para que você possa focar no que importa: sua aplicação.

Recursos

• 40+ módulos de recursos cobrindo toda a superfície da API do Bling ERP
• Autenticação OAuth2 via bling-jwt-auth — renovação automática de tokens
• Rate limiting (3 req/s padrão) com retry em respostas 429 e suporte a Retry-After
• Modelos tipados com Pydantic v2 — campos em snake_case e mapeamento automático para nomes Bling
• Transporte síncrono e assíncrono baseado em HTTPX
• API canônica em pt-BR com aliases em inglês para compatibilidade
• Contratos OpenAPI — gerados e testados contra a especificação oficial
• 500+ testes com HTTP mockado
• Documentação completa em mkdocs com suporte a busca

Instalação

pip install bling-erp-api

Ou com uv:

uv add bling-erp-api

Requer Python 3.12 ou superior.

Início Rápido

Defina as variáveis de ambiente necessárias (veja Autenticação):

export BLING_CLIENT_ID="seu_client_id"
export BLING_CLIENT_SECRET="seu_client_secret"
export BLING_REFRESH_TOKEN="seu_refresh_token"

Depois use o SDK:

from bling_erp_api import BlingClient

with BlingClient.from_env() as client:
    # Listar produtos da primeira página
    produtos = client.produtos.listar(limit=100)
    for produto in produtos.get("data", []):
        print(produto.get("nome"))

    # Obter um contato
    contato = client.contatos.obter(1)
    print(contato)

    # Criar um pedido de venda
    from bling_erp_api.models.aliases import PedidoVenda

    pedido = PedidoVenda(
        cliente=PedidoVenda.Cliente(nome="Cliente Exemplo"),
        itens=[
            PedidoVenda.Item(
                codigo="PROD-001",
                descricao="Produto Exemplo",
                quantidade=2,
                valor_unitario=49.90,
            )
        ],
    )
    resposta = client.pedidos_vendas.criar(pedido)
    print(resposta)

Autenticação

O SDK utiliza OAuth2 (fluxo de autorização) delegado ao pacote bling-jwt-auth.

A forma mais simples de começar é com variáveis de ambiente:

export BLING_CLIENT_ID="seu_client_id"
export BLING_CLIENT_SECRET="seu_client_secret"
export BLING_REFRESH_TOKEN="seu_refresh_token"
export BLING_REDIRECT_URI="sua_redirect_uri"  # opcional

Em seguida, crie um cliente com BlingClient.from_env().

Para autenticação personalizada, passe um token_provider que implemente get_access_token() -> str ou uma instância de httpx.Auth.

Consulte a documentação de autenticação para mais detalhes.

Recursos Disponíveis

Documentação

A documentação completa está disponível em:

https://tempont.github.io/bling-erp-api-python/

• Comece por aqui — instalação e primeiro uso
• Autenticação — configuração de credenciais OAuth2
• Paginação — navegação por resultados paginados
• Tratamento de erros — exceções tipadas
• Referência da API — documentação completa de classes e métodos

Contribuindo

Contribuições são bem-vindas! Consulte o guia completo em CONTRIBUTING.md — em inglês.

Resumo rápido

1. Faça um fork do repositório
2. Crie um branch para sua feature (git checkout -b feat/minha-feature)
3. Instale as dependências: uv sync --all-groups
4. Faça suas alterações
5. Verifique com make check (executa ruff, basedpyright e pytest)
6. Commit e push, depois abra um Pull Request

Para convenções detalhadas de nomenclatura, docstrings, modelos e implementação, veja o arquivo AGENTS.md na raiz do projeto.

Reportando Problemas

Encontrou um bug? Use o rastreador de issues do GitHub.

Ao reportar, inclua:

• Versão do Python (python --version)
• Versão do SDK (bling-erp-api --version)
• Código mínimo para reproduzir o problema
• Comportamento esperado vs. observado

Problemas de segurança devem ser reportados em privado — entre em contato pelos canais do GitHub.

Licença

MIT — veja o arquivo LICENSE.

Roadmap

• Expansão da geração de modelos Pydantic a partir do OpenAPI spec
• Continuação dos slices verticais para mais recursos (contas, estoques, categorias, logística, anúncios)
• Mais exemplos e documentação interativa