Bling

Name: MedusaJS
Brand: Medusa

Manage products, inventory, and orders effortlessly

medusa-plugin-bling

Official Bling ERP integration for MedusaJS v2.3+. Seamlessly sync products, inventory, and orders between your MedusaJS store and Bling ERP using OAuth 2.0.

🎯 Production-ready plugin with Admin UI, automatic token refresh, and webhook support for real-time synchronization.

✨ Features

🔐 OAuth 2.0 Authentication with automatic token refresh
🎨 Admin UI Integration - Complete settings page with real-time status
📦 Product Sync - Import products, variants, prices, and images from Bling
📊 Inventory Management - Real-time stock updates via webhooks
🛒 Order Export - Automatic order creation in Bling with customer data
🔔 Webhook Support - HMAC validation for secure notifications
🇧🇷 Brazilian E-commerce - Built specifically for Brazilian market needs

📋 Table of Contents

Requirements
Installation
Configuration
API Endpoints
Webhook Setup
Development
Contributing
License

📦 Requirements

Node.js 18 or higher
pnpm 8+ (or npm/yarn)
MedusaJS v2.3 or higher
Bling account with API credentials

🚀 Installation

1
pnpm add medusa-plugin-bling

12345678910
import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  plugins: [
    {
      resolve: "medusa-plugin-bling",
      options: {},
    },
  ],
})

⚙️ Configuration

1. Get Bling Credentials

Access Bling Developer Portal
Create a new application
Copy your Copy to clipboardClient ID and Copy to clipboardClient Secret

2. Configure in Admin

Open your Medusa Admin panel
Navigate to Settings → Integrations → Bling ERP
Enter your Copy to clipboardClient ID and Copy to clipboardClient Secret
(Optional) Set a Copy to clipboardWebhook Secret for secure webhook validation
Configure sync preferences:
- Products: Import catalog, images, descriptions, and prices
- Inventory: Real-time stock updates
- Orders: Automatic order export to Bling
Click Connect to Bling to complete OAuth flow

3. Start Syncing

Once connected, you can:

Manual Sync: Click "Sync" button in the admin panel
Automatic Sync: Orders are sent automatically on creation
Webhook Sync: Products and inventory update in real-time

🔌 API Endpoints

Admin Routes

Method Route Description Copy to clipboardGET Copy to clipboard/admin/bling/config Get current configuration Copy to clipboardPOST Copy to clipboard/admin/bling/config Update credentials and preferences Copy to clipboardGET Copy to clipboard/admin/bling/health Check OAuth token validity Copy to clipboardPOST Copy to clipboard/admin/bling/sync Import products and inventory from Bling Copy to clipboardPOST Copy to clipboard/admin/bling/orders/:id/sync Send specific order to Bling

Store Routes

Method Route Description Copy to clipboardPOST Copy to clipboard/store/bling/webhook Receive Bling notifications (HMAC validation)

🛠️ Development

Available Scripts

123456
pnpm run build        # Build TypeScript
pnpm run typecheck    # Type checking without build
pnpm run lint         # Run ESLint
pnpm run lint:fix     # Fix ESLint issues
pnpm run format       # Check formatting
pnpm run format:fix   # Fix formatting

Release Process

This repository uses Copy to clipboardsemantic-release for automated versioning and publishing:

Patch (Copy to clipboard3.0.x): Commits with Copy to clipboardfix: prefix
Minor (Copy to clipboard3.x.0): Commits with Copy to clipboardfeat: prefix
Major (Copy to clipboardx.0.0): Commits with Copy to clipboardBREAKING CHANGE: in footer or Copy to clipboard! after type

Example: Copy to clipboardfeat(admin): add sync status indicator

Estrutura do projeto

12345678910111213
src/
├── admin/                     # Extensão de interface do Admin
│   ├── api/                   # Client wrapper usado pela UI
│   ├── routes/                # Página de configurações
│   └── widgets/               # (vazio, reservado para futuras extensões)
├── api/                       # Rotas Admin/Store expostas pelo plugin
│   ├── admin/bling/*          # Configuração, health, sync de pedidos/produtos
│   └── store/bling/webhook    # Webhook público
├── loaders/register.ts        # Registro de serviços/eventos
├── models/                    # Entidades persistidas (configuração)
├── modules/bling              # Serviço principal (produtos)
├── modules/order-sync.service.ts # Serviço de sincronização de pedidos
└── utils/                     # Utilitários compartilhados

🔔 Webhook Setup

Configure Bling to send notifications to:

1
POST https://your-store.com/store/bling/webhook

If Copy to clipboardWebhook Secret is configured, the plugin validates the Copy to clipboardx-bling-signature header (HMAC SHA-256) before processing requests.

Supported Events:

Product updates
Inventory changes
Order status changes

🐛 Troubleshooting

Authentication Errors

Re-enter your Copy to clipboardClient ID and Copy to clipboardClient Secret, then repeat the OAuth flow.

Orders Not Syncing

Verify customer has valid CPF/CNPJ
Ensure all items have SKU matching Bling products
Check order status is complete

Rate Limiting

The plugin logs all API calls. Check Medusa logs for details and retry manually through the Admin panel.

🗺️ Roadmap

Order status sync from Bling to Medusa
Automated test coverage (unit + integration)
Detailed field mapping documentation
Support for multiple Bling accounts
GraphQL API support

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and development process.

Fork the repository
Create your feature branch (Copy to clipboardgit checkout -b feat/amazing-feature)
Commit your changes (Copy to clipboardgit commit -m 'feat: add amazing feature')
Push to the branch (Copy to clipboardgit push origin feat/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built for the MedusaJS ecosystem
Powered by Bling ERP API v3
Developed by Erick Couto for Casa Moratti

📞 Support

📫 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
🌐 Documentation: Full Docs

Made with ❤️ for Brazilian e-commerce