BenimPOS API: keys, test account and documentation
Getting API keys, the shared test account, the developer documentation (benimpos.com/developers) and frequently asked questions.
The BenimPOS API lets you access the data in your account from your own software: you can send products, stock and prices to your e-commerce site, write orders from the site into BenimPOS as sales, and pull sales, customer, supplier, purchase invoice and income-expense data into your accounting or reporting system.
The API module costs 1.800,00 TL per year and is bought on the Integrations › API Integration tab. There is no separate test environment; for testing you can use the shared test account (below). Receipts cannot be sent to a fiscal cash register through the API; fiscal cash register integrations work only inside the BenimPOS apps.
API documentation
All services, parameters, sample requests and responses, error codes and usage limits are on our developer page: benimpos.com/developers. The page is in Turkish and English. You can run each operation from the browser with the Try it button on the page and see the response.
Services added to the API and changes are announced on the Changelog page. The old PDF document is no longer updated; rely on the developer page for field names and behavior.
Getting API keys
Buy the module
In the web panel, on the Integrations page at the very bottom of the left menu, open the API Integration tab and complete the purchase with Buy on the card.
Open your details
After the purchase, an API Integration row appears in the table at the top of the page. Press the pencil icon on the row; the Your API Integration Details window opens.
Copy the values
The window has three values: Branch ID (store code), Api Key and Secret Key. Copy them with the copy icon and enter them in your application's settings.
The keys give full access to your account: do not put them in a code repository, in code that runs in the browser (JavaScript) or in messages; store them only on the server side. If you think a key has been exposed, generate a new one with the refresh icon in the window; the old key stops working immediately, so remember to update the value in your application.
- Each branch is a separate account and has its own Branch ID and keys. The API module is activated separately on each branch account whose data you will access.
- When the module expires, the services keep working for 3 more days, then requests are rejected. Renew it with Extend on the Integrations page.
Test account
Requests read and change your account's real data. While developing the integration, use the shared test account so you do not touch your own data. The sign-in details are in the Test account section of the API documentation: sign in, get the keys from the Integrations › API Integration row, and use them in your application or on the Try it screen in the documentation.
The test account is public; anyone can see and change the data in it. Do not enter real customer or sales information.
Quick summary
| Item | Value |
|---|---|
| URL | https://dev.benimpos.com/api/<service> (e.g. /api/products) |
| Method | POST, JSON body, up to 2 MB |
| Authentication | HTTP headers: Branch-ID, Api-Key, Secret-Key |
| Choosing the operation | The processType field in the body (e.g. "list", "create") |
| Services | Products and purchase invoices (products), customers (customers), sales (sales), suppliers (firms), categories (categories), payment types (paymentTypes), income-expenses (incomeExpenses) |
Frequently asked questions
Can I create a purchase invoice with the API?
Yes. The createPurchaseInvoice operation in the products service saves the invoice, adds the products to stock and, for an on-account invoice, posts the amount to the supplier's account. If the same invoice is sent a second time, no new record is created.
Can I assign a group (category) to a product with the API?
No, there is no group field when adding or updating products. You can read groups with the categories service, and assign groups to products in the web panel or with Excel.
What should I do so the same order is not written as a sale twice?
When creating a sale, put your own order number in the externalRef field. A second request with the same number does not create a new sale; it returns the code of the first sale.
When does a sale made in the desktop app appear in the API?
After the desktop app sends the data to the web (sync). In the desktop app, you can start sync right away from the Data integration card on the home page. Sales in the web and mobile apps appear instantly.
How do I get technical support?
Write your question to [email protected]. Include the time of the request, the URL, the body (without the keys), the HTTP status code, the response message and any response headers starting with X-BP-. Do not share your API keys.