| 1 |
<?php |
| 2 |
/** |
| 3 |
* Interface Barcode_Service_Interface. |
| 4 |
* |
| 5 |
* @package PostNLWooCommerce\Rest_API\Contracts |
| 6 |
*/ |
| 7 |
|
| 8 |
namespace PostNLWooCommerce\Rest_API\Contracts; |
| 9 |
|
| 10 |
if ( ! defined( 'ABSPATH' ) ) { |
| 11 |
exit; |
| 12 |
} |
| 13 |
|
| 14 |
/** |
| 15 |
* Contract for barcode generation services. |
| 16 |
* |
| 17 |
* Both the Legacy (V1) and any future V4 transport must implement this interface. |
| 18 |
* Callers in Order\Base never need to know which transport answered the request. |
| 19 |
*/ |
| 20 |
interface Barcode_Service_Interface { |
| 21 |
|
| 22 |
/** |
| 23 |
* Generate a PostNL barcode for a single shipment. |
| 24 |
* |
| 25 |
* Derived from Order\Base::create_barcode() and |
| 26 |
* Order\Base::maybe_create_return_barcode(), which both: |
| 27 |
* 1. Construct Barcode\Item_Info from $post_data. |
| 28 |
* 2. Construct Barcode\Client with that Item_Info. |
| 29 |
* 3. Call send_request() on the client. |
| 30 |
* 4. Read $response['Barcode'] as the generated tracking number. |
| 31 |
* |
| 32 |
* The current PostNL Barcode API endpoint is /shipment/v1_1/barcode (GET). |
| 33 |
* Domestic NL/BE shipments use barcode type '3S'; EU uses 'UE'/'LA'; |
| 34 |
* rest-of-world uses the GlobalPack barcode type from settings. |
| 35 |
* |
| 36 |
* @param array $post_data { |
| 37 |
* Context needed to build and send the barcode request. |
| 38 |
* |
| 39 |
* @type \WC_Order $order Required. The WooCommerce order for which |
| 40 |
* to generate the barcode. Used to read the |
| 41 |
* shipping country/state and address. |
| 42 |
* @type array $saved_data Required. Order-level saved data. The |
| 43 |
* 'backend' sub-key contains the admin-selected |
| 44 |
* option flags (e.g. 'packets', 'mailboxpacket') |
| 45 |
* that determine the barcode type via |
| 46 |
* Barcode\Item_Info::check_product_barcode_type(). |
| 47 |
* } |
| 48 |
* |
| 49 |
* Note: return barcodes use a customer code derived internally from |
| 50 |
* Settings::get_return_customer_code(); it is never supplied by the caller. |
| 51 |
* |
| 52 |
* @return array { |
| 53 |
* JSON-decoded PostNL barcode API response body. |
| 54 |
* |
| 55 |
* @type string $Barcode The generated PostNL barcode string, |
| 56 |
* e.g. '3SXXXXXXXXXX' for domestic NL, |
| 57 |
* 'LA000000000NL' for EU registered packets. |
| 58 |
* This value is stored in |
| 59 |
* _postnl_order_metadata['barcodes'][n]['value']. |
| 60 |
* } |
| 61 |
* |
| 62 |
* @throws \Exception If the API request fails (network error, authentication |
| 63 |
* failure, or missing Barcode key in the response). |
| 64 |
*/ |
| 65 |
public function generate( array $post_data ): array; |
| 66 |
} |
| 67 |
|
