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

# Створення та керування замовленнями

> Створюйте замовлення з власного сайту, перенаправляйте клієнта на оформлення та обробляйте оплату, скасування й повернення коштів.

Замовлення (рахунок) містить товари, клієнта та ціну. Клієнт оплачує на хостинговій сторінці `checkout_url`, де обирає будь-який спосіб оплати, який приймає ваш магазин.

Замовлення, створені через API, підпорядковуються тим самим правилам, що й ваша вітрина: ціни беруться з вашого каталогу, залишки резервуються, застосовуються купони та правила товарів, виконуються перевірки на шахрайство.

## Створіть замовлення

```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: 6f1c8a52-4f0e-4b8e-9a7c-2d1b3e5f7a90" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "buyer@example.com",
    "items": [
      { "product_id": "a1B2c3D4e5F6", "quantity": 1 },
      { "product_id": "Zx9Yw8Vu7Ts6", "variant_id": 881 }
    ],
    "coupon_code": "SUMMER10",
    "customer_ip": "203.0.113.10",
    "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 }],
    customer_ip: order.ip,
    metadata: { order_ref: order.id },
  }),
});
const { invoice } = await res.json();
// Перенаправте клієнта на invoice.checkout_url
```

```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"]
```

```json Відповідь (201) theme={"system"}
{
  "success": true,
  "invoice": {
    "id": "c35ffd-19a1b2c3d4e-8c7a20",
    "object": "invoice",
    "status": "pending",
    "currency": "USD",
    "total_cents": 3499,
    "customer_email": "buyer@example.com",
    "source": "api",
    "metadata": { "order_ref": "WEB-1042" },
    "checkout_url": "https://app.papelship.com/invoice/c35ffd-19a1b2c3d4e-8c7a20",
    "expires_at": "2026-10-04T15:00:00.000Z",
    "items": [ ... ]
  }
}
```

Перенаправте клієнта на `checkout_url`. Неоплачені замовлення спливають через 3 години.

> [accordion] Поля, які можна надіслати
>
> | Поле | Примітки |
> | :- | :- |
> | `customer_email` | Обов'язкове. Отримує лист із рахунком і доставку. |
> | `items` | Обов'язкове. Від 1 до 50 рядків із `product_id` (хеш-ID), `quantity` і `variant_id` для товарів із варіантами. |
> | `coupon_code` | Застосовується, якщо дійсний для цих товарів. |
> | `customer_ip` | IP покупця. Вмикає для цього замовлення ваші правила щодо шахрайства, VPN і чорного списку. |
> | `expected_total_cents` | Необов'язкова перевірка. Виклик завершується помилкою `TOTAL_MISMATCH`, якщо ціна змінилася. |
> | `shipping_address`, `shipping_rate_id` | Фізичні товари. Див. нижче. |
> | `custom_fields` | Відповіді на поля вашої сторінки оформлення. |
> | `affiliate_code` | Зараховує замовлення партнеру вашої партнерської програми. |
> | `send_email` | `false`, щоб не надсилати лист із рахунком (за замовчуванням `true`). |
> | `metadata` | До 20 ваших власних рядкових пар ключ/значення. |

> [accordion] Помилки під час створення
>
> | Код | Статус | Значення |
> | :- | :- | :- |
> | `PRODUCT_NOT_FOUND` | `404` | `product_id` відсутній у вашому магазині. |
> | `OUT_OF_STOCK` | `409` | Недостатньо залишків. `details.products` містить перелік того, чого бракує. |
> | `TOTAL_MISMATCH` | `409` | `expected_total_cents` не збігається. `details.expected_total_cents` містить фактичну суму. |
> | `CURRENCY_MISMATCH` | `422` | Товари мають різні валюти, або `currency` не збігається. |
> | `INVALID_VARIANT` | `422` | `variant_id` відсутній або неправильний. |
> | `ADDRESS_INVALID` | `422` | Неповна адреса доставки. `details.fields` називає поля. |
> | `CUSTOMER_BLOCKED` | `403` | Email або IP є у вашому чорному списку. |
> | `FRAUD_BLOCKED` | `403` | Ваші правила щодо шахрайства відхилили замовлення. |
> | `STORE_SUSPENDED` | `403` | Магазин зараз не може приймати замовлення. |

## Фізичні товари

Для товарів, які потребують доставки, додайте адресу. Спершу отримайте варіанти через `POST /shipping/quote` або не вказуйте `shipping_rate_id`, щоб застосувати найдешевший тариф.

```json theme={"system"}
{
  "customer_email": "buyer@example.com",
  "items": [{ "product_id": "Tsh1rtM3d1um", "variant_id": 2041, "quantity": 2 }],
  "shipping_address": {
    "full_name": "Alex Morgan",
    "phone": "+44 20 7946 0958",
    "country_code": "GB",
    "city": "London",
    "line1": "221B Baker Street",
    "postal_code": "NW1 6XE"
  },
  "shipping_rate_id": 12
}
```

Вартість доставки додається до `total_cents` і показується як `shipping_cents`. Без адреси клієнт вводить її на сторінці оформлення перед оплатою. Після оплати відправте замовлення через [`POST /orders/{invoiceId}/shipments`](https://developers.papelship.com/uk/user-api/fulfillment).

## Статуси замовлень

| Статус | Значення |
| :- | :- |
| `pending` | Очікує оплати від клієнта. |
| `payment_pending`, `payment_processing` | Клієнт обрав спосіб оплати; платіж обробляється. |
| `partial_payment` | Надійшла частина суми (криптовалюта). |
| `manual_review_pending` | Ручний платіж очікує вашої перевірки. |
| `completed` | Оплачено й доставлено. |
| `cancelled` | Скасовано до оплати. |
| `expired` | Не оплачено вчасно. |

Замість регулярного опитування слухайте вебхук `order.completed`. Див. [Вебхуки](https://developers.papelship.com/uk/user-api/webhooks.md).

## Після створення замовлення

| Дія | Ендпоінт | Коли |
| :- | :- | :- |
| Позначити як оплачене | `POST /invoices/{id}/complete` | Ви отримали гроші поза PapelShip (банківський переказ, готівка). Доставляє товари. |
| Скасувати | `POST /invoices/{id}/cancel` | Замовлення не оплачене. Звільняє зарезервовані залишки. |
| Зафіксувати повернення коштів | `POST /invoices/{id}/refund` | Ви повернули кошти клієнту. Надішліть `amount_cents` для часткового повернення. |
| Переглянути доставлене | `GET /invoices/{id}/deliveries` | Ліцензійні ключі, файли та нотатки, надіслані клієнту. |
| Оновити | `PATCH /invoices/{id}` | Змінити `metadata` або `delivery_email`. |

> [!TIP]
>
> Використовуйте ID власного замовлення як `Idempotency-Key` для викликів створення, завершення та повернення коштів. Тоді повторні спроби ніколи не створять друге замовлення чи друге повернення.


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