Ուղեցույց

Ինչպես է աշխատում

• 1. Ստացեք WooCommerce պատվերը
• 2. Սինքրոնացրեք WooCommerce պատվերի ապրանքները eHDM-ի հետ
• 3. Ստացեք պատրաստված ապրանքները eHDM պահոցից
• 4. Կանչեք $eHDM->print()
• 5. Ստացեք ֆիսկալ կտրոնի պատասխանը

Աջակցվող սցենարներ

• Անկանխիկ վճարում — ամբողջ վճարումը կատարվում է անկանխիկ
• Կանխիկ վճարում — ամբողջ վճարումը կատարվում է կանխիկ
• Խառը վճարում — մասամբ անկանխիկ, մասամբ կանխիկ
• Մասնակի վճարում — վճարումը փոխանցվում է partialAmount դաշտով
• Կանխավճարի օգտագործում — վճարումը փոխանցվում է prePaymentAmount դաշտով

Բոլոր օրինակներում օգտագործվող հիմնական կարգավորումը՝

$eHDM = apply_filters( 'planetstudio-payment-gateway-ehdm', null );

$wc_order_id = 2708;
$order       = wc_get_order( $wc_order_id );
$amount      = (float) $order->get_total();
$order_id    = '3b2a2c1b-a850-4edd-abf9-bb2a36e1078a';

$eHDM->getWoocommersOrderItems( $wc_order_id );
$items = $eHDM->getWoocommersOrderItemsFromDB( $wc_order_id );

Սցենար 1․ Անկանխիկ վճարում

$result = $eHDM->print(
	array(
		'orderId'          => $order_id,
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => $amount,
		'cashAmount'       => 0,
		'partialAmount'    => 0,
		'prePaymentAmount' => 0,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Սպասվող արդյունքը՝

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "824",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363086000,
		"fiscal": "30247466",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 0, TOTAL_NONCASH: 1, PREP_USAGE: 0, PARTIAL: 0, TOTAL: 1"
	}
}

Սցենար 2․ Կանխիկ վճարում

$result = $eHDM->print(
	array(
		'orderId'          => '',
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => 0,
		'cashAmount'       => $amount,
		'partialAmount'    => 0,
		'prePaymentAmount' => 0,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Սպասվող արդյունքը՝

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "825",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363177000,
		"fiscal": "46682581",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 1, TOTAL_NONCASH: 0, PREP_USAGE: 0, PARTIAL: 0, TOTAL: 1"
	}
}

Սցենար 3․ Խառը վճարում

$result = $eHDM->print(
	array(
		'orderId'          => $order_id,
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => 0.6,
		'cashAmount'       => 0.4,
		'partialAmount'    => 0,
		'prePaymentAmount' => 0,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Սպասվող արդյունքը՝

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "826",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363289000,
		"fiscal": "25105467",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 0.4, TOTAL_NONCASH: 0.6, PREP_USAGE: 0, PARTIAL: 0, TOTAL: 1"
	}
}

Սցենար 4․ Մասնակի վճարում

$result = $eHDM->print(
	array(
		'orderId'          => $order_id,
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => 0,
		'cashAmount'       => 0,
		'partialAmount'    => $amount,
		'prePaymentAmount' => 0,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Սպասվող արդյունքը՝

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "827",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363388000,
		"fiscal": "35778064",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 0, TOTAL_NONCASH: 0, PREP_USAGE: 0, PARTIAL: 1, TOTAL: 1"
	}
}

Սցենար 5․ Կանխավճարի օգտագործում

$result = $eHDM->print(
	array(
		'orderId'          => $order_id,
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => 0,
		'cashAmount'       => 0,
		'partialAmount'    => 0,
		'prePaymentAmount' => $amount,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Սպասվող արդյունքը՝

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "828",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363457000,
		"fiscal": "10900220",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 0, TOTAL_NONCASH: 0, PREP_USAGE: 1, PARTIAL: 0, TOTAL: 1"
	}
}

Նշում կանխավճարի մասին

Կանխավճարի օգտագործումը (prePaymentAmount) կարող է իրականացվել առանց ապրանքների ցանկի։

• Սովորական վաճառքների համար ապրանքների ցանկը պարտադիր է
• Կանխավճարի օգտագործման դեպքում items-ը կարող է դատարկ լինել
• Սա կախված է ֆիսկալ կանոններից և eHDM կարգավորումից

Կանխավճար առանց ապրանքների

Կանխավճարի օգտագործումը (prePaymentAmount) կարող է իրականացվել առանց ապրանքների ցանկի։

$result = $eHDM->print([
	'orderId'          => '',
	'wc_orderId'       => 0,
	'cardAmount'       => 0,
	'cashAmount'       => 0,
	'partialAmount'    => 0,
	'prePaymentAmount' => 1,
	'cashierId'        => 1,
	'mode'             => 3,
	'partnerTin'       => null,
	'items'            => [],
]);

Ապրանքացանկի ստացում

print() մեթոդի համար կարող եք փոխանցել items տարբեր ձևերով՝ կախված ձեր հոսքից։

• 1. WooCommerce պատվերից (ուղիղ)
  
  Օգտագործեք այս մեթոդը, երբ ցանկանում եք ստանալ ապրանքները անմիջապես WooCommerce պատվերից։

$items = $eHDM->getWoocommersOrderItems( $wc_order_id );

Այս մեթոդը ձևավորում է ապրանքների ցանկը ընթացիկ պատվերի տվյալներից

• 2. eHDM բազայից (տպված կտրոնի համար)
  
  Օգտագործեք այս մեթոդը, երբ տվյալ պատվերի ունի կտրոն

$items = $eHDM->getWoocommersOrderItemsFromDB( $wc_order_id );

Սա հիմնականում օգտագործվում է, երբ կտրոնը արդեն ստեղծվել է, և ցանկանում եք օգտագործել նույն ապրանքների ցանկը։

Ապրանքների սեփական ցանկ

Եթե չեք օգտագործում WooCommerce պատվերի ապրանքները, կարող եք items զանգվածը փոծարինել սեփականով։

$items = array(
	array(
		'adgCode'                => '9205',
		'dep'                    => 1,
		'goodCode'               => '9205-13',
		'goodName'               => 'երգեհոն',
		'quantity'               => 2,
		'unit'                   => 'հատ',
		'price'                  => 25000,
		'additionalDiscount'     => null,
		'additionalDiscountType' => null,
		'discount'               => null,
		'discountType'           => null,
	),
);

$result = $eHDM->print(
	array(
		'orderId'          => 'CUSTOM-ORDER-1',
		'wc_orderId'       => 0,
		'cardAmount'       => 50000,
		'cashAmount'       => 0,
		'partialAmount'    => 0,
		'prePaymentAmount' => 0,
		'cashierId'        => 1,
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Կտրոնի վերադարձ

Օգտագործեք վերադարձի ընթացքը նախկինում տպված կտրոնի համար ՀԴՄ վերադարձի կտրոն ստեղծելու նպատակով։ Նախ ստացեք սկզբնական կտրոնի տվյալները, ապա տպեք վերադարձի կտրոնը՝ օգտագործելով ստացված ապրանքային տողերի նույնացուցիչներն ու քանակները։

1. Ստանալ վերադարձի կտրոնի տվյալները

$receipt_id = 824;

$return_info = $eHDM->getReturnedReceiptInfo( $receipt_id );

if ( ! is_array( $return_info ) || 0 !== (int) ( $return_info['code'] ?? -1 ) ) {
	// Հարկային ծառայությունը տվյալ կտրոնի վերաբերյալ տեղեկություն չի վերադարձրել։
	return;
}

$receipt = $return_info['result'];
$items   = $receipt['items'] ?? array();

Արդյունքը պարունակում է սկզբնական կտրոնի տվյալները։ Ապրանքների կտրոնի դեպքում result.items-ը պարունակում է վերադարձման ենթակա ապրանքները։ Վերադարձի կտրոն տպելիս օգտագործեք յուրաքանչյուր տողի receiptProductId-ն ու վերադարձվող քանակը։

2. Տպել վերադարձի կտրոն

// Սկզբնական կտրոնի առաջին ապրանքից վերադարձնել մեկ միավոր։
$return_item_list = array(
	array(
		'receiptProductId' => (int) $items[0]['receiptProductId'],
		'quantity'         => 1,
	),
);

$result = $eHDM->printReturnReceipt(
	array(
		'receiptId'           => $receipt_id,
		'cardAmountForReturn' => 0,
		'cashAmountForReturn' => 5000,
		'returnItemList'      => $return_item_list,
	)
);

Անկանխիկ վերադարձի համար նշեք cardAmountForReturn-ը, իսկ cashAmountForReturn-ը թողեք 0։ Կանխիկ վերադարձի համար՝ հակառակը։ Վերադարձի գումարը պետք է համապատասխանի ընտրված ապրանքներին և չգերազանցի սկզբնական կտրոնի գումարը։

Ապրանքներ չպարունակող կտրոնների, օրինակ՝ կանխավճարի կտրոնի, դեպքում օգտագործեք getReturnedReceiptInfo()-ի վերադարձած տվյալները։ Դատարկ returnItemList փոխանցեք միայն այն դեպքում, երբ Հարկային ծառայության պատասխանում վերադարձման ենթակա ապրանքներ չկան։

Վերադարձի արդյունք

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "829",
		"fiscal": "...",
		"total": 5000,
		"qr": "TIN: ..., TOTAL_CASH: 5000, TOTAL_NONCASH: 0, ..."
	}
}

Հաջող պատասխանի դեպքում code = 0 է։ Նոր վերադարձի կտրոնի համարը հասանելի է result.receiptId-ում։ Դրա QR պատկերը ստանալու համար օգտագործեք $eHDM->getReceiptQR( $result['result']['receiptId'], true )։

Վերադարձի պարամետրեր

Պարամետր	Տիպ	Նկարագրություն
receiptId	int	Վերադարձվող սկզբնական ՀԴՄ կտրոնի համարը։
cardAmountForReturn	double	Քարտին կամ այլ անկանխիկ եղանակով վերադարձվող գումարը։
cashAmountForReturn	double	Կանխիկ վերադարձվող գումարը։
returnItemList	array	Վերադարձվող ապրանքները։ Յուրաքանչյուր տող պարունակում է getReturnedReceiptInfo()-ից ստացված receiptProductId-ն ու վերադարձի quantity-ը։

Կարևոր նշումներ

• Միշտ printReturnReceipt()-ից առաջ կանչեք getReturnedReceiptInfo()-ը։
• receiptProductId-ի արժեքները մի ստեղծեք ձեռքով․ օգտագործեք Հարկային ծառայությունից վերադարձված արժեքները։
• Վերադարձի կտրոնը նոր ֆիսկալ կտրոն է և ունի սեփական կտրոնի համար ու QR տվյալներ։

Կտրոնի QR կոդ

Կարող եք ստեղծել QR կոդ տպված կտրոնի համար՝ օգտագործելով getReceiptQR() մեթոդը։

Օգտագործում

$url = $eHDM->getReceiptQR( 824, true );

Վերադարձնում է QR կոդի նկարի URL։

$html = $eHDM->getReceiptQR( 824 );

Վերադարձնում է պատրաստ HTML <img> թեգ։

Օրինակ արդյունք

https://api.qrserver.com/v1/create-qr-code/?data=...&size=300x300

<img class="ehdm-qr" src="https://api.qrserver.com/..." alt="eHDM QR Code">

Ինչպես է աշխատում

• Բեռնում է կտրոնը eHDM բազայից ըստ receiptId
• Վերցնում է qr դաշտը
• Կոդավորում է տվյալները
• Ստեղծում է QR նկար արտաքին սերվիսի միջոցով

Նշումներ

• receiptId-ը պետք է գոյություն ունենա
• Վերադարձնում է false, եթե կտրոնը չի գտնվել
• QR-ը պարունակում է ամբողջ ֆիսկալ ինֆորմացիան
• Կարող եք օգտագործել URL կամ պատրաստ HTML տարբերակը

Զեղչի կիրառում

Էլեկտրոնային ՀԴՄ գրանցելու և այն ծածկագրումը ինտեգրելու համար, հնարավոր է կիրառել տարբեր տեսակի զեղչեր, որոնք իրենց հերթին ունեն երկու ենթատեսակ:

• 1. Ապրանքի գնի / discount
  • % PERCENT, տոկոսային գին՝ discountType = 1
  • PRICE (դ), մեկ ապրանքի / միավորի համար տրված գումարային գին՝ discountType = 2. Հաշվում՝ (initial_price – discount) * quantity
  • TOTAL (դ), ընդհանուր քանակի համար տրված գին՝ discountType = 4. Հաշվում՝ (price*quantity) – discount
• 2. Ապրանքի լրացուցիչ գին / additionalDiscount
  • Type additionalDiscountType = 16, գումարային գին հաշվվում՝ (price*quantity) – discount
  • % – այս գինը կիրառվում է 8 սիմվոլ

Ինչ է նշանակում պատասխանը

• code = 0 — հաջողություն
• message = OK — կտրոնը հաջողությամբ տպվել է
• errorMessage = null — սխալ չկա
• result.receiptId — կտրոնի ID
• result.fiscal — ֆիսկալ համար
• result.total — կտրոնի ընդհանուր գումարը
• result.change — մանրը
• result.qr — ֆիսկալ QR տող՝ վճարման բաժանմամբ

QR դաշտեր

• TOTAL_CASH — կանխիկ գումար
• TOTAL_NONCASH — անկանխիկ գումար
• PREP_USAGE — օգտագործված կանխավճարի գումար
• PARTIAL — մասնակի վճարման գումար
• TOTAL — վերջնական գումար

Նշումներ

• mode = 2 – Ապրանքներ ռեժիմ / 3 – Կանխավճար
• orderId-ը պարտադիր է անկանխիկ և խառը վճարման սցենարների համար
• WooCommerce ապրանքները նախ պետք է պատրաստվեն getWoocommersOrderItems()-ով
• Այնուհետև դրանք պետք է բեռնվեն getWoocommersOrderItemsFromDB()-ով
• Բոլոր կտրոնները պահվում են eHDM-ում

Պարամետրեր

Պարամետր	Տիպ	Նկարագրություն
cardAmount	double	Անկանխիկ (քարտով) վճարված գումար
cashAmount	double	Կանխիկ վճարված գումար
partialAmount	double	Մասնակի վճարման գումար
prePaymentAmount	double	Օգտագործված կանխավճարի գումար
cashierId	int	Գանձապահի համարը
mode	int	Կտրոնի ռեժիմ՝ 2 – Ապրանքներ / 3 – Կանխավճար
partnerTin	string	Գնորդի ՀՎՀՀ
items	array	Ապրանքների ցանկ

Օգտագործելով այս API-ն և կոդի օրինակները՝ դուք համաձայնվում եք մեր Terms & Conditions-ին։
Խնդրում ենք իրական միջավայրում օգտագործելուց առաջ իրականացնել համապատասխան թեստավորում։