Partner API՝ վաճառողների միացում

VCR-ում ընկերության սեփականատերը մնում է վաճառողը։ Դուք գործում եք մուտքի (grant) հիման վրա՝ կոնկրետ ընկերության նկատմամբ, որը սեփականատերը կարող է ցանկացած պահի հետ կանչել։ Գործընկերոջ մեկ բանալին աշխատում է բոլոր այն ընկերությունների հետ, որոնք ձեզ մուտք են տվել։

Ձեր բոլոր գործողությունները գրանցվում են ընկերության գործողությունների մատյանում՝ գործընկերոջ անվամբ և օգտագործված բանալիով, այնպես որ սեփականատերը միշտ տեսնում է, թե ով ինչ է արել։

1. Մենք ձեր VCR հաշիվը ավելացնում ենք գործընկերոջ թիմին։ Դուք ստանում եք նամակ այս քայլերով։
2. Ձեր ընկերության անունից պայմանագրեր ստորագրելու իրավունք ունեցող անձը մեկ անգամ ընդունում է Գործընկերների պայմանները։ Դրանք անհրաժեշտ են վաճառողի գրավոր լիազորությամբ մուտքը հավաստելու համար. սեփականատիրոջից հաստատում խնդրել կարելի է նաև առանց դրանց։ Ընդունել պայմանները
3. Թիմի անդամը թողարկում է API բանալի գործընկերոջ անձնական էջում։ Բանալին ցուցադրվում է մեկ անգամ. փոխանցեք այն X-API-Key վերնագրով։ Բացել գործընկերոջ անձնական էջը

Ստուգեք բանալին՝ GET /whoami-ը կվերադարձնի գործընկերոջը, բանալին և արդյոք ընդունված են գործող պայմանները։

curl https://vcr.am/api/partner/v1/whoami \
  -H "X-API-Key: $VCR_PARTNER_KEY"

Մուտք խնդրեք POST /entities-ով՝ նշելով վաճառողի ՀՎՀՀ-ն։ Եթե VCR-ը դեռ չգիտի այդ ՀՎՀՀ-ն, ընկերությունը գտնվում է պետական ռեգիստրում և ստեղծվում։ Մուտքը հիմնվում է երկու հիմքերից մեկի վրա։

Հաստատում է սեփականատերը

Սեփականատերը ստանում է նամակ՝ մեկ սեղմումով հղումով, որը գործում է 7 օր։ Քանի դեռ նա չի սեղմել, մուտքը pending վիճակում է։ Եթե VCR-ում ընկերությունն արդեն ունի սեփականատերեր, մի փոխանցեք owner. հարցումը կուղարկվի նրա ներկայիս սեփականատերերին, ոչ թե ձեր նշած հասցեին։

curl -X POST https://vcr.am/api/partner/v1/entities \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "01234567",
    "access": {
      "basis": "owner_confirmation",
      "owner": { "email": "owner@merchant.am", "language": "hy" }
    }
  }'

Հավաստում եք դուք

Եթե վաճառողի հետ ձեր պայմանագիրը ձեզ գրավոր լիազորում է, հղում կատարեք դրան, և մուտքը անմիջապես կդառնա active։ endsOn-ը լիազորության մեջ նշված ժամկետի վերջին օրն է՝ signedOn-ից ոչ ուշ, քան երեք տարի. եթե ժամկետ նշված չէ, մի փոխանցեք դաշտը, և մուտքը կգործի ստորագրման օրվանից մեկ տարի։

curl -X POST https://vcr.am/api/partner/v1/entities \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "01234567",
    "access": {
      "basis": "partner_attestation",
      "merchantAuthorization": {
        "reference": "Service agreement No. 17, clause 4.2",
        "signedOn": "2026-10-01",
        "endsOn": "2027-09-30"
      }
    }
  }'

Քանի դեռ մուտքը pending է, ձեր կողմից VCR բերված ընկերությունում արդեն կարելի է ստեղծել ՀԴՄ-ներ, ստանալ CSR և վերբեռնել վկայագիրը. ակտիվացումն ու կտրոնները սպասում են սեփականատիրոջ հաստատմանը։ Մինչ ձեզ VCR-ում եղած ընկերությունում մինչև active ոչինչ թույլատրված չէ։

Մուտքից ինքներդ հրաժարվելու համար կանչեք DELETE /entities/{entityId}/grant․ այն չեղարկում է հարցումը, որին սեփականատերը դեռ չի պատասխանել, կամ դադարեցնում է գործող մուտքը։ Գործընկերների պայմանները պահանջում են դա անել հաճախորդի լիազորության ավարտից հետո երեք աշխատանքային օրվա ընթացքում։ Կգա grant.ended՝ relinquished պատճառով։

curl -X DELETE https://vcr.am/api/partner/v1/entities/42/grant \
  -H "X-API-Key: $VCR_PARTNER_KEY"

POST /entities/{entityId}/registers-ը ստեղծում է ՀԴՄ՝ բանալիների նոր զույգով և 101 դիմումի համար CSR-ով։ tradingPlatformName-ը դիմումի 5.4 դաշտն է և տպվում է կտրոնների վրա, website-ը՝ 5.3 դաշտը։

curl -X POST https://vcr.am/api/partner/v1/entities/42/registers \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "tradingPlatformName": "Merchant Cafe Abovyan",
    "website": "https://cafe.merchant.am",
    "mode": "production"
  }'

Թայմաութից հետո կրկնված հարցումը կստեղծեր երկրորդ ՀԴՄ, ուստի ուղարկեք Idempotency-Key վերնագիրը (UUID)․ կրկնությունն այդ դեպքում կվերադարձնի առաջին կանչով ստեղծված ՀԴՄ-ն՝ Idempotent-Replay: true վերնագրով։

GET /registers/{registerId}/application-ը վերադարձնում է, թե ինչ լրացնել 101 դիմումում, և դրան կցվող CSR-ը։

curl https://vcr.am/api/partner/v1/registers/104/application \
  -H "X-API-Key: $VCR_PARTNER_KEY"
# -> { "tin": "...", "website": "...", "applicationName": "...", "csr": "-----BEGIN CERTIFICATE REQUEST-----..." }

Հարկ վճարողը 101 դիմումը ներկայացնում է հարկային մարմնի պորտալում՝ ստորագրելով իր էլեկտրոնային ստորագրությամբ, և հարկային մարմինը տալիս է վկայագիր։ Վերբեռնեք այն PEM ձևաչափով։ Այն պետք է հանգի հարկային մարմնի արմատային վկայագրին, պարունակի այս ընկերության ՀՎՀՀ-ն և համապատասխանի ՀԴՄ-ի CSR-ին. նույն վկայագրի կրկնակի վերբեռնումը ոչինչ չի փոխում։ Վկայագիրը ՀԴՄ-ին տալիս է գրանցման համար (CRN)։

curl -X PUT https://vcr.am/api/partner/v1/registers/104/certificate \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile pem certificate.crt '{certificate: $pem}')"

Ավազարկղի ՀԴՄ-ն վկայագիրը ստանում է թեստային սերտիֆիկացման կենտրոնից՝ 101 դիմումի փոխարեն.

curl -X POST https://vcr.am/api/partner/v1/registers/104/sandbox-certificate \
  -H "X-API-Key: $VCR_PARTNER_KEY"
# -> { "certificate": "-----BEGIN CERTIFICATE-----...", "crn": "99123456" }
# Upload it with PUT /registers/104/certificate, as you would SRC's.

Ակտիվացման համար անհրաժեշտ է active մուտք։ Ընտրեք ՀԴՄ-ի առաջին բաժնի հարկային ռեժիմը՝ vat, vat_exempt, turnover_tax կամ micro_enterprise։ Այն տպվում է յուրաքանչյուր կտրոնի վրա, և սեփականատերերը նամակ են ստանում ձեր ընտրությամբ։ Կրկնակի կանչն անվտանգ է։

curl -X POST https://vcr.am/api/partner/v1/registers/104/activation \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taxRegime": "turnover_tax" }'

GET /registers/{registerId}-ը ցույց է տալիս, թե որ քայլում է ՀԴՄ-ն.

Վաճառքները, վերադարձները, գանձապահներն ու բաժինները անցնում են սովորական API-ով՝ /api/v1, գործընկերոջ բանալիով։ ՀԴՄ-ն նշվում է id-ով VCR-Register վերնագրում։ Առանց վերնագրի պատասխանը 400 է, ՀԴՄ, որին մուտք չունեք՝ 404, սեփականատիրոջը դեռ սպասող մուտք՝ 403։

# The regular API, with the partner key and the register named in a header.
curl https://vcr.am/api/v1/cashiers \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "VCR-Register: 104"

Մեթոդները նույնն են, ինչ ՀԴՄ-ի սեփական բանալիով. API փաստաթղթեր

Ավելացրեք մինչև 5 հասցե գործընկերոջ անձնական էջում. յուրաքանչյուրը պետք է լինի https և հասանելի ինտերնետից։ Յուրաքանչյուր հարցում ստորագրված է Standard Webhooks սպեցիֆիկացիայով (webhook-id, webhook-timestamp, webhook-signature). ստուգեք ստորագրությունը հասցեի գաղտնի բանալիով, որը ցուցադրվում է մեկ անգամ՝ ավելացնելիս։

Չհաջողված առաքումը կրկնվում է մոտ մեկ օրվա ընթացքում։ Յուրաքանչյուր իրադարձության մարմինը նկարագրված է տեղեկատուում՝ webhooks բաժնում։ Անձնական էջից կարելի է ուղարկել թեստային իրադարձություն՝ հասցեն ստուգելու համար։

Մերժումը գալիս է JSON-ով՝ error դաշտով՝ նախադասություն մարդու համար, և code-ով՝ կայուն կոդ ծրագրի համար։ Կոդերի իմաստը չի փոխվում, բայց կարող են ավելանալ նորերը, ուստի անծանոթ կոդը մշակեք ըստ HTTP կարգավիճակի։ Յուրաքանչյուր մեթոդի կարգավիճակները թվարկված են տեղեկատուում։

POST /registers/{registerId}/closure-ը փակում է ՀԴՄ-ն VCR-ում. դրա բանալիները դադարում են աշխատել, ուղարկվում է register.closed։

curl -X POST https://vcr.am/api/partner/v1/registers/104/closure \
  -H "X-API-Key: $VCR_PARTNER_KEY"

Հարկային մարմնին այդ մասին չի հայտնվում. ՀԴՄ-ն հաշվառումից հանելը հենց հարկ վճարողի դիմումն է հարկային մարմնի պորտալում։ Ինչպես հանել ՀԴՄ-ն հաշվառումից