API reference

Organizations & Locations

REST endpoints for managing your organization's profile (name, billing address), its locations, and its notification subscriber list.

Organizations & Locations

The Organizations API covers the eight endpoints under /api/v1/org that read and write your organization's profile and its locations subcollection. Use it to fetch the organization profile, rename the organization, edit the billing address used on invoices, manage the list of physical locations that devices are attached to, and configure who receives email notifications for reports, alerts, billing events, device events and analytics.

Unlike the Receipts, Devices and Reports APIs, none of the routes on this page accept an API key. The whole /api/v1/org surface requires a Portal session token. Generate one with POST /api/v1/auth/login and pass it as Authorization: Bearer <jwt>. There is no API-key scope that grants access to organization administration. See Authentication › JWT authentication.

The error envelope, rate limits and pagination conventions are documented once on API overview; only the per-endpoint error codes are listed in full on this page.

GET /api/v1/org

Returns the organization document for the authenticated user's organization (resolved from the JWT's orgId claim).

Auth: Portal JWT (any org member)

Response 200

{
  "id": "acme_corp",
  "name": "Acme Corp SRL",
  "cui": "RO12345678",
  "billingAddress": {
    "country": "Romania",
    "county": "București",
    "city": "București",
    "street": "Str. Lipscani 12, ap. 4",
    "postalCode": "030031"
  },
  "plan": "pro",
  "createdAt": "2025-09-01T08:00:00.000Z",
  "updatedAt": "2026-04-01T12:30:00.000Z"
}

The exact set of fields depends on what is stored — cui, plan, billingAddress and any other organization-level metadata are returned unchanged. All timestamps are returned as ISO-8601 strings.

Errors

UNAUTHORIZED (401) — missing or invalid JWT.
NOT_FOUND (404) — the JWT's orgId does not resolve to an organization. This normally only happens after a manual data deletion.

The full HTTP catalogue is on API overview › HTTP error code catalogue.

Example

curl https://api.e-bon.ro/api/v1/org \
  -H "Authorization: Bearer <portal-jwt>"

PATCH /api/v1/org

Updates the organization's display name and/or billing address. At least one field must be provided. Other organization fields (cui, plan, createdAt, …) cannot be edited through this endpoint.

Auth: Portal JWT, role Owner or Admin

Request body

Field	Type	Required	Notes
`name`	string	no	1–255 chars. Empty string is rejected.
`billingAddress`	object	no	All sub-fields optional. Sending the object replaces the previous one.
`billingAddress.country`	string	no	≤ 100 chars.
`billingAddress.county`	string	no	≤ 100 chars.
`billingAddress.city`	string	no	≤ 100 chars.
`billingAddress.street`	string	no	≤ 300 chars.
`billingAddress.postalCode`	string	no	≤ 20 chars.

The schema enforces that the body is not empty — at least one of name or billingAddress must be present.

Response 200

The updated organization document, in the same shape as GET /api/v1/org.

Errors

VALIDATION_ERROR (400) — body failed validation, or no fields were provided.
UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller is not Owner or Admin.
NOT_FOUND (404) — organization does not exist.

Example

curl -X PATCH https://api.e-bon.ro/api/v1/org \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp SRL",
    "billingAddress": {
      "country": "Romania",
      "county": "București",
      "city": "București",
      "street": "Str. Lipscani 12, ap. 4",
      "postalCode": "030031"
    }
  }'

GET /api/v1/org/locations

Returns every location that belongs to the authenticated user's organization, ordered by createdAt descending (most recently created first). Every device in e-bon is attached to exactly one location, and each receipt inherits the device's location, so this list is the canonical "where do I do business" registry.

Auth: Portal JWT (any org member)

Response 200

[
  {
    "id": "loc_main",
    "name": "Sediu principal",
    "address": "Str. Lipscani 12, București",
    "orgId": "acme_corp",
    "createdAt": "2025-09-01T08:00:00.000Z",
    "updatedAt": "2026-02-15T10:00:00.000Z"
  },
  {
    "id": "loc_warehouse",
    "name": "Depozit Pipera",
    "address": "Bd. Pipera 21, Voluntari",
    "orgId": "acme_corp",
    "createdAt": "2025-10-10T08:00:00.000Z",
    "updatedAt": "2025-10-10T08:00:00.000Z"
  }
]

The endpoint always returns an array — never paginated. If your organization has no locations, the response is [].

Errors

UNAUTHORIZED (401) — missing or invalid JWT.

Example

curl https://api.e-bon.ro/api/v1/org/locations \
  -H "Authorization: Bearer <portal-jwt>"

POST /api/v1/org/locations

Creates a new location under the organization. The location's orgId is set automatically from the JWT — there is no way to create a location in another organization.

Auth: Portal JWT, role Owner or Admin

Request body

Field	Type	Required	Notes
`name`	string	yes	1–255 chars.
`address`	string	yes	1–500 chars.

Response 201

{
  "id": "loc_warehouse",
  "name": "Depozit Pipera",
  "address": "Bd. Pipera 21, Voluntari",
  "orgId": "acme_corp",
  "createdAt": "2026-04-09T08:10:00.000Z",
  "updatedAt": "2026-04-09T08:10:00.000Z"
}

The response includes ISO-8601 timestamps for the newly created location.

Errors

VALIDATION_ERROR (400) — body failed validation (missing field, length out of range).
UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller is not Owner or Admin.

Example

curl -X POST https://api.e-bon.ro/api/v1/org/locations \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Depozit Pipera",
    "address": "Bd. Pipera 21, Voluntari"
  }'

PATCH /api/v1/org/locations/{locationId}

Updates the name and/or address of an existing location. At least one field must be provided.

Auth: Portal JWT, role Owner or Admin

Path parameters

Parameter	Type	Notes
`locationId`	string	ID returned by `POST /locations` or `GET /locations`.

Request body

Field	Type	Required	Notes
`name`	string	no	1–255 chars. Empty string is rejected.
`address`	string	no	1–500 chars. Empty string is rejected.

Response 200

The updated location document, same shape as the GET /api/v1/org/locations items.

Errors

VALIDATION_ERROR (400) — body failed validation, or no fields were provided.
UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller is not Owner or Admin.
NOT_FOUND (404) — no location with that ID in your organization.

Example

curl -X PATCH https://api.e-bon.ro/api/v1/org/locations/loc_warehouse \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Depozit Pipera (etaj 2)" }'

DELETE /api/v1/org/locations/{locationId}

Permanently deletes a location. The request is refused if any device is currently assigned to the location — move or delete those devices first via the Devices API.

Auth: Portal JWT, role Owner or Admin

Path parameters

Parameter	Type	Notes
`locationId`	string	Location to delete.

Response 204

Empty body on success.

Errors

UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller is not Owner or Admin.
NOT_FOUND (404) — no location with that ID in your organization.
CONFLICT (409) — one or more devices are still assigned to the location. The error message includes the count, e.g. Cannot delete location — it has 3 device(s) assigned. Move or delete the devices first.

Example

curl -X DELETE https://api.e-bon.ro/api/v1/org/locations/loc_warehouse \
  -H "Authorization: Bearer <portal-jwt>"

GET /api/v1/org/settings/notifications

Returns the organization's notification subscriber list — the email addresses that receive system notifications, and the categories each subscriber is opted into. Up to 20 subscribers are supported.

Auth: Portal JWT, role Owner or Admin

For backward compatibility, if your organization still has legacy notification emails from an older format, they are returned as subscribers opted into all categories. Call PATCH to migrate explicitly to the new subscriber model.

Response 200

{
  "subscribers": [
    {
      "email": "owner@acme.example",
      "categories": ["reports", "billing"]
    },
    {
      "email": "ops@acme.example",
      "categories": ["alerts", "device_events", "analytics"]
    }
  ]
}

The five valid category values are:

Category	Notifications it covers
`reports`	X/Z and monthly fiscal reports.
`alerts`	Operational alerts.
`billing`	Invoices, plan changes, payment events.
`device_events`	Device online / offline / error events.
`analytics`	Periodic analytics digests.

Errors

UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller is not Owner or Admin.
NOT_FOUND (404) — organization document does not exist.

Example

curl https://api.e-bon.ro/api/v1/org/settings/notifications \
  -H "Authorization: Bearer <portal-jwt>"

PATCH /api/v1/org/settings/notifications

Replaces the organization's notification subscriber list. The body is the complete list — passing an empty array clears all subscribers. There is no per-subscriber add/remove endpoint; read the current list, mutate it client-side, then write it back.

Auth: Portal JWT, role Owner or Admin

Request body

Field	Type	Required	Notes
`subscribers`	object	yes	0–20 entries. The full list replaces the previous one.
`subscribers[].email`	string	yes	Must be a valid email address.
`subscribers[].categories`	string	yes	At least one entry. Each value must be one of the five categories above.

Response 200

{
  "subscribers": [
    { "email": "owner@acme.example", "categories": ["reports", "billing"] }
  ]
}

Errors

VALIDATION_ERROR (400) — body failed validation (invalid email, unknown category, more than 20 subscribers, empty categories).
UNAUTHORIZED (401) — missing or invalid JWT.
FORBIDDEN (403) — caller is not Owner or Admin.
NOT_FOUND (404) — organization document does not exist.

Example

curl -X PATCH https://api.e-bon.ro/api/v1/org/settings/notifications \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribers": [
      { "email": "owner@acme.example", "categories": ["reports", "billing"] },
      { "email": "ops@acme.example",   "categories": ["alerts", "device_events"] }
    ]
  }'