{"openapi":"3.1.0","info":{"title":"МЦР API","version":"1.0.0","description":"Платіжні посилання з QR-кодом НБУ. Документація: https://mcr.procrm.ua/dokumentatsiia-api"},"servers":[{"url":"https://mcr.procrm.ua/api/v1"}],"security":[{"bearer":[]}],"paths":{"/links":{"get":{"summary":"Список посилань, новіші першими","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","paid","cancelled","expired"]}},{"name":"externalId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"nextCursor з попередньої відповіді","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Сторінка посилань","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"description":"Немає ключа або ключ відкликано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Неправильні параметри","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Перевищено ліміт запитів","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Створити посилання","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkCreate"}}}},"responses":{"200":{"description":"Посилання з таким externalId вже є: повертаємо його без змін","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"201":{"description":"Посилання створено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"400":{"description":"Тіло не є JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Немає ключа або ключ відкликано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Тіло більше за 64 КБ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Перевірте поля","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Перевищено ліміт запитів","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Курс НБУ недоступний","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{id}":{"get":{"summary":"Одне посилання","parameters":[{"name":"id","in":"path","required":true,"description":"id посилання (uuid) або його код (slug)","schema":{"type":"string"}}],"responses":{"200":{"description":"Посилання","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"401":{"description":"Немає ключа","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{id}/paid":{"post":{"summary":"Позначити оплаченим","parameters":[{"name":"id","in":"path","required":true,"description":"id посилання (uuid) або його код (slug)","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"paidAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Посилання","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"404":{"description":"Не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Посилання скасоване","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Перевірте поля","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{id}/cancel":{"post":{"summary":"Скасувати","parameters":[{"name":"id","in":"path","required":true,"description":"id посилання (uuid) або його код (slug)","schema":{"type":"string"}}],"responses":{"200":{"description":"Посилання","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"404":{"description":"Не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Посилання вже оплачене","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recipients":{"get":{"summary":"Збережені одержувачі","responses":{"200":{"description":"Одержувачі","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}}}}}}}}}}},"webhooks":{"link.paid":{"post":{"summary":"Посилання оплачено","parameters":[{"name":"X-MCR-Event","in":"header","required":true,"schema":{"type":"string","const":"link.paid"}},{"name":"X-MCR-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-MCR-Signature","in":"header","required":true,"description":"t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Будь-яка відповідь 2xx означає, що подію отримано"}}}},"link.cancelled":{"post":{"summary":"Посилання скасовано","parameters":[{"name":"X-MCR-Event","in":"header","required":true,"schema":{"type":"string","const":"link.cancelled"}},{"name":"X-MCR-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-MCR-Signature","in":"header","required":true,"description":"t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Будь-яка відповідь 2xx означає, що подію отримано"}}}},"link.reopened":{"post":{"summary":"Посилання знову активне","parameters":[{"name":"X-MCR-Event","in":"header","required":true,"schema":{"type":"string","const":"link.reopened"}},{"name":"X-MCR-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-MCR-Signature","in":"header","required":true,"description":"t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Будь-яка відповідь 2xx означає, що подію отримано"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Ключ з кабінету МЦР (API). Не більше 60 запитів на хвилину для ключа"}},"schemas":{"Recipient":{"type":"object","required":["id","name","iban","code","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"iban":{"type":"string"},"code":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Item":{"type":"object","required":["name","qty","price"],"properties":{"name":{"type":"string","maxLength":200},"qty":{"type":["number","string"]},"price":{"type":["number","string"],"description":"Ціна в валюті посилання"}}},"LinkCreate":{"type":"object","required":["purpose"],"additionalProperties":false,"description":"Одержувач: recipient або recipientId. Сума: amount або items, або нічого (суму вводить платник, лише UAH)","properties":{"recipient":{"type":"object","required":["name","iban","code"],"properties":{"name":{"type":"string"},"iban":{"type":"string"},"code":{"type":["string","number"]}}},"recipientId":{"type":"string","format":"uuid"},"purpose":{"type":"string","description":"Призначення платежу; МЦР додає до нього код оплати"},"amount":{"type":["number","string"],"description":"Сума в currency, до двох знаків після коми"},"items":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Item"}},"currency":{"type":"string","default":"UAH","pattern":"^[A-Za-z]{3}$"},"rate":{"type":["number","string"],"description":"Гривень за 1 одиницю валюти. Без нього: курс НБУ на сьогодні"},"markupPercent":{"type":["number","string"],"minimum":0,"maximum":100},"validUntil":{"type":"string","format":"date","description":"Останній день оплати (за Києвом)"},"title":{"type":"string","maxLength":100,"description":"Ваша назва, платник її не бачить"},"externalId":{"type":["string","number"],"maxLength":100,"description":"Ваш id (угода, замовлення, чат), унікальний у кабінеті"},"metadata":{"type":"object","maxProperties":20,"additionalProperties":{"type":["string","number","boolean"]}}}},"Link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"pdfUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","paid","cancelled","expired"]},"title":{"type":["string","null"]},"amount":{"type":["number","null"],"description":"Гривні в QR-коді; null: суму вводить платник"},"currency":{"type":"string"},"currencyAmount":{"type":["number","null"]},"rate":{"type":["number","null"]},"rateSource":{"type":["string","null"]},"rateDate":{"type":["string","null"],"format":"date"},"markupPercent":{"type":["number","null"]},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"qty":{"type":"number"},"price":{"type":"number"},"total":{"type":"number"}}}},"recipient":{"type":"object","properties":{"name":{"type":"string"},"iban":{"type":"string"},"code":{"type":"string"}}},"purpose":{"type":"string"},"validUntil":{"type":["string","null"],"format":"date"},"paidAt":{"type":["string","null"],"format":"date-time"},"externalId":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"views":{"type":"integer"},"shareText":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Event":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"type":"string","format":"uuid","description":"Однаковий у всіх повторах: за ним відкидайте дублікати"},"type":{"type":"string","enum":["link.paid","link.cancelled","link.reopened","ping"]},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"link":{"$ref":"#/components/schemas/Link"}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}