specs.yaml

openapi: 3.0.0

info:
  title: Adapter - Kontaktdaten Erfassungs Apps (Provider) zu Gesundheitsbehörden 
  description: Gesundheitsbehörden digital (tm)
  version: 0.0.1
security:
  - ApiKeyAuth: []
      
servers:
  - url: https://api.darfichrein.de
    description: Production URL
  - url: https://dev-api.darfichrein.de
    description: Staging URL

tags: 
  - name: Search for location
    description: Standortsuche
  - name: Request contact data
    description: Kontaktdaten Anfrage
  - name: Provide download url
    description: Bereitstellung Download URL
  - name: Download tracing data
    description: Kontaktdaten Download

paths:
  /{search_location_endpoint}/{search}:
    get:
      tags:
        - Search for location
      security:
        - ApiKeyAuth: [ ]
      operationId: findCompanyByStartingValue
      summary: Lookup for company or locations matching search param.      
      description: Dieser Endpunkt wird vom Provider implementiert. Den finalen Pfad kann der Provider bestimmen.
      parameters:
        - in: path
          description: URL encoded String
          name: search
          schema:
            type: string
            minimum: 4
          required: true
        - in: path
          description: Endpoint wie vom Provider konfiguriert
          name: search_location_endpoint
          schema:
            type: string
          required: true

      responses:
        '500':
          description: Error at Provider
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LocationInformation'
          description: Companies matching the keyword. In case there are no results an empty array is returned. 
        '401':
          description: Unauthorized - API Key not set or invalid

  
  /{request_contact_data_endpoint}:
    post:
      description: Dieser Endpunkt wird vom Provider implementiert. Den finalen Pfad kann der Provider bestimmen.
      tags:
        - Request contact data
      security:
        - ApiKeyAuth: [ ]
      operationId: createNewTicketForTracingCase
      summary: Creates a new TracingTicket
      parameters:
        - in: path
          name: request_contact_data_endpoint
          description: Endpoint wie vom Provider konfiguriert
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TracingTicketRequest'
      responses:
        '400':
          description: Fehler in der Anfrage vom Portal
        '500':
          description: Fehler im Provider        
        '202':
          description: Request accepted
        '401':
          description: Unauthorized - API Key not set or invalid

  
  /tracing-cases/{caseId}/tickets/{ticketId}/download:
    put:
      description: Dieser Endpunkt wird vom Portal implementiert. Die caseId und ticketId findet man in der Kontaktdaten Anfrage.
      tags:
        - Provide download url
      security:
        - ApiKeyAuth: [ ]
      operationId: uploadTracingData
      summary: Provides Download URL
      parameters:
        - in: path
          name: caseId
          schema:
            type: string
          required: true
        - in: path
          name: ticketId
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadURL'
      responses:
        '201':
          description: 'Upload was successful'
        '401':
          description: Unauthorized - API Key not set or invalid


  /{download_url}:
    get:
      description: Dieser Endpunkt wird vom Provider implementiert. Der finalen Pfad (download_url) bestimmt der Provider beim Upload der download_url .
      tags:
        - Download tracing data
      parameters:
        - in: path
          name: download_url
          description: Wird vom Provider bereitgestellt in "Provide Download URL"
          schema:
            type: string
          required: true
 
      security:
        - ApiKeyAuth: [ ]
      operationId: uploadTracingData
      summary: Downlods contact data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationVisitUpload'
      responses:
        '401':
          description: Unauthorized - API Key not set or invalid
        '404':
          description: resource not found
        '200':
          description: 'Download successful'
        '500':
          description: Fehler beim Provider
            

components:
  schemas:
    LocationInformation:
      type: object
      required:
        - "id"
        - "name"
        - "contact"
      properties:
        id:
          type: string
          description: 'Interne ID (beim Provider)'
          example: '5eddd61036d39a0ff8b11fdb'
        name:
          type: string
          description: 'Name des Standorts'
          example: 'Restaurant Alberts'
        publicKey:
          type: string
          description: 'Öffentlicher Schlüssel, ggf. für Nachrichtenaustausch'
        contact:
          $ref: '#/components/schemas/LocationContact'
          description: 'Kontaktperson des Standorts'
        contexts:
          type: array
          items:
            $ref: '#/components/schemas/LocationContext'

    LocationContact:
      type: object
      required:
        - "address"
      properties:
        officialName:
          type: string
          description: 'Offizieller Unternehmensname'
          example: 'Darfichrein GmbH'
        representative:
          type: string
          description: 'Ansprechpartner für dieses Unternehmen'
          example: 'Stefan Michalk'
        address:
          $ref: '#/components/schemas/LocationAddress'
          description: 'Anschrift des Standorts'
        ownerEmail:
          type: string
          description: 'E-Mail des Inhabers'
          example: 'stefan@darfichrein.de'
        email:
          type: string
          description: 'ggf. E-Mail einer weiteren Kontaktperson'
          example: 'covid@darfichrein.de'
        phone:
          type: string
          description: 'Telefonnummer eines Ansprechpartners'
          example: 'die bleibt privat :-)'

    LocationContext:
      type: object
      description: 'Ein Standort hat ggf. weitere Informationen wie Tische/Räume, etc.'
      properties:
        id:
          type: string
          description: 'Interne ID des Kontext'
          example: '5f4bfff742c1bf5f72918851'
        name:
          type: string
          description: 'Bezeichnung'
          example: 'Raum 0815'
    
    LocationAddress:
      required:
        - street
        - city
        - zip
      properties:
        street:
          type: string
          description: 'street + number'
          example: 'Türkenstr. 7'
        city:
          type: string
          description: 'Stadt'
          example: 'München'
        zip:
          type: string
          description: 'Postleitzahl'
          example: '80333'

    LocationVisitUpload:
      description: 'Angeforderte Kontaktdaten inkl. Informationen der Destination'
      required:
        - "visits"        
      type:
        object
      properties:
        visits:
          description: 'Liste der Kontaktdaten des angeforderten Zeitraums'
          type: array
          items:
            $ref: '#/components/schemas/LocationVisit'
        tracingSource:
          description: 'Referenz zur Destination'
          $ref: '#/components/schemas/Location'

    DownloadURL:

      description: 'URL unter der das Portal die Kontaktdaten runterladen kann.'
      type:
        object
      required:
        - "download_url"
      properties:
        download_url:
          type: string

    Location:
      type: object
      description: 'Dieses Objekt wird separat abgelegt, um die Referenz zu den Kontaktdaten zu halten'
      properties:
        name:
          type: string
          description: 'Name der Destination'
          example: 'Restaurant Alberts'
        officialName:
          type: string
          description: 'Offizieller Unternehmensname'
          example: 'Darfichrein GmbH'
        provider:
          type: string
          description: 'Name des Kontaktdatenproviders'
          example: 'darfichrein'
        address:
          $ref: '#/components/schemas/LocationAddress'
    
    LocationVisit:
      required:
        - "data"
        - "timestampEntrance"
        - "timestampExit"
      type:
        object
      properties:
        data:
          type: string
          description: 'Verschlüsselte Kontaktdaten *mehr dazu im Implementierungsleitfaden'
          example: 'YOUCANNOTREADTHISBASE64ENCODEDENCRYPEDDATA'
        context:
          type: string
          description: 'Kontext des Besuchers, z. B. bestimmter Tisch/Raum'
          example: 'Raum 0815'
        timestampEntrance:
          type: string
          format: date-time
          description: 'Zeitpunkt des Eintritts im ISO-Format'
          example: '2021-02-21T20:00:00.000Z'
        timestampExit:
          type: string
          format: date-time
          description: 'Zeitpunkt des Austritts im ISO-Format *mehr dazu im Implementierungsleitfaden'
          example: '2021-02-21T22:00:00.000Z'

    TracingTicketRequest:
      description: 'All information needed to create a new TracingTicket'
      allOf:
        - $ref: '#/components/schemas/TracingTicket'

    TracingTicketResponse:
      description: 'TracingTicket with ID and Status'
      allOf:
        - $ref: '#/components/schemas/TracingTicket'
      properties:
        id:
          type: string
          description: 'ID innerhalb "Gesundheitsbehörde digital"'
          example: '60327fe6b07ab12701e9f8e4'
        provider:
          type: string
          description: 'Name des Providers'
          example: 'darfichrein'
        status:
          $ref: "#/components/schemas/TracingStatus"

    TracingTicket:
      type: object
      required:
        - ticketId
        - caseId
        - code      
        - provider
        - companyId
        - issuer
        - from
        - to
      properties:
        ticketId:
          type: string
          description: 'Ticket-ID innerhalb "Gesundheitsbehörde digital"'
          example: '602bb183931cfb3b604398f9'
        caseId:
          type: string
          description: 'Fall-ID innerhalb "Gesundheitsbehörde digital"'
          example: '602bb183931cfb3b604398f9'
        code:
          type: string
          description: 'Identifizierendes Merkmal/Referenz bei Rückfragen (via Telefon/E-Mail)'
          example: 'a57b-e17b-9460'
        companyId:
          type: string
          description: "ID der Destination innerhalb des Providers"
          example: '5f4bfff742c1bf5f72918851'
        issuer:
          description: 'Ausstellende Gesundheitsbehörde'        
          $ref: '#/components/schemas/TracingIssuer'
        from:
          type: string
          format: date-time
          description: 'Zeitpunkt, ab wann Daten angefordert werden (UTC)'
          example: '2021-02-21T20:00:00.000Z'
        to:
          type: string
          format: date-time
          description: 'Zeitpunkt, bis wann Daten angefordert werden (UTC)'
          example: '2021-02-21T22:00:00.000Z'

    TracingIssuer:
      type: object
      properties:
        name:
          type: string
          description: 'Anfragende Gesundheitsbehörde'
          example: 'Gesundheitsbehörde Darfichrein GmbH'
        certificate:
          type: string
          description: 'Zertifikat der Gesundheitsbehörde *mehr im Implementierungsleitfaden'
          example: '-----BEGIN CERTIFICATE-----
MIIFPjCCAyagAwIBAgIUOlPemeKSf9Jbl5LCTEuK/5ovoywwDQYJKoZIhvcNAQEL
BQAwgc8xCzAJBgNVBAYTAkRFMQ8wDQYDVQQIDAZCYXllcm4xETAPBgNVBAcMCE3D
vG5jaGVuMRkwFwYDVQQKDBBEYXJmaWNocmVpbiBHbWJIMR4wHAYDVQQLDBVaZXJ0
aWZpemllcnVuZ3NzdGVsbGUxFDASBgNVBAMMC2RhcmZpY2hyZWluMQ4wDAYDVQQR
DAU4MDMzMzEZMBcGA1UECQwQVMO8cmtlbnN0cmHDn2UgNzEgMB4GCSqGSIb3DQEJ
ARYRaGlAZGFyZmljaHJlaW4uZGUwHhcNMjEwMTMxMTExNzMzWhcNMzEwMTI5MTEx
NzMzWjCBqzEqMCgGA1UEAwwhYmFkIGFpYmxpbmcuaGVhbHRoLmRhcmZpY2hyZWlu
LmRlMQswCQYDVQQGEwJERTEUMBIGA1UEBwwLQmFkIEFpYmxpbmcxGjAYBgNVBAoM
EVN0YWR0IERhcmZpY2hyZWluMRwwGgYDVQQLDBNHZXN1bmRoZWl0c2JlaMO2cmRl
MSAwHgYJKoZIhvcNAQkBFhFoaUBkYXJmaWNocmVpbi5kZTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAK8YktDPMy91tmDyKCsC/qJbrpRTlQ1TFSeiux6p
HiPRNXYRzEHj6aWfpcNZkHNWy7yJT8CxD0Gp81KmzFz/cXtwibTTzkIONZXbfxwV
DuRNd1TAoBfDuTNh2WpuR6HFlKQyoJAvy7m2XgtcVDPOULKA7L7/5IdUUrNVyZzb
H0xtFLAvW5Ipy11JX7b+0M5BtGbo8ahewBl65VZzIXATxdGWo5TPqsC6p67CpZZu
FV9uBhHrFCIyLHSWYMpzyzqRIJyuD09Bjh7Y6OFTX/fCeZjO9RqUgcYJDQNSiO4b
xOQ/lru1NUK9/R8D9S6yTWJ3gIbX8aq3rfdn8MTKbXuU2+sCAwEAAaM0MDIwMAYD
VR0RBCkwJ4IOZGFyZmljaHJlaW4uZGWCFWhlYWx0aC5kYXJmaWNocmVpbi5kZTAN
BgkqhkiG9w0BAQsFAAOCAgEAdoVNFokIX9uG3vhDXoOzzFXqjnSz89+ld/bToxo/
uQXF2791oROyNGBltiTgIDbkCX1TbEffuuGYZ0sbWUoh+LkmCICA1bDFDuzWH4Qd
MbZCr+V5gb0vHzR3w94gRytv1rfZzEN5w3CcCk73YBrzZjcFx5KfFO81TCLmHJIx
NB936JiijC5I8f0ksNSZOe+IAy0b+2lg94BFPuznnrHXwHIcna8zbmSJ+DqE6IeC
a5eeG0UjIf5BBPkT2dYiZKb80G9h2BcyBMbjbOTvsyOsdpw/2rgn08RfQY3Yr53s
128P1PI8VvQdZNmYDSwFd+4egFLzIOzMFHv1IWMRAwEV+PzwzdvJTrZubjSFtohm
h+WWPAdBzFS3kYUSaUcWoaOaspxvLEEc5aoFiCEMuWcBepXQBHPWl734zXd9MJlD
Z/hqO8PX/176+Z5Hi3mbyuafmTUPFgk4nE0LJbnpipfbCagpEJpMIJXVV6gAJP9l
NKgMhPcrM6P5ZP3HgUXnCxrzgaht+L9pgIyrkx/WbK4prlrpGQ5sxU9GbS7XyPNI
TMiORKYqTHRtTXevXQDippbMqWY38d96cFwcpIih50VT+1k235MDn4soWvdLu2a3
bya01G9Zgp+ywKqSF+jhIC3JEKzg3trK6ldLzuF6ya1RQN0k/1HGpAeIi6y6N7LM
Bu4=
-----END CERTIFICATE-----
'
        fingerprint:
          type: string
          description: 'Fingerabdruck des Zertifikats *mehr im Implementierungsleitfaden'
          example: 'dc3f230b761752b6f07c98f70251b9ca1b27b24528966f61497dff69ec5715aa'
        publicKey:
          type: string
          description: 'Öffentlicher Schlüssel der Gesundheitsbehörde *mehr im Implementierungsleitfaden'
          example: 'LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0NCk1JSUNJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBZzhBTUlJQ0NnS0NB'
    
    TracingStatus:
      description: 'Aktueller Status des Tickets'      
      type: string
      enum:
        - DRAFT
        - REQUESTED
        - REQUEST_SEEN
        - CANCELLED
        - READY
        - DOWNLOADED
        - TRANSFERED
        - CLOSED
      readOnly: true

    ContactData:
      description: Persönliche Informationen des Gasts. Dieses Objekt muss mit dem öffentlichen Schlüssel der anfragenden Behörde verschlüsselt werden.
      properties:
        f:
          type: string
          description: 'Vorname'
          example: 'Stefan'
        g:
          type: string
          description: 'Familienname'
          example: 'Michalk'
        p:
          type: string
          description: 'Telefonnummer'
          example: '01234 67901526'
        e:
          type: string
          description: 'E-Mail'
          example: 'stefan@darfichrein.de'
        a:
          type: string
          description: 'Vollständige Anschrift. Straße & Hausnummer#Postleitzahl#Ort.'
          example: 'Türkenstraße 7#80333#München'
        c:
          type: string
          description: 'ggf. Kontext des Aufenthalts'
          example: 'Raum 0815'
        m:
          type: string
          description: 'Kommentar, falls notwendig'
          example: 'Check-out wurde berechnet'

          
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: 'x-wfd-api-key'
      description: 'Api-Key needed to authenticate the communication to Providers'