# Overview

Tediware handles EDI translation and delivery between your system and your trading partners. You configure partners, connections, and document types in the Tediware application. Your system then uses the Platform API and webhooks to exchange data: submitting documents for translation, receiving notifications when processing completes, and retrieving the results.

This page explains how the pieces fit together before you dive into the individual endpoints.

## How It Works

Tediware sits between your system and your trading partners. EDI documents flow in two directions:

- **Inbound**: a trading partner sends EDI to you. Tediware receives it, translates it to JSON, and notifies your system. Your system then fetches the translated JSON through the API.
- **Outbound**: your system sends JSON data to Tediware. Tediware translates it to EDI and delivers it to the trading partner's connection (SFTP, AS2, etc.). Your system is notified of the outcome.

In both directions, the pattern is the same: Tediware handles translation and delivery, and your system interacts through a combination of API calls and notifications about processing outcomes.

**Choosing how you receive results.** Tediware offers two ways to learn that a document is ready, and you pick per partner:

- **[Webhooks](/resources/api-docs/webhooks) (recommended)**: Tediware pushes a lightweight notification to an HTTPS endpoint you host the moment processing completes. Event-driven and signed. Choose this when your system can accept inbound HTTP requests.
- **Polling**: Tediware writes every outcome to a feed, and your system pulls from it on its own schedule with no endpoint to host. Choose this when your platform is firewalled or can only fetch. See the [Polling page](/resources/api-docs/polling).

Both deliver the same outcomes and carry only identifiers (`resultId`, `traceGuid`), never document content: your system pulls the full data through the Results and Artifacts API either way. A partner is set to one method or the other on its **Configuration** card.

## Receiving EDI from Partners

Tediware receives EDI from your trading partners automatically. In most integrations, your partner delivers EDI via SFTP or AS2, and Tediware picks it up without any action from your system. SFTP connections are polled on a configurable schedule; AS2 deliveries are processed as they arrive. Your system's role begins when the document is processed: Tediware fires your inbound webhook, or, for a poll-based partner, the entry appears in the feed on your next poll.

For cases where your system receives EDI directly (e.g., from a vendor portal, email, or another protocol), Tediware also provides an API endpoint to push EDI in for processing. See the Inbound EDI page for details on this endpoint.

Regardless of how EDI arrives, the processing sequence is the same:

1. Tediware parses the EDI, extracts individual transaction sets, and converts each one to JSON
2. Tediware notifies your system with a `resultId` and `traceGuid`, either by calling your **inbound webhook** or, for a poll-based partner, by adding the entry to the feed
3. Your system calls `GET /platform/results/:id` using the `resultId` from the webhook payload or the feed entry
4. The result contains an `artifacts` array: the artifact with `"usage": "output"` is the translated JSON
5. Your system calls `GET /platform/artifacts/:id` to download the JSON content
6. Your system processes the JSON data, creating orders, updating records, routing to internal systems, or whatever your business logic requires

From your system's perspective, the entry point is the notification that a document has been processed: a webhook call if the partner uses webhooks, or the next poll of the feed if it is poll-based. Either way, your system then pulls the data it needs through the Results and Artifacts API.

## Sending EDI to Partners

When your system needs to send an EDI document to a trading partner, it submits JSON data to Tediware. Tediware applies your mapping, generates the EDI, and delivers it.

The full sequence:

1. Your system calls `POST /platform/partners/:key/ts/:code` with the transaction data as JSON
2. The API returns immediately with a `traceGuid` and the control numbers assigned to the interchange
3. Tediware applies your mapping and implementation to convert the JSON to EDI, then delivers the EDI file to the partner's connection
4. If delivery succeeds, Tediware notifies you with a `resultId`, via your **outbound webhook** or the feed for a poll-based partner. You can fetch the result to get the generated EDI content and confirm the control numbers.
5. If processing fails at any step, the outcome is an error instead, delivered to your **error webhook** or as an error entry in the feed. The result's `errorMessage` field describes what went wrong.

The `traceGuid` returned by the API links all results from this processing run. You can store it to correlate the initial submission with the notifications that follow.

## Designing Your Integration

A typical integration has three parts: an API client for submitting data and fetching results, a way to receive notifications (webhook endpoints, or a poller that reads the feed), and background processing to handle the data.

### Receiving Notifications

If your partners use webhooks, set up HTTP endpoints to receive them. If they are poll-based, you skip the endpoints and run a poller against the feed instead; see the Polling page for that loop. The subsection below covers the webhook endpoints.

Set up three HTTP endpoints in your application, one for each webhook type:

- **Inbound results**: called when EDI from a partner is processed. This is where most of your integration logic lives: fetching the result, downloading the JSON artifact, and processing the translated data.
- **Outbound deliveries**: called when EDI you submitted is successfully delivered. Use this to confirm delivery, record control numbers, or update internal status.
- **Errors**: called when processing fails in either direction. Use this to log errors, alert your team, or trigger retry logic.

Your webhook endpoints should accept the request and return a `200` response immediately. Perform any processing (fetching results, downloading artifacts, updating your database) asynchronously in a background job. Tediware expects a response within 10 seconds.

### Verifying Webhook Authenticity

Every webhook delivery includes an `X-Webhook-Signature` header that you should verify to confirm the request came from Tediware. The Webhooks page covers the verification process in detail.

### Working with Results and Artifacts

When you receive a notification (a webhook call or a feed entry), it includes a `resultId`. Use it to fetch the result, which contains metadata and references to artifacts. The artifacts are the actual files: download the one with `"usage": "output"` to get the translated content (JSON for inbound documents, EDI for outbound documents).

The Results & Artifacts page covers the API details for fetching results and downloading artifacts.

### Storing the Trace

Every processing run produces a `traceGuid` that links all related results together. Store this value in your system alongside the records you create from the processed data. It is useful for debugging: you can look up the trace in the Tediware UI to see every processing step, or query `GET /platform/results?trace=...` to retrieve all results programmatically.

### Multi-Step Flows

Many EDI workflows involve receiving a document from a partner and sending a response back. Tediware handles each direction through its own flow, and your system ties them together with your business logic.

**Example: Responding to a Load Tender**

1. Your carrier partner sends a 204 (Motor Carrier Load Tender) via SFTP or AS2
2. Tediware processes it and fires your inbound webhook
3. Your system fetches the translated JSON, reviews the load details, and decides to accept
4. Your system submits a 990 (Response to Load Tender) via `POST /platform/partners/PARTNER_KEY/ts/990` with the acceptance data
5. Tediware translates it to EDI and delivers it to the partner. Your outbound webhook confirms delivery.

The inbound and outbound steps are independent API operations with separate traces. Your system provides the business logic in between, deciding whether to accept, reject, or counter the tender. Correlate the inbound and outbound traces in your own system if you need to link the original document with the response.

## What You Need Before Starting

Before your system can exchange data through the API, the following must be configured in Tediware:

- **A partner** with a connection, internal and external envelopes, and at least one transaction setting for the direction you need (inbound, outbound, or both)
- **Active flows** built for the partner: these are the processing pipelines that handle translation and delivery
- **A delivery method** for the partner: either **Webhooks** created and assigned (at minimum an inbound webhook, ideally outbound and error too), or **Polling**, in which case no webhooks are needed and you read the feed
- **An API key** for your organization: used to authenticate all API requests (and to read the feed when polling)