Integration Guidelines

Purpose and Scope

This page describes the integration requirements for a client interface using the SADV API, to ensure safe and effective use.

It is intended for software integrators who design the final user interface (business software, patient portal, web application, or mobile app).

The rules presented here are based on:

  • usability evaluations conducted on representative samples of end users (health professionals and the general public), in situations close to real-world use;
  • the SADV OpenAPI technical specification, which remains the source of truth for JSON schemas.

Mentor Reference App

The Mentor application is the reference implementation of the integration recommendations presented in this guide. It is publicly accessible and can be used to test integration flows, data entry, API calls, and the rendering of recommendations.

Normative Levels

Level Meaning
MUST Mandatory requirement for usability safety and integration compliance.
SHOULD Strong recommendation to improve usability, quality, and adoption.
MAY Optional choice depending on the product context, with no direct impact on critical safety.
Step Description Main endpoint
1. Collect minimum data Enter date of birth and sex, then prepare the entry context. POST /questionnaire (filtered profile) or GET /questionnaire (full profile)
2. Enter the health profile Display the section tree and collect typed conditions. POST /questionnaire
3. Build the patient record Assemble the patient payload with the required and optional fields. POST /diagnostic_for_patient
4. Render the diagnosis Present the conclusions, dates, messages, and reference documents. POST /diagnostic_for_patient

Non-Backward-Compatible Updates

When a new SADV version is not backward compatible, it is made available in the integration environment during a notice period.

Concretely:

  1. Syadem makes the version available in the integration environment.
  2. Syadem updates the integration documentation corresponding to that version and sends it to clients.
  3. The integrator validates their implementation in the integration environment during the notice period.
  4. The version is opened in production after the notice period expires, if the validations are compliant.

MUST Requirements - Collection and Entry

ID Requirement Justification
MUST-01 The interface must collect patient > birthdate and patient > gender before any diagnostic call. Required fields in the OpenAPI schema.
MUST-02 The interface must enforce a precise date format and validate the date before sending it. Reduces critical input errors.
MUST-03 The interface must display an anti-error mechanism between date of birth and age (visible dynamic calculation). Reduces critical input errors.
MUST-04 The health profile must be entered through the tree structure returned by /questionnaire and support the boolean, integer, date, and float types. API contract alignment and omission reduction.
MUST-05 The health profile must include a condition search function. Measure validated as effective in summative testing.
MUST-06 Each patient > prevention_acts item must contain date, prevention_method_id, and booster (explicit boolean). booster is required in vaccination act objects.

MUST Requirements - API Calls and Robustness

ID Requirement Justification
MUST-07 The interface must validate JSON completeness before POST /diagnostic_for_patient. Avoids blocking errors and diagnostic inconsistencies.
MUST-08 The interface must handle 400 responses in a comprehensible way by exposing error > code and an actionable detail. Allows the user to correct the data.
MUST-09 Before establishing HTTPS communication, the client interface must verify the server TLS certificate (trust chain, validity period, domain name matching). If verification fails, the connection must be rejected and the request must not be sent. See the Authentication page. Reduces the risk of compromising confidentiality and integrity of exchanges.

MUST Requirements - Clinical Rendering

ID Requirement Justification
MUST-10 The rendering must display for each disease advice > conclusion, targeted_date, limit_date, messages, and documents. Required fields in the detailed diagnosis.
MUST-11 The interface must visually distinguish critical situations (for example: contraindicated and alert) and display a summary of the entered data before the final decision. Reduces the risk of dangerous misinterpretation.
MUST-12 Technical conclusion enums must be translated into labels understandable by the end user. Avoids clinical ambiguity.
MUST-13 The professional workflow must explicitly remind users that the final prescribing responsibility remains with the health professional. Documented usability safety requirement.
MUST-14 The interface must display the knowledge base versions from knowledge_base_references (recommendation_rules, nuva_vaccine_nomenclature, condition_nomenclature) in the recommendation rendering. Ensures traceability of the recommendations and data used.

SHOULD Recommendations - Usability and Adoption

ID Recommendation Benefit
SHOULD-01 Collect patient > area_of_residency > zipcode when the information is available. More refined recommendations based on the area of residence.
SHOULD-02 Collect patient > birthplace > countrycode when the information is known. Contextual refinement of recommendations.
SHOULD-03 Support the patient > journey field for interfaces covering traveler vaccination. Covers broader use cases.
SHOULD-04 Offer vaccine search by name and target disease, with generic options. Reduces historical entry friction.
SHOULD-05 Add a Previous button and navigation breadcrumbs. Reduces navigation and flow errors.
SHOULD-06 Allow printing or exporting the diagnosis for professional use. Makes patient record integration easier.
SHOULD-07 Adapt wording according to public_destination (general, patient, professional). Improves comprehension depending on the audience.
SHOULD-08 Display knowledge_base_references > description when the field is available, according to the interface language with an explicit fallback. Improves understanding of displayed versions without blocking the flow if the description is missing.

Error Handling and Edge Cases

Validation Errors

  • In case of 400, display a clear message about invalid fields and offer immediate correction.
  • Always log error > code on the technical side for support.

Null or Missing Values

  • targeted_date and limit_date may be null and must not block the display of the rest of the recommendation.
  • When an optional patient field is unknown (birthplace, area_of_residency, journey), the interface must remain functional with only the required data.

Non-Standard Cases

  • Conclusions exception, unmanaged, or complete_scheme must be rendered explicitly with an unambiguous label.
  • alert-type messages must be visually prioritized over informative messages.

OpenAPI <-> Interface Mapping Tables

Patient Input (Requests)

JSON field OpenAPI type Required Level Expected UI validation
patient > birthdate string (date) Yes MUST Format appropriate to the user’s context, real date, no empty value.
patient > gender string (m or f) Yes MUST Explicit selector, no implicit value.
patient > prevention_acts[] > date string No MUST if act entered Controlled date, temporal consistency.
patient > prevention_acts[] > prevention_method_id string or integer No MUST if act entered Valid NUVA/prevention-act identifier.
patient > prevention_acts[] > booster boolean No MUST if act entered Always send true or false.
patient > conditions[] > id string No MUST if condition entered Identifier present in the loaded questionnaire.
patient > conditions[] > value typed according to condition No MUST if condition entered Compatible type (boolean, integer, date, float).
requested_by_professional boolean No SHOULD Explicitly indicate the professional/general-public usage context.

Diagnostic Output (Response)

JSON field OpenAPI type Display priority Interface rule
conclusion enum High Display a comprehensible global status at the beginning.
diagnostic_per_disease[] array High Present a card or section per disease.
diagnostic_per_disease[] > disease > name string High Display the target disease name in the section header.
diagnostic_per_disease[] > advice > conclusion enum High Display a local status with explicit color coding.
diagnostic_per_disease[] > advice > targeted_date date or null Medium Display only if non-null.
diagnostic_per_disease[] > advice > limit_date date or null Medium Display only if non-null.
diagnostic_per_disease[] > advice > messages[] array High Sort by criticality (alert first).
diagnostic_per_disease[] > advice > documents[] array Medium Display the available official references.
knowledge_base_references > recommendation_rules > version_id string High Display the ruleset version in the recommendation rendering.
knowledge_base_references > nuva_vaccine_nomenclature > version_id string High Display the NUVA nomenclature version in the recommendation rendering.
knowledge_base_references > condition_nomenclature > version_id string High Display the condition nomenclature version in the recommendation rendering.

Integrator Compliance Checklist

  • The interface collects and validates birthdate and gender before the diagnostic.
  • The date format is controlled and an age/date anti-error mechanism is visible.
  • Health profile entry is based on the /questionnaire tree.
  • Condition search is available in the health profile.
  • Vaccination acts always include date, prevention_method_id, and booster.
  • The payload is validated before POST /diagnostic_for_patient.
  • 400 errors are understandable and actionable.
  • The client verifies the TLS certificate before any HTTPS communication and rejects the connection on failure.
  • The rendering shows the conclusion, dates, messages, documents, and data that influenced the decision.
  • The recommendation rendering displays the knowledge base versions.
  • Critical messages and contraindications are visually prioritized.
  • Technical enums are translated into understandable business labels.
  • The professional workflow reminds users of the final prescribing responsibility.

References

Next Step

Move on to a complete API call example, from assembling the patient record to interpreting the diagnosis.