Paperless Parts Integration Actions API

openapi: 3.2.0
info:
  title: Paperless Parts Integration Actions API
  description: 'The Paperless Parts API provides access to your data, enabling developers to easily integrate Paperless Parts with third-party systems, such as Customer Relationship Management (CRM) and Enterprise Resource Planning (ERP) tools. The API is designed to support two primary use case. First, reading all information associated with a particular order or quote for import into another system. Second, managing customer data, either for an initial bulk import or for on-going synchronization with an external database.

    ## Authorization ##

    Requests are authorized via an API key. Administrators of a Paperless Parts account can generate an API Token which grants access to all of the endpoints documented here. The token obtained from the application must be added to the header of all requests using the key `"Authorization"` with the value `"API-Token <api_token>"`, where `<api_token>` is your Paperless Parts API Token.


    You can use the "Execute" button in an endpoint''s documentation on this page to try out the endpoint. This will send a request to the endpoint on the Paperless Parts server and display the result on this page. Before doing so, however, you''ll need to click on the ''Authorize'' button at the top of the screen, and in the "Value" field enter `"API-Token <api_token>"`, where `<api_token>` is your API token as described above.


    ## Overview ##

    The API endpoints are organized around REST. API calls should be made to the `https://api.paperlessparts.com` base domain. URLs are designed to clearly describe an entity or collection of entities. HTTP verbs typically describe whether entities are being read, created, modified, or deleted. Where applicable, request and response bodies are in JSON format. Standard HTTP response codes, in addition to error messages, are used to help explain request failures.

    ### Associations

    Many entities in the API data model are associated with other entities. As a guiding principle, `GET` requests that fetch data nest associated entities in the JSON response. However, when creating or modifying entities, a flat (non-nested) object must be provided, as explained in the documentation for each endpoint. Associations are specified when writing data by using entity IDs in fields ending in `_id`.


    For example, consider the relationship where a Company has many Customers. When fetching a Customer via a `GET` request, the associated Company will be nested as an object with key `company` in the response. When creating a Customer, the Company is specified via its integer id using the key `company_id`.

    ### Events Overview

    Events are a way of logging relevant actions that are taken within your account. For instance, when you create a new quote, Paperless Parts logs a `quote.created` event, and once you send that quote, we log another `quote.sent` event.


    These logs offer you a trail of data that you can use to keep integrations in sync. By polling for new events, you can maintain an up-to-date record of what actions Paperless Parts has initiated that your integration has not. For instance, you could poll for `part.interrogation_succeeded` events and send out a notification upon receiving one.

    ### HTTP Methods

    The API endpoints support different HTTP methods depending on whether records are being read, created, or updated. To read an entity, use `GET`. To create a new entity, use `POST`. To modifying an entity, use `PATCH`. Note, `PATCH` is used rather than `PUT` to indicate that entities can be partially updated. In other words, in general, if a field is omitted from a `PATCH` request, that field''s value will stay the same (rather than be set to `null`). All fields requiring values are required to be included in `POST` requests.

    > Note: Endpoints with a documented `PATCH` method can generally be used with a `PUT` method. The `PUT` is implemented as a partial update (as opposed to a replacement) and is supported for maximum compatibilty.


    For example, consider the `email` field on the Customer entity, which is required. All Customers must have a non-null `email`. When creating a Customer via `POST`, the request body must contain an `email` key and its value cannot be `null` (other validation applies to that field, as well, including a valid email format and a unique value). When editing a Customer via `PATCH` request, it is not necessary to include an `email` key in the request body. If `email` is omitted, the existing email address will not be changed. If you send a `PATCH` request with `email=null`, then you will receive an error response indicating that a value for `email` is required.'
  version: '1.0'
  termsOfService: https://www.paperlessparts.com/web-service-agreement/
  contact:
    name: Paperless Parts
    url: https://www.paperlessparts.com
    email: support@paperlessparts.com
servers:
- url: '{url}/{version}'
  variables:
    url:
      default: https://api.paperlessparts.com
    version:
      default: v1
security:
- app_id: []
tags:
- name: Integration Actions
  description: Endpoints for interacting with ERP integrations
paths:
  /managed_integrations/public:
    get:
      summary: Returns a list of managed integrations
      description: Returns a list of managed integrations. Use the UUID provided from the managed integration to create integration actions
      operationId: ListManagedIntegrations
      tags:
      - Integration Actions
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ManagedIntegrationDetails'
        404:
          description: Not found response
          content:
            text/plain:
              schema:
                title: Managed integrations not found
                type: string
                example: 'Error: Not Found'
    post:
      summary: Create managed integration
      description: Creates a new managed integration. This is required to later create integration actions
      operationId: CreateManagedIntegration
      tags:
      - Integration Actions
      responses:
        201:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedIntegrationDetails'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedIntegration'
  /managed_integrations/public/{managed_integration_uuid}:
    get:
      summary: Get managed integration details
      description: Get the details for a managed integration
      operationId: GetManagedIntegration
      parameters:
      - in: path
        name: managed_integration_uuid
        schema:
          type: string
        required: true
        description: The unique identifier for the managed integration to be returned
      tags:
      - Integration Actions
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedIntegrationDetails'
        404:
          description: Not found response
          content:
            text/plain:
              schema:
                title: Integration action with that action uuid not found
                type: string
                example: 'Error: Not Found'
    patch:
      summary: Update fields on a managed integration
      description: Update fields on a managed integration. Cannot update UUID or erp_name
      operationId: UpdateManagedIntegration
      parameters:
      - in: path
        name: managed_integration_uuid
        schema:
          type: string
        required: true
        description: The unique identifier for the managed integration to be returned
      tags:
      - Integration Actions
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedIntegrationDetails'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                is_active:
                  type: boolean
                  example: true
                  description: whether the integration is active
                erp_name:
                  type: string
                  example: JobBOSS
                  description: The name of the ERP system being integrated with
                erp_version:
                  type: string
                  example: '1.0'
                  description: The version of the ERP system being integrated with
                integration_version:
                  type: string
                  example: '1.0'
                  description: The version of the codebase processing the integration
                create_integration_action_after_creating_new_order:
                  type: boolean
                  example: true
                  description: Whether a new integration action should be created after a new order is faciliated in Paperless
                create_integration_action_after_quote_sent:
                  type: boolean
                  example: true
                  description: Whether a new integration action should be created after a new quote is sent in Paperless
  /managed_integrations/public/{managed_integration_uuid}/heartbeat:
    post:
      summary: Post an integration heartbeat
      description: Post to confirm that the integration is still active
      operationId: PostManagedIntegrationHeartbeat
      parameters:
      - in: path
        name: managed_integration_uuid
        schema:
          type: string
        required: true
        description: The unique identifier for the managed integration whose heartbeat is being recorded
      tags:
      - Integration Actions
      responses:
        201:
          description: Successful response
  /managed_integrations/public/{managed_integration_uuid}/integration_actions:
    get:
      summary: Returns a list of integration actions
      description: Returns a list of integration actions available to be used for ERP integrations.
      operationId: ListIntegrationActions
      parameters:
      - in: path
        name: managed_integration_uuid
        schema:
          type: string
        required: true
        description: The unique identifier for the managed integration whose integration actions you would like
      - in: query
        name: status_in
        schema:
          type: string
        required: false
        description: Value used to search for only integrations that currently have a certain status. Valid options are queued, in_progress, completed, cancelled, failed, or timed_out
      - in: query
        name: type_in
        schema:
          type: string
        required: false
        description: Value used to search for only integrations that currently have a certain type. Valid options are export_order, export_quote, import_purchased_component, import_work_center, import_vendor, import_material, or import_account
      - in: query
        name: page
        schema:
          type: string
        required: false
        description: The page of results to return.
      tags:
      - Integration Actions
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IntegrationAction'
        404:
          description: Not found response
          content:
            text/plain:
              schema:
                title: Integration actions not found
                type: string
                example: 'Error: Not Found'
    post:
      summary: Create new integration action
      parameters:
      - in: path
        name: managed_integration_uuid
        schema:
          type: string
        required: true
        description: The unique identifier for the managed integration whose integration action you would like
      description: Creates a new integration action
      operationId: CreateIntegrationAction
      tags:
      - Integration Actions
      responses:
        201:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationAction'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  example: export_order
                  description: the type of action being requested
                entity_id:
                  type: string
                  example: '8'
                  description: The identifier for the entity that should be processed as part of the action. For example, process order 8
  /integration_actions/public/{integration_action_uuid}:
    get:
      summary: Get integration action details
      description: Get the details for a specific integration action.
      operationId: Get integration action details
      parameters:
      - in: path
        name: integration_action_uuid
        schema:
          type: string
        required: true
        description: The unique identifier for the integration action to be returned
      tags:
      - Integration Actions
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationAction'
        404:
          description: Not found response
          content:
            text/plain:
              schema:
                title: Integration action with that action uuid not found
                type: string
                example: 'Error: Not Found'
    patch:
      summary: Update fields on an integration action
      description: Update fields on an integration action.
      operationId: UpdateOrder
      parameters:
      - in: path
        name: integration_action_uuid
        schema:
          type: string
        required: true
        description: The unique identifier for the integration action to be returned
      tags:
      - Integration Actions
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationAction'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: in_progress
                  description: the new status of the integration action
                status_message:
                  type: string
                  example: The order 8 is now processing
                  description: The new status message for the integration
components:
  schemas:
    ManagedIntegrationDetails:
      allOf:
      - $ref: '#/components/schemas/ManagedIntegration'
    IntegrationAction:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        type:
          type: string
          example: export_order
          description: the type of action being requested
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
        current_record_count:
          type: integer
        last_checkin:
          type:
          - string
          - 'null'
          format: date-time
        related_object:
          type:
          - string
          - 'null'
        related_object_type:
          type: string
        status:
          type: string
          example: in_progress
          description: The current status of the action
        status_message:
          type: string
          example: Order 8 is currently being processed
        entity_id:
          type: string
          example: '8'
          description: The identifier for the entity that should be processed as part of the action. For example, process order 8
    ManagedIntegrationLogo:
      type: object
      properties:
        original:
          type:
          - string
          - 'null'
          format: uri
        thumbnail:
          type:
          - string
          - 'null'
          format: uri
    ManagedIntegration:
      type: object
      properties:
        uuid:
          type: string
        updated:
          type: string
          format: date-time
        author:
          type: string
          example: John Doe
          description: The creator of this integration
        category:
          type: string
          example: ERP
          description: The category of tool that this integration belongs to
        configuration_parameters:
          type: object
        description:
          type: string
          example: Connecting other shop software to Paperless Parts
          description: A short description for the integration
        developed_by_paperless_parts:
          type: boolean
          example: true
          description: A boolean reflecting whether the integration was created by Paperless Parts
        erp_name:
          type: string
        erp_version:
          type: string
        icc_setup_complete:
          type: boolean
        icc_ssh_tunnel_status:
          type:
          - string
          - 'null'
        icc_ssh_tunnel_status_expiration:
          type:
          - string
          - 'null'
          format: date-time
        integrated_software_name:
          type: string
          example: JobBOSS²
          description: The name of the integration
        integrated_software_version:
          type: integer
          example: The version of the codebase processing the integration
          description: '1.0'
        integration_template_id:
          type:
          - integer
          - 'null'
        integration_version:
          type: integer
          example: The version of the codebase processing the integration
          description: '1.0'
        internal_productized_name:
          type:
          - string
          - 'null'
        is_active:
          type: string
          example: Whether the integration is active
          description: 'True'
        is_icc_compatible:
          type: boolean
        is_icc_enabled:
          type: boolean
        locator:
          type:
          - string
          - 'null'
        logo:
          $ref: '#/components/schemas/ManagedIntegrationLogo'
        name:
          type: string
          example: JobBOSS²
          description: The name of the integration
        release_channel:
          type: string
        status:
          type: string
          example: up
          description: Either 'up' or 'down', reflecting the health of the integration
        support_contact:
          type: string
          example: support@paperlessparts.com
          description: A contact to reach out to for support on this integration
  securitySchemes:
    app_id:
      type: apiKey
      description: API key to authorize requests.
      name: Authorization
      in: header