Փաստաթղթեր ծրագրավորողների համար

Գրանցեք վաճառքներ, կանխավճարներ և վերադարձներ Հայաստանի ՊԵԿ-ում ցանկացած տեխնոլոգիական փաթեթից։

Հիմնական URLhttps://vcr.am/api/v1

Արագ մեկնարկ

Գրանցեք վաճառք մեկ POST հարցումով։

bash

curl https://vcr.am/api/v1/sales \
  -H "X-API-Key: $VCR_AM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cashier": { "id": 1 },
    "items": [{
      "offer": { "externalId": "SKU-001" },
      "department": { "id": 1 },
      "quantity": "1",
      "price": "20000",
      "unit": "pc"
    }],
    "amount": { "nonCash": "20000" },
    "buyer": {
      "type": "individual",
      "receipt": { "email": "buyer@example.com", "language": "en" }
    }
  }'

Սկսեք առանց ՊԵԿ-ի վկայագրերի

Փորձնական դրամարկղը գրանցման համարը ստանում է ստեղծման պահին՝ առանց ՊԵԿ-ի հետ վկայագրերի փոխանակման և առանց սպասելու։ Նույն բազային URL-ը, նույն էնդփոինթները, բանալու նույն տրամաբանությունը. տարբերվում են միայն կտրոնները՝ նշվում են TEST-ով և երբեք չեն ներկայացվում։

1Կառավարման վահանակում բացեք «Դրամարկղներ», սեղմեք «Ստեղծել դրամարկղ» և ընտրեք «Փորձնական դրամարկղ»։ Ստեղծեք այնքան, որքան պետք է։
2Այդ դրամարկղի վրա ստեղծեք API բանալի։ Բանալին կապված է մեկ դրամարկղի հետ, ուստի աշխատանքային դրամարկղից վերցրածը կշարունակի 403 վերադարձնել։
3Կանչեք նույն էնդփոինթները նույն բազային URL-ով։ Երբ պատրաստ լինեք իրական ֆիսկալացման, ստեղծեք աշխատանքային դրամարկղ և փոխարինեք բանալին։

Ստեղծված է աշխատանքային ինտեգրումների համար

REST՝ JSON-ի վրա

Վիճակազուրկ JSON վերջնակետեր՝ կանչելի ցանկացած լեզվից և շրջանակից։

Տիպավորված Node.js և PHP SDK-ներ

Վերջից վերջ տիպավորված հաճախորդներ npm-ում և Packagist-ում՝ պատրաստ ինչպես Node.js, այնպես էլ PHP սերվերի կոդի համար։

Նույնականացում API բանալիով

Թարմացվող API բանալիներ, որոնք կառավարվում են անձնական էջից։

Դրամարկղի ամբողջական API

Վաճառք, կանխավճար, վերադարձ և կտրոններ՝ մեկ հետևողական ինտերֆեյսով։

Ինչ պետք է տրամադրի ձեր համակարգը

Մինչ ինտեգրումը, համոզվեք, որ յուրաքանչյուր վաճառք պարունակում է ՊԵԿ-ի պահանջվող տվյալները։

Դասակարգչի կոդ

Ապրանքների համար՝ ապրանքային դասակարգչից, ծառայությունների համար՝ տնտեսական գործունեության դասակարգչից։

Չափման միավոր

կգ, հատ, մ², ժամ, ծառայություն, աշխատանք և այլն։

Բաժնի ID

Որտեղ գրանցել վաճառքը ձեր դրամարկղում — և ինչ հարկման ռեժիմ կնշվի չեկում։ Ոչ պարտադիր՝ եթե չփոխանցեք, տողը կվերցնի իր ապրանքի բաժինը։

Գանձապահի ID

Ով է գրանցում վաճառքը։

Նույնականացում

Յուրաքանչյուր հարցում պետք է պարունակի ձեր API բանալին X-API-Key վերնագրում։ Միակ բացառությունը GET /exchange-rate-ն է՝ այն հանրային է և բանալի չի պահանջում։

X-API-Key: your_api_key

Ստեղծեք և թարմացրեք API բանալիները ձեր դրամարկղի կարգավորումներում։

Պահեք API բանալին գաղտնի

Մի տեղադրեք այն հաճախորդի կողմի կոդում, հանրային շտեմարաններում կամ ընդհանուր մատյաններում։ Եթե բանալին արտահոսել է՝ անմիջապես փոխարինեք այն դրամարկղի կարգավորումներում։

Իդեմպոտենտություն

Ֆիսկալ կտրոնը հնարավոր չէ ուղղել՝ միայն վերադարձնել և նորից գեներացնել։ Այդ պատճառով կրկնօրինակն այս API-ի ամենաթանկ սխալն է, իսկ վճարային համակարգի webhook-ի կրկնակի ուղարկումը նորմալ է, ոչ թե բացառություն։ Ուղարկեք Idempotency-Key վերնագիրը յուրաքանչյուր POST-ում. նույն հարցման կրկնությունը կվերադարձնի սկզբնական կտրոնը՝ երկրորդը գեներացնելու փոխարեն։

Idempotency-Key: 3f6b2c1e-9a84-4d77-9f2a-1c5e0b7d8a63

Առանց վերնագրի պաշտպանություն չկա

Երկրորդ նույնական POST-ը կգեներացնի երկրորդ ֆիսկալ կտրոն։ Դա իրական փաստաթուղթ է ՊԵԿ-ում, և հետդարձի միակ ճանապարհը վերադարձի կտրոնն է։ Համարեք վերնագիրը պարտադիր, նույնիսկ եթե API-ն ընդունում է հարցումներ առանց դրա։

Ի՞նչ օգտագործել որպես բանալի

UUID, որը գեներացվում է մեկ անգամ՝ մեկ ֆիսկալ գործողության համար, և պահվում է պատվերի կողքին մինչև առաջին կանչը, ապա օգտագործվում է ամեն կրկնափորձի ժամանակ։ Ոչ թե պատվերի համարն ինքնին՝ մեկ պատվերը կարող է օրինականորեն առաջացնել մի քանի ֆիսկալ փաստաթուղթ։ Եվ ոչ թե նոր UUID ամեն փորձի համար, ինչը զրկում է մեխանիզմն իմաստից։

Ինչպես տարբերել կրկնությունը նոր կտրոնից

Կրկնված պատասխանը բայթ առ բայթ համընկնում է սկզբնականի հետ և պարունակում է Idempotent-Replay: true վերնագիրը։ Ստուգեք այն, նախքան պատասխանը նոր գեներացված փաստաթուղթ համարելը։

Երբ webhook-ը կարող է գալ երկու անգամ

Վիճակ չպահող մշակիչը դեռ ոչինչ պահած չունի, ուստի բանալին պետք է հաշվարկել, ոչ թե գեներացնել։ Այդ դեպքում երկու առաքումներն էլ կստանան նույն բանալին, և երկրորդը կվերադարձնի կրկնությունը։ Մի՛ հաշվարկեք բանալին վճարային համակարգի իրադարձության համարից. նույն պատվերի մասին այլ իրադարձությունը կտա այլ բանալի և կհանգեցնի կրկնակի ֆիսկալացման։

import { v5 as uuidv5 } from "uuid";

const NAMESPACE = "6f1d1a58-0d0c-4a1e-9a1a-2f9a7b3c4d5e";
const key = uuidv5(`${order.id}:sale`, NAMESPACE);

await fetch("https://vcr.am/api/v1/sales", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.VCR_API_KEY,
    "Idempotency-Key": key,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

Բանալին մնում է կրկնելի 30 օր՝ բավական, որպեսզի ամսական համադրման կրկնակի գործարկումը վերադարձնի կրկնությունը, ոչ թե ստեղծի նոր փաստաթուղթ։ Նույն բանալին այլ հարցման մարմնով տալիս է 422; նույն բանալին, քանի դեռ առաջին հարցումը կատարվում է, տալիս է 409՝ դա նշանակում է սպասել և կրկնել նույն բանալիով, ոչ թե ստեղծել նորը։ Սխեմայի կողմից մերժված մարմինը բանալի ընդհանրապես չի ծախսում՝ հարցումը չի հասել գործողությանը, ուստի ուղղեք դաշտը և կրկնեք նույն բանալիով։

Սխալներ

Սխալները վերադարձվում են ստանդարտ HTTP կարգավիճակի կոդերով և JSON մարմնով՝ մանրամասներով։

Կարգավիճակ	Անվանում	Երբ է առաջանում
400	Սխալ հարցում	Սխալ ձևաչափի մարմին կամ սխեմայի վավերացման ձախողում։
401	Չնույնականացված	API բանալին բացակայում է կամ անվավեր է։
403	Արգելված է	Դրամարկղը դեռ չի կարող փաստաթղթեր ներկայացնել՝ գրանցման համար չկա կամ այն ակտիվացված չէ ՊԵԿ-ում։
404	Չի գտնվել	Հարցվող ռեսուրսը գոյություն չունի։
409	Կոնֆլիկտ	ՊԵԿ-ը մերժել է փաստաթուղթն ըստ էության, ներդրված դիրքը կոնֆլիկտի մեջ է արդեն գոյություն ունեցողի հետ, կամ նույն Idempotency-Key-ով հարցումը դեռ կատարվում է։ Մերժման դեպքում գալիս է `pending`. փաստաթուղթը պահպանված է, ուստի վերացրեք պատճառը, ոչ թե ուղարկեք կրկին։
422	Բանալին կրկին օգտագործված է	Նույն Idempotency-Key-ն եկել է այլ հարցման մարմնով։ Նոր փաստաթղթին պետք է նոր բանալի։
500	Ներքին սխալ	Անսպասելի սխալ մեր կողմից։ Կրկնեք՝ էքսպոնենցիալ հետաձգումով։
502	ՊԵԿ-ն անհասանելի է	Փաստաթուղթը պահպանված է, պատասխանում գալիս է `pending`։ Նախ կարդացեք `pending.mayResubmit`. false նշանակում է, որ կրկնումը կստեղծի երկրորդ կտրոն՝ փոխարենը հարցումներ արեք `pending.statusUrl`-ին։