Invoke mappings

Once you create a mapping, you can use it to transform JSON into a custom shape.

​

Inbound - Mappings API

You can use webhooks to automatically send transaction processed events to any API endpoint. Then, you can use the Map Transaction Output endpoint to return the mapped output of the processed inbound transaction.

You can also call the Invoke Mapping API to transform JSON into a custom shape.

​

Outbound - Create Outbound Transaction

Call the Create Outbound Transaction endpoint with a mapping ID. Stedi uses the specified mapping to automatically transform your system’s data into Guide JSON before generating and delivering the EDI file.

​

Payload validation

By default, the Mappings API doesn’t validate incoming or transformed JSON.

When you enable strict validation mode, Mappings uses the source schema to validate the input JSON payload and the target schema to validate the outgoing JSON payload.

To enable strict validation mode, set the validation_mode query parameter to strict. The following example shows how to enable strict validation mode in your request.

POST https://mappings.us.stedi.com/2021-06-01/mappings/01AB3DEF4GHIJ5KL67MNOP8QR9/map?validation_mode=strict HTTP/1.1

Success and failure responses

• If the mapping is evaluated successfully and there are no validation failures, the body of the response is the mapped document.
• If the evaluation of the mapping expression fails, then validation of the input and the output is not applied, the response is a 400 error with the mapping_failed code and no validation_errors object.
• If validation of the input or output payload fails, the response is a 400 error with the validation_failed code and validation_errors object.

​

Example request

The following example shows a request to the Invoke Mapping API. The request body is the JSON document that you want to map.

POST https://mappings.us.stedi.com/2021-06-01/mappings/01AB3DEF4GHIJ5KL67MNOP8QR9/map HTTP/1.1
"Authorization: ${STEDI_API_KEY}"
Content-Type: application/json

{
  "quantity": 15,
  "unit_price": 2.50
}

The body of the response is the mapped document.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "total": 37.50
}

​

Send a compressed payload to the API

To send a gzip compressed payload to the Mappings API, set the Content-Encoding header to the value of gzip. Mappings API currently only supports gzip compression.

Note that the maximum document size limit is applied after decompressing the content of the payload. If the decompressed payload of a given request is larger than the maximum document size limit, the Mappings API will reject the request.

The following is an example written in TypeScript of creating mapping and sending a gzip compressed payload to the /map endpoint.

import axios from 'axios';
import { gzipSync } from 'zlib';

const STEDI_API_KEY = 'YOUR_API_KEY';
const rootURL = 'https://mappings.us.stedi.com/2021-06-01/mappings';
const headers = { Authorization: `Key ${STEDI_API_KEY}` };

async function doRequest() {
  const mapping = {
    name: 'GzipPayloadMapping',
    mapping: `{"Hello": keyFromSource}`,
    type: 'only_mapped_keys',
  };

  const createMappingResponse = await axios.post(rootURL, mapping, { headers });

  const payload = gzipSync(JSON.stringify({ keyFromSource: 'World!' }));
  const mapResponse = await axios.post(
    `${rootURL}/${createMappingResponse.data.id}/map`,
    payload,
    {
      headers: {
        ...headers,
        'Content-Encoding': 'gzip',
      },
    },
  );

  console.log(mapResponse.data);
}

async function main() {
  try {
    await doRequest();
  } catch (e) {
    console.log(e);
  }
}

main();

​

API concurrency

Mappings allows up to 200 concurrent requests, so if you need to map 200 documents or less, you can send them all at once. If you need to map more than 200 documents, you should make sure that you don’t exceed 1000 requests per second. Also keep in mind that there’s a maximum of one million requests per day.

If you make more requests than Mappings is able to handle, you will receive a 429 Too Many Requests response.

• Keep track of how many outstanding requests you have. Don’t send any new requests if you have 200 or more.
• Keep track of how many total requests you’ve sent in a day and make sure it doesn’t exceed 1,000,000.
• Keep a timestamp for every successful response you receive. When sending a new request, first check the timestamp for 1000 requests ago. If it’s less than a second ago, wait until the second has passed before making a new request.
• If you receive a 429 Too Many Requests response, wait for one second before sending new requests. If you still get back 429 after waiting for one second, then wait for two seconds. If that’s not enough wait for four, then eight, etc.
• If you receive a 429 Too Many Requests response, add the document back into the list of documents that you need to map. Don’t resend the request immediately.