{"openapi":"3.0.2","info":{"title":"Basware push notification APIs","description":"Steps to use:\n1. Publish a webservice to receive notifications from Basware API.\n2. Subscribe to push notifications using 'subscriptions' API, specifying your webservice URL.\n3. API will POST notifications to specified URL when documents become available.\n4. Retrieve the document(s) from the API(s) indicated by taskType in the received notification. \n\nThe notification data format is documented under 'Callbacks' section of POST subscriptions API. \nSee full documentation on Basware API developer site: <https://developer.basware.com/api/p2p/manual#PushNotifications>","version":"1.0.0","x-logo":{"url":"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"}},"paths":{"/v1/subscriptions":{"post":{"tags":["Subscribe to notifications"],"summary":"Subscribes to receive push notifications.","description":"Use this API to subscribe to task notifications. See <https://developer.basware.com/api/p2p/manual#PushNotifications> for notification format which needs to be supported by the receiving endpoint. \n\nNote: Basware API validates the receiving endpoint by sending a notification with taskType 'ConnectionTest', to which a 200 OK HTTP response needs to be returned.","operationId":"create_item_v1_subscriptions_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Subscription-Input"},"title":"Items"}}}},"callbacks":{"notification":{"{$notificationWebhookURL}":{"post":{"summary":"Notification","operationId":"notification__notificationWebhookURL__post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPayload"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityErrorResponse"}}},"description":"Unprocessable Entity"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Subscription-Output"},"title":"Response Create Item V1 Subscriptions Post"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityErrorResponse"}}},"description":"Unprocessable Entity"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}},"description":"Bad Request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}},"description":"Internal Server Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizeErrorResponse"}}},"description":"Unauthorized"}}},"get":{"tags":["Subscribe to notifications"],"summary":"List existing subscriptions.","operationId":"read_items_v1_subscriptions_get","parameters":[{"name":"taskType","in":"query","required":false,"schema":{"type":"string","description":"The task type of the subscription(s) to be returned.","title":"Tasktype"},"description":"The task type of the subscription(s) to be returned."},{"name":"taskSubType","in":"query","required":false,"schema":{"type":"string","description":"Task sub type of the subscriptions(s) to be returned.","title":"Tasksubtype"},"description":"Task sub type of the subscriptions(s) to be returned."},{"name":"lastUpdated","in":"query","required":false,"schema":{"type":"string","description":"Date Filter. Returns items that have been updated after specified date.","title":"Lastupdated"},"description":"Date Filter. Returns items that have been updated after specified date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionsResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}},"description":"Internal Server Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizeErrorResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordNotFoundResponse"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityErrorResponse"}}},"description":"Unprocessable Entity"}}},"delete":{"tags":["Subscribe to notifications"],"summary":"Deletes existing subscriptions.","operationId":"delete_item_v1_subscriptions_delete","parameters":[{"name":"lastUpdated","in":"query","required":true,"schema":{"type":"string","description":"Deletes subscriptions where lastUpdated is after specified datetime.","title":"Lastupdated"},"description":"Deletes subscriptions where lastUpdated is after specified datetime."},{"name":"taskType","in":"query","required":true,"schema":{"type":"string","description":"TaskType of subscription(s) to delete. ‘All’ can be used to specify any taskType.","title":"Tasktype"},"description":"TaskType of subscription(s) to delete. ‘All’ can be used to specify any taskType."},{"name":"taskSubType","in":"query","required":true,"schema":{"type":"string","description":"TaskSubType of subscription(s) to delete. ‘All’ can be used to speciy any taskSubType.","title":"Tasksubtype"},"description":"TaskSubType of subscription(s) to delete. ‘All’ can be used to speciy any taskSubType."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSubscriptionResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}},"description":"Internal Server Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizeErrorResponse"}}},"description":"Unauthorized"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityErrorResponse"}}},"description":"Unprocessable Entity"}}}},"/v1/tasks/{taskId}":{"get":{"tags":["Notification history"],"summary":"Used to check status of an individual task by taskId. Does not contain task payload.","operationId":"read_item_v1_tasks__taskId__get","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","description":"TaskId of the task to be returned.","title":"Taskid"},"description":"TaskId of the task to be returned."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TasksResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}},"description":"Internal Server Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizeErrorResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordNotFoundResponse"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityErrorResponse"}}},"description":"Unprocessable Entity"}}}},"/v1/tasks":{"get":{"tags":["Notification history"],"summary":"Returns task status by search criteria. Does not contain task payload.","operationId":"read_item_v1_tasks_get","parameters":[{"name":"taskType","in":"query","required":false,"schema":{"type":"string","description":"Task type (InvoiceGenericTask, InvoiceCalcTax, etc)","title":"Tasktype"},"description":"Task type (InvoiceGenericTask, InvoiceCalcTax, etc)"},{"name":"taskStatus","in":"query","required":false,"schema":{"type":"string","description":"Status of the task. Available values: 'New', 'Completed', 'Failed'.","title":"Taskstatus"},"description":"Status of the task. Available values: 'New', 'Completed', 'Failed'."},{"name":"documentId","in":"query","required":false,"schema":{"type":"string","description":"Returns all tasks for a specific document (for example all tasks related to one AccountingDocument).","title":"Documentid"},"description":"Returns all tasks for a specific document (for example all tasks related to one AccountingDocument)."},{"name":"lastUpdated","in":"query","required":false,"schema":{"type":"string","description":"Date Filter. Returns tasks which have been updated after specified datetime.","title":"Lastupdated"},"description":"Date Filter. Returns tasks which have been updated after specified datetime."},{"name":"x-amz-meta-continuationtoken","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Used to get next page of results when item count indicated by 'pageSize' is exceeded. A token is returned in header (not body) parameter 'X-amz-meta-continuationToken' of the response whenever there are more records to fetch. Post the received value here in a new GET request to receive the next page of results.","title":"X-Amz-Meta-Continuationtoken"},"description":"Used to get next page of results when item count indicated by 'pageSize' is exceeded. A token is returned in header (not body) parameter 'X-amz-meta-continuationToken' of the response whenever there are more records to fetch. Post the received value here in a new GET request to receive the next page of results."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TasksResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}},"description":"Internal Server Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizeErrorResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordNotFoundResponse"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityErrorResponse"}}},"description":"Unprocessable Entity"}}}}},"components":{"schemas":{"AutoResponder":{"properties":{"autoResponseMode":{"allOf":[{"$ref":"#/components/schemas/AutoResponseModeEnum"}],"description":"Determines whether task autoresponder is enabled and whether it returns task responses with status 'Success' or 'Failed'. The entire autoresponder functionality is reserved for later use.","example":"Disabled"},"autoResponseMessage":{"type":"string","title":"Autoresponsemessage","description":"Determines message returned by task autoresponser to P2P.","example":"Updated coding details."},"fieldUpdateArray":{"anyOf":[{"items":{"$ref":"#/components/schemas/FieldUpdateArray"},"type":"array"},{"type":"null"}],"title":"Fieldupdatearray","description":"Reserved for later use. Array of field values to automatically update when autoresponder is enabled."}},"type":"object","title":"AutoResponder"},"AutoResponseModeEnum":{"type":"string","enum":["Disabled","Success","Failed"],"title":"AutoResponseModeEnum"},"DeleteSubscriptionResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Success message","default":"Deleted successfully","example":"Deleted successfully"},"numberOfRecordsDeleted":{"type":"integer","title":"Numberofrecordsdeleted","description":"Number of records deleted","example":"1"}},"type":"object","title":"DeleteSubscriptionResponse"},"FieldUpdateArray":{"properties":{"fieldId":{"type":"string","title":"Fieldid","description":"Specifies the field to update. Use JSONpath to identify the value on response schema to update.","example":"codingRows[2]/accountCode"},"updateToValue":{"type":"string","title":"Updatetovalue","description":"Specifies value to which field contents are set by the autoresponder.","example":"02600"}},"type":"object","title":"FieldUpdateArray"},"InternalServerErrorResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Detail of error","default":"Internal server error","example":"Internal server error"}},"type":"object","title":"InternalServerErrorResponse"},"NotificationPayload":{"properties":{"taskId":{"type":"string","title":"Taskid","description":"Defines id of task","example":"eb9ea3fa-69de-4a5a-8a1a-f4347cd18626"},"taskStatus":{"type":"string","title":"Taskstatus","description":"Defines status of task","example":"New"},"taskType":{"type":"string","title":"Tasktype","description":"Defines task type","example":"AccoutingDocuments"},"taskSubType":{"type":"string","title":"Tasksubtype","description":"Defines sub task type","example":"WaitingForTransfer"},"documentId":{"type":"string","title":"Documentid","description":"Defines document id","example":"63255782d0a04d8d8defcc6a0062101d"},"expirationTime":{"type":"string","title":"Expirationtime","description":"Defines notification's expiration time","example":"2021-12-11T08:53:31Z"}},"type":"object","required":["taskId","taskStatus","taskType","documentId"],"title":"NotificationPayload"},"RecordNotFoundResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Detail of error","default":"Not Found","example":"Not Found"}},"type":"object","title":"RecordNotFoundResponse"},"SchemaValidationError":{"properties":{"type":{"type":"string","title":"Type","description":"Type of error","example":"VALIDATION"},"code":{"type":"string","title":"Code","description":"Code of error","example":"SCHEMA_VALIDATION_ERROR"},"message":{"type":"string","title":"Message","description":"Detail of error","example":"taskType field required"}},"type":"object","title":"SchemaValidationError"},"Subscription-Input":{"properties":{"taskType":{"type":"string","minLength":1,"title":"Tasktype","description":"Task type for which notifications are sent. Supported values: 'AccountingDocuments', 'ExportedPurchaseRequisitions', 'ExportedPurchaseOrders', 'RequestStatus', 'ExportedContracts' , 'ExportedContractSpends'.","example":"AccountingDocuments"},"taskSubType":{"type":"string","title":"Tasksubtype","description":"Task subtype for which webhook notifications are sent. Supported values: 'WaitingForPrebook', 'WaitingForTransfer', 'WaitingForPrebookCancelation', 'WaitingToBeRemoved', 'WaitingToBeReturned', 'WaitingToBeCompleted', 'WaitingForExport', 'Error', 'Success', 'All'. Available values depend on taskType. If null, defaults to 'Error' for RequestStatus taskType and 'All' for other taskTypes.","example":"All"},"subscriptionType":{"allOf":[{"$ref":"#/components/schemas/SubscriptionType"}],"description":"Subscription type. Supported values: 'Webhook'. 'Polling' subscription type is reserved for later use.","example":"Webhook"},"notificationWebhookURL":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Notificationwebhookurl","description":"URL where API posts push notifications when subscriptionType = 'Webhook' (then field is mandatory). This URL needs to implement the Basware's notification receival API specification.","example":"https://bwnotificationapi.customer.com/accountingdocumentnotifications"},"webhookAuthenticationToken":{"type":"string","minLength":1,"title":"Webhookauthenticationtoken","description":"Secret key used by API to sign sent push notifications so authenticity can be verified by customer. Mandatory when subscription type is 'Webhook'.","example":"ad65rujltr9093ijhdkutiyua09döijhsa76d8799w8pqugdfafjdhfkjhadls"},"lastUpdated":{"type":"string","format":"date-time","title":"Lastupdated","description":"Timestamp when this subscription has been last updated (set automatically by Basware API).","example":"2021-08-04T08:39:13Z"},"autoResponder":{"anyOf":[{"$ref":"#/components/schemas/AutoResponder"},{"type":"null"}],"description":"Reserved for later use."}},"additionalProperties":false,"type":"object","required":["taskType","subscriptionType","notificationWebhookURL","webhookAuthenticationToken"],"title":"Subscription"},"Subscription-Output":{"properties":{"taskType":{"type":"string","minLength":1,"title":"Tasktype","description":"Task type for which notifications are sent. Supported values: 'AccountingDocuments', 'ExportedPurchaseRequisitions', 'ExportedPurchaseOrders', 'RequestStatus', 'ExportedContracts' , 'ExportedContractSpends'.","example":"AccountingDocuments"},"taskSubType":{"type":"string","title":"Tasksubtype","description":"Task subtype for which webhook notifications are sent. Supported values: 'WaitingForPrebook', 'WaitingForTransfer', 'WaitingForPrebookCancelation', 'WaitingToBeRemoved', 'WaitingToBeReturned', 'WaitingToBeCompleted', 'WaitingForExport', 'Error', 'Success', 'All'. Available values depend on taskType. If null, defaults to 'Error' for RequestStatus taskType and 'All' for other taskTypes.","example":"All"},"subscriptionType":{"allOf":[{"$ref":"#/components/schemas/SubscriptionType"}],"description":"Subscription type. Supported values: 'Webhook'. 'Polling' subscription type is reserved for later use.","example":"Webhook"},"notificationWebhookURL":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Notificationwebhookurl","description":"URL where API posts push notifications when subscriptionType = 'Webhook' (then field is mandatory). This URL needs to implement the Basware's notification receival API specification.","example":"https://bwnotificationapi.customer.com/accountingdocumentnotifications"},"webhookAuthenticationToken":{"type":"string","minLength":1,"title":"Webhookauthenticationtoken","description":"Secret key used by API to sign sent push notifications so authenticity can be verified by customer. Mandatory when subscription type is 'Webhook'.","example":"ad65rujltr9093ijhdkutiyua09döijhsa76d8799w8pqugdfafjdhfkjhadls"},"lastUpdated":{"type":"string","format":"date-time","title":"Lastupdated","description":"Timestamp when this subscription has been last updated (set automatically by Basware API).","example":"2021-08-04T08:39:13Z"},"autoResponder":{"anyOf":[{"$ref":"#/components/schemas/AutoResponder"},{"type":"null"}],"description":"Reserved for later use."}},"additionalProperties":false,"type":"object","required":["taskType","subscriptionType","notificationWebhookURL","webhookAuthenticationToken"],"title":"Subscription"},"SubscriptionType":{"type":"string","enum":["Webhook","Polling"],"title":"SubscriptionType"},"SubscriptionsResponse":{"properties":{"subscriptions":{"items":{"$ref":"#/components/schemas/Subscription-Output"},"type":"array","title":"Subscriptions"}},"type":"object","required":["subscriptions"],"title":"SubscriptionsResponse"},"Task":{"properties":{"taskId":{"type":"string","title":"Taskid","description":"Task id identifies the task and is used to correlate task response to the correct operation in P2P.","example":"sajkhe1i87yhdgdi6sad7iyahljh1ut1"},"taskStatus":{"type":"string","title":"Taskstatus","description":"Status of the task (=notification). Available values: 'New', 'Completed', 'Failed'.","example":"New"},"taskType":{"type":"string","title":"Tasktype","description":"Task type specifies type of document. It also determines the API endpoint from which the document needs to be fetched.","example":"AccountingDocuments"},"taskSubType":{"type":"string","title":"Tasksubtype","description":"Specifies status of the document when notification was sent.","example":"WaitingForTransfer"},"documentId":{"type":"string","title":"Documentid","description":"Identifies the document being processed. Same identifier is used in API from which document needs to be fetched.","example":"198phejkbaku7dilj12kdg867hbdsmag"},"expirationTime":{"type":"string","title":"Expirationtime","description":"Timestamp after which the notification expires. Reseved for future use. Responses are no longer accepted for expired tasks.","example":"2020-12-04T08:39:13Z"},"externalProcessingTime":{"type":"string","title":"Externalprocessingtime","description":"Reserved for future use.","example":"2020-12-04T08:39:13Z"},"isSimulatedTask":{"type":"boolean","title":"Issimulatedtask","description":"Reserved for future use. Indicates if task is a simulated task (created using 'simulate' API).","example":"false"},"lastUpdated":{"type":"string","title":"Lastupdated","description":"Timestamp when task has been last updated. Value is set automatically by API.","example":"2020-12-04T08:39:13Z"},"taskHistory":{"items":{"$ref":"#/components/schemas/TaskHistory"},"type":"array","title":"Taskhistory","description":"Shows information aboout task status changes."}},"type":"object","title":"Task"},"TaskHistory":{"properties":{"action":{"type":"string","title":"Action","description":"Action performed on the task.","example":"New"},"timeStamp":{"type":"string","title":"Timestamp","description":"Timestamp when action occurred.","example":"2021-08-12T08:39:13Z"},"messages":{"items":{"type":"string"},"type":"array","title":"Messages","description":"Additional information regarding task status change, such as error messages.","example":"Task Created"}},"type":"object","title":"TaskHistory"},"TasksResponse":{"properties":{"taskStatus":{"items":{"$ref":"#/components/schemas/Task"},"type":"array","title":"Taskstatus"}},"type":"object","required":["taskStatus"],"title":"TasksResponse"},"UnauthorizeErrorResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Detail of error","default":"Unauthorized","example":"Unauthorized"}},"type":"object","title":"UnauthorizeErrorResponse"},"UnprocessableEntityErrorResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Detail of error","default":"UnprocessableEntity","example":"UnprocessableEntity"}},"type":"object","title":"UnprocessableEntityErrorResponse"},"ValidationErrorResponse":{"properties":{"requestId":{"type":"string","title":"Requestid","description":"RequestId of request","example":"KLF5BiZ9DoEEMlQ="},"hasError":{"type":"boolean","title":"Haserror","description":"Tells that request has error","example":true},"errorMessages":{"items":{"$ref":"#/components/schemas/SchemaValidationError"},"type":"array","title":"Errormessages"}},"type":"object","title":"ValidationErrorResponse"}}}}