LABORATORY CONNECTORS

Best Practices / APIs & SDK / Next Steps

8 of 8

Guidance, reference implementations and next steps for building robust, secure and interoperable laboratory integrations with Mediloop.

Production ReadySecure by DesignFHIR FirstInteroperableObservableCompliant

1. Integration approaches

LIS-Orchestrated — recommended

Use the LIS as the single source of truth for laboratory orchestration

Ensure integrity, auditing and regulatory compliance

Best for hospitals, reference laboratories and large facilities

Mediloop / HIS / EHRLISAnalyzer

Direct Analyzer Integration — controlled use

Use only when no LIS interface is available or for POCT / standalone instruments

Manage with Workstation Agent under strict governance

Ensure reconciliation back to LIS/HIS when possible

Mediloop / HISWorkstation AgentAnalyzer

2. Authentication & scopes

OAuth 2.1 / OpenID Connect for application/user context

mTLS for service-to-service communication

Role-based access control

Least-privilege laboratory scopes

lab:orderslab:specimenslab:results:writelab:results:readlab:devices:manage

3. Laboratory APIs — REST & FHIR

Method	Endpoint	Use
POST	/ServiceRequest	Create laboratory order
GET	/ServiceRequest/{id}	Get order details
POST	/Specimen	Create specimen
GET	/Specimen/{id}	Get specimen status
POST	/Observation	Create / update result
GET	/Observation/{id}	Get observation
POST	/DiagnosticReport	Create report
GET	/DiagnosticReport/{id}	Get report
POST	/Task	Acknowledgement / action
GET	/Subscription	Manage event subscriptions

4. End-to-end laboratory flow — developer view

Create ServiceRequest

Send order to LIS / Lab

Order accepted

Receive ACK & order ID

Specimen collected

Barcode registered

Specimen in transit

Track status

Results available

Observation(s) received

Report generated

DiagnosticReport available

Validate & reconcile

Quality & matching

Acknowledge & deliver

Notify clinician / patient

All steps are auditable, traceable and linked to the original order.

5. Webhooks & events

order.accepted

order.updated

specimen.collected

specimen.received

specimen.rejected

result.available

result.amended

report.finalized

critical.result

device.status

ack.received

Webhooks should be secure, signed and retry-enabled.

6. SDK examples

typescriptCopy

import { MediloopSDK } from '@mediloop/sdk';
const sdk = new MediloopSDK({ clientId, clientSecret });

const order = await sdk.labs.orders.create({
  patient: { reference: 'Patient/123' },
  code: { coding: [{ system: 'http://loinc.org', code: '718-7' }] },
  specimen: { type: 'blood', collectionTime: new Date().toISOString() }
});

console.log('Order created:', order.id);

7. Error handling & resiliency

Use standard HTTP status codes and FHIR OperationOutcome

Implement exponential backoff and retry

Use Idempotency-Key for POST operations

Handle partial failures and continue processing

Persist outbound messages until acknowledged

Dead-letter queue for unresolvable messages

Reconcile periodically to detect missing data

Design for eventual consistency with safe retries.

8. Security & compliance

mTLS for server-to-server traffic

TLS 1.3 for communications

Data encryption at rest

Minimum necessary data principle

Audit every access, change and event

PHI/PII pseudonymization where applicable

GDPR / HDS / ISO 15189 aligned controls

Never log or store unnecessary patient data.

9. Monitoring & observability

Connector health and uptime

Message throughput & latency

Error rate & failure reasons

Reconciliation mismatch rate

Queue depth & retry metrics

Device / analyzer status

Custom alerts & dashboards

Use dashboards and alerts to act early.

10. Next steps

Sandbox access

Request sandbox and API credentials

Build & test

Use APIs & SDK

Validate & reconcile

Run reconciliation plan

Prepare for Go Live

Monitor your integration

11. Support & community

Documentation & guides

Developer community

Support channels

Connector integration assistance

Key benefits

Reliable and standards-based integrations

Better data quality and patient safety

Full traceability and auditability

Operational efficiency and automation

Scalable and future-proof architecture