openapi: 3.0.1 info: title: App Marketplace accounting-entries Export API (v2) API description: API for Pleo App Marketplace termsOfService: https://pleo.io/terms/ contact: email: partner-ecosystem-team@pleo.io license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 39.4.0 servers: - url: https://external.pleo.io description: Production server - url: https://external.staging.pleo.io description: Staging server security: - bearerAuth: [] - basicAuth: [] tags: - name: Export API (v2) paths: /v2/export-job-events: post: tags: - Export API (v2) summary: Create an Export Job Event description: "\n The Export Job Events imply the current status of the Export Job through the export lifecycle.\n Send a request to this endpoint to update the status of the export job. If an export job has failed,\n mention the failure reason and the reason type.\n " operationId: createExportJobEventV2 requestBody: content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/CreateExportJobEvent' responses: '202': description: Export Job Event created successfully. '422': description: Attempted invalid operation (trying to mark a `completed` job as `started`, and so on.) content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExceptionInfo' example: type: INVALID_EXPORT_JOB_STATUS_CHANGE message: Export Job status change failed /v2/export-jobs: get: tags: - Export API (v2) summary: Get a list of Export Jobs description: Fetch a list of export jobs. operationId: getExportJobsListV2 parameters: - name: company_id in: query description: Enter the specific company ID for which you want to retrieve the list of export jobs processed before. required: false style: form explode: true schema: type: string format: uuid - name: status in: query description: Fetch a list of jobs for a specific status. required: false deprecated: true style: form explode: true schema: type: string nullable: true enum: - pending - in_progress - failed - completed - completed_with_errors - name: statuses in: query description: Fetch a list of jobs for specific statuses. required: false style: form explode: true schema: type: array items: type: string enum: - pending - in_progress - failed - completed - completed_with_errors - name: before in: query description: Lower bound of the page of data to return (cannot be used together with [after] or [offset]). required: false style: form explode: true schema: pattern: ^[A-Z2-7=~]+$ type: string - name: after in: query description: Upper bound of the page of data to return (cannot be used together with [before] or [offset]). required: false style: form explode: true schema: pattern: ^[A-Z2-7=~]+$ type: string - name: offset in: query description: Offset of the page of data to return (cannot be used together with [before] or [after]). required: false style: form explode: true schema: minimum: 0 type: integer format: int64 - name: limit in: query description: The maximum amount of items to return. required: false style: form explode: true schema: minimum: 0 type: integer format: int32 - name: sorting_keys in: query description: The keys to sort the results by. required: false style: form explode: true schema: type: array items: type: string - name: sorting_order in: query description: The order to sort the results by. Must be the same length as [sortingKeys]; one order per key. required: false style: form explode: true schema: type: array items: $ref: '#/components/schemas/PageOrder' responses: '200': description: List of export jobs. If no jobs are found, an empty list is returned. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/CursorPaginatedResponseExportJob' post: tags: - Export API (v2) summary: Create a new export job description: Use this endpoint to create a new export job that would transfer a list of specific accounting entries from Pleo to the target ERP/accounting system. operationId: createExportJobV2 requestBody: content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/CreateExportJob' responses: '201': description: Export job created successfully. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/DataResponseExportJob' '409': description: An export job is already in progress for this specific company. You cannot create a new export job until the current one has finished. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExceptionInfo' example: type: EXPORT_ALREADY_IN_PROGRESS message: Export Job already in progress for this company. /v2/export-jobs/{jobId}: get: tags: - Export API (v2) summary: Get an Export Job description: Retrieve an export job by a specific export job ID. operationId: getExportJobByIdV2 parameters: - name: jobId in: path required: true style: simple explode: false schema: type: string description: Enter the specific export job ID that you are looking for. format: uuid responses: '200': description: Export job found. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/DataResponseExportJob' '404': description: Export job not found. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExceptionInfo' example: type: EXPORT_NOT_FOUND message: Export job not found. /v2/export-jobs/{jobId}/items: get: tags: - Export API (v2) summary: Get Export Job Items description: 'An export job item tracks the export progress of a specific accounting entry in an export job. Use this endpoint to retrieve a list of export job items that you want to track.' operationId: getExportJobItemsV2 parameters: - name: jobId in: path required: true style: simple explode: false schema: type: string description: Enter the specific export job ID to retrieve details about the job items included in this export job. format: uuid - name: status in: query description: Enter a specific status with which the list of export job items returned conforms. required: false style: form explode: true schema: type: string nullable: true enum: - pending - in_progress - failed - successful - abandoned - name: before in: query description: Lower bound of the page of data to return (cannot be used together with [after] or [offset]). required: false style: form explode: true schema: pattern: ^[A-Z2-7=~]+$ type: string - name: after in: query description: Upper bound of the page of data to return (cannot be used together with [before] or [offset]). required: false style: form explode: true schema: pattern: ^[A-Z2-7=~]+$ type: string - name: offset in: query description: Offset of the page of data to return (cannot be used together with [before] or [after]). required: false style: form explode: true schema: minimum: 0 type: integer format: int64 - name: limit in: query description: The maximum amount of items to return. required: false style: form explode: true schema: minimum: 0 type: integer format: int32 - name: sorting_keys in: query description: The keys to sort the results by. required: false style: form explode: true schema: type: array items: type: string - name: sorting_order in: query description: The order to sort the results by. Must be the same length as [sortingKeys]; one order per key. required: false style: form explode: true schema: type: array items: $ref: '#/components/schemas/PageOrder' responses: '200': description: Export job items found. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/CursorPaginatedResponseExportJobItem' '404': description: Export job not found. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExceptionInfo' example: type: EXPORT_NOT_FOUND message: Export job not found. put: tags: - Export API (v2) summary: Update Export Job Items description: Update the status and other attributes of the export job items in batches of 100. This API only supports updating up to 100 items. operationId: updateExportJobItemsV2 parameters: - name: jobId in: path required: true style: simple explode: false schema: type: string description: Export Job ID format: uuid requestBody: content: application/json;charset=UTF-8: schema: type: array items: $ref: '#/components/schemas/UpdateExportJobItem' responses: '200': description: Export job items updated successfully. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExportJobItemUpdate' '404': description: Export job not found. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExceptionInfo' example: type: EXPORT_NOT_FOUND message: Export job not found. '413': description: Number of items to update is more than 100. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExceptionInfo' example: type: EXPORT_JOB_ITEMS_UPDATE_LIMIT message: Number of items to update is more than 100. '422': description: Export job is finished. content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExceptionInfo' example: type: EXPORT_JOB_STATUS_UNPROCESSABLE message: Export job is finished. components: schemas: CursorPaginatedResponseExportJobItem: required: - data - pagination type: object properties: data: type: array items: $ref: '#/components/schemas/ExportJobItem' pagination: $ref: '#/components/schemas/CursorPageInfo' ExportJobItemUpdateError: required: - accountingEntryId - message - type type: object properties: accountingEntryId: type: string description: Accounting entry ID for which this error occurred. format: uuid message: type: string description: Descriptive error message. type: type: string description: Descriptive error type. enum: - ACCOUNTING_ENTRY_DOES_NOT_EXIST - EXPORT_ENTRY_STATUS_UPDATE_FAILED - ACCOUNTING_ENTRY_UPDATE_FAILED description: If any errors occurred in updating the export job items, they will be listed here. ExceptionInfo: required: - type type: object properties: message: type: string type: type: string ExportJob: required: - companyId - createdAt - expiresIn - id - isInteractive - numberOfItems - status - vendorBasedBookkeeping type: object properties: companyId: type: string description: The Pleo unique identifier of the company the export job belongs to. format: uuid completedAt: pattern: YYYY-MM-DDTHH:mi:ssZ type: string description: Date and time when the export job was completed. format: date-time nullable: true createdAt: pattern: YYYY-MM-DDTHH:mi:ssZ type: string description: Date and time when the export job was initiated by the user, that is, when the user clicked the Export button in the Pleo application. format: date-time createdBy: type: string description: This is the Pleo unique identifier of the user that initiated the export job. format: uuid nullable: true default: null expiredAt: pattern: YYYY-MM-DDTHH:mi:ssZ type: string description: Date and time when the export job expired. format: date-time nullable: true expiresIn: type: integer description: This is the time specified in seconds when the job would expire; this is calculated since the last action performed on the job. The last time an action was taken on the job is reflected in the lastUpdatedAt attribute. format: int32 failureReason: type: string description: Reason why the job failed in the case of a failure. nullable: true failureReasonType: type: string description: The classification for the failure from a list of described failure reason types. nullable: true enum: - invalid_configuration - missing_configuration - authentication_failure - accounting_system_authentication_failure - pleo_rate_limit - accounting_system_rate_limit - service_unreachable - accounting_system_unreachable - validation_failure - authorization_failure - integration_unusable - job_expired - service_timeout - accounting_system_timeout - canceled_by_user id: type: string description: The unique identifier generated by Pleo for the export job. format: uuid isInteractive: type: boolean description: Indicates whether the export job was initiated by a user or by the system. lastUpdatedAt: pattern: YYYY-MM-DDTHH:mi:ssZ type: string description: Last time the job was updated or action on the job was taken. format: date-time nullable: true numberOfItems: type: integer description: Number of accounting entries that were selected for processing. startedAt: pattern: YYYY-MM-DDTHH:mi:ssZ type: string description: Date and time when the export job was started - this indicates the time when the export job event was triggered to change the status of the export job to in_progress. format: date-time nullable: true status: type: string description: Specifies the current execution state of the export job. Some here are the definitions of the values that are supported for this field. enum: - pending - in_progress - failed - completed - completed_with_errors vendorBasedBookkeeping: type: boolean description: When enabled, the export items would include vendor and bookkeeping data ExportJobItemUpdate: required: - data - errors type: object properties: data: type: array items: $ref: '#/components/schemas/ExportJobItem' errors: type: array description: If any errors occurred in updating the export job items, they will be listed here. items: $ref: '#/components/schemas/ExportJobItemUpdateError' CursorPaginatedResponseExportJob: required: - data - pagination type: object properties: data: type: array items: $ref: '#/components/schemas/ExportJob' pagination: $ref: '#/components/schemas/CursorPageInfo' CreateExportJobEvent: required: - event - jobId type: object properties: event: $ref: '#/components/schemas/ExportJobEventType' failureReason: type: string description: Reason why the job failed in the case of a failure. Include this only when the export job event has a `failed` status. failureReasonType: $ref: '#/components/schemas/ExportJobFailureReasonType' jobId: type: string description: Identifier of the job the event is to be processed for. format: uuid UpdateExportJobItem: required: - accountingEntryId - status type: object properties: accountingEntryId: type: string description: ID of the accounting entry being updated. format: uuid exportedAt: pattern: YYYY-MM-DDTHH:mi:ssZ type: string description: Date and time when the export job was initiated. format: date-time externalId: type: string description: The accounting system identifier of the entry after export. externalUrl: type: string description: URL to access the resource of the entry in the accounting system. failureReason: type: string description: Detailed message explaining the failure. failureReasonType: type: string description: If the export of this accounting entry failed, specify the failure reason type. enum: - receipt_upload_failure - receipt_download_failure - receipt_file_size_limit_exceeded - receipt_conversion_failure - unexpected_failure - invalid_configuration - missing_configuration - accounting_system_authentication_failure - accounting_system_rate_limit - accounting_system_unreachable - validation_failure - accounting_system_validation_failure - authorization_failure - accounting_system_timeout status: type: string description: Status of the export Item after being processed. enum: - pending - in_progress - failed - successful - abandoned ExportJobEventType: type: string description: ' | Value | Description | | ------ | ----------- | | started | The integration has started processing the job. | | failed | The job has failed due to a connection error, authentication failure, or similar issue. | | completed | The job has been successfully processed. | | completed_with_errors | The job has been completed, but only some accounting entries were exported successfully. |' enum: - started - failed - completed - completed_with_errors ExportJobFailureReasonType: type: string description: ' | Value | Description | | ------ | ----------- | | invalid_configuration | This would define a failure reason pertaining to invalid configuration needed to complete the export job or interact with the accounting system. | | missing_configuration | This would define a failure reason pertaining to incomplete configuration needed to complete the export job or interact with the accounting system. | | authentication_failure | Pleo API failed to authenticate with the integration service when sending off a WebHook API call. | | accounting_system_authentication_failure | Integration service could not authenticate with the accounting system. | | pleo_rate_limit | Irrecoverable rate limit issue with Pleo API. | | accounting_system_rate_limit | Irrecoverable rate limit issue with the accounting system. | | service_unreachable | Integration service unreachable. | | accounting_system_unreachable | Integration service unable to reach accounting system. | | validation_failure | Irrecoverable validation error making the job unprocessable. | | authorization_failure | Authorisation revoked or user no longer has access in the accounting system. | | integration_unusable | Integration service blocked or unusable for the customer. | | job_expired | Job not updated within expiry time limit. | | service_timeout | Irrecoverable timeout communicating with integration service. | | accounting_system_timeout | Irrecoverable timeout communicating with accounting system. | | canceled_by_user | Job was canceled by user. |' enum: - invalid_configuration - missing_configuration - authentication_failure - accounting_system_authentication_failure - pleo_rate_limit - accounting_system_rate_limit - service_unreachable - accounting_system_unreachable - validation_failure - authorization_failure - integration_unusable - job_expired - service_timeout - accounting_system_timeout - canceled_by_user ExportJobItem: required: - accountingEntryId - exportJobId - status type: object properties: accountingEntryId: type: string description: The accounting entry identifier being exported. format: uuid exportJobId: type: string description: The export job identifier for which this item belongs to. format: uuid exportedAt: pattern: YYYY-MM-DDTHH:mi:ssZ type: string description: Date and time the item was exported. format: date-time nullable: true externalId: type: string description: This is an external identifier of the corresponding accounting entry in the accounting system after export. nullable: true externalUrl: type: string description: This is the external URL pointing to the accounting entry resource in the accounting system after the export. nullable: true failureReason: type: string description: Reason why the export of this item failed in the case of a failure. nullable: true failureReasonType: type: string description: The classification for the failure from a list of described failure reason types. nullable: true enum: - receipt_upload_failure - receipt_download_failure - receipt_file_size_limit_exceeded - receipt_conversion_failure - unexpected_failure - invalid_configuration - missing_configuration - accounting_system_authentication_failure - accounting_system_rate_limit - accounting_system_unreachable - validation_failure - accounting_system_validation_failure - authorization_failure - accounting_system_timeout status: type: string description: Status of the export job Item after being processed. The status of the export job item is null until an attempt has been made to process the export job item. enum: - pending - in_progress - failed - successful - abandoned CursorPageInfo: required: - currentRequestPagination - hasNextPage - hasPreviousPage type: object properties: currentRequestPagination: $ref: '#/components/schemas/CursorPageCurrentRequestInfo' endCursor: type: string hasNextPage: type: boolean hasPreviousPage: type: boolean startCursor: type: string total: type: integer format: int64 Options: type: object properties: vendorBasedBookkeeping: type: boolean description: When enabled, the export items will include vendor and bookkeeping data. nullable: true default: false description: Provides additional configurations for the export job. nullable: true CreateExportJob: required: - accountingEntryIds - companyId type: object properties: accountingEntryIds: type: array description: The IDs of accounting entries that you want to include in the export job for transmission. items: type: string description: The IDs of accounting entries that you want to include in the export job for transmission. format: uuid companyId: type: string description: The unique company ID for which you want to create the export job. format: uuid employeeId: type: string description: This is the Pleo unique identifier of the user that initiated the export job. format: uuid nullable: true isInteractive: type: boolean description: Non-interactive jobs are jobs that are not initiated by a user. These jobs are usually triggered in the background and require no user interaction. Interactive jobs are the opposite. Set this flag to true if the export job is to be initiated by a user. By default, this is set to true. nullable: true default: true options: $ref: '#/components/schemas/Options' DataResponseExportJob: required: - data type: object properties: data: $ref: '#/components/schemas/ExportJob' CursorPageCurrentRequestInfo: required: - parameters type: object properties: after: type: string before: type: string limit: type: integer format: int32 offset: type: integer format: int64 parameters: type: object additionalProperties: type: array items: type: string sortingKeys: type: array items: type: string sortingOrder: type: array items: $ref: '#/components/schemas/PageOrder' PageOrder: type: string enum: - ASC - ASC_NULLS_FIRST - ASC_NULLS_LAST - DESC - DESC_NULLS_FIRST - DESC_NULLS_LAST securitySchemes: bearerAuth: type: http description: 'JWT Bearer token authentication. Include the token in the Authorization header as: `Bearer `' scheme: bearer bearerFormat: JWT basicAuth: type: http description: Basic HTTP authentication using API key. Use your API key as the username and leave the password empty. The credentials will be Base64 encoded automatically. scheme: basic