This functionality is available in a Stedi module.

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

Inbound - Destination webhooks

Destination webhooks allow you to send data and events from Stedi to any external API. The most common use case is sending processed transaction data to your internal systems and business applications.

When you attach a mapping to a Destination webhook, Stedi automatically invokes the mapping when the webhook is triggered. This approach allows you to automatically transform processed transaction data to a custom JSON shape before sending it to your business system. Visit Configure Destination webhooks for complete details.

Outbound - Invoke Mapping API

You can use the Invoke Mapping API to transform transaction data from your business systems into Guide JSON format. Then, you can use the Guide JSON to create a request for the Generate EDI API.

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
}

You must make a separate request to the API for each JSON document. Visit Concurrency for more details.

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.

Was this page helpful?