openapi: 3.0.1
info:
  title: documents_network API
  description: Merged OpenAPI spec for documents_network domain
  version: 1.0.0
servers:
- description: ''
  url: https://api.uat.btx.fr.banqup.com/documents/network
- description: ''
  url: https://api.uat.btx.eu.banqup.com/documents/network
paths:
  /transaction/v1/spaces/{spaceId}/documents/{documentId}/relations:
    get:
      tags:
      - Documents
      summary: Get list of document relations
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Get list of document relations on the given space, with the option to
        filter out the result. <br/> Scope: space_read"
      operationId: getAllDocumentRelations
      parameters:
      - name: spaceId
        in: path
        description: The space identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: documentId
        in: path
        description: The document identifier
        required: true
        schema:
          type: string
          format: uuid
        example: 1d0159ca-ab19-49d5-9e13-9d34afb03849
      - name: list
        in: query
        description: Filter specific relation
        schema:
          type: string
          enum:
          - parents
          - children
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllDocumentRelationsResult'
              example:
                documentRelations:
                  parents:
                  - id: a17ba374-e2cf-4858-8b0a-6c42a3165125
                    document:
                      id: 0ca2797b-6365-4bf2-a490-247075e3cede
                      description: Sample Invoice 1
                      folder: SALES
                      category: INVOICE
                      documentNumber: INV-001
                  - id: 9aa597ce-803b-4d85-ac0a-1bff4432573c
                    document:
                      id: 0a0eaf40-58e0-4164-a915-66bc591b24a0
                      description: Sample Invoice 2
                      folder: SALES
                      category: INVOICE
                      documentNumber: INV-002
                  children:
                  - id: 88f803f1-6523-488d-97d2-cb4f262ee9d5
                    document:
                      id: a51bdf43-b4d0-4e70-bd6a-309c1071ee37
                      description: Sample Delivery Note
                      folder: SALES
                      category: CREDIT_NOTE
                      documentNumber: DN-003
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_read
    post:
      tags:
      - Documents
      summary: Create document relations
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Create document relations for given document <br/> Scope: space_write"
      operationId: createDocumentRelations
      parameters:
      - name: spaceId
        in: path
        description: The space identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: documentId
        in: path
        description: The document identifier
        required: true
        schema:
          type: string
          format: uuid
        example: 1d0159ca-ab19-49d5-9e13-9d34afb03849
      requestBody:
        description: Document relations to create. Requires at list one of 'parent'
          or 'children' list.
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/CreateDocumentRelationsRequest'
            examples:
              Document relations:
                description: Document relations
                value:
                  parents:
                  - 249edc81-f652-4117-bfe3-b5aa18688cc1
                  - 3432c22-f652-4117-bfe3-b5aa18a3742a2
                  children:
                  - 4f006378-3e55-4cba-8bd1-5e0e78ab468e
                  - 5cf7f2aa-a3b6-4dc5-88b9-707ce2d2988f
        required: true
      responses:
        '200':
          description: At least one succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDocumentRelationsResult'
              examples:
                Partial success:
                  description: Partial success
                  value:
                    success:
                    - 249edc81-f652-4117-bfe3-b5aa18688cc1
                    - 4f006378-3e55-4cba-8bd1-5e0e78ab468e
                    - 5cf7f2aa-a3b6-4dc5-88b9-707ce2d2988f
                    failure:
                    - 3432c22-f652-4117-bfe3-b5aa18a3742a2
        '400':
          description: Bad request body or all relation creations failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
  /transaction/v1/spaces/{spaceId}/documents/{documentId}/relations/{relationId}:
    delete:
      tags:
      - Documents
      summary: Delete document relation
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Delete document relation by id on the given space <br/> Scope: space_write"
      operationId: deleteDocumentRelation
      parameters:
      - name: spaceId
        in: path
        description: The space identifier
        required: true
        schema:
          type: string
          format: uuid
      - name: documentId
        in: path
        description: The document identifier
        required: true
        schema:
          type: string
          format: uuid
        example: 1d0159ca-ab19-49d5-9e13-9d34afb03849
      - name: relationId
        in: path
        description: The document relation identifier
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Ok.
        '404':
          description: UUID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27 12:34:50+00:00
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
      security:
      - oauth2:
        - space_write
components:
  schemas:
    JsonBMap:
      type: object
      additionalProperties: true
    JsonBMapNullable:
      type: object
      additionalProperties: true
      nullable: true
    PatchRequest:
      type: array
      items:
        $ref: '#/components/schemas/PatchDocument'
    PatchDocument:
      required:
      - op
      - path
      type: object
      properties:
        op:
          type: string
          description: The operation to be performed
          enum:
          - add
          - remove
          - replace
          - move
          - copy
          - test
        path:
          type: string
          description: A JSON-Pointer
        value:
          type: object
          description: The value to be used within the operations.
        from:
          type: string
          description: A string containing a JSON Pointer value.
      description: A JSONPatch document as defined by RFC 6902
    CreateDocumentRelationsResult:
      type: object
      properties:
        success:
          type: array
          description: List of successfully linked document ids
          items:
            type: string
            description: Document id
            format: uuid
        failure:
          type: array
          description: List of document ids that failed to link
          items:
            type: string
            description: Document id
            format: uuid
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
    CreateDocumentRelationsRequest:
      type: object
      properties:
        parents:
          type: array
          description: List of parent ids
          items:
            type: string
            description: Parent document id
            format: uuid
        children:
          type: array
          description: List of child ids
          items:
            type: string
            description: Child document id
            format: uuid
    AllDocumentRelationsResult:
      type: object
      properties:
        documentRelations:
          $ref: '#/components/schemas/DocumentRelationsResult'
    DocumentCategory:
      type: string
      description: Document category
      example: PURCHASE_ORDER
      enum:
      - PURCHASE_ORDER
      - ORDER_CONFIRMATION
      - DELIVERY_NOTE
      - GOODS_RECEIVED_NOTE
      - PROFORMA_INVOICE
      - INVOICE
      - INVOICE_REMINDER
      - CREDIT_NOTE
      - RECEIPT
      - STATEMENT
      - FILE
      - QUOTE
      - CREDIT_CARD_STATEMENT
      - THIRD_PARTY_STATEMENT
      - SELF_BILLED_INVOICE
      - SELF_BILLED_CREDIT_NOTE
      - OTHER
    DocumentRelationResult:
      type: object
      properties:
        id:
          type: string
          description: Payment account ID
          format: uuid
        document:
          $ref: '#/components/schemas/RelatedDocumentResult'
    DocumentRelationsResult:
      type: object
      properties:
        parents:
          type: array
          description: List of response entities
          items:
            $ref: '#/components/schemas/DocumentRelationResult'
        children:
          type: array
          description: List of response entities
          items:
            $ref: '#/components/schemas/DocumentRelationResult'
      description: Document relations
    Folder:
      type: string
      description: Document folder
      example: PURCHASES
      enum:
      - AP
      - AR
      - PURCHASES
      - SALES
      - DRAFTS
      - INBOX
      - STATEMENTS
      - FILES
    RelatedDocumentResult:
      required:
      - category
      type: object
      properties:
        id:
          type: string
          description: Document ID
          format: uuid
        description:
          type: string
          description: Document description
          example: Sample invoice 1
        folder:
          $ref: '#/components/schemas/Folder'
        category:
          $ref: '#/components/schemas/DocumentCategory'
        documentNumber:
          type: string
          description: Document number from document metadata
          example: INV-001
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.uat.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.uat.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.uat.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
tags:
- name: Spaces
  description: "Spaces are virtual environments (work spaces) where all relevant resources
    of an entity are managed.  Spaces can also facilitate document exchange and communication
    among entities, depending on the space type.\nThe role of spaces is to gather
    all relevant data of an entity into one accessible setting.  Such data can include:
    invoices, connections, cards, clients, payments, users, installed apps etc.  The
    capabilities offered by a space depends on the space type and the active subscription."
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Files
  description: A file refers to the digital container that stores the data of one
    or more documents.  Files are the medium through which electronic documents are
    stored, transmitted, and accessed.
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Documents
  description: "A document in e-invoicing refers to a formal, structured piece of
    information that contains details  related to invoicing: e.g financial data, payment
    details, tax information etc. or any other information  relevant to the company's
    operations, services, or interactions with clients and partners.\nEvery Banqup
    document is associated with a unique UUID that is stored in the Banqup database
    as documentId.  The UUID is generated when a new file is received/uploaded into
    Banqup and is necessary when performing  document actions via the Banqup APIs."
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Connections
  description: 'Connections are business and persons in the private address book of
    a space and they represent the actors involved  in document exchange, such as:
    customers, suppliers, accountants, partners, groups.'
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Payments
  description: A payment is a generic term for the business event of transferring
    funds from one party to another.
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Payment Accounts
  description: "Payment accounts are bank or financial accounts used for managing
    payments, deposits, withdrawals, and transfers. \nThe Payment Accounts of a space
    are all bank or financial account the business represented by the space interacts
    with via e-invoicing or payments."
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Payment Information
  description: "Payment Information representing some sort of evidence related to
    a Payment.\nThis evidence could be in different forms :\n  - PaymentTransaction
    : information related to a payment of which the transaction (initiation) \n  \
    \                       was started on platform.\n  - BookedPaymentMovement :
    information imported from your own account indicating a payment movement was booked.
    \n  - PlannedPaymentMovement : information imported from your own account indicating
    an amount was reserved \n                         for a future payment.\n  - ManualPaymentInformation
    : information about a payment that was manually entered by a user of the platform.\n\
    \  - CounterpartyPaymentInformation : information added to your space about a
    payment which was based on the \n                         PaymentInformation the
    counter party of the payment indicated on BTX platform."
  x-BTX:
    unDocumented: 'false'
    internal: 'false'
- name: Internal Payments
  description: "This is a set of internal API call only intended to be used by BTX
    Payment Service or Aggregation Service. They are restricted to ensure that updates
    on payments, payment information and links to documents (BalanceOffset)  are done
    in consistent way.  \nThe higher level public APIs for adding payment, payment
    information and linking payments to documents  will be provided by the BTX Payment
    Service or Aggregation Service."
  x-BTX:
    unDocumented: 'false'
    internal: 'true'
- name: Internal
  description: This is a set of pure internal API.  It contains for example callback
    endpoints that get registered to receive messages.
  x-BTX:
    unDocumented: 'true'
    internal: 'true'
