dgc-openapi.yaml

openapi: 3.0.0

info:
  title: ERE Digital Green Certificate
  version: 0.1.1
  description: |
    Digital green certificate service for issuing both vaccination certificates
    and recovery certificates.

paths:
  /api/certify/v2/issue:
    get:
      parameters:
        - $ref: '#/components/parameters/Mandant'
        - $ref: '#/components/parameters/ClientSystem'
        - $ref: '#/components/parameters/Workplace'
        - $ref: '#/components/parameters/CardHandle'
        - $ref: '#/components/parameters/FamilyName'
        - $ref: '#/components/parameters/GivenName'
        - $ref: '#/components/parameters/DateOfBirth'
        - $ref: '#/components/parameters/AdministeringId'
        - $ref: '#/components/parameters/Illness'
        - $ref: '#/components/parameters/Vaccine'
        - $ref: '#/components/parameters/Product'
        - $ref: '#/components/parameters/Manufacturer'
        - $ref: '#/components/parameters/DosisNumber'
        - $ref: '#/components/parameters/DosisCount'
        - $ref: '#/components/parameters/VaccinationDate'
      responses:
        200:
          description: PDF file with certificate
          content:
            application/pdf: {}
        400:
          $ref: '#/components/responses/InvalidParameters'
        401:
          $ref: '#/components/responses/InvalidSmcbAuthentication'
        403:
          $ref: '#/components/responses/InvalidCertificateServiceAuthentication'
        500:
          $ref: '#/components/responses/InternalEreServerError'
        501:
          $ref: '#/components/responses/InvalidCertificateServerError'
    post:
      parameters:
        - $ref: '#/components/parameters/Mandant'
        - $ref: '#/components/parameters/ClientSystem'
        - $ref: '#/components/parameters/Workplace'
        - $ref: '#/components/parameters/CardHandle'
      requestBody:
        description: Vaccination certificate creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaccinationCertificateRequest'
      responses:
        200:
          description: PDF file with certificate
          content:
            application/pdf: {}
        400:
          $ref: '#/components/responses/InvalidParameters'
        401:
          $ref: '#/components/responses/InvalidSmcbAuthentication'
        403:
          $ref: '#/components/responses/InvalidCertificateServiceAuthentication'
        500:
          $ref: '#/components/responses/InternalEreServerError'
        501:
          $ref: '#/components/responses/InvalidCertificateServerError'

  /api/certify/v2/recovered:
    get:
      parameters:
        - $ref: '#/components/parameters/Mandant'
        - $ref: '#/components/parameters/ClientSystem'
        - $ref: '#/components/parameters/Workplace'
        - $ref: '#/components/parameters/CardHandle'
        - $ref: '#/components/parameters/FamilyName'
        - $ref: '#/components/parameters/GivenName'
        - $ref: '#/components/parameters/DateOfBirth'
        - $ref: '#/components/parameters/AdministeringId'
        - $ref: '#/components/parameters/Illness'
        - $ref: '#/components/parameters/PositiveTestDate'
        - $ref: '#/components/parameters/CertificateStartDate'
        - $ref: '#/components/parameters/CertificateEndDate'
      responses:
        200:
          description: PDF file with certificate
          content:
            application/pdf: {}
        400:
          $ref: '#/components/responses/InvalidParameters'
        401:
          $ref: '#/components/responses/InvalidSmcbAuthentication'
        403:
          $ref: '#/components/responses/InvalidCertificateServiceAuthentication'
        500:
          $ref: '#/components/responses/InternalEreServerError'
        501:
          $ref: '#/components/responses/InvalidCertificateServerError'
    post:
      parameters:
        - $ref: '#/components/parameters/Mandant'
        - $ref: '#/components/parameters/ClientSystem'
        - $ref: '#/components/parameters/Workplace'
        - $ref: '#/components/parameters/CardHandle'
      requestBody:
        description: Vaccination certificate creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecoverdCertificateRequest'
      responses:
        200:
          description: PDF file with certificate
          content:
            application/pdf: {}
        400:
          $ref: '#/components/responses/InvalidParameters'
        401:
          $ref: '#/components/responses/InvalidSmcbAuthentication'
        403:
          $ref: '#/components/responses/InvalidCertificateServiceAuthentication'
        500:
          $ref: '#/components/responses/InternalEreServerError'
        501:
          $ref: '#/components/responses/InvalidCertificateServerError'
  /test-api/certify/v2/issue:
    post:
      description: This endpoint allows to test the integration into other systems
        The response type may be controlled up to a certain extend by the given
        name of the vaccinated person (400, 401, 403).
      requestBody:
        description: Vaccination certificate creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaccinationCertificateRequest'
      responses:
        200:
          description: PDF file with certificate
          content:
            application/pdf: {}
        400:
          $ref: '#/components/responses/InvalidParameters'
        401:
          $ref: '#/components/responses/InvalidSmcbAuthentication'
        403:
          $ref: '#/components/responses/InvalidCertificateServiceAuthentication'
        500:
          $ref: '#/components/responses/InternalEreServerError'
        501:
          $ref: '#/components/responses/InvalidCertificateServerError'

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          description: Error code for further reference
          example: 3456
          minimum: 1
        message:
          description: Human readable error message (may contain also technical details)
          type: string
    CertificateRequest:
      type: object
      properties:
        nam:
          type: object
          properties:
            fn:
              type: string
              description: Family name
            gn:
              type: string
              description: Given name
        dob:
          type: string
          description: Date of bith
          format: date
    VaccinationCertificateRequest:
      allOf:
        - $ref: '#/components/schemas/CertificateRequest'
        - type: object
          properties:
            v:
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Administering id (e.g. Betriebsstättennummer)
                  tg:
                    type: string
                    description: Illenss identification
                  vp:
                    type: string
                    description: Vaccination name
                  mp:
                    type: string
                    description: Product
                  ma:
                    type: string
                    description: Manufacturer of vaccination
                  dn:
                    type: integer
                    minimum: 1
                    description: Number of dosis
                  sd:
                    type: integer
                    minimum: 1
                    description: Total dosis count for complete immunization
                  dt:
                    type: string
                    format: date
                    description: Date of vaccination
    RecoverdCertificateRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/CertificateRequest'
        - type: object
          properties:
            r:
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Administering id (e.g. Betriebsstättennummer)
                  tg:
                    type: string
                    description: Illenss identification
                  fr:
                    type: string
                    format: date
                    description: Date of first positive test result
                  df:
                    type: string
                    format: date
                    description: Start date of certificate validity
                  du:
                    type: string
                    format: date
                    description: End date of certificate validity
      
  responses:
    InvalidParameters:
      description: Missing parameters in request or invalid types
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidSmcbAuthentication:
      description: Missing parameters in request or invalid types
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidCertificateServiceAuthentication:
      description: Authentication error (Certifcate service)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalEreServerError:
      description: Server error in ERE application
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidCertificateServerError:
      description: Server error in Certificate service
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Mandant:
      name: X-Mandant
      in: header
      description: Mandant id to be used in the request (overrides the default value)
      schema:
        type: string
    ClientSystem:
      name: X-ClientSystem
      in: header
      description: Client system to be used in the request (overrides the default value)
      schema:
        type: string
    Workplace:
      name: X-Workplace
      in: header
      description: Workplace identification to be used in the request (overrides the default value)
      schema:
        type: string
    CardHandle:
      name: X-CardHandle
      in: header
      description: Card handle to be used in the request (overrides the default value)
      schema:
        type: string
    FamilyName:
      name: fn
      in: query
      required: true
      description: Family name
      schema:
        type: string
    GivenName:
      name: gn
      in: query
      required: true
      description: Given name(s)
      schema:
        type: string
    DateOfBirth:
      name: dob
      in: query
      required: true
      description: Date of birth
      schema:
        type: string
        format: date
    AdministeringId:
      name: id
      in: query
      required: true
      description: Administering id (e.g. Betriebsstättennummer)
      schema:
        type: string
    Illness:
      name: tg
      in: query
      required: true
      description: Illenss identification
      schema:
        type: string
    Vaccine:
      name: vp
      in: query
      required: true
      description: Vaccination name
      schema:
        type: string
    Product:
      name: mp
      in: query
      required: true
      description: Product
      schema:
        type: string
    Manufacturer:
      name: ma
      in: query
      required: true
      description: Manufacturer of vaccination
      schema:
        type: string
    DosisNumber:
      name: dn
      in: query
      required: true
      description: Number of dosis
      schema:
        type: integer
        example: 1
        minimum: 1
    DosisCount:
      name: sd
      in: query
      required: true
      description: Total dosis count for complete immunization
      schema:
        type: integer
        example: 2
        minimum: 1
    VaccinationDate:
      name: dt
      in: query
      required: true
      description: Date of vaccination
      schema:
        type: string
        format: date
    PositiveTestDate:
      name: fr
      in: query
      required: true
      description: Date of first positive test result
      schema:
        type: string
        format: date
    CertificateStartDate:
      name: df
      in: query
      required: true
      description: Start date of certificate validity
      schema:
        type: string
        format: date
    CertificateEndDate:
      name: du
      in: query
      required: true
      description: End date of certificate validity
      schema:
        type: string
        format: date