24/7 Support: 800.608.6482

Get Started

Navigation


Getting Started Guide - Miva JSON API

  1. API Endpoints
  2. Authentication & Permissions
  3. Group & Function Permissions
  4. JSON Request Format
  5. JSON Response & Error Handling
  6. Throttling & Timeouts
  7. Client Side Requests
  8. Working With Dates & Times
  9. Troubleshooting Authentication Issues

Overview

The Miva JSON API allows any external system to both push data to Miva and pull data from Miva. The JSON API is the same underlying functions as the Miva admin to push and pull data via JavaScript. Any external system that needs to get or push data back to Miva should use the JSON API.

Requirements

To use the Miva JSON API you must be using Miva 9.12.00 or greater as well as the 5.32 engine or greater.

API Endpoints

Every store has its own unique API endpoint associated with the domain name. The format will be as follow:

https://www.domain.com/mm5/json.mvc

Note: Some stores use an alternate folder name other than "/mm5" such as "Merchant2" or "/store/". You can see what folder structure is being used under Domain Settings > Site Configuration.

Authentication & Permissions

Access to the API is determined by an API Access Token. This token is generated in the Miva admin under Users > API Tokens

Within the access token setting, there are 3 additional levels of security:

  • IP Address Whitelist
  • HMAC Signature
  • Timestamp

IP Address Whitelist

Each access token is restricted to a list of IP addresses you want to have access to make API calls. It accepts a comma separated list of IPs. If you don’t have static IP addresses or don’t want to use this feature (less secure), you can disable it by using 0.0.0.0/0 which will allow any IP address.

HMAC Signature

This is an optional but strongly recommended feature to prevent man in the middle attacks on API requests. Miva will generate a Private Key which you then use to generate an HMAC using the message body using and either SHA256 or SHA1 as the encryption algorithm. This signature then gets passed in the header of the request with the name of "X-Miva-API-Authorization".

Header Format: X-Miva-API-Authorization: type <access token>[:<hmac>]

There are 3 type options:

  • MIVA-HMAC-SHA256
  • MIVA-HMAC-SHA1
  • MIVA (no hmac present)

3 steps to generate HMAC header

  1. base64 decode private key
  2. pass base 64 decoded private key, algorithm type (sha1 or sha256) and JSON request body into your languages hmac funciton as seperate parameters.
  3. base64 encode result of hmac function and pass in header of each request

PHP Example Function to generate header using private key

API Access Token Header

API Access Token Header with No HMAC signature

API Access Token Header with SHA256 signature

API Access Token Header with SHA1 signature

Base64 Encoding: Its very important that once the HMAC is generated it needs to be base64 encoded before being passed in the header. Also the Private Key needs to be base64 decoded before it gets passed into the HMAC function.

Timestamp

This is optional but a highly recommended security feature to help prevent a replay attack against an API request. When enabled each API request has a max window of execution of 30 seconds from the timestamp passed in the body of the request. To use this feature pass the following parameter in the JSON body:

"Miva_Request_Timestamp" : "1535646272",

The value passed should be a unix timestamp of the time the request was initiated. Miva will then give a 30 second window for that request to be received.

While both the timstamp and HMAC signature are optional if you have an integration you want to be listed in the app store, both will be required.

Group & Function Permissions

In addition to being used for authenticaiton, each access token also has Group and Function Level permissions. These permissions will determine which API functions they are allowed to run.

Group Permissions

Group permissions allow an access token to inherit the permissions assigned to each individual group. These are the same group permissions used to give to Miva Administrator users. To assign group permissions to an access token, select the record from the batch list and a Groups button will display.

Function Permissions

You can also explicity tie an access token to one or more functions. The full list of API available functions can be in the left menu. Here you enter whether it is a domain level funciton or a store level function and then the function name. You can use Groups and Functions in conjunction with each other to get the correct permissions you need.

JSON Request Format

The Miva JSON API is accepts data in JSON format passed in the body of the request. The data sent will be determined by the funciton you wish to run and whether you are pushing or pulling data. Please see each functions specific definition on which json data is needed.

Required JSON Data with Each Request

  1. Miva_Request_Timestamp - (optional but recommended) The unix timestamp from when the request was generated. Miva will only run a request in a 30 second window from this time.
  2. Store_Code - The Miva store code of the store you wish to execute the function against.
  3. Function - The function to execute

Then depending on the function you're running, it will have its own required json you must pass to get the correct data out or to push the correct data in. See the API Function Reference Guide for details on all available functions.

JSON Response & Error Handling

All response to the JSON API whether it was successful or an error is returned will be formatted valid JSON.

Success Response

Successful calls return their data as a JSON structure in the following format:

Some success response will contain additional data as well. For example when OrderItem_Update the success response looks like this:

Error Responses

Errors are returned in the following format:.

Required Fields Validation Error

Some errors will include additional fields with further information about input validation errors:

Example:

Throttling and Timeouts

API Throttling

There is no throttling we enforce on API requests. To the server it will appear just like any other http request. Miva will process the request and then return the results back to the client. This does mean that the burden is placed on the developer doing any integration to prevent API requests inadvertently causing a Denial Of Service attack because a client made too many API requests.

API Timeouts

The API uses the same timeouts defined the the Miva’s stores mivavm.conf file. These are the global timeouts used across any Miva page for each site. If you need adjust timeouts, it would need to be adjusted for the entire site, not just the API requests. Default timeout in most Miva stores is 60 seconds.

Logging

API requests are not logged separately against regular requests. The server's access logs can be used to help troubleshoot any API related issues.

Client Side Requests

The JSON API is not able to be used in untrusted client requests via JavaScript/AJAX. This is because doing so will expose your API credentials in the header of each request. There are special API functions intended to be called clientside without an API key needed. Specifics on these coming soon.

Dates & Times

All date/time fields in the API will return Unix timestamps. You'll need convert the unix time to the proper date format depending on your needs.

Troubleshooting Authentication Issues

The following error responses are around Authentication and Permissions. Its important to note that if you do not pass the Miva "X-Miva-API-Authorization" header or its name is incorrect, no response will be given.

Access Denied

An access denied error could be for any of the following reasons:

  1. Invalid Access Token
  2. Missing Header Type or Type mismatch

Access Denied - Invlaid Request Signature

This means that you passed a header type where miva is expecting a request signature but you are not sending one or it is incorrect.

Access Denied - Missing required timestamp

This means that your Access Token is configured to require a timestamp in the JSON body but you are not passing one.

Access Denied - Timestamp outside Configured Window

This means that your Access Token is configured to require a timestamp in the JSON body but you are not passing one.

This website uses cookies to identify visitors, track visitors to our website, store login session information and to remember your user preferences. By continuing to use this site you agree to our use of cookies. Learn More.

This website uses cookies. By continuing to use this site you agree to our use of cookies. Learn More.

Accept

Miva believes that all online businesses should have access to a scalable ecommerce platform that can meet their unique business requirements. Miva offers PCI compliant ecommerce, hosting, and custom website design and development solutions. Miva customers have processed over $100 billion in online sales since 1997.

Copyright © 2016 Miva, Inc - All Rights Reserved   Privacy Policy | Store Policy

Links
Contact Us
Receive Tips & Updates

Copyright © 2017 Miva, Inc - All Rights Reserved

Back To The Top