woo-postnl / src / Rest_API / Contracts / Label_Service_Interface.php

Label_Service_Interface.php in PostNL for WooCommerce trunk, at src/Rest_API/Contracts/Label_Service_Interface.php

110 lines 5.3 KB

Raw Download Zip

1	<?php
2	/**
3	* Interface Label_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 outbound shipping label generation services.
16	*
17	* Covers both standard parcel labels (Shipping\Client, /v1/shipment) and
18	* letterbox-parcel labels (Letterbox\Client, same endpoint with a different
19	* product code). Both callers in Order\Base pass the same $post_data shape
20	* and the return value is stored directly in _postnl_order_metadata['labels']
21	* without further transformation.
22	*
23	* The interface sits at the service level: it replaces the entire
24	* Order\Base::create_label() call chain (API request + file write + merge).
25	* Callers in Order\Base assign the return value straight to $saved_data['labels'].
26	*
27	* Both the Legacy (V1) and any future V4 transport must implement this interface.
28	* Callers in Order\Base never need to know which transport answered.
29	*/
30	interface Label_Service_Interface {
31
32	/**
33	* Create a PostNL shipping label for an order and return the normalized
34	* label record ready to be stored in _postnl_order_metadata['labels'].
35	*
36	* The return shape is derived from Order\Base::create_label() and
37	* Order\Base::maybe_create_letterbox() — specifically the value those
38	* methods return after the full pipeline:
39	* 1. PostNL API call (/v1/shipment, POST, confirm=true).
40	* 2. Validation of barcode + label content in the response.
41	* 3. Base64 decode + file write of each label to POSTNL_UPLOADS_DIR.
42	* 4. Merge of multiple A6 files into one A4 sheet when label format is A4
43	* (via Order\Base::put_label_content() + maybe_merge_labels()).
44	*
45	* The resulting array is keyed by the label-type string (e.g. 'label',
46	* 'letterbox') and assigned to $saved_data['labels'] in
47	* Order\Base::save_meta_value():
48	* $saved_data['labels'] = $label_service->create( $post_data );
49	*
50	* Multi-collo (num_labels > 1) shipments are sent in a single API request
51	* with multiple Shipments entries grouped by GroupType '03'; the merged
52	* result is still a single entry in the returned array.
53	*
54	* @param array $post_data {
55	* Context needed to build and send the label request.
56	*
57	* @type \WC_Order $order Required. WooCommerce order object.
58	* @type array $saved_data {
59	* Required. Order-level saved data.
60	* @type array $backend Admin-selected option flags, e.g.:
61	* num_labels, insured_shipping, letterbox,
62	* id_check, signature_on_delivery, etc.
63	* @type array $frontend Customer-selected checkout options, e.g.
64	* delivery_day_, dropoff_points_.
65	* }
66	* @type string $main_barcode Required. The primary barcode
67	* string for the first shipment.
68	* @type string[] $barcodes Required. All barcodes for
69	* multi-collo; index 0 is main.
70	* @type string $return_barcode Return barcode string.
71	* Empty string when not applicable.
72	* @type string $shipping_return_barcode Shipping-return barcode string.
73	* Empty string when not applicable.
74	* @type bool $is_return_activated Whether return function was
75	* previously activated for this order.
76	* }
77	*
78	* @return array {
79	* Normalized label record keyed by label-type string. This array is
80	* stored verbatim as _postnl_order_metadata['labels'] by the caller.
81	*
82	* @type array $label_type {
83	* Key is the label-type string, e.g. 'label' or 'letterbox'.
84	* Matches the parent_label_type passed internally to put_label_content().
85	*
86	* @type string $type Same as the array key, e.g. 'label'.
87	* @type string $barcode The main/parent barcode string, e.g.
88	* '3SXXXXXXXXX'. Read by get_tracking_link()
89	* and displayed in the orders list column.
90	* @type int $created_at Unix timestamp (current_time('timestamp'))
91	* at the moment of label creation.
92	* @type string $filepath Absolute path to the final label file on
93	* disk (merged A4 PDF or single A6 file).
94	* Used by download_label() and delete_label().
95	* @type string[] $merged_files Absolute paths of the individual label
96	* files that were merged into $filepath.
97	* Present whenever labels were merged, i.e.
98	* any case other than a single A6 label
99	* (covers A4 and multi-collo A6).
100	* Removed by delete_label() alongside $filepath.
101	* }
102	* }
103	*
104	* @throws \Exception If the API request fails, the barcode is missing, the
105	* label content is empty, or the resulting label array is
106	* empty after processing.
107	*/
108	public function create( array $post_data ): array;
109	}
110