SmartBill Integration
Overview
Section titled “Overview”SmartBill is the most popular invoicing and inventory SaaS in Romania. The MicroPIM SmartBill integration is a one-way PULL: MicroPIM authenticates against the SmartBill API and reads your current stock per warehouse (gestiune). From a single API call, MicroPIM creates one Warehouse per SmartBill gestiune, one Product per item that has a product code, and one WarehouseInventory row per (warehouse × product) pair.
SmartBill is treated as a source-of-truth for inventory, not as a store platform. No products, invoices, or stock changes are pushed back to SmartBill from MicroPIM.
Prerequisites
Section titled “Prerequisites”- An active SmartBill account (any plan that includes API access)
- The API Token generated from your SmartBill account
- The CIF (Romanian fiscal code) of the company in SmartBill
- “Folosesc cod produs” enabled in SmartBill (see the disclaimer below)
- An active MicroPIM account
What you’ll need
Section titled “What you’ll need”| Field | Where to find it |
|---|---|
| The email you log in to SmartBill with | |
| CIF | The fiscal code of the company in SmartBill, e.g. RO12345678 |
| API Token | Generated in SmartBill: Setări → Cont API → Generează token |
Enable Product Codes in SmartBill (REQUIRED)
Section titled “Enable Product Codes in SmartBill (REQUIRED)”The SmartBill /stocks endpoint only returns stock rows for products that have a product code (cod produs). Items without a code are returned without an identifier and cannot be imported into MicroPIM, because Product.sku is the unique key per organization.
The “Folosesc cod produs” option is enabled from the following menu:
-
Go to Configurare → Configurari program → Preferințe generale (Configuration → Program Settings → General Preferences).
-
Check the Folosesc cod produs option (“I use product codes”), then click Salvează preferințe generale (“Save general preferences”).
-
SmartBill will then prompt you to add product codes. Choose Mai târziu (“Add later”) — you can manage codes on your own schedule from Nomenclator → Produse/Servicii.
Once enabled, you can assign unique codes to every product. From that point on, when you add an item to an invoice the product code must be filled in too — otherwise the invoice cannot be saved.
After enabling the option, go back through your existing nomenclator and add codes to any item you want to see in MicroPIM. Items without a code will be silently skipped on every import.
Connect MicroPIM to SmartBill
Section titled “Connect MicroPIM to SmartBill”- In MicroPIM, go to Integrations → Add Integration.
- Select SmartBill from the platform list.
- Fill in Email, CIF, and API Token.
- Click Test Connection to verify your credentials before saving (this issues a single cheap request to the SmartBill
/stocksendpoint filtered to a non-existent warehouse, so it costs nothing). - Click Save to create the integration.
One integration = one CIF. For multi-company SmartBill accounts, create one MicroPIM integration per CIF.
Run an import
Section titled “Run an import”- Open your SmartBill integration’s detail page.
- Click Import Stocks. The request is queued immediately and processed asynchronously by the
smartbill_syncworker. - Refresh the page to see the result in the Recent Activity feed.
What gets imported
Section titled “What gets imported”| Data | Direction | Notes |
|---|---|---|
| Warehouses (gestiuni) | SmartBill → MicroPIM | One Warehouse per gestiune, keyed by SMARTBILL-{CIF}-{slug} |
| Products | SmartBill → MicroPIM | One Product per productCode, created as draft with currency = RON. Existing products with the same SKU are not modified (first import wins for name/description). |
| Stock per warehouse | SmartBill → MicroPIM | One WarehouseInventory row per (warehouse × product). Quantity is floored to an integer. |
| Total stock | derived | Product.stock = sum of WarehouseInventory.quantity across all SmartBill warehouses for this CIF. |
| Measuring unit | SmartBill → MicroPIM | Stashed as a smartbill:unit:{x} tag on the Product (e.g. smartbill:unit:buc, smartbill:unit:kg). |
Re-importing — what happens to drift
Section titled “Re-importing — what happens to drift”Re-running Import Stocks is safe and idempotent. Each import is a snapshot:
| Drift in SmartBill | What MicroPIM does |
|---|---|
| Quantity changed | WarehouseInventory.quantity is updated. |
| Quantity is 0 in the response | WarehouseInventory.quantity is set to 0. |
| Product is missing from a warehouse | The existing WarehouseInventory row for that pair is set to 0. |
| Product is missing from the entire response | All its WarehouseInventory rows are zeroed; Product.stock = 0, Product.inStock = false. The Product row itself is not deleted or archived. |
| Warehouse was renamed in SmartBill | A new Warehouse row is created in MicroPIM. The old one is kept with its zeroed inventory. (Manual merge is a future feature.) |
Product.name is never overwritten on subsequent imports — first import wins. Edit the name in MicroPIM if you need to.
Fractional quantities
Section titled “Fractional quantities”SmartBill returns quantities as strings that may include decimals (e.g. 12.5 kg). MicroPIM’s WarehouseInventory.quantity is an integer, so fractional values are floored (never rounded up). The activity log reports how many rows were truncated. Decimal-quantity support is on the roadmap.
Troubleshooting
Section titled “Troubleshooting”Test Connection returns “Authentication failed” — your email, CIF, or API Token is wrong. Regenerate the token in SmartBill (Setări → Cont API) and update it in MicroPIM.
Import runs but creates 0 products — your SmartBill items don’t have product codes set. Enable “Folosesc cod produs” (see above) and add codes to existing items, then re-import.
Some products are missing after import — those rows had no productCode in SmartBill. Check the activity log for the skippedNoCode count, then add codes to the missing items in SmartBill.
My kg/litre products show the wrong quantity — fractional quantities are floored. A SmartBill stock of 12.5 kg becomes 12 in MicroPIM. This is intentional (“never overstate stock”) and tracked in the fractionalTruncated counter.
Two warehouses with similar names appeared in MicroPIM — the SmartBill gestiune was renamed. The new name created a new Warehouse row. The old row keeps its zeroed inventory; you can disable it.
SmartBill returns HTTP 500 — the worker retries automatically (up to 5 attempts, 2s–60s exponential backoff). Persistent failures land in the failed Messenger transport and are visible via php bin/console messenger:failed:show.
Does the integration push anything back to SmartBill? No. This is a one-way PULL of stock data. No invoices, products, or stock changes are written to SmartBill from MicroPIM.
Can I connect multiple SmartBill accounts? Yes — one integration per (account email + CIF) pair. Multi-company SmartBill setups need one MicroPIM integration per CIF.
Can I schedule imports? Not yet — for now use the Import Stocks button manually. Scheduled imports are on the roadmap.
Are the products created as published? No — every new product is created with status = draft and price = null. SmartBill doesn’t expose a sell price via the public API, so you set the price in MicroPIM before publishing.
Why are colons not used in the warehouse code? The Warehouse.warehouseCode column is restricted to letters, numbers, hyphens, and underscores. SmartBill warehouses are coded as SMARTBILL-{CIF}-{SLUG_OF_GESTIUNE_NAME}.