8571051831

Committed 05 Apr 2024 02:05PM UTC coverage: 5.917% (+0.8%) from 5.079%

Build # 8571051831

Build Type

push

github

Committed by

mlocati

Commit Message

Document some of the features

Run Details

111 of 1876 relevant lines covered (5.92%)

0.51 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/src/Client.php

<?php

declare(strict_types=1);

namespace MLocati\Nexi;

use MLocati\Nexi\HttpClient\Response;
use MLocati\Nexi\Service\QueryEntityInterface;
use stdClass;

/*
 * WARNING: DO NOT EDIT THIS FILE
 * It has been generated automaticlly from a template.
 * Edit the template instead.
 */

class Client
{
    /**
     * @var \MLocati\Nexi\Configuration
     */
    protected $configuration;

    /**
     * @var \MLocati\Nexi\HttpClient
     */
    protected $httpClient;

    /**
     * @var \MLocati\Nexi\CorrelationProvider
     */
    protected $correlationProvider;

    /**
     * @var \MLocati\Nexi\Entity\Webhook\Request|null
     */
    private $notificationRequest;

    /**
     * @throws \MLocati\Nexi\Exception\NoHttpClient if $httpClient is NULL and no HTTP client is available
     */
    public function __construct(
        Configuration $configuration,
        ?HttpClient $httpClient = null,
        ?CorrelationProvider $correlationProvider = null
    ) {
        $this->configuration = $configuration;
        $this->httpClient = $httpClient ?? $this->buildHttpClient();
        $this->correlationProvider = $correlationProvider ?? $this->buildCorrelationProvider();
    }

    /**
     * @throws \MLocati\Nexi\Exception\InvalidJson is no (valid) request data is detected
     * @throws \MLocati\Nexi\Exception\MissingField is the received data does not contain a security token
     */
    public function getNotificationRequest(): Entity\Webhook\Request
    {
        if ($this->notificationRequest === null) {
            $data = $this->decodeJsonToObject(file_get_contents('php://input') ?: '');
            $notificationRequest = new Entity\Webhook\Request($data);
            $notificationRequest->checkRequiredFields('webhookRequest', 'receive');
            if ((string) $notificationRequest->getSecurityToken() === '') {
                throw new Exception\MissingField('securityToken');
            }
            $this->notificationRequest = $notificationRequest;
        }

        return $this->notificationRequest;
    }

    /**
     * Initiating payment through the Hosted Payment Page solution, the API returns the URL to redirect the customer to complete the transaction. For more information, please refer to the dedicated page Hosted Payment Page.
     *
     * @see https://developer.nexi.it/en/api/post-orders-hpp
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createOrderForHostedPayment(Entity\CreateOrderForHostedPayment\Request $requestBody): Entity\CreateOrderForHostedPayment\Response
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/hpp');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\CreateOrderForHostedPayment\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Generate a link to share with the customer to execute a payment. For more information, please refer to the dedicated page Pay-by-Link.
     *
     * @see https://developer.nexi.it/en/api/post-orders-paybylink
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createOrderForPayByLink(Entity\CreateOrderForPayByLink\Request $requestBody): Entity\PayByLinkResponse
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/paybylink');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\PayByLinkResponse($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Cancel a Pay-By-Link that has not yet been paid. For more information on the Pay-by-Link solution, please refer to the dedicated page Pay-by-Link.
     *
     * @param string $linkId Unpaid Pay-By-Link ID to be canceled.
     *
     * @see https://developer.nexi.it/en/api/post-paybylink-linkId-cancels
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Request rejected (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return bool returns FALSE if not found
     */
    public function cancelPayByLink(string $linkId): bool
    {
        $url = $this->buildUrl('/paybylink/{linkId}/cancels', ['linkId' => $linkId]);
        $response = $this->invoke('POST', $url, 3);
        if ($response->getStatusCode() === 200) {
            return true;
        }
        if ($response->getStatusCode() === 404) {
            return false;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Request rejected', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Verify registration with the 3DS protocol. This operation initiates the 2-step Server-to-Server payment flow. For more information, please refer to the dedicated page Payment 2 Steps.
     *
     * @see https://developer.nexi.it/en/api/post-orders-2steps-init
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function twoSteps3DSInit(Entity\MultiStepInitRequest $requestBody): Entity\MultiStepInitResponse
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/2steps/init');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\MultiStepInitResponse($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Payment Authorization. This completes the 2-step Server-to-Server payment flow. For more information, refer to the dedicated page Pagamento 2 Steps.
     *
     * @see https://developer.nexi.it/en/api/post-orders-2steps-payment
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function twoSteps3DSPayment(Entity\MultiStepPaymentRequest $requestBody): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/2steps/payment');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Verify registration with the 3DS protocol. This operation initiates the 3-step Server-to-Server payment flow. For more information, please refer to the dedicated page Payment 3 Steps.
     *
     * @see https://developer.nexi.it/en/api/post-orders-3steps-init
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function threeSteps3DSInit(Entity\MultiStepInitRequest $requestBody): Entity\MultiStepInitResponse
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/3steps/init');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\MultiStepInitResponse($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Validation of the 3DS authentication outcome. This operation is required during the 3-step Server-to-Server payment flow. For more information, please refer to the dedicated page Payment 3 Steps.
     *
     * @see https://developer.nexi.it/en/api/post-orders-3steps-validation
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function threeSteps3DSValidation(Entity\ThreeSteps3DSValidation\Request $requestBody): Entity\ThreeSteps3DSValidation\Response
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/3steps/validation');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\ThreeSteps3DSValidation\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Payment authorization. This operation completes the 3-step Server-to-Server payment flow. For more information, please refer to the dedicated page Payment 3 Steps.
     *
     * @see https://developer.nexi.it/en/api/post-orders-3steps-payment
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function threeSteps3DSPayment(Entity\MultiStepPaymentRequest $requestBody): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/3steps/payment');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * MIT (Merchant Initiated Transaction) payment, a recurring payment method used in services such as subscriptions. For more information, please refer to the dedicated page Recurring Payments.
     *
     * @param string $idempotencyKey an identifier of the request (to be used on subsequent retries); if empty, it will be set as output
     *
     * @see https://developer.nexi.it/en/api/post-orders-mit
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createOrderForMerchantInitiatedTransaction(Entity\CreateOrderForMerchantInitiatedTransaction\Request $requestBody, string &$idempotencyKey = ''): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/mit');
        $response = $this->invoke('POST', $url, 7, $requestBody, $idempotencyKey);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Card verification operation, without any charge, with the sole purpose of confirming the validity of the card data entered by the customer.This API is a feature dedicated to the Server to Server integration mode, and is therefore subject to obtaining PCI DSS security certification (SAQ D questionnaire).This API is not subject to 3D Secure authentication.
     *
     * @see https://developer.nexi.it/en/api/post-orders-card_verification
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function cardVerification(Entity\CardVerification\Request $requestBody): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/card_verification');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Server-to-Server MOTO payment. For more information, please refer to the dedicated page M.O.T.O..
     *
     * @see https://developer.nexi.it/en/api/post-orders-moto
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createOrderForMotoPayment(Entity\CreateOrderForMotoPayment\Request $requestBody): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/moto');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Server to Server payment (PCI certification required) via virtual card.
     *
     * @see https://developer.nexi.it/en/api/post-orders-virtual_card
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createVirtualCartOrder(Entity\CreateVirtualCartOrder\Request $requestBody): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/virtual_card');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Create an order and initiate the payment using the XPay Build solution.
     * WARNING: for the proper functioning of XPay Build solution, it is necessary for the browser used to allow the use of third-party cookies.
     *
     * @see https://developer.nexi.it/en/api/post-orders-build
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createXPayBuildOrder(Entity\CreateXPayBuildOrder\Request $requestBody): Entity\FieldSet
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/orders/build');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FieldSet($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Conclude a payment using the XPay Build solution.
     *
     * @see https://developer.nexi.it/en/api/post-build-finalize-payment
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function finalizeXPayBuildOrder(Entity\Session $requestBody): Entity\FinalizeXPayBuildOrder\Response
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/build/finalize_payment');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FinalizeXPayBuildOrder\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Cancel a payment session XPay Build. Once a session is invalidated, any further submissions of requests related to the canceled session are destined to fail. Therefore, it will be necessary to invoke the API POST /orders/build for the generation of a new sessionId. This API can be applied to a payment cancellation button placed in the merchant's checkout: it is not mandatory to implement the API; in case it is not used, any session will be invalidated upon session expiration (5 minutes).
     *
     * @see https://developer.nexi.it/en/api/post-build-cancel
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function cancelXPayBuildOrder(Entity\Session $requestBody): Entity\CancelXPayBuildOrder\Response
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/build/cancel');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\CancelXPayBuildOrder\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Get current payment status via XPay Build solution.
     *
     * @see https://developer.nexi.it/en/api/get-build-state
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function getXPayBuildOrderStatus(?Entity\Session $query = null): Entity\GetXPayBuildOrderStatus\Response
    {
        if ($query !== null) {
            $query->checkRequiredFields(__FUNCTION__, 'send');
        }
        $url = $this->buildUrl('/build/state', [], $query);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\GetXPayBuildOrderStatus\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * List of orders in reverse chronological order. For more information about orders, please refer to the dedicated page Orders.
     *
     * @see https://developer.nexi.it/en/api/get-orders
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function findOrders(?Entity\FindOrders\Query $query = null): Entity\FindOrders\Response
    {
        if ($query !== null) {
            $query->checkRequiredFields(__FUNCTION__, 'send');
        }
        $url = $this->buildUrl('/orders', [], $query);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FindOrders\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Searches for an order and returns its details. For more information about orders, please refer to the dedicated page Orders.
     *
     * @param string $orderId Identification code sent during the payment initialization phase (it must be unique).
     *
     * @see https://developer.nexi.it/en/api/get-orders-orderId
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\FindOrderById\Response|null returns NULL if not found
     */
    public function findOrderById(string $orderId): ?Entity\FindOrderById\Response
    {
        $url = $this->buildUrl('/orders/{orderId}', ['orderId' => $orderId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FindOrderById\Response($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * List of all operations created within the specified time range. For more information on operations, refer to the dedicated page Operations.
     *
     * @see https://developer.nexi.it/en/api/get-operations
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function findOperations(?Entity\FindOperations\Query $query = null): Entity\FindOperations\Response
    {
        if ($query !== null) {
            $query->checkRequiredFields(__FUNCTION__, 'send');
        }
        $url = $this->buildUrl('/operations', [], $query);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FindOperations\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Searches for an operation and returns its details. For more information on operations, please refer to the dedicated page Operations.
     *
     * @param string $operationId Identification code of the operation.
     *
     * @see https://developer.nexi.it/en/api/get-operations-operationId
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\Operation|null returns NULL if not found
     */
    public function findOperationById(string $operationId): ?Entity\Operation
    {
        $url = $this->buildUrl('/operations/{operationId}', ['operationId' => $operationId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\Operation($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Retrieve the allowed actions associated to an operation and the range of value acceptable. For more information on operations, please refer to the dedicated page Operations.
     *
     * @param string $operationId Operation id
     *
     * @see https://developer.nexi.it/en/api/get-operations-operationId-actions
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\GetOperationActions\Response|null returns NULL if not found
     */
    public function getOperationActions(string $operationId): ?Entity\GetOperationActions\Response
    {
        $url = $this->buildUrl('/operations/{operationId}/actions', ['operationId' => $operationId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\GetOperationActions\Response($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Partial/total refund or cancellation based on the order status. For more information on operations, please refer to the dedicated page Operations.
     *
     * @param string $operationId Identification code of the operation.
     * @param string $idempotencyKey an identifier of the request (to be used on subsequent retries); if empty, it will be set as output
     *
     * @see https://developer.nexi.it/en/api/post-operations-operationId-refunds
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Request rejected (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\OperationInfo|null returns NULL if not found
     */
    public function refund(string $operationId, Entity\AmountWithDescription $requestBody, string &$idempotencyKey = ''): ?Entity\OperationInfo
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/operations/{operationId}/refunds', ['operationId' => $operationId]);
        $response = $this->invoke('POST', $url, 7, $requestBody, $idempotencyKey);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationInfo($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Request rejected', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Partial or total accounting. For more information on operations, refer to the dedicated page Operations..
     *
     * @param string $operationId Identification code of the operation.
     * @param string $idempotencyKey an identifier of the request (to be used on subsequent retries); if empty, it will be set as output
     *
     * @see https://developer.nexi.it/en/api/post-operations-operationId-captures
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Request rejected (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\OperationInfo|null returns NULL if not found
     */
    public function capture(string $operationId, Entity\AmountWithDescription $requestBody, string &$idempotencyKey = ''): ?Entity\OperationInfo
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/operations/{operationId}/captures', ['operationId' => $operationId]);
        $response = $this->invoke('POST', $url, 7, $requestBody, $idempotencyKey);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationInfo($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Request rejected', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Cancels a accounting operation. Does not apply to any other type of operation. For more information about operations, please refer to the dedicated page Operations.
     *
     * @param string $operationId Operation id of a capture operation to be cancelled.
     *
     * @see https://developer.nexi.it/en/api/post-operations-operationId-cancels
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Request rejected (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\OperationInfo|null returns NULL if not found
     */
    public function cancel(string $operationId, Entity\Cancel\Request $requestBody): ?Entity\OperationInfo
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/operations/{operationId}/cancels', ['operationId' => $operationId]);
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationInfo($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Request rejected', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Search for contracts using the customer's identification. For more information on contracts, refer to the dedicated Contracts page.
     *
     * @param string $customerId Customer identification code.
     *
     * @see https://developer.nexi.it/en/api/get-contracts-customers-customerId
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\FindRecurringContractsByCustomerId\Response|null returns NULL if not found
     */
    public function findRecurringContractsByCustomerId(string $customerId): ?Entity\FindRecurringContractsByCustomerId\Response
    {
        $url = $this->buildUrl('/contracts/customers/{customerId}', ['customerId' => $customerId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FindRecurringContractsByCustomerId\Response($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Disable a contract. For more information on contracts, please refer to the dedicated Contracts page.
     *
     * @param string $contractId Recurring contract ID.
     *
     * @see https://developer.nexi.it/en/api/post-contracts-contractId-deactivation
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function disableContract(string $contractId): void
    {
        $url = $this->buildUrl('/contracts/{contractId}/deactivation', ['contractId' => $contractId]);
        $response = $this->invoke('POST', $url, 3);
        if ($response->getStatusCode() === 200) {
            return;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * List of payment methods supported by the merchant terminal along with associated attributes.
     *
     * @see https://developer.nexi.it/en/api/post-payment_methods
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function listSupportedPaymentMethods(): Entity\ListSupportedPaymentMethods\Response
    {
        $url = $this->buildUrl('/payment_methods');
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\ListSupportedPaymentMethods\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Create Terms and Condition for orders.
     *
     * @see https://developer.nexi.it/en/api/post-termsAndConditions
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createTermsAndConditions(Entity\CreateTermsAndConditions\Request $requestBody): Entity\CreateTermsAndConditions\Response
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/termsAndConditions');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\CreateTermsAndConditions\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Retrieve one Terms and Conditions details.
     *
     * @param string $termsAndConditionsId Terms and Conditions ID.
     *
     * @see https://developer.nexi.it/en/api/get-terms_and_conditions-termsAndConditionsId
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function findTermsAndConditionsById(string $termsAndConditionsId): Entity\FindTermsAndConditionsById\Response
    {
        $url = $this->buildUrl('/terms_and_conditions/{termsAndConditionsId}', ['termsAndConditionsId' => $termsAndConditionsId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FindTermsAndConditionsById\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Incremental of a pre-authorization.
     *
     * @param string $idempotencyKey an identifier of the request (to be used on subsequent retries); if empty, it will be set as output
     *
     * @see https://developer.nexi.it/en/api/post-incrementals
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function incrementOrder(Entity\ChangeAmountRequest $requestBody, string &$idempotencyKey = ''): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/incrementals');
        $response = $this->invoke('POST', $url, 7, $requestBody, $idempotencyKey);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Cancel a T&C not associated to any operation.
     *
     * @param string $termsAndConditionsId Terms and Conditions ID.
     *
     * @see https://developer.nexi.it/en/api/post-terms_and_conditions-termsAndConditionsId-cancels
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Request rejected (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return bool returns FALSE if not found
     */
    public function cancelTermsAndConditions(string $termsAndConditionsId): bool
    {
        $url = $this->buildUrl('/terms_and_conditions/{termsAndConditionsId}/cancels', ['termsAndConditionsId' => $termsAndConditionsId]);
        $response = $this->invoke('POST', $url, 3);
        if ($response->getStatusCode() === 200) {
            return true;
        }
        if ($response->getStatusCode() === 404) {
            return false;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Request rejected', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Possibility of making additional charges for example for a customer who has used the mini bar or has caused damage to the property.
     *
     * @param string $idempotencyKey an identifier of the request (to be used on subsequent retries); if empty, it will be set as output
     *
     * @see https://developer.nexi.it/en/api/post-delay_charges
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function delayedCharge(Entity\ChangeAmountRequest $requestBody, string &$idempotencyKey = ''): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/delay_charges');
        $response = $this->invoke('POST', $url, 7, $requestBody, $idempotencyKey);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * If the customer does not show up and the reservation has not been canceled within the defined terms and conditions, you can charge the card for the amount corresponding to an overnight stay.
     *
     * @param string $idempotencyKey an identifier of the request (to be used on subsequent retries); if empty, it will be set as output
     *
     * @see https://developer.nexi.it/en/api/post-no_shows
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function noShowCharge(Entity\ChangeAmountRequest $requestBody, string &$idempotencyKey = ''): Entity\OperationResult
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/no_shows');
        $response = $this->invoke('POST', $url, 7, $requestBody, $idempotencyKey);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\OperationResult($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Create reservation.
     *
     * @see https://developer.nexi.it/en/api/post-reservations
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createReservation(Entity\CreateReservation\Request $requestBody): Entity\CreateReservation\Response
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/reservations');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\CreateReservation\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Find reservations.
     *
     * @see https://developer.nexi.it/en/api/get-reservations
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function findReservations(?Entity\FindReservations\Query $query = null): Entity\FindReservations\Response
    {
        if ($query !== null) {
            $query->checkRequiredFields(__FUNCTION__, 'send');
        }
        $url = $this->buildUrl('/reservations', [], $query);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FindReservations\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Generate PayByLink for a specific reservation. In case of the first payment for the reservation, a contractId is created. In case of the following payment the existing reservation contractId is used.
     *
     * @param string $reservationId Merchant reservation id, unique in the merchant domain
     *
     * @see https://developer.nexi.it/en/api/post-reservations-reservationId-paybylink
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createPayByLinkForReservation(string $reservationId, Entity\CreatePayByLinkForReservation\Request $requestBody): Entity\PayByLinkResponse
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/reservations/{reservationId}/paybylink', ['reservationId' => $reservationId]);
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\PayByLinkResponse($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Find reservation by ID.
     *
     * @param string $reservationId Merchant reservation id
     *
     * @see https://developer.nexi.it/en/api/get-reservations-reservationId
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\FindReservationById\Response|null returns NULL if not found
     */
    public function findReservationById(string $reservationId): ?Entity\FindReservationById\Response
    {
        $url = $this->buildUrl('/reservations/{reservationId}', ['reservationId' => $reservationId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FindReservationById\Response($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Create a structure.
     *
     * @see https://developer.nexi.it/en/api/post-structures
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createStructure(Entity\StructureInfo $requestBody): void
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/structures');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            return;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Find structure in reversed chronological order.
     *
     * @see https://developer.nexi.it/en/api/get-structures
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\StructureInfo|null returns NULL if not found
     */
    public function findStructures(): ?Entity\StructureInfo
    {
        $url = $this->buildUrl('/structures');
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\StructureInfo($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Retrieve information of a specific structure identified by structure id.
     *
     * @param string $structureId Identification code of the structure.
     *
     * @see https://developer.nexi.it/en/api/get-structures-structureId
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\StructureInfo|null returns NULL if not found
     */
    public function findStructureById(string $structureId): ?Entity\StructureInfo
    {
        $url = $this->buildUrl('/structures/{structureId}', ['structureId' => $structureId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\StructureInfo($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * No Show validation.
     *
     * @see https://developer.nexi.it/en/api/post-noshow_validation
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function noShowValidation(Entity\ReservationValidation $requestBody): void
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/noshow_validation');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            return;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Delay charge validation.
     *
     * @see https://developer.nexi.it/en/api/post-delaycharge_validation
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function delayedChargeValidation(Entity\ReservationValidation $requestBody): void
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/delaycharge_validation');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            return;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Incremental validation
     *
     * @see https://developer.nexi.it/en/api/post-incremental_validation
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function incrementOrderValidation(Entity\ReservationValidation $requestBody): void
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/incremental_validation');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            return;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Create terms and conditions defined for a unique structure.
     *
     * @see https://developer.nexi.it/en/api/post-structure_conditions
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createStructureTermsAndConditions(Entity\CreateStructureTermsAndConditions\Request $requestBody): Entity\CreateStructureTermsAndConditions\Response
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/structure_conditions');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\CreateStructureTermsAndConditions\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Retrieve the list of terms and conditions associated to a specific structure.
     *
     * @param string $structureid Unique identifier for the structure.
     *
     * @see https://developer.nexi.it/en/api/get-structure_conditions-structures-structureid
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function findStructureTermsAndConditionsByStructureId(string $structureid): array
    {
        $url = $this->buildUrl('/structure_conditions/structures/{structureid}', ['structureid' => $structureid]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToArray($response->getBody());

            return array_map(static function (array $item) { return new Entity\StructureTermsAndConditions($item); }, $data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Retrieve all the details for a given terms and conditions.
     *
     * @param string $structureConditionId Unique identifier of terms and conditions for the structure.
     *
     * @see https://developer.nexi.it/en/api/get-structure_conditions-structureConditionId
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function findStructureTermsAndConditionsById(string $structureConditionId): Entity\FindStructureTermsAndConditionsById\Response
    {
        $url = $this->buildUrl('/structure_conditions/{structureConditionId}', ['structureConditionId' => $structureConditionId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\FindStructureTermsAndConditionsById\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Cancel terms and condition not associated to any operation.
     *
     * @param string $structureConditionId Unique identifier of terms and conditions for the structure.
     *
     * @see https://developer.nexi.it/en/api/post-structure_conditions-structureConditionId-cancels
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Request rejected (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return bool returns FALSE if not found
     */
    public function cancelStructureTermsAndConditions(string $structureConditionId): bool
    {
        $url = $this->buildUrl('/structure_conditions/{structureConditionId}/cancels', ['structureConditionId' => $structureConditionId]);
        $response = $this->invoke('POST', $url, 3);
        if ($response->getStatusCode() === 200) {
            return true;
        }
        if ($response->getStatusCode() === 404) {
            return false;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Request rejected', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Activate or deactivate the service.
     *
     * @see https://developer.nexi.it/en/api/post-services
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function toggleService(Entity\ServiceRequest $requestBody): void
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/services');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            return;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Retrieve the information service.
     *
     * @see https://developer.nexi.it/en/api/get-services
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     *
     * @return \MLocati\Nexi\Entity\ServiceRequest|null returns NULL if not found
     */
    public function getService(Entity\GetService\Query $query): ?Entity\ServiceRequest
    {
        $query->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/services', [], $query);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\ServiceRequest($data);
        }
        if ($response->getStatusCode() === 404) {
            return null;
        }
        $this->throwErrorResponse($response, [
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Create custom fields.
     *
     * @see https://developer.nexi.it/en/api/post-custom_fields
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function createCustomField(Entity\CustomFieldDetails $requestBody): Entity\CreateCustomField\Response
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/custom_fields');
        $response = $this->invoke('POST', $url, 3, $requestBody);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\CreateCustomField\Response($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Retrieve custom fields details
     *
     * @see https://developer.nexi.it/en/api/get-custom_fields-customFieldId
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function getCustomField(string $customFieldId): Entity\CustomFieldDetails
    {
        $url = $this->buildUrl('/custom_fields/{customFieldId}', ['customFieldId' => $customFieldId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            $data = $this->decodeJsonToObject($response->getBody());

            return new Entity\CustomFieldDetails($data);
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Retrieval of the terms and conditions with .pdf extension of the structure.
     *
     * @param string $structureConditionId Terms and condition of the structure unique identifier.
     *
     * @see https://developer.nexi.it/en/api/get-structure_conditions-structureConditionId-pdf
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function getStructureTermsAndConditionsPdf(string $structureConditionId): void
    {
        $url = $this->buildUrl('/structure_conditions/{structureConditionId}/pdf', ['structureConditionId' => $structureConditionId]);
        $response = $this->invoke('GET', $url, 3);
        if ($response->getStatusCode() === 200) {
            return;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * Recurring Payment (MIT) on a reservation.
     *
     * @param string $reservationId Reservation identification code.
     * @param string $idempotencyKey an identifier of the request (to be used on subsequent retries); if empty, it will be set as output
     *
     * @see https://developer.nexi.it/en/api/post-reservation-reservationId-mit
     *
     * @throws \MLocati\Nexi\Exception\HttpRequestFailed if the HTTP request could not be made
     * @throws \MLocati\Nexi\Exception\InvalidJson if we couldn't decode the response body as JSON
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Invalid request data (HTTP code: 400)
     * @throws \MLocati\Nexi\Exception\ErrorResponse Unauthorized (HTTP code: 401)
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed Internal Server Error (HTTP code: 500)
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    public function payRecurringReservation(string $reservationId, Entity\PayRecurringReservation\Request $requestBody, string &$idempotencyKey = ''): void
    {
        $requestBody->checkRequiredFields(__FUNCTION__, 'send');
        $url = $this->buildUrl('/reservation/{reservationId}/mit', ['reservationId' => $reservationId]);
        $response = $this->invoke('POST', $url, 7, $requestBody, $idempotencyKey);
        if ($response->getStatusCode() === 200) {
            return;
        }
        $this->throwErrorResponse($response, [
            ['from' => 400, 'to' => 400, 'description' => 'Invalid request data', 'detailed' => true],
            ['from' => 401, 'to' => 401, 'description' => 'Unauthorized'],
            ['from' => 500, 'to' => 500, 'description' => 'Internal Server Error', 'detailed' => true],
        ]);
    }

    /**
     * @throws \MLocati\Nexi\Exception\NoHttpClient
     */
    protected function buildHttpClient(): HttpClient
    {
        if (HttpClient\Curl::isAvailable()) {
            return new HttpClient\Curl();
        }
        if (HttpClient\StreamWrapper::isAvailable()) {
            return new HttpClient\StreamWrapper();
        }
        throw new Exception\NoHttpClient();
    }

    protected function buildCorrelationProvider(): CorrelationProvider
    {
        if (CorrelationProvider\UUID::isAvailable()) {
            return new CorrelationProvider\UUID();
        }

        return new CorrelationProvider\Random();
    }

    protected function buildUrl(string $path, array $pathParams = [], ?QueryEntityInterface $query = null): string
    {
        $matches = null;
        if (preg_match_all('/\\{(?<name>[^\\}]+)\\}/', $path, $matches) !== 0) {
            $names = $matches['name'];
            while ($names !== []) {
                $name = array_shift($names);
                if (!array_key_exists($name, $pathParams)) {
                    throw new \RuntimeException('Missing required URL parameter: ' . $name);
                }
                $path = str_replace('{' . $name . '}', rawurlencode((string) $pathParams[$name]), $path);
                unset($pathParams[$name]);
            }
        }
        if ($pathParams !== []) {
            throw new \RuntimeException("Unexpected URL parameters:\n- " . implode("\n- ", array_keys($pathParams)));
        }
        $url = rtrim($this->configuration->getBaseUrl(), '/') . '/' . ltrim($path, '/');
        $qs = $query === null ? '' : $query->getQuerystring();
        if ($qs !== '') {
            $url .= '?' . $qs;
        }

        return $url;
    }

    /**
     * @param \MLocati\Nexi\Entity|\MLocati\Nexi\Entity[]|null $requestBody
     */
    protected function invoke(string $method, string $url, int $headerFlags, $requestBody = null, string &$idempotencyKey = ''): HttpClient\Response
    {
        if ($requestBody === null) {
            $requestBodyJson = '';
        } else {
            $requestBodyJson = json_encode($requestBody, JSON_UNESCAPED_SLASHES);
            if ($requestBodyJson === false) {
                throw new \RuntimeException('Failed to create the JSON data: ' . (json_last_error_msg() ?: 'unknown reason'));
            }
        }
        $headers = $this->buildHeaders($method, $url, $requestBodyJson, $headerFlags, $idempotencyKey);

        return $this->httpClient->invoke($method, $url, $headers, $requestBodyJson);
    }

    protected function buildHeaders(string $method, string $url, string $requestBody, int $flags, string &$idempotencyKey): array
    {
        $headers = [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ];
        if ($flags & 1) {
            $headers['X-Api-Key'] = $this->configuration->getApiKey();
        }
        if ($flags & 2) {
            $headers['Correlation-Id'] = $this->correlationProvider->getCorrelationID($method, $url, $requestBody);
        }
        if ($flags & 4) {
            if ($idempotencyKey === '') {
                $idempotencyKey = $this->generateIdempotencyKey();
            }
            $headers['Idempotency-Key'] = $idempotencyKey;
        }

        return $headers;
    }

    /**
     * @throws \MLocati\Nexi\Exception\InvalidJson
     */
    protected function decodeJsonToArray(string $json): array
    {
        $data = $this->decodeJson($json);
        if (is_array($data)) {
            return $data;
        }
        throw new Exception\InvalidJson($json, 'The JSON does NOT represent an array');
    }

    /**
     * @throws \MLocati\Nexi\Exception\InvalidJson
     */
    protected function decodeJsonToObject(string $json): stdClass
    {
        $data = $this->decodeJson($json);
        if ($data instanceof stdClass) {
            return $data;
        }

        throw new Exception\InvalidJson($json, 'The JSON does NOT represent an object');
    }

    /**
     * @throws \MLocati\Nexi\Exception\ErrorResponse\Detailed
     * @throws \MLocati\Nexi\Exception\ErrorResponse
     */
    protected function throwErrorResponse(Response $response, array $cases): void
    {
        foreach ($cases as $case) {
            if ($case['from'] <= $response->getStatusCode() && $response->getStatusCode() <= $case['from']) {
                $message = $case['description'];
                if ($message === '') {
                    $message = "Request failed with return code {$response->getStatusCode()}";
                }
                if (empty($case['detailed'])) {
                    throw new Exception\ErrorResponse($response->getStatusCode(), $message);
                }
                $data = $this->decodeJsonToArray($response->getBody());
                $errors = new Entity\Errors($data);

                throw new Exception\ErrorResponse\Detailed($response->getStatusCode(), $message, $errors);
            }
        }

        throw new Exception\ErrorResponse($response->getStatusCode(), "Request failed with return code {$response->getStatusCode()}");
    }

    /**
     * Maximum length: 63 characters
     */
    protected function generateIdempotencyKey(): string
    {
        return bin2hex(random_bytes(31));
    }

    /**
     * @throws \MLocati\Nexi\Exception\InvalidJson
     */
    private function decodeJson(string $json)
    {
        if ($json === 'null') {
            return null;
        }
        $decoded = json_decode($json);
        if ($decoded === null) {
            throw new Exception\InvalidJson($json);
        }

        return $decoded;
    }
}

mlocati / nexi / 8571051831

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous