Brand Management API

The Brand Management API allows you to manage brand information in the Nilo platform. These endpoints help you create, update, and retrieve brand data, including brand details and status.

Understanding Brands

Brands in Nilo represent the manufacturers or trademark owners of products:

Brand Structure
- Unique internal code for identification
- Name and image for display
- Weight for controlling display order
- Status for enabling/disabling visibility
- Optional metadata for additional information
Brand Hierarchy
- Independent entities not tied to categories
- Can be associated with multiple products
- Maintain their own status and visibility
- Support batch operations for bulk updates

Important Considerations

Unique Codes: Each brand requires a unique internal code for identification
Image Management: Brand images should follow specific format and size guidelines
Weight System: Controls the order of appearance in listings and searches
Status Control: Brands can be enabled or disabled without deletion
Batch Operations: Support for bulk updates to manage multiple brands efficiently

Single Brand Operations

Create Brand

POST/brand

Create a new brand in the Nilo platform. This endpoint is used to register all brand details including:

Brand information (name, internal code)
Brand image and weight

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Brand name
internalCode	string	Yes	Brand code (unique identifier)
weight	integer	No	Order positioning in listings
image	string	No	URL of brand image

Request Body Example

{
  "name": "Marca 1",
  "internalCode": "1235",
  "weight": 1,
  "image": "/qa/brand/12442.png"
}

Response Codes

Code	Description
200	Brand created successfully
404	Brand not found

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  name: "Marca 1",
  internalCode: "1235",
  weight: 1,
  image: "/qa/brand/12442.png",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "name": "Marca 1",
    "internalCode": "1235",
    "weight": 1,
    "image": "/qa/brand/12442.png"
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Get All Brands

GET/brand

Retrieve a paginated list of all brands. This endpoint is useful for:

Browsing through the brand catalog
Implementing pagination in your application
Filtering brands by enabled status

Query Parameters

Parameter	Type	Required	Description
take	number	No	Number of items per page (default: 50, max: 50)
page	string	No	Page number (default: 1)
enabled	boolean	No	Filter brands by enabled status (true for active, false for inactive)
cursor	string	No	Cursor for pagination. First call use 0, then use the cursor from the previous response

Response Example

{
  "data": [
    {
      "name": "Marca 1",
      "internalCode": "1235",
      "weight": 1,
      "image": "/qa/brand/12442.png"
    }
  ],
  "page": {
    "pageBased": {
      "count": 100
    },
    "cursorBased": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "firstCursor": "0",
      "lastCursor": "49"
    }
  }
}

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand?take=10&page=1&enabled=true",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand"
params = {
    "take": 10,
    "page": 1,
    "enabled": True
}

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get(url, headers=headers, params=params)
print(response.text)

Upsert Brand

PUT/brand

Create or update a brand in the Nilo platform. This endpoint is useful when you need to:

Create a new brand if it doesn't exist
Update an existing brand with new information

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Brand name
internalCode	string	Yes	Brand code (unique identifier)
weight	integer	No	Order positioning in listings
image	string	No	URL of brand image
enabled	boolean	Yes	Whether the brand is active

Request Body Example

{
  "name": "Marca 1",
  "internalCode": "1235",
  "weight": 1,
  "image": "/qa/brand/12442.png",
  "enabled": true
}

Response Codes

Code	Description
200	Brand upserted successfully
404	Brand not found

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  name: "Marca 1",
  internalCode: "1235",
  weight: 1,
  image: "/qa/brand/12442.png",
  enabled: true,
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand", {
  method: "PUT",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "name": "Marca 1",
    "internalCode": "1235",
    "weight": 1,
    "image": "/qa/brand/12442.png",
    "enabled": True
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Get Brand Details

GET/brand/{code}

Retrieve detailed information about a specific brand. This endpoint returns:

Brand metadata
Brand image and weight

Path Parameters

Parameter	Type	Description
code	string	Brand internal code (unique identifier)

Response Example

{
  "name": "Marca 1",
  "internalCode": "1235",
  "weight": 1,
  "image": "/qa/brand/12442.png"
}

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235", {
  method: "GET",
  headers: headers,
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

Update Brand

PUT/brand/{code}

Update an existing brand's information. This endpoint allows you to modify:

Brand name
Brand image
Brand weight for ordering

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Brand internal code (unique identifier)

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Brand name
weight	integer	No	Order positioning in listings
image	string	No	URL of brand image

Request Body Example

{
  "name": "Updated Brand Name",
  "weight": 2,
  "image": "/qa/brand/updated-image.png"
}

Response Codes

Code	Description
200	Brand updated successfully
404	Brand not found

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  name: "Updated Brand Name",
  weight: 2,
  image: "/qa/brand/updated-image.png",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235", {
  method: "PUT",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "name": "Updated Brand Name",
    "weight": 2,
    "image": "/qa/brand/updated-image.png"
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Change Brand Status

PUT/brand/{code}/status

Update the status of a brand. This endpoint allows you to:

Enable/disable a brand

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Brand internal code (unique identifier)

Request Body Parameters

Parameter	Type	Required	Description
enabled	boolean	Yes	Whether the brand should be enabled

Request Body Example

{
  "enabled": true
}

Response Codes

Code	Description
200	Status updated successfully
404	Brand not found

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  enabled: true,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235/status",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235/status"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "enabled": True
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Batch Operations

Batch Upsert Brands

POST/batch/brand

Perform bulk operations on brands. This endpoint allows you to:

Upsert multiple brands (update or create if not exists)

The batch operation is processed asynchronously, meaning you'll receive an immediate acknowledgment of the request, and the updates will be processed in the background.

Request Body Parameters

Parameter	Type	Description
upsert	array	Array of brands to update or create if needed

Request Body Example

{
  "upsert": [
    {
      "name": "Marca 1",
      "internalCode": "1235",
      "weight": 1,
      "image": "/qa/brand/12442.png",
      "enabled": true
    }
  ]
}

Response Codes

Code	Description
202	Batch request accepted for processing
402	Bad request

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  upsert: [
    {
      name: "Marca 1",
      internalCode: "1235",
      weight: 1,
      image: "/qa/brand/12442.png",
      enabled: true,
    },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/brand",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/brand"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "upsert": [
        {
            "name": "Marca 1",
            "internalCode": "1235",
            "weight": 1,
            "image": "/qa/brand/12442.png",
            "enabled": True
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Best Practices

Brand Management
- Use consistent naming conventions
- Maintain high-quality brand images
- Implement proper status management
- Keep brand information up to date
Code Structure
- Create meaningful internal codes
- Use consistent code patterns
- Document code conventions
- Validate codes before use
Image Handling
- Use optimized image formats
- Maintain consistent image dimensions
- Implement image caching
- Handle image updates efficiently
Performance Optimization
- Use batch operations for multiple updates
- Implement proper caching strategies
- Optimize image delivery
- Monitor API usage patterns

Common Use Cases

Initial Brand Setup
- Create brand profiles
- Upload brand images
- Set initial weights
- Configure brand status
Brand Maintenance
- Update brand information
- Manage brand visibility
- Adjust display order
- Update brand images
Bulk Operations
- Import multiple brands
- Update brand statuses
- Modify brand weights
- Sync brand data
Brand Integration
- Connect with product catalog
- Implement brand filtering
- Set up brand search
- Configure brand display

Response Types

Success Response

{
  "code": 200,
  "message": "Operation successful",
  "data": {
    "name": "Example Brand",
    "internalCode": "BRD-001",
    "image": "/brands/example.png",
    "enabled": true,
    "weight": 1
  }
}

Error Response Examples

Not Found

{
  "code": 404,
  "message": "Brand not found"
}

Validation Error

{
  "code": 400,
  "message": "Invalid brand data",
  "errors": [
    {
      "field": "internalCode",
      "message": "Internal code is required"
    }
  ]
}

Duplicate Error

{
  "code": 409,
  "message": "Brand with this internal code already exists"
}

Implementation Guidelines

Brand Creation
- Validate required fields
- Check for duplicate codes
- Process brand images
- Set default values
Brand Updates
- Verify brand existence
- Handle partial updates
- Manage image changes
- Update timestamps
Status Management
- Handle status transitions
- Update related products
- Maintain audit logs
- Notify relevant systems
Batch Processing
- Validate batch data
- Handle partial failures
- Implement rollback
- Report batch results

Security

All API endpoints require two types of authentication:

API Key in header: x-api-key
Authorization token in header: Authorization

Required Permissions

For brand management endpoints, the following permissions are required:

For read operations: supplier/brand.read
For write operations: supplier/brand.write

Error Handling

Input Validation
- Validate all required fields
- Check data types and formats
- Verify image specifications
- Validate internal codes
Error Responses
- Use appropriate HTTP status codes
- Provide detailed error messages
- Include field-level errors
- Add error tracking codes
Recovery Procedures
- Handle network failures
- Implement retry logic
- Maintain data consistency
- Log error details
Monitoring
- Track error rates
- Monitor API performance
- Alert on critical errors
- Analyze error patterns

Understanding Brands​

Important Considerations​

Single Brand Operations​

Create Brand​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Get All Brands​

Query Parameters​

Response Example​

Example Usage​

Upsert Brand​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Get Brand Details​

Path Parameters​

Response Example​

Example Usage​

Update Brand​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Change Brand Status​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Batch Operations​

Batch Upsert Brands​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Best Practices​

Common Use Cases​

Response Types​

Success Response​

Error Response Examples​

Not Found​

Validation Error​

Duplicate Error​

Implementation Guidelines​

Security​

Required Permissions​

Error Handling​

Understanding Brands

Important Considerations

Single Brand Operations

Create Brand

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Get All Brands

Query Parameters

Response Example

Example Usage

Upsert Brand

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Get Brand Details

Path Parameters

Response Example

Example Usage

Update Brand

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Change Brand Status

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Batch Operations

Batch Upsert Brands

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Best Practices

Common Use Cases

Response Types

Success Response

Error Response Examples

Not Found

Validation Error

Duplicate Error

Implementation Guidelines

Security

Required Permissions

Error Handling