API v1 · SANDBOX

Свържи касата.
Останалото следва.

Карти за лоялност, текуща сметка, точки и кампании — през един API за търговци и софтуерни партньори.

Работеща тестова среда

Заявките се записват в Laravel базата MySQL. Sandbox плащанията и push доставката са симулации. Native live бележката е свързана с IRIS тестовата среда; реални преводи и FCM/APNs доставка не са проверени. Клиентският и бизнес порталът използват същата база. API ключовете се управляват след вход с търговски профил.

BASE URL

Достъп от сървър на партньор

Authorization: Bearer $PUSHCARD_API_KEY
Content-Type: application/json
Idempotency-Key: уникален-идентификатор

За локалния Laravel API е нужен само tenant bearer ключ. Sites служебният ключ се отнася единствено за отделната частна Worker демонстрация. Не го използвай в Laravel интерфейсите.

Ключ за твоята интеграция

Само собственикът може да издава и отнема ключове. Всеки ключ е ограничен до един търговец и избраните права. Тайната се показва веднъж.

Все още няма издаден ключ в тази сесия.

Отделен sandbox тест без IRIS

Създава тестова регистрация, каса и сметка за 2,99 EUR, приема картата и симулира плащане. Записите остават в базата. Използвай ключ с всички права за този тест.

Demo каса

Настрой интеграцията и касата в бизнес портала. В Demo tool приемаш входящи Push заявки, маркираш артикули и финализираш бележката.

Настрой в бизнес портала Отвори Demo касата

От картата до плащането

Подготви касата: POST /tills. Поддръжката на push се задава с card_push_supported.
Изпрати картата: POST /pos-sessions с card_id и till_id.
Касата приема: GET /tills/{till_id}/sessions, след това POST /pos-sessions/{id}/accept.
Покажи маркираното: PUT /pos-sessions/{id}/basket. Клиентът чете GET /pos-sessions/{id}.
Финализирай сметката: POST /pos-sessions/{id}/finalize. Едва тогава POST /payments.
Потвърди тестовото плащане: POST /sandbox/payments/{id}/complete. Точките се начисляват веднъж.

pending → accepted → marking → finalized → paid
            ↑ обновяване на сметката ↑
Отказ: cancelled · Изтекла заявка: expired

Потокът свързва автоматично картата, касата и сумата. Demo касата маркира през API, а клиентът плаща през IRIS от live бележката. IRIS плащанията се потвърждават само сървърно; sandbox complete не може да ги приключи.

Маршрути и примери

Разгъни маршрут за заявка и JSON схема на отговора. Всички пътища са спрямо /api/v1.

Правила за интеграция

Суми: цели евроцентове. 299 = 2,99 EUR. quantity_milli: 1500 = 1,5 единици. Всеки ред се закръгля до цент; общата сума се изчислява на сървъра.
За tenant записващите заявки подай Idempotency-Key от 8–128 ASCII символа. Повторение със същото тяло връща същия отговор. Друго тяло връща 409. Не сменяй ключа след timeout.
При REQUEST_IN_PROGRESS изчакай и повтори със същия ключ. При REVISION_CONFLICT прочети актуалния ресурс и изпрати нова логическа заявка с нов ключ и expected_revision.
GET /events?after=0&limit=50 връща трайни събития за търговеца. Запази next_cursor след успешна обработка и дедупликирай по event id. Доставка чрез webhooks още няма; използвай polling.
GET /cards има cursor pagination чрез after и next_cursor. Останалите списъци са ограничени до последните limit записи (максимум 100).
Сесията изтича след 60–900 секунди преди финализиране. Финализираната сума не се редактира. Неуспешно плащане допуска нов опит.
Тестови точки: 1 точка за всяко пълно EUR от успешно плащане. Корекции чрез points-adjustments създават запис в историята.

Код	Действие
400 / 413	Поправи входните данни / размера (64 KiB).
401 / 403	Провери ключа, правата и частния достъп.
404	Ресурсът не съществува за този търговец.
409	Провери състоянието, revision или повторната заявка.
503	Временен проблем. Повтори безопасно със същия ключ.

Данни и граници

Регистрите за търговеца връщат идентификатори, маскиран номер, тип карта и баланс. Имена, имейли, телефони и фирмени имена не се връщат от тези маршрути. Контактите и корпоративните метаданни се съхраняват криптирано; API ключовете — като хеш.

Картата остава псевдонимен клиентски запис. Ключовете за регистрация и под профили са само за доверена сървърна интеграция. Регистрацията на клиент през адреса на търговеца изисква вход в клиентски профил. Не поставяй API ключ в QR код.

Промоциите имат период, обекти и аудитория. Push задачите броят само картите с маркетингово съгласие; не представляват реално доставени съобщения. Клиентът има локално филтриране по координати и IRIS адаптер. Външна push доставка и production lifecycle/лимити предстоят.