| 1 |
<?php |
| 2 |
/** |
| 3 |
* Interface Postcode_Check_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 Dutch postcode / address validation services. |
| 16 |
* |
| 17 |
* Covers the PostNL postal-code check API |
| 18 |
* (/shipment/checkout/v1/postalcodecheck). Called from |
| 19 |
* Frontend\Container::validated_address() during the classic checkout |
| 20 |
* order-review refresh, and from Checkout_Blocks\Extend_Block_Core for |
| 21 |
* blocks-checkout validation. |
| 22 |
* |
| 23 |
* This service REMAINS on the Legacy (V1) transport permanently; it is not |
| 24 |
* routed through the V4 API. The interface exists solely to keep the |
| 25 |
* service-factory layer uniform so callers do not need a special case. |
| 26 |
* |
| 27 |
* Both the Legacy implementation and any future passthrough implementation |
| 28 |
* must implement this interface. |
| 29 |
*/ |
| 30 |
interface Postcode_Check_Service_Interface { |
| 31 |
|
| 32 |
/** |
| 33 |
* Validate a Dutch postcode and house number against the PostNL address database. |
| 34 |
* |
| 35 |
* Derived from Frontend\Container::validated_address(), which: |
| 36 |
* 1. Constructs Postcode_Check\Item_Info from $post_data (reads |
| 37 |
* shipping_postcode, shipping_house_number, shipping_address_2). |
| 38 |
* 2. Constructs Postcode_Check\Client with that Item_Info. |
| 39 |
* 3. Calls send_request() on the client. |
| 40 |
* 4. Reads $response[0]['city'], $response[0]['streetName'], and |
| 41 |
* $response[0]['houseNumber'] to populate the WC session key |
| 42 |
* POSTNL_SETTINGS_ID . '_validated_address'. |
| 43 |
* 5. Sets the '_invalid_address_marker' session key when $response is empty. |
| 44 |
* |
| 45 |
* The current PostNL endpoint is /shipment/checkout/v1/postalcodecheck (POST). |
| 46 |
* Only Dutch (NL) addresses are validated; other countries are not sent. |
| 47 |
* |
| 48 |
* @param array $post_data { |
| 49 |
* Checkout POST data as collected from the classic checkout form or the |
| 50 |
* blocks-checkout AJAX handler. |
| 51 |
* |
| 52 |
* @type string $shipping_postcode Required. Dutch postcode in the format |
| 53 |
* '1234AB' (spaces are stripped by |
| 54 |
* Base_Info::set_settings_data()). |
| 55 |
* @type string $shipping_house_number Required. House number string, |
| 56 |
* e.g. '10' or '10a'. |
| 57 |
* @type string $shipping_address_2 Optional. House number extension, |
| 58 |
* e.g. 'bis'. Sent as |
| 59 |
* housenumberaddition in the request body. |
| 60 |
* } |
| 61 |
* |
| 62 |
* @return array Indexed array of address records that match the query. |
| 63 |
* Returns an empty array when no matching address is found |
| 64 |
* (i.e. the postcode / house number combination is invalid). |
| 65 |
* Each record contains at minimum: |
| 66 |
* { |
| 67 |
* @type string $city City name used to populate the |
| 68 |
* billing/shipping city field. |
| 69 |
* @type string $streetName Street name used to populate |
| 70 |
* the address_1 field. |
| 71 |
* @type string|int $houseNumber House number confirmed by PostNL. |
| 72 |
* } |
| 73 |
* |
| 74 |
* @throws \Exception If the API request fails at transport level (network error |
| 75 |
* or authentication failure). An empty or non-matching |
| 76 |
* response is NOT an exception; the caller handles it by |
| 77 |
* setting the invalid-address session marker. |
| 78 |
*/ |
| 79 |
public function check( array $post_data ): array; |
| 80 |
} |
| 81 |
|
