mbrindam/stedi-sim repository overview

⁠stedi-sim

A lightweight simulator of the Stedi Healthcare Clearinghouse API for local EDI development and testing.

Drop it into any EHR dev environment that submits 837 claims through Stedi. No Stedi account, API keys, or network access required. Runs entirely in Docker — no configuration needed to get started.

⁠Quick start

docker run -d \
  --name stedi-sim \
  -p 3005:3005 \
  -e WEBHOOK_CALLBACK_URL=http://host.docker.internal:3000/webhooks/stedi \
  mbrindam/stedi-sim

• Dashboard: http://localhost:3005/dashboard⁠
• API base: http://localhost:3005/change/medicalnetwork/⁠...

Or with Docker Compose:

services:
  stedi-sim:
    image: mbrindam/stedi-sim
    container_name: stedi_sim
    ports:
      - "3005:3005"
    environment:
      - WEBHOOK_CALLBACK_URL=http://your-backend:3000/webhooks/stedi
    restart: unless-stopped

Point your EHR backend at the simulator:

STEDI_API_URL=http://localhost:3005

⁠Embedding alongside your backend

If both services are in the same Compose network, use the container name as the hostname and omit the external port mapping:

services:
  stedi-sim:
    image: mbrindam/stedi-sim
    container_name: stedi_sim
    environment:
      - WEBHOOK_CALLBACK_URL=http://your-backend:3000/webhooks/stedi
    networks:
      - your_network

  your-backend:
    environment:
      - STEDI_API_URL=http://stedi-sim:3005
    networks:
      - your_network

⁠What it does

• Accepts 837P and 837I claim submissions and returns a synchronous SUCCESS response
• Schedules async payer adjudication: fires a 277CA claim acknowledgment then an 835 ERA remittance to your configured webhook URL
• Answers real-time eligibility (270/271) requests
• Answers synchronous claim status (276/277) requests
• Serves generated 835 and 277CA reports by transaction ID
• Serves a real-time monitoring dashboard at /dashboard

⁠Environment variables

⁠API endpoints

All paths mirror the Stedi Change Healthcare Medical Network API.

⁠Payer scenario engine

Set tradingPartnerServiceId in your claim request to trigger a specific adjudication outcome. All scenarios are deterministic — no random failures.

After the configured delay, the simulator:

1. Builds a 277CA acknowledgment and fires a transaction.processed.v2 webhook (transactionSetIdentifier: "277")
2. 200ms later builds an 835 ERA and fires a second webhook (transactionSetIdentifier: "835")

Retrieve the full report using the transactionId from the webhook payload:

GET /change/medicalnetwork/reports/835/{transactionId}
GET /change/medicalnetwork/reports/277/{transactionId}

⁠Eligibility scenarios

⁠Webhook payload format

{
  "version": "0",
  "id": "uuid",
  "detail-type": "transaction.processed.v2",
  "source": "stedi.core",
  "account": "sim",
  "time": "2024-03-15T12:00:00.000Z",
  "region": "us-east-1",
  "resources": [],
  "detail": {
    "x12": { "transactionSetIdentifier": "835" },
    "transactionId": "uuid"
  }
}

Headers on delivery:

Content-Type: application/json
X-Stedi-Signature: sim

⁠Dashboard

The dashboard at /dashboard auto-refreshes every 5 seconds and shows:

• Stats — claims received, 277CA acks sent, 835 ERAs sent, claims paid
• Claims table — payer, billed amount, outcome (approved / denied / partial), delay, correlation ID
• 277CA table — acknowledgment status codes and descriptions
• 835 ERA table — check number, total paid, claim status

⁠Platforms

linux/amd64 and linux/arm64 (Apple Silicon compatible).

⁠Source

https://github.com/mbrindam/stedi-sim⁠