Products API Documentation

Manage your products programmatically using our REST API.

🔐 Authentication

All API requests require authentication using your company's API key. Include the X-API-Key header in every request.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://poslovno.ba/api/v1/products

Contact support to obtain your API key (EntityHash).

🌐 Base URL

https://poslovno.ba/api/v1

📚 Endpoints

GET/api/v1/products

Get all products for your company

Query Parameters

Name	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page (max 100)
`isActive`	boolean	-	Filter by active status
`category`	string	-	Filter by category ID

Response (200)

{
  "success": true,
  "data": [
    {
      "_id": "693f43dc8cdc5130d6ca085b",
      "name": "Product Name",
      "description": "...",
      "category": "25",
      "variants": [...],
      "isActive": true,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5,
    "hasMore": true
  }
}

GET/api/v1/products/{productId}

Get a single product by ID

Response (200)

{
  "success": true,
  "data": {
    "_id": "693f43dc8cdc5130d6ca085b",
    "name": "Product Name",
    "description": "Product description",
    "category": "25",
    "tags": ["tag1", "tag2"],
    "images": ["image1.jpg"],
    "variants": [
      {
        "variantName": "Default",
        "sku": "SKU123",
        "price": 99.99,
        "unit": "kom",
        "availableStock": 100,
        "images": ["https://s3.amazonaws.com/your-bucket/variant-img.jpg", "https://s3.amazonaws.com/your-bucket/variant2-img.jpg"],
        "isActive": true
      }
    ],
    "currency": "BAM",
    "isActive": true,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  }
}

POST/api/v1/products

Create a new product. Note: At least one variant is required, and for images you can use your own self hosted urls (https://yourdomain.com/image.jpg).

Request Body

{
  "name": "Product Name",           // required
  "description": "Description",     // optional
  "category": 25,                   // optional (category ID)
  "tags": ["tag1", "tag2"],         // optional
  "images": ["image1.jpg"],         // optional
  "variants": [                     // optional
    {
      "variantName": "Default",     // required if variants provided
      "sku": "SKU123",
      "price": 99.99,
      "unit": "kom",
      "availableStock": 100,
      "images": ["variant-img.jpg", "variant-img2.jpg"],
      "isActive": true
    }
  ],
  "currency": "BAM",                // optional, default: "BAM"
  "isActive": true                  // optional, default: true
}

Response (201)

{
  "success": true,
  "data": { ... },
  "message": "Product created successfully"
}

POST/api/v1/products/bulk

Create multiple products in a single request (max 100). Each product must include at least one variant. For images, you can use your own self hosted URLs (https://yourdomain.com/image.jpg). All fields are the same as in the single product creation endpoint.

Request Body

{
  "products": [
    {
      "name": "Product 1",
      "category": 25,
      "variants": [{"variantName": "Default", "price": 10}]
    },
    {
      "name": "Product 2",
      "category": 25,
      "variants": [{"variantName": "Default", "price": 20}]
    }
  ]
}

Response (201)

{
  "success": true,
  "data": [...],
  "summary": {
    "requested": 2,
    "created": 2,
    "failed": 0
  },
  "message": "Successfully created 2 product(s)"
}

PUT/api/v1/products/{productId}

Update a product (partial update - only include fields to change)

Request Body

{
  "name": "Updated Name",           // optional
  "description": "New description", // optional
  "category": 30,                   // optional
  "isActive": false,                // optional
  "variants": [...]                 // optional (replaces all variants)
}

Response (200)

{
  "success": true,
  "data": { ... },
  "message": "Product updated successfully"
}

DELETE/api/v1/products/{productId}

Delete a product (soft delete)

Response (200)

{
  "success": true,
  "message": "Product deleted successfully"
}

⚠️ Error Responses

All errors return JSON with an error field:

{
  "error": "Error message description"
}

Status Code	Description
`400`	Bad Request - Invalid input data
`401`	Unauthorized - Missing or invalid API key
`404`	Not Found - Product doesn't exist
`503`	Service Unavailable - Database connection failed
`500`	Internal Server Error

💻 Code Examples

cURL

# Get all products
curl -X GET "https://poslovno.ba/api/v1/products?page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

# Create a product
curl -X POST "https://poslovno.ba/api/v1/products" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Product", "category": 25, "basePrice": 99.99}'

# Update a product
curl -X PUT "https://poslovno.ba/api/v1/products/PRODUCT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "isActive": false}'

# Delete a product
curl -X DELETE "https://poslovno.ba/api/v1/products/PRODUCT_ID" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript / Node.js

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://poslovno.ba/api/v1';

// Get all products
const response = await fetch(`${BASE_URL}/products`, {
  headers: { 'X-API-Key': API_KEY }
});
const data = await response.json();

// Create a product
const newProduct = await fetch(`${BASE_URL}/products`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Product',
    category: 25,
    variants: [{
      variantName: 'Default',
      price: 99.99,
      availableStock: 100
    }]
  })
});

Python

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://poslovno.ba/api/v1'
headers = {'X-API-Key': API_KEY}

# Get all products
response = requests.get(f'{BASE_URL}/products', headers=headers)
products = response.json()

# Create a product
new_product = requests.post(
    f'{BASE_URL}/products',
    headers={**headers, 'Content-Type': 'application/json'},
    json={
        'name': 'My Product',
        'category': 25,
        'variants': [{
            'variantName': 'Default',
            'price': 99.99,
            'availableStock': 100
        }]
    }
)
print(new_product.json())

ℹ️ Rate Limits

Currently there are no rate limits. Please use the API responsibly. Bulk operations are limited to 100 items per request.