Ultra B2B API V1

Basics

https://eshop.ultra.md/api

Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>

Authentication

POST /api/auth/token and POST /api/auth/refresh are public. All other V1 routes in this document require a valid bearer token and use the bearer-api throttle. Access tokens expire after 1 hour. Refresh tokens expire after 30 days and rotate on every refresh.

Create tokens

POST /api/auth/token

Request body:

{
  "username": "dealer@example.com",
  "password": "secret"
}

Response status: 200 OK

{
  "access_token": "1|plain-access-token",
  "refresh_token": "plain-refresh-token",
  "expires_in": 3600,
  "token_type": "Bearer",
  "user_email": "dealer@example.com",
  "user_id": 10
}

Refresh access token

POST /api/auth/refresh

Request body:

{
  "refresh_token": "plain-refresh-token"
}

Response status: 200 OK

{
  "access_token": "2|new-plain-access-token",
  "refresh_token": "new-plain-refresh-token",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Revoke access token

With an empty payload, the current access token is revoked.

POST /api/auth/revoke

Request body:

{}

To revoke a specific access token owned by the current user, pass the plain token value:

Request body:

{
  "token": "2|plain-access-token"
}

Response status: 200 OK

{
  "message": "Token revoked successfully"
}

Endpoints

Products

List products

GET /api/product?category=CAT-001&in_stock=true&limit=50&offset=0

Response status: 200 OK

[
  {
    "ultra_code": "PRD-001",
    "ultra_uuid": "product-uuid",
    "product_name": {"ro": "Produs", "ru": "Product"},
    "description": "Description",
    "description_by_language": {
      "romanian": "Descriere",
      "russian": "Opisanie",
      "english": "Description"
    },
    "quantity": 12,
    "image_urls": ["https://cdn.example.com/product.jpg"],
    "brand": {
      "uuid": "brand-uuid",
      "name": "Brand",
      "updated_at": "2026-06-15T10:30:00"
    },
    "category": {
      "uuid": "category-uuid",
      "name": {"ro": "Categorie", "ru": "Category"},
      "updated_at": "2026-06-15T10:30:00",
      "level": null,
      "hierarchy": []
    },
    "user_price": null,
    "fixed_price": null,
    "price_d": null,
    "promo_b2b": null,
    "property_groups": [],
    "updated_at": "2026-06-15T10:30:00",
    "created_at": "2026-06-01T10:30:00"
  }
]

Fetch one product

GET /api/product/PRD-001

Response status: 200 OK

The response is a single product object with the same fields as the list endpoint. If the product is not found, the API returns 404 Not Found.

Fetch products in batch

ultra_codes accepts up to 1000 values. Each value can be an ultra_code or ultra_uuid.

POST /api/product/batch

Request body:

{
  "ultra_codes": ["PRD-001", "PRD-002"]
}

Response status: 200 OK

The response is an array of product objects with the same fields as GET /api/product.

Categories

List categories

Use code to filter by category ultra_code.

GET /api/category?code=CAT-001

Response status: 200 OK

[
  {
    "uuid": "category-uuid",
    "code": "CAT-001",
    "name": {"ro": "Categorie", "ru": "Category"},
    "product_count": 120,
    "updated_at": "2026-06-15T10:30:00"
  }
]

Fetch one category

Pass include_products=true to include a compact products list.

GET /api/category/CAT-001?include_products=true

Response status: 200 OK

{
  "uuid": "category-uuid",
  "code": "CAT-001",
  "name": {"ro": "Categorie", "ru": "Category"},
  "product_count": 2,
  "updated_at": "2026-06-15T10:30:00",
  "products": [
    {
      "ultra_code": "PRD-001",
      "product_name": {"ro": "Produs", "ru": "Product"},
      "quantity": 12,
      "price": {
        "amount": 100,
        "currency": "MDL"
      }
    }
  ]
}

products contains compact product rows for category previews or quick category synchronization. Product detail pages should still use GET /api/product/{id}.

Category extra prices

The authenticated user must be associated with a store.

GET /api/category/extra-prices

Response status: 200 OK

[
  {
    "id": 1,
    "category": {
      "uuid": "category-uuid",
      "code": "CAT-001",
      "name": {"ro": "Categorie", "ru": "Category"}
    },
    "price_extra": 5
  }
]

Quantities

Quantity identifiers can be ultra_code or ultra_uuid.

List quantities

GET /api/quantity?category=CAT-001&low_stock=5

Response status: 200 OK

Fetch one quantity

GET /api/quantity/PRD-001

Response status: 200 OK

Fetch quantities in batch

POST /api/quantity/batch

Request body:

{
  "ultra_codes": ["PRD-001", "PRD-002"]
}

Response status: 200 OK

{
  "ultra_code": "PRD-001",
  "product_name": {"ro": "Produs", "ru": "Product"},
  "quantity": 12,
  "updated_at": "2026-06-15T10:30:00"
}

Brands

Use GET /api/brand to list brands and GET /api/brand/{id} to fetch one brand.

GET /api/brand?code=BR-001

Response status: 200 OK

[
  {
    "code": "BR-001",
    "uuid": "brand-uuid",
    "name": "Brand",
    "product_count": 25,
    "updated_at": "2026-06-15T10:30:00"
  }
]

Fetch one brand

GET /api/brand/BR-001

Response status: 200 OK

The response is a single brand object with the same fields as the list endpoint.

Changes

Use GET /api/changes for incremental synchronization. Store the returned next_since and use it as the next request's since value while has_more is true.

GET /api/changes?since=2026-06-15T00:00:00&entity=product&limit=100

Response status: 200 OK

{
  "changes": [
    {
      "entity": "product",
      "action": "updated",
      "entity_id": "PRD-001",
      "changed_at": "2026-06-15T10:30:00.000000Z",
      "fields_changed": ["product"]
    }
  ],
  "next_since": "2026-06-15T10:30:00.000000Z",
  "has_more": false
}

Orders

Create order

POST /api/order

Request body:

{
  "delivery": "pickup",
  "payment": "cash",
  "shipping_data": {
    "storeId": "1",
    "filialId": "2",
    "client_type": "1",
    "name": "Customer Name",
    "phone": "+37300000000",
    "address": "Street 1",
    "city": "Chisinau",
    "recipient": "Customer Name"
  },
  "products": [
    {"ultra_code": "PRD-001", "quantity": 2},
    {"ultra_uuid": "product-uuid", "quantity": 1}
  ]
}

Response status: 200 OK

{
  "message": "Order created successfully",
  "order_id": 12345
}

Read orders

• GET /api/order returns orders that belong to the authenticated user.
• GET /api/order/{id} returns one authenticated-user order and includes its items.
• GET /api/orders/all returns store-associated orders when the user has access.

GET /api/order

GET /api/order/12345

GET /api/orders/all

Response status: 200 OK

{
  "order_id": 12345,
  "user_id": 10,
  "delivery": "pickup",
  "payment": "cash",
  "total": 1200.5,
  "status": 1,
  "created_at": "2026-06-15T10:30:00",
  "updated_at": "2026-06-15T10:45:00",
  "shipping_data": {
    "phone": "+37300000000",
    "name": "Customer Name",
    "storeId": "1",
    "filialId": "2",
    "client_type": "1",
    "delivery_status": null,
    "destination": null
  },
  "exchange_rate": null,
  "items": [
    {
      "product_ultra_uuid": "product-uuid",
      "product_name": {"ro": "Produs", "ru": "Product"},
      "quantity": 2,
      "price": 600.25
    }
  ]
}

Health

GET /api/health

Response status: 200 OK

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-06-15T10:30:00",
  "services": {
    "database": "healthy",
    "cache": "healthy",
    "auth": "healthy"
  },
  "uptime_seconds": 1
}

Errors and Status Codes

{
  "message": "Bad Request",
  "errors": {
    "field": ["Validation message"]
  }
}

{
  "message": "Invalid or expired token."
}

Integration notes

• Keep access tokens in server-side storage and rotate them through /auth/refresh before expiry.
• Use limit and offset for large catalog reads, and keep page sizes below 1000.
• Prefer /changes for regular synchronization instead of repeatedly downloading the full catalog.
• Retry 429 responses with backoff. Do not retry validation errors without changing the request.
• Use stable identifiers: ultra_code for business integrations and ultra_uuid when the UUID is already stored in your system.