`<mvt:call>`#

The <mvt:call> tag in Miva Merchant’s template language enables the execution of system or user-defined functions directly within your templates. It is commonly used to perform HTTP requests (e.g., GET, POST) to external services or APIs, making it an essential tool for integrating external functionality into Miva templates.

With <mvt:call>, you can send requests, process responses, and dynamically manipulate data within your templates.

Parameters#

The <mvt:call> tag accepts various attributes to define the action, method, and parameters for the HTTP request.

Attribute	Description
`ACTION`	Required. Specifies the fully qualified URL to be contacted (e.g., `http://example.com/api`).
`METHOD`	Required. HTTP method: `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, etc. Defaults to `POST` for `XML` or `RAW`.
`CONTENT-TYPE`	Optional. Specifies the content type (`text/xml`, `application/json`, etc.) for `XML` or `RAW` methods.
`FIELDS`	Optional. Comma-delimited list of variable-value pairs sent as data with the request (for `POST` method).
`FILES`	Optional. Specifies file variables for file uploads.
`CERTFILE`	Optional. Specifies a file containing certificates for secure communication.
`CERTTYPE`	Optional. Format of the certificate (`PEM` or `ASN1`).
`CERTPASS`	Optional. Decrypts a certificate with the specified password.
`TIMEOUT`	Optional. Specifies a timeout value, overriding the default `MvCONFIG_CALL_TIMEOUT`.
`HEADERS`	Optional. Custom HTTP headers added to the request.
`PIN-ALGORITHM`	Optional. Specifies a digest algorithm for certificate pinning (`sha256`, `md5`, etc.). Requires Miva Empresa 5.33+.
`PIN-DIGEST`	Optional. The binary fingerprint of the X509 certificate. Requires Miva Empresa 5.33+.

Return Value#

The <mvt:call> function stores the response data in the system variable s.callvalue. This value can be processed, displayed, or saved for later use.

Examples#

Basic GET Request#

Send a GET request to fetch data from an external API.

<mvt:assign name="g.endpoint" value="'https://api.example.com/data'" />

<mvt:call action="g.endpoint" method="'GET'">
    <mvt:assign name="g.response" value="g.response $ s.callvalue" />
</mvt:call>

<p>API Response:</p>
<textarea rows="10" cols="80">
    &mvt:global:response;
</textarea>

POST Request with Data#

Send a POST request with form data to an external API.

<mvt:assign name="g.endpoint" value="'https://api.example.com/submit'" />
<mvt:assign name="g.fields" value="'name=John&email=john@example.com'" />

<mvt:call action="g.endpoint" method="'POST'" fields="g.fields">
    <mvt:assign name="g.response" value="g.response $ s.callvalue" />
</mvt:call>

<p>Response:</p>
<textarea rows="10" cols="80">
    &mvt:global:response;
</textarea>

JSON API Call with Headers#

Make a POST request with JSON data and custom headers.

<mvt:assign name="g.endpoint" value="'https://api.example.com/json'" />
<mvt:assign name="g.headers" value="'Content-Type: application/json'" />
<mvt:assign name="g.json_data" value="'{\"name\": \"John\", \"email\": \"john@example.com\"}'" />

<mvt:call action="g.endpoint" method="'POST'" headers="g.headers" content-type="'application/json'" fields="g.json_data">
    <mvt:assign name="g.response" value="g.response $ s.callvalue" />
</mvt:call>

<p>JSON Response:</p>
<textarea rows="10" cols="80">
    &mvt:global:response;
</textarea>

HMAC-Signed Miva JSON API Call#

Send an HMAC-signed request to the Miva JSON API.

<mvt:comment>
Replace Access token, signature and endpoint
</mvt:comment>
<mvt:assign name="g.endpoint"       value ="'https://version9.mivamerchant.net/mm5/json.mvc'" />
<mvt:assign name="g.access_token"   value ="''" />
<mvt:assign name="g.signature"      value ="crypto_base64_decode('')" />
<mvt:assign name="g.timestamp" value="' \"Miva_Request_Timestamp\" : ' $ '\"' $ s.time_t $ '\",' " />
<mvt:comment>Replace Order Id with the new order you created</mvt:comment>
<mvt:assign name="g.json_data" value="'{' $ g.timestamp $ ' 
        \"Store_Code\": \"beta\",
        \"Function\": \"OrderList_Load_Query\",
        \"Count\": \"1\",
        \"Offset\": \"0\",
        \"Filter\": [
                {
                        \"name\": \"search\",
                        \"value\": [
                                {
                                        \"field\": \"id\",
                                        \"operator\": \"EQ\",
                                        \"value\": \"200001\"
                                }
                        ]
                },
                {
                        \"name\": \"ondemandcolumns\",
                        \"value\": [
                                \"payment_module\",
                                \"cust_pw_email\",
                                \"cust_login\",
                                \"ship_method\",
                                \"customer\",
                                \"items\",
                                \"charges\",
                                \"coupons\",
                                \"discounts\",
                                \"payments\",
                                \"notes\",
                                \"CustomField_Values:customfields:*\",
                                \"payment_data\"
                        ]
                }
        ]
}
'"/>
<mvt:assign name="l.ok" value="crypto_hmac_sha256(g.json_data,g.signature,'binary',g.hmac_response)" />
<mvt:assign name="g.b64encoded_hmac_response" value="crypto_base64_encode(g.hmac_response)" />  
<mvt:assign name="g.headers" value="'X-Miva-API-Authorization: MIVA-HMAC-SHA256 ' $ g.access_token $ ':' $ g.b64encoded_hmac_response $ asciichar( 13 ) $ asciichar( 10 )" />

<mvt:call action="g.endpoint" method="'RAW'" headers="g.headers" content-type="'application/json'" fields="'g.json_data'">
    <mvt:assign name="g.response" value="g.response $ s.callvalue" />
</mvt:call>

Order Load Response: <br>
<textarea rows="20" cols="200">
    &mvt:global:response;
</textarea>

Best Practices#

Use Descriptive Variables:
- Name your variables clearly to ensure readability and maintainability.
Secure Sensitive Data:
- Avoid hardcoding sensitive information (e.g., API keys, secrets) directly in templates. Use secure storage mechanisms where possible.
Handle Timeouts Gracefully:
- Use the TIMEOUT attribute to specify acceptable wait times for requests.
Validate Responses:
- Always validate the response content to avoid issues with unexpected or malformed data.
Leverage Headers and Content-Type:
- Use appropriate headers and content types to match the API requirements.

Summary#

The <mvt:call> tag is a powerful tool for integrating external APIs and functionalities into your Miva templates. By understanding its attributes and leveraging it effectively, you can create dynamic and responsive e-commerce experiences.

Key Takeaways:#

Use <mvt:call> for GET, POST, and other HTTP requests.
Process responses with s.callvalue.
Combine with custom headers, content types, and advanced authentication techniques for secure integrations.

<mvt:call>#