> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Швидкий старт

> Створіть перше замовлення через PapelShip Store API, перенаправте клієнта на оформлення та підтвердьте оплату через вебхук або читанням замовлення.

Цей посібник проведе вас через повний цикл замовлення з PapelShip Store API: створіть замовлення на один зі своїх товарів, перенаправте клієнта на хостингову сторінку оформлення та підтвердьте оплату, перш ніж на неї покладатися.

## Передумови

* Магазин PapelShip щонайменше з одним товаром
* Ключ Store API (`pk_live_...`) з дозволом `orders:write`, а також ID вашого магазину для заголовка `x-store-hash`

> [!TIP]
>
> Обидва значення ви знайдете в [панелі керування PapelShip](https://app.papelship.com) у налаштуваннях API вашого магазину. Див. [Автентифікація](https://developers.papelship.com/uk/guides/authentication.md).

**1. Створіть замовлення**

Надішліть email клієнта та товари. Додайте заголовок `Idempotency-Key`, щоб повторні спроби ніколи не створювали друге замовлення.

```bash cURL theme={"system"}
curl -X POST https://app.papelship.com/api/v1/invoices \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id" \
  -H "Idempotency-Key: WEB-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "buyer@example.com",
    "items": [{ "product_id": "a1B2c3D4e5F6", "quantity": 1 }],
    "metadata": { "order_ref": "WEB-1042" }
  }'
```

```javascript Node.js theme={"system"}
const res = await fetch("https://app.papelship.com/api/v1/invoices", {
  method: "POST",
  headers: {
    "x-api-key": process.env.PAPELSHIP_API_KEY,
    "x-store-hash": process.env.PAPELSHIP_STORE_ID,
    "Idempotency-Key": order.id,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_email: order.email,
    items: [{ product_id: "a1B2c3D4e5F6", quantity: 1 }],
    metadata: { order_ref: order.id },
  }),
});
const { invoice } = await res.json();
```

```python Python theme={"system"}
import os, requests

res = requests.post(
    "https://app.papelship.com/api/v1/invoices",
    headers={
        "x-api-key": os.environ["PAPELSHIP_API_KEY"],
        "x-store-hash": os.environ["PAPELSHIP_STORE_ID"],
        "Idempotency-Key": order_id,
    },
    json={
        "customer_email": "buyer@example.com",
        "items": [{"product_id": "a1B2c3D4e5F6", "quantity": 1}],
        "metadata": {"order_ref": order_id},
    },
)
invoice = res.json()["invoice"]
```

**2. Перенаправте клієнта на оформлення**

Відповідь містить замовлення з його `checkout_url`. Перенаправте туди клієнта, щоб він оплатив будь-яким способом, який приймає ваш магазин.

```json Відповідь (201) theme={"system"}
{
  "success": true,
  "invoice": {
    "id": "c35ffd-19a1b2c3d4e-8c7a20",
    "status": "pending",
    "currency": "USD",
    "total_cents": 3499,
    "checkout_url": "https://invoice.papelship.com/c35ffd-19a1b2c3d4e-8c7a20",
    "expires_at": "2026-10-04T15:00:00.000Z"
  }
}
```

Збережіть `invoice.id` разом зі своїм замовленням. Неоплачені замовлення спливають через 3 години. Щоб одразу списати кошти з картки або показати форму картки на власному сайті, див. [PapelPay](https://developers.papelship.com/uk/papelpay/overview.md).

**3. Підтвердьте оплату**

Ніколи не покладайтеся лише на повернення клієнта на ваш сайт. Слухайте вебхук `order.completed` або прочитайте замовлення на своєму сервері:

```bash theme={"system"}
curl https://app.papelship.com/api/v1/invoices/c35ffd-19a1b2c3d4e-8c7a20 \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"
```

Замовлення оплачене й доставлене, коли `status` має значення `completed`.

> [!WARNING]
>
> Зберігайте API-ключ на своєму сервері. Ніколи не включайте його в браузерний код, мобільні застосунки чи десктопні клієнти.

## Наступні кроки

> [card] [Замовлення](https://developers.papelship.com/uk/user-api/orders.md)
>
> Фізичні товари, статуси, скасування та повернення коштів.

> [card] [PapelPay](https://developers.papelship.com/uk/papelpay/overview.md)
>
> Оплата карткою, підписки та форма картки на вашому сайті.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.