Customizer – integracja API

Integracja API – uwierzytelnianie

Aby zintegrować się z API Customizera i pobierać dane produktów, musisz najpierw wygenerować klucze dostępu.

Generowanie kluczy API:

  1. Zaloguj się do panelu: Ustawienia e-commerce
  2. Przejdź do sekcji Integracja API.
  3. Kliknij Generuj klucze API. ⚠️ Klucze można wyświetlić tylko raz po wygenerowaniu. Jeśli je utracisz, konieczne będzie wygenerowanie nowych.

Nagłówki uwierzytelniające

Wszystkie żądania muszą zawierać nagłówki z danymi uwierzytelniającymi (tylko po stronie serwera!).

x-alter-access-key: API_KEY
x-alter-access-token: API_TOKEN

Test połączenia

Aby sprawdzić, czy połączenie z API działa poprawnie, wyślij żądanie GET na adres:

GET https://alterproduct.com/public-api/v1/auth/check

Oczekiwana odpowiedź:

{
  "message": "success"
}

Przykład żądania (Node.js / fetch)

const response = await fetch('https://alterproduct.com/public-api/v1/auth/check', {
  method: 'GET',
  headers: {
    'x-alter-access-key': 'YOUR_API_KEY',
    'x-alter-access-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  }
});

const result = await response.json();
console.log(result);

Przykład żądania (axios)

import axios from 'axios';

const result = await axios.get('https://alterproduct.com/public-api/v1/auth/check', {
  headers: {
    'x-alter-access-key': 'YOUR_API_KEY',
    'x-alter-access-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  }
});

console.log(result.data);

API – Endpointy dla zamówień klientów

Lista dostępnych endpointów dla zasobu customer-orders, używanych do pobierania i aktualizowania zamówień klientów (np. po dodaniu projektu do koszyka w Customizerze). Zamówienia możesz przeglądać również na stronie zamówień.
MetodaEndpointOpis
GET/public-api/v1/customer-orders/:idPobiera szczegóły pojedynczego zamówienia
POST/public-api/v1/customer-orders/batchPobiera listę zamówień na podstawie tablicy ID
PATCH/public-api/v1/customer-orders/:id/statusAktualizuje status zamówienia
PATCH/public-api/v1/customer-orders/:orderId/quantityAktualizuje ilość wybranej pozycji produktu w zamówieniu
PATCH/public-api/v1/customer-orders/:orderId/quantity/allUstawia tę samą ilość dla wszystkich pozycji produktu w zamówieniu
DELETE/public-api/v1/customer-orders/:idUsuwa zamówienie

Pobieranie pojedynczego zamówienia klienta

GET https://alterproduct.com/public-api/v1/customer-orders/:id

Endpoint zwraca pełne szczegóły pojedynczego zamówienia klienta – w tym status, przypisany projekt, model 3D, link do edycji, wybrany wariant oraz całkowitą cenę.

Przykład żądania (fetch)

const res = await fetch('https://alterproduct.com/public-api/v1/customer-orders/1', {
  method: 'GET',
  headers: {
    'x-alter-access-key': 'YOUR_API_KEY',
    'x-alter-access-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

const data = await res.json();
console.log(data);

Przykładowa odpowiedź

{
    "success": true,
    "customerOrder": {
        "id": 1,
        "customizerId": 10,
        "orderStatus": "pending",
        "createdAt": "2025-07-28T14:18:20.000Z",
        "customizerOrderURL": "https://alterproduct.com/app/customizer/10/1",
        "productItems": [
            {
                "id": 1,
                "model3d": {
                    "id": 10
                },
                "size": {
                    "id": 9,
                    "name": {
                        "pl": "450ml (15oz)",
                        "en": "450ml (15oz)"
                    },
                    "measureSize": {
                        "D": 8.65,
                        "H": 11.95
                    }
                },
                "material": {
                    "id": 3,
                    "name": {
                        "pl": "Ceramika",
                        "en": "Ceramic"
                    }
                },
                "printType": {
                    "id": 5,
                    "name": {
                        "pl": "Sublimacja",
                        "en": "Sublimation"
                    }
                },
                "color": {
                    "id": 11,
                    "name": {
                        "pl": "Domyślny",
                        "en": "Default"
                    },
                    "hex": "#FFFFFF"
                },
                "variant": {
                    "id": 11,
                    "productGroupId": 1,
                    "productModel3dId": 3,
                    "sizeId": 9,
                    "materialId": 3,
                    "printTypeId": 5,
                    "colorId": 11,
                    "metadata": null,
                    "minOrderQuantity": null,
                    "processingTime": null,
                    "stockQuantity": null,
                    "volume": null,
                    "weight": null
                },
                "unitPrice": {
                    "value": 0,
                    "currency": "EUR"
                },
                "totalPrice": {
                    "value": 0,
                    "currency": "EUR"
                },
                "quantity": 1,
                "updatedAt": "2025-07-28 14:18:20.000000"
            }
        ],
        "designName": "Mug 450ml (15oz)",
        "productGroup": {
            "id": 1,
            "name": {
                "pl": "Kubek 450ml (15oz)",
                "en": "Mug 450ml (15oz)"
            }
        },
        "totalPrice": {
            "value": 0,
            "currency": "EUR"
        }
    }
}

Pobieranie wielu zamówień

POST https://alterproduct.com/public-api/v1/customer-orders/batch

Endpoint pozwala pobrać listę zamówień na podstawie ich ID. Szczególnie przydatny, gdy użytkownik dodał wiele projektów do koszyka.

Przykład żądania

JSON body:

{
  "customerOrderIds": [1, 2, 3]
}

fetch (Node.js):

const response = await fetch('https://alterproduct.com/public-api/v1/customer-orders/batch', {
  method: 'POST',
  headers: {
    'x-alter-access-key': 'YOUR_API_KEY',
    'x-alter-access-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerOrderIds: [1, 2, 3]
  })
});

const data = await response.json();
console.log(data);

Przykładowa odpowiedź

{
    "success": true,
    "customerOrders": [
        {
            "id": 1,
            "customizerId": 10,
            "orderStatus": "pending",
            "createdAt": "2025-07-28T14:18:20.000Z",
            "customizerOrderURL": "https://alterproduct.com/app/customizer/10/1",
            "productItems": [
                {
                    "id": 1,
                    "model3d": {
                        "id": 10
                    },
                    "size": {
                        "id": 9,
                        "name": {
                            "pl": "450ml (15oz)",
                            "en": "450ml (15oz)"
                        },
                        "measureSize": {
                            "D": 8.65,
                            "H": 11.95
                        }
                    },
                    "material": {
                        "id": 3,
                        "name": {
                            "pl": "Ceramika",
                            "en": "Ceramic"
                        }
                    },
                    "printType": {
                        "id": 5,
                        "name": {
                            "pl": "Sublimacja",
                            "en": "Sublimation"
                        }
                    },
                    "color": {
                        "id": 11,
                        "name": {
                            "pl": "Domyślny",
                            "en": "Default"
                        },
                        "hex": "#FFFFFF"
                    },
                    "variant": {
                        "id": 11,
                        "productGroupId": 1,
                        "productModel3dId": 3,
                        "sizeId": 9,
                        "materialId": 3,
                        "printTypeId": 5,
                        "colorId": 11,
                        "metadata": null,
                        "minOrderQuantity": null,
                        "processingTime": null,
                        "stockQuantity": null,
                        "volume": null,
                        "weight": null
                    },
                    "unitPrice": {
                        "value": 0,
                        "currency": "EUR"
                    },
                    "totalPrice": {
                        "value": 0,
                        "currency": "EUR"
                    },
                    "quantity": 1,
                    "updatedAt": "2025-07-28 14:18:20.000000"
                }
            ],
            "designName": "Mug 450ml (15oz)",
            "productGroup": {
                "id": 1,
                "name": {
                    "pl": "Kubek 450ml (15oz)",
                    "en": "Mug 450ml (15oz)"
                }
            },
            "totalPrice": {
                "value": 0,
                "currency": "EUR"
            }
        },
        {
            "id": 2,
            "customizerId": 10,
            "orderStatus": "pending",
            "createdAt": "2025-07-28T14:20:48.000Z",
            "customizerOrderURL": "https://alterproduct.com/app/customizer/10/2",
            "productItems": [
                {
                    "id": 2,
                    "model3d": {
                        "id": 10
                    },
                    "size": {
                        "id": 9,
                        "name": {
                            "pl": "450ml (15oz)",
                            "en": "450ml (15oz)"
                        },
                        "measureSize": {
                            "D": 8.65,
                            "H": 11.95
                        }
                    },
                    "material": {
                        "id": 3,
                        "name": {
                            "pl": "Ceramika",
                            "en": "Ceramic"
                        }
                    },
                    "printType": {
                        "id": 5,
                        "name": {
                            "pl": "Sublimacja",
                            "en": "Sublimation"
                        }
                    },
                    "color": {
                        "id": 11,
                        "name": {
                            "pl": "Domyślny",
                            "en": "Default"
                        },
                        "hex": "#FFFFFF"
                    },
                    "variant": {
                        "id": 11,
                        "productGroupId": 1,
                        "productModel3dId": 3,
                        "sizeId": 9,
                        "materialId": 3,
                        "printTypeId": 5,
                        "colorId": 11,
                        "metadata": null,
                        "minOrderQuantity": null,
                        "processingTime": null,
                        "stockQuantity": null,
                        "volume": null,
                        "weight": null
                    },
                    "unitPrice": {
                        "value": 0,
                        "currency": "EUR"
                    },
                    "totalPrice": {
                        "value": 0,
                        "currency": "EUR"
                    },
                    "quantity": 1,
                    "updatedAt": "2025-07-28 14:20:48.000000"
                }
            ],
            "designName": "Mug 450ml (15oz)",
            "productGroup": {
                "id": 1,
                "name": {
                    "pl": "Kubek 450ml (15oz)",
                    "en": "Mug 450ml (15oz)"
                }
            },
            "totalPrice": {
                "value": 0,
                "currency": "EUR"
            }
        },
        {
            "id": 3,
            "customizerId": 10,
            "orderStatus": "pending",
            "createdAt": "2025-07-28T14:21:19.000Z",
            "customizerOrderURL": "https://alterproduct.com/app/customizer/10/3",
            "productItems": [
                {
                    "id": 3,
                    "model3d": {
                        "id": 10
                    },
                    "size": {
                        "id": 9,
                        "name": {
                            "pl": "450ml (15oz)",
                            "en": "450ml (15oz)"
                        },
                        "measureSize": {
                            "D": 8.65,
                            "H": 11.95
                        }
                    },
                    "material": {
                        "id": 3,
                        "name": {
                            "pl": "Ceramika",
                            "en": "Ceramic"
                        }
                    },
                    "printType": {
                        "id": 5,
                        "name": {
                            "pl": "Sublimacja",
                            "en": "Sublimation"
                        }
                    },
                    "color": {
                        "id": 11,
                        "name": {
                            "pl": "Domyślny",
                            "en": "Default"
                        },
                        "hex": "#FFFFFF"
                    },
                    "variant": {
                        "id": 11,
                        "productGroupId": 1,
                        "productModel3dId": 3,
                        "sizeId": 9,
                        "materialId": 3,
                        "printTypeId": 5,
                        "colorId": 11,
                        "metadata": null,
                        "minOrderQuantity": null,
                        "processingTime": null,
                        "stockQuantity": null,
                        "volume": null,
                        "weight": null
                    },
                    "unitPrice": {
                        "value": 0,
                        "currency": "EUR"
                    },
                    "totalPrice": {
                        "value": 0,
                        "currency": "EUR"
                    },
                    "quantity": 1,
                    "updatedAt": "2025-07-28 14:21:19.000000"
                }
            ],
            "designName": "Mug 450ml (15oz)",
            "productGroup": {
                "id": 1,
                "name": {
                    "pl": "Kubek 450ml (15oz)",
                    "en": "Mug 450ml (15oz)"
                }
            },
            "totalPrice": {
                "value": 0,
                "currency": "EUR"
            }
        }
    ]
}

Aktualizacja statusu zamówienia

PATCH https://alterproduct.com/public-api/v1/customer-orders/:id/status

Pozwala zmienić status wybranego zamówienia klienta. Aktualizacja statusu jest zalecana po dokonaniu płatności i może być wykonana ręcznie w panelu zamówień lub przez API.

Kontekst

Kiedy klient kliknie „Dodaj do koszyka” w Customizerze, tworzony jest nowy rekord zamówienia ze statusem domyślnym: pending. Pozwala on klientowi kontynuować edycję projektu (np. przez link: https://alterproduct.com/app/customizer/{customizerId}/{orderId}). Gdy status zostanie zmieniony na inny niż „pending”, edycja zostaje zablokowana — klient widzi zamrożoną wersję projektu.

Dostępne statusy (enum)

StatusOpis
pendingZamówienie oczekujące — pozwala na edycję projektu w Customizerze
paidZamówienie opłacone
processingZamówienie w trakcie realizacji
completedZamówienie zakończone
cancelledZamówienie anulowane

Status 'pending' jest jedynym, który pozwala klientowi otworzyć Customizer i edytować projekt.

Przykład żądania (fetch)

const res = await fetch('https://alterproduct.com/public-api/v1/customer-orders/1/status', {
  method: 'PATCH',
  headers: {
    'x-alter-access-key': 'YOUR_API_KEY',
    'x-alter-access-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'processing'
  })
});

const data = await res.json();
console.log(data);

Przykładowa odpowiedź

{
  "success": true,
  "orderId": 1,
  "newStatus": "processing"
}

Aktualizacja ilości wybranej pozycji w zamówieniu

PATCH https://alterproduct.com/public-api/v1/customer-orders/:orderId/quantity

Endpoint pozwala zaktualizować ilość wybranego wariantu produktu (productItem) w zamówieniu.

Przykład żądania

JSON body:

{
  "updates": [
    { "id": 1, "quantity": 3 }
  ]
}

fetch (Node.js):

const response = await fetch('https://alterproduct.com/public-api/v1/customer-orders/1/quantity', {
  method: 'PATCH',
  headers: {
    'x-alter-access-key': 'YOUR_API_KEY',
    'x-alter-access-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    updates: [
      { id: 1, quantity: 3 } // ID pozycji z zamówienia (productItem)
    ]
  })
});

const result = await response.json();
console.log(result);

Przykładowa odpowiedź

{
  "success": true
}

Ustawienie tej samej ilości dla wszystkich pozycji (productItems) w zamówieniu

PATCH https://alterproduct.com/public-api/v1/customer-orders/:orderId/quantity/all

Endpoint pozwala łatwo ustawić tę samą ilość dla wszystkich pozycji (productItems) w zamówieniu.

Przykład żądania

JSON body:

{
  "quantity": 2
}

fetch (Node.js):

const response = await fetch('https://alterproduct.com/public-api/v1/customer-orders/1/quantity/all', {
  method: 'PATCH',
  headers: {
    'x-alter-access-key': 'YOUR_API_KEY',
    'x-alter-access-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    quantity: 2
  })
});

const result = await response.json();
console.log(result);

Przykładowa odpowiedź

{
  "success": true
}

Usuwanie zamówienia klienta

DELETE https://alterproduct.com/public-api/v1/customer-orders/:id

Endpoint służy do trwałego usunięcia zamówienia klienta — np. jeśli projekt został porzucony lub anulowany przed produkcją. Po usunięciu zamówienia nie można go już otworzyć ani edytować.

Przykład żądania (fetch, Node.js)

const response = await fetch('https://alterproduct.com/public-api/v1/customer-orders/1', {
  method: 'DELETE',
  headers: {
    'x-alter-access-key': 'YOUR_API_KEY',
    'x-alter-access-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(result);

Przykładowa odpowiedź

{
  "success": true
}