# 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.