# Product Integration (API)

### 1. Create Product

<mark style="color:green;">`POST`</mark> `https://ai-image-service-dev.internalsizebay.com/products`\
\
**Description:** Submits a product for asynchronous processing. A callback will notify success or failure after processing.&#x20;

#### Headers

| Header      | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| `x-api-key` | string | ✅        | API key for authentication |

#### Body Parameters

| Field                     | Type   | Required | Description                                  |
| ------------------------- | ------ | -------- | -------------------------------------------- |
| `tenantId`                | number | ✅        | Tenant (client) ID                           |
| `collectionName`          | string | ✅        | Product collection name                      |
| `processType`             | string | ✅        | Type: `SIMILAR`, `COMPLEMENTARY`, `ALL`      |
| `brandName`               | string | ✅        | Brand name                                   |
| `specialtyFromPersona`    | string | ✅        | Product style (e.g., "casual fashion")       |
| `productItem.id`          | string | ✅        | Unique ID of the variant (e.g. color + size) |
| `productItem.itemGroupId` | string | ✅        | Common ID for all variants of a product      |
| `localizations`           | object | ✅        | Language-specific title, link, availability  |
| `pricing`                 | object | ✅        | Prices by currency (price, salePrice, date)  |
| `productType`             | string | ✅        | Category hierarchy                           |
| `imageLink`               | string | ✅        | Main image of the variant                    |
| `additionalImageLinks`    | array  | Optional | Additional images for the variant            |
| `gender`                  | string | ✅        | `male`, `female`, `unisex`                   |
| `ageGroup`                | string | ✅        | `adult`, `kids`                              |
| `size`                    | string | ✅        | Sizes, comma-separated (e.g., `S,M,L`)       |
| `sizeSystem`              | string | ✅        | Size system (`BR`, `US`, etc.)               |
| `color`                   | string | ✅        | Product color                                |
| `gtin`                    | string | Optional | Barcode (Global Trade Item Number)           |

#### Callback Notification

After processing, a POST request is sent to your callback URL:

```
{
  "productId": "380145e972ee",
  "status": "success",
  "message": "Required only if status is 'error'"
}
```

> Header `Authorization` will be included in the request.

#### Payload Example

```json
{
  "tenantId": 1234,
  "collectionName": "sizebay-collection",
  "processType": "SIMILAR",
  "brandName": "Sizebay",
  "specialtyFromPersona": "casual fashion",
  "productItem": {
    "id": "380145e972ee",
    "itemGroupId": "edb1e435d172",
    "localizations": {
      "en-US": {
        "title": "Classic White T-Shirt",
        "availability": "in stock",
        "link": "www.example.com/us/product"
      },
      "pt-BR": {
        "title": "Camiseta Branca",
        "availability": "in stock",
        "link": "www.example.com/br/product"
      }
    },
    "pricing": {
      "USD": {
        "price": 25,
        "salePrice": 19.99,
        "salePriceEffectiveDate": "2024-06-10T00:00:00/2024-06-20T23:59:59"
      },
      "BRL": {
        "price": 99.9,
        "salePrice": 79.9,
        "salePriceEffectiveDate": "2024-06-10T00:00:00/2024-06-20T23:59:59"
      }
    },
    "productType": "KIDS > MALE > BOTTOMS",
    "brand": "Sizebay",
    "imageLink": "www.example.com/image.jpg",
    "additionalImageLinks": [
      "www.example.com/image.jpg"
    ],
    "gender": "unisex",
    "ageGroup": "adult",
    "size": "XS,S,M,L,XL",
    "sizeSystem": "BR",
    "color": "Blue",
    "gtin": "00012345678905"
  }
}
```

#### Responses

| Status | Meaning                         |
| ------ | ------------------------------- |
| 202    | Product accepted for processing |
| 400    | Invalid or missing fields       |
| 500    | Internal server error           |

### 2. Update Product

<mark style="color:green;">`PATCH`</mark> `https://ai-image-service-dev.internalsizebay.com/products`<br>

**Description:** Updates an existing product’s title, availability and pricing.

#### Headers

| Header      | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| `x-api-key` | string | ✅        | API key for authentication |

#### Body Parameters

| Field            | Type   | Required | Description                             |
| ---------------- | ------ | -------- | --------------------------------------- |
| `tenantId`       | number | ✅        | Tenant ID                               |
| `collectionName` | string | ✅        | Collection name                         |
| `productId`      | string | ✅        | ID of the product to update             |
| `localizations`  | object | ✅        | Updated title & availability per locale |
| `pricing`        | object | ✅        | Updated prices per currency             |

#### Payload Example

```json
{
  "tenantId": 123,
  "collectionName": "string",
  "productId": "FSW012345",
  "localizations": {
    "en-US": {
      "title": "Classic White T-Shirt",
      "availability": "in stock"
    },
    "pt-BR": {
      "title": "Camiseta Branca",
      "availability": "in stock"
    }
  },
  "pricing": {
    "USD": {
      "price": 25,
      "salePrice": 19.99,
      "salePriceEffectiveDate": "2024-06-10T00:00:00/2024-06-20T23:59:59"
    },
    "BRL": {
      "price": 99.9,
      "salePrice": 79.9,
      "salePriceEffectiveDate": "2024-06-10T00:00:00/2024-06-20T23:59:59"
    }
  }
}
```

#### Responses

| Status | Meaning                      |
| ------ | ---------------------------- |
| 200    | Product updated successfully |
| 400    | Invalid or missing fields    |
| 404    | Product not found            |
| 500    | Internal server error        |

### 3. Swagger – Interactive API Explorer

To simplify integration and testing, you can access the official [**Swagger API Reference**](https://ai-image-service-dev.internalsizebay.com/api/docs)**.**

What you can do there:

| Feature           | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| Explore endpoints | View all available endpoints with descriptions and example payloads         |
| Test requests     | Use the “Try it out” button to send test requests directly from the browser |
| Validate payloads | Ensure your request structure matches the API’s expected schema             |
| Check responses   | See example success and error responses                                     |
| Use your API key  | Authenticate and test using your tenant’s `x-api-key`                       |

> This tool is ideal for developers and integrators during setup, debugging, and ongoing maintenance.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sizebay.com/fashion-hub/product-integration-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.