CarmenSoftware API — Bruno Collection

A Bruno collection for the CarmenSoftware ERP API (dev: https://dev.blueledgers.com:4001).

Covers: login, logout, locations, products (+ category / sub-category / item-group), vendors, locations-product, product-locations.

Prerequisites

• Bruno (desktop app or bru CLI)

Getting started

1. Open the collection in Bruno: File → Open Collection → select the bruno/ folder (not the repo root).
2. Select the environment dev (top-right dropdown).
3. Set credentials on the environment:
   • email and password — your login credentials
   • bu_code — business unit code (default T02)
   • x_app_id — application id (a default is preset for the frontend website)
4. Run auth/Login — a post-response script stores access_token and refresh_token as secret environment variables automatically. All other requests pick up the token via {{access_token}}.
5. Run any other request. For detail endpoints, fill in :id (or :locationId, :product_id, :location_1, :location_2) in the params:path block.
6. Run auth/Logout to revoke the session and clear the stored tokens.

Environment variables

Defined in bruno/environments/dev.bru:

Variable	Purpose
baseUrl	API base URL (defaults to dev). Swap for other environments.
bu_code	Business unit code — path param on most endpoints
x_app_id	Application id sent as the x-app-id header
email / password	Credentials used by the login request
access_token (secret)	JWT written by the login post-response script
refresh_token (secret)	Refresh token written by login, sent by logout

To target a different environment (local, UAT, etc.), duplicate dev.bru and change baseUrl. Known servers from the OpenAPI spec:

• http://localhost:4000 / https://localhost:4001 — local
• http://dev.blueledgers.com:4000 / https://dev.blueledgers.com:4001 — dev
• https://43.209.126.252 — UAT

Collection layout

bruno/
├── bruno.json                        collection root
├── environments/
│   └── dev.bru                       baseUrl, bu_code, x_app_id, creds, secret tokens
├── auth/
│   ├── login.bru                     POST /api/auth/login (auto-stores tokens)
│   ├── logout.bru                    POST /api/auth/logout (clears tokens)
│   └── login/                        per-role / per-domain login variants
├── locations/                        CRUD on /api/config/{bu_code}/locations
├── products/                         CRUD on /api/config/{bu_code}/products
│   ├── category/                     CRUD on /products/category
│   ├── sub-category/                 CRUD on /products/sub-category
│   └── item-group/                   CRUD on /products/item-group
├── vendors/                          CRUD on /api/config/{bu_code}/vendors
├── locations-product/                list, by-location, between-locations, refresh
│                                     (config side: /api/config/{bu_code}/location-product)
└── product-locations/                read side
    ├── products-by-location.bru      GET /api/{bu_code}/products/locations/:id
    └── locations-by-product.bru      GET /api/{bu_code}/locations/product/:product_id

Conventions

• Auth: every non-auth request uses auth:bearer with {{access_token}}.
• Headers: x-app-id: {{x_app_id}} is sent on every request; write requests also set Content-Type: application/json.
• List endpoints: support optional query params page, perpage, search, filter, searchfields, sort (left empty / disabled by default using Bruno's ~ prefix).
• Bodies: examples come from the OpenAPI spec — adjust UUIDs (e.g. inventory_unit_id, tax_profile_id) to values that exist in your tenant before sending.

Troubleshooting

• 401 Unauthorized: run auth/Login again — the access token likely expired.
• Cannot connect / TLS errors against :4001: the dev server uses a self-signed cert. Enable Settings → SSL verification → off in Bruno, or switch baseUrl to the :4000 (http) server.
• 404 on /api/config/.../{id}: make sure bu_code matches the tenant that owns the resource.