openapi: 3.0.3 info: title: Contract Document Processor API description: API to transfer document data to Fonds Finanz. contact: name: Vertragsmanagment, Fonds Finanz Maklerservice GmbH url: https://www.fondsfinanz.de/ email: development@fondsfinanz.de version: 1.0.0 servers: - url: https://staging-api.fondsfinanz.de description: Stage - url: https://api.fondsfinanz.de description: Production paths: /contract-document-transactions: post: operationId: CreateTransaction tags: - Contract Document Processor API summary: Route to create a new Transaction description: Route to create a new Transaction requestBody: $ref: "#/components/requestBodies/TransactionRequest" responses: "201": $ref: "#/components/responses/Transaction.Created" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /contract-document-transactions/{transactionId}: parameters: - name: transactionId in: path description: ID of transaction that needs to be updated required: true schema: $ref: "#/components/schemas/DataType.Uuid" put: operationId: CreateTransactionDocuments tags: - Contract Document Processor API summary: Route to add documents to a transaction description: Processes contract documents and metadata requestBody: $ref: "#/components/requestBodies/StackRequest" responses: "201": $ref: "#/components/responses/Created" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "415": $ref: "#/components/responses/UnsupportedMediaType" "500": $ref: "#/components/responses/InternalServerError" components: schemas: DataType.Uuid: description: UUID (version 4). type: string format: uuid pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$ example: 10f80a96-4c97-4033-818b-c9e02bf99afd DataType.PartnerId: description: Fonds Finanz partner/customer (i.e. person or legal entity) ID. type: string pattern: ^MAK\d{5,7}\/\d{5}$ example: MAK12345/00001 DataType.DocumentType: description: | The document type. * `ABG`: Ablehnung * `ADRAEND`: Adressänderung * `ANBEST`: Annahmebestätigung * `ANT`: Antrag * `ANTNB`: Antragsnachbearbeitung * `ANTRANF`: KFZ-Antragsanforderung * `ANTZKN`: Antrag zur Kenntnisnahme * `AUSWEISKOPIEVN`: Ausweiskopie VN * `BANKDATAEND`: Bankdatenänderung * `BAP`: Beitragsanpassung * `BEITRFRST`: Beitragsfreistellung * `BERATNGDOKU`: Beratungsdokumentation * `BESTLN`: Bestandslegitimationsnachweis * `BSTSABG`: Bestandsabgabe * `BSTSUEB`: Bestandsübernahme * `BSTAKT`: Bestandsaktion * `BTRWCHL`: Betreuerwechsel * `BUEABL`: BUE Ablehnung * `BUEANNA`: BUE Annahme * `BUEFEHUN`: BUE fehlende Unterlagen * `BUEINFO`: Info zur BUE * `BUERUECKBEANTRAGT`: BUE Rückabwicklung beantragt * `BUERUECKBESTAETIGT`: BUE Rückabwicklung bestätigt * `ELANTNB`: Erledigte Antragsnachbearbeitung * `ELANTNBZKNME`: Erledigte Antragsnachbearbeitung zur Kenntnisnahme * `ERLANTRANF`: erledigte KFZ-Antragsanforderung * `ERLFVNW`: erledigter Folgeversicherungsnachweis * `FVNW`: Folgeversicherungsnachweis * `INFASGLZ`: Info zur Ausgleichzahlung * `INFO`: Info * `IVANG`: Invitatio-Angebot * `KUENDG`: Kündigung * `NAMENAEND`: Namensänderung * `NTRG`: Nachtrag * `POL`: Police * `RECH`: Rechnung * `RGNASGL`: Rechnung Ausgleichszahlung * `SCHAD`: Schaden * `SG`: Stornogefahrmeldung * `VERSBEST`: Versicherungsbestätigung * `VORANF`: Voranfrage * `VORDEBEST`: Vorläufige Deckungsbestätigung * `VTRUEBST`: Vertragsübersicht * `WI`: Widerruf type: string enum: - ABG - ADRAEND - ANBEST - ANT - ANTNB - ANTRANF - ANTZKN - AUSWEISKOPIEVN - BANKDATAEND - BAP - BEITRFRST - BERATNGDOKU - BESTLN - BSTSABG - BSTSUEB - BTRWCHL - BUEABL - BUEANNA - BUEFEHUN - BUEINFO - BUERUECKBEANTRAGT - BUERUECKBESTAETIGT - ELANTNB - ELANTNBZKNME - ERLANTRANF - ERLFVNW - FVNW - INFASGLZ - INFO - IVANG - KUENDG - NAMENAEND - NTRG - POL - RECH - RGNASGL - SCHAD - SG - VERSBEST - VORANF - VORDEBEST - VTRUEBST - WI example: ANT DataType.Error: description: An error. type: object additionalProperties: false required: - message properties: message: description: | The error message. A human-readable representation of the error that occurred. _Please note:_ This error message may be subject to change even without a version change of the API. Thus do not rely on it for deterministic processing of an error. Use the HTTP status code instead in order to identify an error in general and its error class. type: string DataType.ErrorMeta: description: An error response meta data. type: object additionalProperties: false required: - traceId properties: traceId: description: An ID that allows Fonds Finanz developers to trace an error. type: string minLength: 8 maxLength: 8 example: "string" Dto.Stack: description: Stack data. type: object additionalProperties: false required: - documents properties: errors: type: array description: List of errors for the stack, not document specific. nullable: true default: null items: $ref: "#/components/schemas/Dto.ExternalError" documents: type: array description: List of document data from the given stack/transaction. items: $ref: "#/components/schemas/Dto.Document" Dto.Document: description: A single document from the stack. type: object required: - data properties: brokerId: description: Fonds Finanz broker ID. type: string nullable: true pattern: ^MAK\d{5,7}$ example: MAK12345 contractId: description: Fonds Finanz contract number. If both `contractId` and `contractUuid` are provided, `contractUuid` takes precedence. type: string nullable: true pattern: ^V\d{8}$ example: V01234567 contractUuid: description: Fonds Finanz contract UUID. If both `contractId` and `contractUuid` are provided, `contractUuid` takes precedence. type: string format: uuid example: 10f80a96-4c97-4033-818b-c9e02bf99afd policyNumber: description: The contract's policy number. type: string nullable: true example: "131231234677" contractLicensePlate: description: Licence plate associated with the contract. type: string default: null nullable: true example: "M-AB 123" companyId: description: Fonds Finanz company id. type: string pattern: ^GES\d{5}$ example: GES12345 default: null nullable: true businessDivision: description: | Business Division. * `KV`: Health insurance * `LV`: Life insurance * `S`: Property insurance type: string enum: - KV - LV - S example: LV default: null nullable: true documentType: description: Fonds Finanz document type. type: string nullable: true maxLength: 100 $ref: "#/components/schemas/DataType.DocumentType" title: description: Title of the document type: string nullable: true maxLength: 150 description: description: A description of the document type: string nullable: true maxLength: 1000 verified: description: Document is verified. type: boolean example: true default: false classified: description: Document is classified. type: boolean example: true default: false totalPages: type: number description: total number of pages default: 1 example: 21 data: description: The base64 encoded binary data of the document. type: string format: base64 nullable: true contractPartner: description: The contract owner. type: object nullable: true $ref: "#/components/schemas/Dto.Person" insuredPersons: description: List of insured persons covered by the contract. type: array nullable: true items: $ref: "#/components/schemas/Dto.Person" externalIdServiceProvider: description: An identifier of the requesting client for the document. type: string default: null nullable: true maxLength: 200 errors: type: array description: List of errors specific to this document. nullable: true default: null items: $ref: "#/components/schemas/Dto.ExternalError" Dto.Person: description: Person data type: object required: - firstName - lastName properties: id: $ref: "#/components/schemas/DataType.PartnerId" firstName: type: string description: Fist name of the person. example: "Max" lastName: type: string description: Last name of the person. example: "Mustermann" Dto.ExternalError: description: An error. type: object additionalProperties: false required: - code - message properties: code: description: An ID that allows Fonds Finanz developers to trace an error. type: string enum: - unreadable # previously encryptedPDF flag - broken_document # errorDocument - unknown_contract # previously nif flag - duplicate # previously contractDoubler flag - other # Your custom error message: description: | The error message. A human-readable representation of the error that occured. _Please note:_ This error message may be subject to change even without a version change of the API. Thus do not rely on it for deterministic processing of an error. Use the HTTP status code instead in order to identify an error in general and its error class. type: string Dto.Transaction: description: Requirements to create a Transaction. type: object additionalProperties: false required: - documents properties: externalId: description: id inside the foreign system to identify the corresponding stack inside our system type: string nullable: true sendToInsurance: description: Document will be sent to the insurance company. type: boolean example: true default: false documents: type: array description: List of document data from the given stack/transaction. items: $ref: "#/components/schemas/Dto.Document" Dto.ErrorResponse: description: An error response. type: object additionalProperties: false required: - meta - error properties: meta: $ref: "#/components/schemas/DataType.ErrorMeta" error: $ref: "#/components/schemas/DataType.Error" requestBodies: TransactionRequest: description: request body to create a new Transaction required: true content: application/json: schema: $ref: "#/components/schemas/Dto.Transaction" StackRequest: description: Stack of documents required: true content: application/json: schema: $ref: "#/components/schemas/Dto.Stack" responses: Transaction.Created: description: Document successfully received content: application/json: schema: type: object properties: transactionId: $ref: "#/components/schemas/DataType.Uuid" Created: description: Document successfully received BadRequest: description: | Bad request response. It occurs if a request is semantically incorrect (e.g. path parameters, query parameters or request body). content: application/json: schema: $ref: "#/components/schemas/Dto.ErrorResponse" Unauthorized: description: | Unauthorized response. It occurs if no or an insufficient authorization token is provided. content: application/json: schema: $ref: "#/components/schemas/Dto.ErrorResponse" NotFound: description: | Not found response. It occurs if a requested resource is not found. content: application/json: schema: title: Response.NotFound allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" UnsupportedMediaType: description: | Unsupported media type response. It occurs if the request payload is in an unsupported format. content: application/json: schema: title: Response.UnsupportedMediaType allOf: - $ref: "#/components/schemas/Dto.ErrorResponse" InternalServerError: description: | Internal server error response. It occurs in case of an unexpected or fatal error. content: application/json: schema: $ref: "#/components/schemas/Dto.ErrorResponse" securitySchemes: JWT: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.fondsfinanz.de/oauth2/token scopes: target-entity:df9f00f4-a72a-476a-9bf6-d86abbff4f3a: target api for staging target-entity:ef0d0337-1016-4875-8c39-8f450b60cc6e: target api for production security: - JWT: - target-entity:df9f00f4-a72a-476a-9bf6-d86abbff4f3a # target api for staging - target-entity:ef0d0337-1016-4875-8c39-8f450b60cc6e # target api for production tags: - name: Contract Document Processor API description: API to transfer document data to Fonds Finanz.