Public API for Voucher Validation
The app provides a public API endpoint that is called by the checkout widget to validate Carte Cultura voucher codes. This endpoint performs the validation by communicating with the official Ministry of Culture SOAP service.
Endpoint Details
The endpoint is accessible via a POST request to the following path: /api/public/validate-voucher.
Note: This endpoint is designed to be called from the Shopify checkout extension and does not require merchant authentication. It uses CORS headers to allow requests from extensions.shopifycdn.com.
Required Request Parameters
The request must be a POST with the following parameters sent as multipart/form-data:
action: The specific action for the SOAP call.codiceVoucher: The voucher code entered by the customer in the checkout widget.importo: The total cart amount for which the voucher is being validated.
The request must also include the shop domain, provided in one of the following headers:
X-Shopify-Shop-DomainX-Shop-Domain
Alternatively, the shop domain can be passed as a query parameter: ?shop=your-store.myshopify.com.
Validation Process and Billing Check
When a validation request is received, the API performs several critical checks before contacting the Ministry’s service:
- Billing Status Verification: The API first checks the shop’s billing status stored in Shopify Metafields. If the status is
expired,cancelled, or inactive, the validation is immediately blocked, and an error is returned to the checkout widget. - License Expiration Date Check: The API performs a second, critical check against the license expiration date. Even if the billing status hasn’t been updated yet, a license that has passed its expiration date will cause the validation to fail. If an expired license is detected, the billing status is automatically updated to
expired. - Shop Configuration: The API verifies that the app is properly configured for the requesting shop by loading settings from Shopify Metafields.
- SOAP Service Call: If all checks pass, the API proceeds to validate the voucher. It uses a PHP microservice to handle the SOAP call to the Carte Cultura endpoint (either sandbox or production, based on the shop’s settings), ensuring compatibility with the IBM DataPower system.
Response Format
The API returns a JSON response. A successful validation will include details about the voucher. If any check fails, the response will contain a success: false flag and an error message explaining the reason (e.g., “La licenza Carte Cultura è scaduta” or “Il servizio Carte Cultura non è al momento disponibile”).
Note: In a development or test environment, the API may use mock voucher responses for testing purposes. In a production environment, all validations go through the real SOAP service.
Certificate Status Check Endpoint
A separate public endpoint allows the checkout widget to check if the voucher service is enabled for a shop before displaying the input field. This endpoint is accessible via a GET request to /api/public/certificate-status.
The shop domain must be provided as a query parameter: ?shop=your-store.myshopify.com.
The response indicates if the widget should be enabled, based on whether the shop is in sandbox mode or has a valid production certificate loaded.