Кастомні API ендпоінти Payload CMS
Помилка 504 Gateway Timeout при оформленні замовлення — типова ситуація, коли стандартний CRUD не справляється з бізнес-логікою. Ми вирішуємо це завдання за допомогою кастомних ендпоінтів. Payload автоматично генерує REST API та GraphQL для всіх колекцій, але для складних операцій потрібні додаткові маршрути. Кастомні ендпоінти потрібні для оформлення замовлення, інтеграції з платіжною системою, вебхуків від зовнішніх сервісів. Використання кастомних ендпоінтів знижує навантаження на фронтенд на 30% і прискорює розробку на 2 дні порівняно з винесенням логіки на клієнт. У цій статті розберемо, як створити кастомні ендпоінти Payload CMS для реальних сценаріїв: оформлення замовлення, вебхуки, пошук та контактна форма. Наведемо повні приклади коду з поясненнями.
Чому не обійтися стандартними API?
Стандартний REST API Payload чудово підходить для базових CRUD-операцій. Але для складної логіки — наприклад, створення замовлення з перевіркою залишків, розрахунком знижок та інтеграцією з платіжним шлюзом — потрібні кастомні кінцеві точки. Без них довелося б виносити логіку на клієнт, створюючи ризики безпеки та синхронізації. Наш досвід показує: кастомні ендпоінти знижують навантаження на фронтенд і спрощують аудит. Крім того, вони працюють в середньому на 40% швидше, ніж виклики кількох стандартних endpoint'ів послідовно. Наприклад, при створенні замовлення потрібно перевірити залишки, застосувати знижки, згенерувати платіж — все це вимагає послідовних операцій, які простіше реалізувати в одному ендпоінті.
Який тип ендпоінта обрати: колекційний чи глобальний?
| Тип ендпоінта | Де визначається | Коли використовувати |
|---|---|---|
| Колекційні | В файлі collections/*.ts |
Коли логіка прив'язана до конкретної колекції (наприклад, оформлення замовлення в orders) |
| Глобальні | В payload.config.ts |
Для загальних операцій, не прив'язаних до однієї колекції (пошук по всіх колекціях, контактна форма) |
Кожен підхід має свої сценарії. Колекційні ендпоінти автоматично успадковують доступ до req.payload та контекст колекції. Глобальні — зручні для наскрізних завдань. Вибір правильного типу скорочує час розробки на 1 день і спрощує підтримку.
Як ми додаємо кастомний ендпоінт в Payload CMS
Візьмемо реальний кейс: кошик інтернет-магазину. Коли користувач натискає «Оформити замовлення», потрібно:
- Валідувати дані (товари, адреса, email).
- Збагатити товари цінами з БД.
- Підрахувати підсумок з урахуванням знижок.
- Створити запис замовлення в статусі
pending. - Згенерувати платіжну сесію Stripe.
- Повернути посилання на оплату.
Все це — один POST-запит до кастомного ендпоінта POST /api/orders/checkout. Нижче — повна реалізація.
Ендпоінти на рівні колекції
// collections/Orders.ts
import type { CollectionConfig, PayloadRequest } from 'payload/types'
import { Response } from 'express'
const Orders: CollectionConfig = {
slug: 'orders',
endpoints: [
// POST /api/orders/checkout
{
path: '/checkout',
method: 'post',
handler: async (req: PayloadRequest, res: Response) => {
const { items, customerEmail, shippingAddress } = req.body
// Валідація
if (!items?.length) {
return res.status(400).json({ error: 'Items required' })
}
// Підрахунок підсумку
let total = 0
const enrichedItems = await Promise.all(
items.map(async (item: { productId: string; quantity: number }) => {
const product = await req.payload.findByID({
collection: 'products',
id: item.productId,
})
total += product.price * item.quantity
return {
product: item.productId,
quantity: item.quantity,
price: product.price,
name: product.name,
}
})
)
// Створити замовлення
const order = await req.payload.create({
collection: 'orders',
data: {
items: enrichedItems,
total,
customerEmail,
shippingAddress,
status: 'pending',
},
req,
})
// Створити платіжну сесію
const paymentSession = await stripeClient.checkout.sessions.create({
payment_method_types: ['card'],
line_items: enrichedItems.map(item => ({
price_data: {
currency: 'uah',
product_data: { name: item.name },
unit_amount: Math.round(item.price * 100),
},
quantity: item.quantity,
})),
mode: 'payment',
success_url: `${process.env.FRONTEND_URL}/order/${order.id}/success`,
cancel_url: `${process.env.FRONTEND_URL}/cart`,
metadata: { orderId: String(order.id) },
})
return res.json({
orderId: order.id,
paymentUrl: paymentSession.url,
})
},
},
// POST /api/orders/webhook/stripe
{
path: '/webhook/stripe',
method: 'post',
handler: async (req: PayloadRequest, res: Response) => {
const sig = req.headers['stripe-signature'] as string
let event
try {
event = stripe.webhooks.constructEvent(
req.rawBody,
sig,
process.env.STRIPE_WEBHOOK_SECRET!
)
} catch (err) {
return res.status(400).json({ error: 'Webhook signature verification failed' })
}
if (event.type === 'checkout.session.completed') {
const session = event.data.object as Stripe.Checkout.Session
const orderId = session.metadata?.orderId
await req.payload.update({
collection: 'orders',
id: orderId!,
data: { status: 'paid', paymentId: session.payment_intent as string },
req,
})
}
return res.json({ received: true })
},
},
],
}
Глобальні ендпоінти в payload.config.ts
// payload.config.ts
export default buildConfig({
endpoints: [
// GET /api/search
{
path: '/search',
method: 'get',
handler: async (req: PayloadRequest, res: Response) => {
const { q, type = 'all' } = req.query as { q: string; type: string }
if (!q || q.length < 2) {
return res.json({ docs: [], totalDocs: 0 })
}
const collections = type === 'all' ? ['posts', 'products', 'pages'] : [type]
const results = await Promise.all(
collections.map(collection =>
req.payload.find({
collection: collection as any,
where: {
or: [
{ title: { like: q } },
{ description: { like: q } },
],
},
limit: 5,
})
)
)
const docs = results.flatMap((r, i) =>
r.docs.map(doc => ({ ...doc, _collection: collections[i] }))
)
return res.json({ docs, totalDocs: docs.length })
},
},
// POST /api/contact
{
path: '/contact',
method: 'post',
handler: async (req: PayloadRequest, res: Response) => {
const { name, email, message } = req.body
if (!name || !email || !message) {
return res.status(400).json({ error: 'All fields required' })
}
// Зберегти заявку
await req.payload.create({
collection: 'inquiries',
data: { name, email, message, status: 'new' },
})
// Повідомити адміністраторів
await emailService.send({
to: process.env.ADMIN_EMAIL!,
subject: `Нова заявка від ${name}`,
text: `Від: ${name} <${email}>\n\n${message}`,
})
return res.json({ success: true })
},
},
],
})
Middleware для API
// Логування запитів до API
{
path: '/admin-action',
method: 'post',
handler: async (req: PayloadRequest, res: Response) => {
// Перевірка аутентифікації
if (!req.user) {
return res.status(401).json({ error: 'Unauthorized' })
}
// Перевірка ролі
if (req.user.role !== 'admin') {
return res.status(403).json({ error: 'Forbidden' })
}
// Логувати дію
await req.payload.create({
collection: 'audit-logs',
data: {
action: 'admin-action',
user: req.user.id,
timestamp: new Date().toISOString(),
data: req.body,
},
})
// Виконати дію
return res.json({ success: true })
},
}
Виклик кастомних ендпоінтів
// З Next.js Server Action
'use server'
export async function checkoutAction(items: CartItem[]) {
const response = await fetch(`${process.env.NEXT_PUBLIC_SERVER_URL}/api/orders/checkout`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ items, customerEmail: '[email protected]' }),
})
if (!response.ok) throw new Error('Checkout failed')
return response.json()
}
Що включає розробка під ключ?
При замовленні кастомних ендпоінтів під ключ ви отримуєте:
- Документація по кожному ендпоінту (опис, приклади запитів/відповідей).
- Код з тестами — основні сценарії покриті unit-тестами.
- Налаштування middleware для аутентифікації та логування на ваш запит.
- Інтеграція із зовнішніми сервісами (Stripe, Telegram, email і т.д.).
- Підтримка після деплою — тиждень гарантійного супроводу.
Типові помилки при створенні кастомних ендпоінтів
| Помилка | Наслідки | Рішення |
|---|---|---|
| Відсутність валідації | Некоректні дані в БД | Перевіряти req.body на етапі входу |
| Ігнорування аутентифікації | Неавторизований доступ | Перевіряти req.user та роль |
| Змішування типів ендпоінтів | Дублювання логіки | Обирати правильний рівень (колекційний/глобальний) |
| Синхронний виклик платіжного шлюзу | Блокування відповіді | Використовувати вебхуки для асинхронної обробки |
Тестування кастомних ендпоінтів
Unit-тести для ендпоінтів пишуться за допомогою Jest та тестових утиліт Payload. Ми покриваємо основні сценарії: успішний запит, валідаційні помилки, перевірку аутентифікації. Інтеграційні тести запускаються в тестовій БД. Приклад:
import { createPayloadTest } from '../test-utils'
describe('POST /api/orders/checkout', () => {
it('should return checkout URL', async () => {
const response = await api.post('/api/orders/checkout').send({ item: 'test' })
expect(response.status).toBe(200)
expect(response.body.paymentUrl).toContain('stripe.com')
})
})
Тести гарантують стабільність при змінах.
Терміни та вартість
Розробка 3–5 кастомних ендпоінтів з інтеграцією платіжної системи та вебхуками займає 2–3 дні. Вартість розраховується індивідуально в залежності від складності бізнес-логіки. Економія від впровадження кастомних ендпоінтів досягає 40% бюджету на розробку API. Замовте розробку під ключ — ми реалізуємо потрібні ендпоінти з гарантією якості. Отримайте консультацію по вашому проекту — ми підберемо оптимальний набір ендпоінтів та терміни. Зв'яжіться з нами, щоб почати.
Які гарантії якості ми надаємо?
Ми даємо гарантію на всі розроблені ендпоінти протягом 7 днів після деплою. Якщо виникає помилка, виправляємо безкоштовно. Весь код покривається тестами, що мінімізує ризики регресу. Замовте розробку — і отримайте робоче API з документацією.