Docs / Application Integration

Use ModernEDI from your application's language

Official TypeScript, Python, and .NET clients cover the same Integration API: retrieve mapped documents, send replies through your outgoing maps, inspect transactions, and optionally automate configuration or scenario runs. Choose the language your server already uses.

Jump to TypeScript / JavaScript, Python, .NET / C#, or configuration automation.

Create a key for your server

In your workspace's Integration API keys section, give the key a recognizable label, select its Allowed API access, and choose Create integration API key. Copy the one-time value directly into your server's secret store. The examples below need only configuration:read; they read the workspace identity without applying configuration or sending EDI.

Make the secret available to your process as MODERNEDI_API_KEY. Never commit it, print it, or embed it in browser JavaScript, mobile apps, or distributed desktop clients. A browser application should call your own backend, which holds the key. A Git-provider token and a signed-in ModernEDI browser session are not Integration API keys.

These clients default to https://api.modernedi.com. Select additional permissions only for the operations your application needs; configuration, scenario operations, and document sending have separate scopes. Choosing Test traffic does not make a key Test-only.

TypeScript / JavaScript

@modernedi/sdk on npm · Node.js 20 or newer · ECMAScript modules (import).

npm install @modernedi/sdk

import { ModernEdiClient } from "@modernedi/sdk";

const apiKey = process.env.MODERNEDI_API_KEY;
if (!apiKey) throw new Error("Set MODERNEDI_API_KEY.");
const client = new ModernEdiClient({ apiKey });
const context = await client.configurationAsCode.getIntegrationConfigurationContext({});
console.log("Workspace ID:", context.workspace.id);

Ordinary methods return parsed data. Use their *Raw() counterparts when you need response headers or exact bytes. Read the TypeScript SDK guide, examples, and source.

Python

modernedi-sdk on PyPI · Python 3.10 or newer · Synchronous and native asynchronous clients.

Preview 0.2.1: the Python client API may evolve before 1.0. Pin the version you test with your application.

python -m pip install modernedi-sdk==0.2.1

import os
from modernedi import ModernEdiClient

with ModernEdiClient(api_key=os.environ["MODERNEDI_API_KEY"]) as client:
    response = client.configuration_as_code.get_integration_configuration_context()
    print("Support request ID:", response.request_id)

The package is named modernedi-sdk; the Python import is modernedi. Calls return an ApiResponse with parsed data, headers, and exact raw_body bytes. For async code, use AsyncModernEdiClient with async with and await. Read the Python SDK guide, examples, and source.

.NET / C#

ModernEdi on NuGet · .NET 8 or newer · Asynchronous methods with cancellation support.

Preview 0.2.1: the .NET client API may evolve before 1.0. Pin the version you test with your application.

dotnet add package ModernEdi --version 0.2.1

using ModernEdi;

using var client = new ModernEdiClient(
    apiKey: Environment.GetEnvironmentVariable("MODERNEDI_API_KEY")
        ?? throw new InvalidOperationException("Set MODERNEDI_API_KEY."));
var response = await client.ConfigurationAsCode.GetIntegrationConfigurationContextAsync();
Console.WriteLine($"Support request ID: {response.RequestId}");

Calls return an ApiResponse<T> with parsed Data, headers, and exact RawBody bytes. Reuse a client rather than creating one per request. Read the .NET SDK guide, examples, and source.

Make the next call deliberately

Use ordinary cursor pagination for read-only lists. The mapped-output queue is different: polling acquires temporary leases, cursors can repeat, and empty scan pages can still have more results. The SDKs provide bounded queue iterators (iterateMappedOutputs, iterate_mapped_outputs/iterate_mapped_outputs_async, and Pagination.MappedOutputsAsync). Save and deduplicate each output before acknowledging its latest receipt handle. The helpers do not acknowledge for you or automatically retry a failed poll; after a lost response, unacknowledged leases expire so the outputs can be collected again.

For conditional configuration exports, pass the previous ETag. An unchanged snapshot returns 304 Not Modified with no data, not an error. Single-output acknowledgment responses contain their identity and timestamp under acknowledgment, alongside success and environment.

The API reference defines each operation's permissions, request fields, and errors. The SDK guides explain typed models, pagination, retries, and webhook verification. Keep request IDs for support, but do not log credentials or raw partner documents. Retain original response bytes when verifying evidence hashes rather than hashing reserialized JSON.

Configuration apply and scenario operations retain the API's review, idempotency, and concurrency checks. An SDK does not bypass them or automatically deploy a mapping. See scenario automation when your application needs conversation-level evidence.

Optional: reviewed configuration in CI

The configuration runner is a separate Node.js tool for plan, optional saved-case verify, apply-reviewed, and wait. It works with any CI provider or a reviewed local workflow; you do not need to write your own apply orchestration using an SDK.

The public configuration-example template connects partner and AS2 files, public certificates, incoming and outgoing maps, optional scenarios, and GitHub Actions. Its synthetic sample is for learning, not a configuration to apply over an existing workspace. Start a private copy from your workspace's complete export and review every change. Never put workspace exports, plans, or credentials in the public template.

Live apply is off by default. The hosted workflow requires protected branches and a required-reviewer environment in your private repository; check your GitHub plan supports those protections before enabling it. If it does not, keep apply local and explicitly reviewed rather than removing the approval gate. Follow the configuration workflow guide, and choose one owner for applying a branch so automatic Git imports and CI do not race.