API routes (Click a route to expand it, click here to expand/collapse all)
GET/ ⎘
Provides the API-specification. Only enabled if API exposure is enabled.
Parameter Location Type Requirements Optional Default value Description
format URI-Query string
enum: [ "KateAPI", "InternalAPIMap", "OpenAPI", "Swagger" ]
 Yes "KateAPI" Documentation format. We support KateAPI documentation, Swagger/OpenAPI documentation and raw output of the internal API-map cache.
openApiVersion URI-Query int
enum: [ 2, 3 ]
 Yes 2 Version 3 is crappy with request bodies, so we prefer version 2 (which only sucks regarding Response definitions; hence we prefer KateAPI documentation).
Response HTTP Type Description
Success 200 object The API-documentation.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
GET/{idValuation} ⎘Authentication required
Returns associated XBRL-data related to this valuation. It can be used to retrieve data, as well as check on the current data state (are signatures present? etc.)
Parameter Location Type Requirements Optional Default value Description
idValuation URI-Path string
minLength: 1
 No ID of the valuation.
noData URI-Query bool Yes false If true, does not return the data contents, but only booleans on whether the data is present.
Response HTTP Type Description
Success 200 object Object with 5 properties:<br />
  • xbrl : XBRL content string<br />
  • xades1 : Signature generated with type valuer_1, or false if it is not present (yet).<br />
  • xades2 : Signature generated with type valuer_2 or reviewer_2, or false if it is not present (yet).<br />
  • tsTransferred : Timestamp when this was sent to the BIV, or 0 if not transferred yet.<br />
  • bivReference : Reference assigned by the BIV, upon transfer request; or false if not transferred yet.
DataNotFoundException 404 XBRL-entry for this idValuation that was supposedly generated by /generate was not found.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
kate AND ('xbrl:*' OR 'xbrl:all') ⎘
POST/generate ⎘Authentication required
Generates and stores XBRL for the given mapping. If former XBRL or signatures existed, these will be deleted first.
Parameter Location Type Requirements Optional Default value Description
idMapping POST-body string
minLength: 10
 No Id of the mapping, for example "mapping-vt15-taxatiegegevens".
idValuation POST-body string
minLength: 5
 No Id of valuation.".
jsonValuation POST-body string
format: json
maxLength: 4194304
 No JSON-stringified version a JSON valuation interpretable by the specified mapping.
returnData POST-body bool Yes false True of XBRL-document should be returned, false to return "OK". Note that false is default, as XBRL should not be persisted elsewhere than this service; and it can be retrieved at any time using /{idValuation}.
Response HTTP Type Description
Success 200 string XBRL document. Do not save this document into persistence; it can be requested at any time by invoking GET /{idValuation}.
InvalidMappingIdException 400 Invalid XBRL Mapping ID: contains illegal characters.
ValidationFailedException 200 One of the validation constraints was unsatisfied (Input valuation is invalid). The error will contain extensive details in a fixed format.
PipeProcessingException 200 Runtime Error when a pipe encounters an error. The description will contain additional details.
MappingNotFoundException 404 Unable to locate mapping definition. See error details for mapping ID.
XBRLIncompleteMappingDefinitionException 500 One of the value-maps in the mapping-definition is missing a key to be mapped. See details for involved key.
XBRLInvalidMappingDefinitionException 500 The mapping definition is invalid. The description will contain additional details.
InvalidJSONException 500 JSON-string could not be parsed into valid JSON.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
kate AND ('xbrl:*' OR 'xbrl:all') ⎘
POST/sign/initialize ⎘Authentication required
Initialize signing procedure. This method registers all required parameters in a secure way, and returns a one-time-token URL to navigate to, to continue the signing process.
Parameter Location Type Requirements Optional Default value Description
idValuation POST-body string
minLength: 1
 No ID of the valuation corresponding to the XBRL-string.
type POST-body string
enum: [ "valuer_1", "valuer_2", "reviewer_2" ]
 No Type of signature to be generated.
navCallback POST-body string
minLength: 1
 No Callback-URI to navigate back to upon completion/failure of signing, as a result of the subsequent call to /sign/{oneTimeToken}. If an error occurred, a query-string parameter "error" will be appended with an error-code.
Response HTTP Type Description
Success 200 string URI with one-time token to navigate to, to continue the signing process. It has the form /sign/{oneTimeToken}. This OTT can only be used once; even if an error occurs.
PathNotWritableException 500 Path is not writable.
DataNotFoundException 404 XBRL-entry for this idValuation that was supposedly generated by /generate was not found.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
kate AND ('xbrl:*' OR 'xbrl:all') ⎘
POST/transfer ⎘Authentication required
Transfers the generated XBRL (including signatures if present) for given valuation to the bank through the BIV.
Parameter Location Type Requirements Optional Default value Description
idValuation POST-body string
minLength: 10
maxLength: 64
 No ID of the valuation for which to transfer (signed) XBRL to bank
debugRun POST-body bool Yes false If true, will not actually send to bank and output SOAP message.
forceRetransfer POST-body bool Yes false If true, it will still transfer if already marked as transferred. Should only be used on DEV when testing XBRLTransfer connection.
Response HTTP Type Description
Success 200 object Object with the following keys: tsFinalStatus, bivStatus (=400), bivDescription, bivReference, kateReference (=idValuation)
XBRLAlreadyTransferredException 409 This XBRL was already transferred to the BIV.
DataNotFoundException 404 XBRL-entry for this idValuation that was supposedly generated by /generate was not found.
CertificateNotFoundException 500 No PKIO-certificate found at specified location.
CertificateExpiredException 500 PKIO-certificate has expired.
CertificateRejectedException 500 The PKIO-certificate was rejected.
InvalidCertificatePasswordException 200 PKIO-certificate found, but it could not be decoded with the password provided by Customer settings.
InvalidXBRLException 200 Provided XBRL is invalid and rejected. See details which stakeholder invalidated the XBRL, and why.
BIVCertificateNotFoundException 500 The public BIV-certificate could not be found. Note that this is something different than the customer PKIO-certificate.
BIVCertificateInvalidException 500 The public BIV-certificate is invalid. Note that this is something different than the customer PKIO-certificate.
ConfigurationException 500 Invalid microservice configuration. See details for details.
InvalidIdentityException 200 This providing or receiving party identity is invalid and/or not supported. See details for details.
DigitalSignatureException 500 Something related to the Digital Signatures is wrong; see details for details.
BIVException 200 The BIV responded with a faultCode. See details for details.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
kate AND ('xbrl:*' OR 'xbrl:all') ⎘
POST/transferMultiple ⎘Authentication required
Transfers the generated XBRL (including signatures if present) for given valuations to the bank through the BIV. Make sure all signatures are present to prevent failures. Result responses are provided on a per item basis through a callback.
Parameter Location Type Requirements Optional Default value Description
idValuations POST-body string[]
minItems: 1
maxItems: 1000
minLength: 10
maxLength: 64
 No IDs of the valuations to transfer (signed) XBRL to bank
callbackURL POST-body string
minLength: 10
maxLength: 128
 No Callback URL to invoke. This callback will be invoked for each given ID, and will contain 3 application/x-www-form-urlencoded POST-body parameters: idValuation [string], success [bool], errorCode [string: Any of the error-code listed on /transfer], errorDetails [*].
callbackHeaders POST-body string[] Yes [] Headers to provide to callback URL. Must be a full header string including header-name per header-string, for example: "Authorization: Bearer bearerkey".
Response HTTP Type Description
Success 200 boolean Will always return true immediately. Any further response-feedback will be provided to individual callbacks. Technically all might still fail, but these are reported by callbacks.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
kate AND ('xbrl:*' OR 'xbrl:all') ⎘
Authentication schemes (Click an authentication scheme to expand it)
JWTAuth
Result wrappers (Click a result-wrapper to expand it)
Success
Error