Connecting the laboratory system to Neolung

1. Address and key
The engine calls Neolung over HTTPS, outbound from the trust: no port or VPN to open. Each request carries the organisation's key, which an admin creates in Neolung, in its Authorization header.

Address and header:
https://app.neolung.io/api/integration/v1/fhir
Authorization: Bearer <key>

2. Test the connection
Neolung answers 200 when the key works. The admin sees the check in Neolung, in Settings, Integration.

Request:
curl -H "Authorization: Bearer <key>" 'https://app.neolung.io/api/integration/v1/check'

3. Send each new specimen
A ServiceRequest with its Specimens, as application/fhir+json: in a transaction or batch Bundle POSTed to the base, answered 200 with a response for each entry; or alone to /ServiceRequest, answered 201 with an OperationOutcome. The lab number is the Specimen's accessionIdentifier. A refusal says why in words.

Request:
curl -X POST -H "Authorization: Bearer <key>" -H "Content-Type: application/fhir+json" --data-binary @specimen.json 'https://app.neolung.io/api/integration/v1/fhir'

specimen.json:
{
  "resourceType": "Bundle",
  "type": "transaction",
  "meta": {
    "security": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "HTEST"
      }
    ]
  },
  "entry": [
    {
      "fullUrl": "urn:uuid:5f0d1f1e-0000-4000-8000-000000000001",
      "resource": {
        "resourceType": "Specimen",
        "accessionIdentifier": {
          "value": "ZZ26-00001"
        },
        "type": {
          "text": "Right upper lobectomy"
        }
      },
      "request": {
        "method": "POST",
        "url": "Specimen"
      }
    },
    {
      "resource": {
        "resourceType": "ServiceRequest",
        "status": "active",
        "intent": "order",
        "specimen": [
          {
            "reference": "urn:uuid:5f0d1f1e-0000-4000-8000-000000000001"
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "ServiceRequest"
      }
    }
  ]
}

4. Collect each signed report
Every minute, GET the DiagnosticReports waiting (UK Core, oldest first). File each, then acknowledge it: outcome filed, or refused when the laboratory system couldn't file it. The same reports come until acknowledged.

Request:
curl -H "Authorization: Bearer <key>" 'https://app.neolung.io/api/integration/v1/fhir/DiagnosticReport?_count=20'

Acknowledgement:
curl -X POST -H "Authorization: Bearer <key>" -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Parameters","parameter":[{"name":"outcome","valueCode":"filed"}]}' \
  'https://app.neolung.io/api/integration/v1/fhir/DiagnosticReport/<id>/$acknowledge'

5. Test messages first
Until the organisation is approved for patient data in Neolung, mark each request as test (the HTEST security label): Neolung refuses production ones.

6. What Neolung reads
Only the lab number, the specimen types and the requester's and site's codes. Neolung never reads the patient, clinical details or notes, and never keeps them.