feat: custom invoicing api

api/openapi.yaml

@@ -665,6 +665,201 @@ paths:
                 $ref: '#/components/schemas/UnexpectedProblemResponse'
       tags:
         - Apps
+  /api/v1/apps/custom-invoicing/{invoiceId}/draft/synchronized:
+    post:
+      operationId: appCustomInvoicingDraftSynchronized
+      summary: Submit draft synchronization results
+      parameters:
+        - name: invoiceId
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: ^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$
+            example: 01G65Z755AFWAKHE12NY0CQ9FH
+      responses:
+        '204':
+          description: 'There is no content to send for this request, but the headers may be useful. '
+        '400':
+          description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/BadRequestProblemResponse'
+        '401':
+          description: The request has not been applied because it lacks valid authentication credentials for the target resource.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/UnauthorizedProblemResponse'
+        '403':
+          description: The server understood the request but refuses to authorize it.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ForbiddenProblemResponse'
+        '412':
+          description: One or more conditions given in the request header fields evaluated to false when tested on the server.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/PreconditionFailedProblemResponse'
+        '500':
+          description: The server encountered an unexpected condition that prevented it from fulfilling the request.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/InternalServerErrorProblemResponse'
+        '503':
+          description: The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableProblemResponse'
+        default:
+          description: An unexpected error response.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/UnexpectedProblemResponse'
+      tags:
+        - Apps
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CustomInvoicingDraftSyncronizedRequest'
+  /api/v1/apps/custom-invoicing/{invoiceId}/issuing/synchronized:
+    post:
+      operationId: appCustomInvoicingIssuingSynchronized
+      summary: Submit issuing synchronization results
+      parameters:
+        - name: invoiceId
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: ^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$
+            example: 01G65Z755AFWAKHE12NY0CQ9FH
+      responses:
+        '204':
+          description: 'There is no content to send for this request, but the headers may be useful. '
+        '400':
+          description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/BadRequestProblemResponse'
+        '401':
+          description: The request has not been applied because it lacks valid authentication credentials for the target resource.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/UnauthorizedProblemResponse'
+        '403':
+          description: The server understood the request but refuses to authorize it.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ForbiddenProblemResponse'
+        '412':
+          description: One or more conditions given in the request header fields evaluated to false when tested on the server.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/PreconditionFailedProblemResponse'
+        '500':
+          description: The server encountered an unexpected condition that prevented it from fulfilling the request.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/InternalServerErrorProblemResponse'
+        '503':
+          description: The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableProblemResponse'
+        default:
+          description: An unexpected error response.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/UnexpectedProblemResponse'
+      tags:
+        - Apps
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CustomInvoicingFinalizedRequest'
+  /api/v1/apps/custom-invoicing/{invoiceId}/payment/status:
+    post:
+      operationId: appCustomInvoicingUpdatePaymentStatus
+      summary: Update payment status
+      parameters:
+        - name: invoiceId
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: ^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$
+            example: 01G65Z755AFWAKHE12NY0CQ9FH
+      responses:
+        '204':
+          description: 'There is no content to send for this request, but the headers may be useful. '
+        '400':
+          description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/BadRequestProblemResponse'
+        '401':
+          description: The request has not been applied because it lacks valid authentication credentials for the target resource.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/UnauthorizedProblemResponse'
+        '403':
+          description: The server understood the request but refuses to authorize it.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ForbiddenProblemResponse'
+        '412':
+          description: One or more conditions given in the request header fields evaluated to false when tested on the server.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/PreconditionFailedProblemResponse'
+        '500':
+          description: The server encountered an unexpected condition that prevented it from fulfilling the request.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/InternalServerErrorProblemResponse'
+        '503':
+          description: The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableProblemResponse'
+        default:
+          description: An unexpected error response.
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/UnexpectedProblemResponse'
+      tags:
+        - Apps
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CustomInvoicingUpdatePaymentStatusRequest'
   /api/v1/apps/{id}:
     get:
       operationId: getApp
@@ -12473,6 +12668,121 @@ components:
             - $ref: '#/components/schemas/Metadata'
           description: Metadata to be used by the custom invoicing provider.
       description: Custom Invoicing Customer App Data.
+    CustomInvoicingDraftSyncronizedRequest:
+      type: object
+      properties:
+        invoicing:
+          allOf:
+            - $ref: '#/components/schemas/CustomInvoicingSyncResult'
+          description: The result of the synchronization.
+      description: Information to finalize the draft details of an invoice.
+    CustomInvoicingFinalizedInvoicingRequest:
+      type: object
+      properties:
+        invoiceNumber:
+          allOf:
+            - $ref: '#/components/schemas/InvoiceNumber'
+          description: If set the invoice's number will be set to this value.
+        sentToCustomerAt:
+          type: string
+          format: date-time
+          description: If set the invoice's sent to customer at will be set to this value.
+          example: '2023-01-01T01:01:01.001Z'
+      description: Information to finalize the invoicing details of an invoice.
+    CustomInvoicingFinalizedPaymentRequest:
+      type: object
+      properties:
+        externalId:
+          type: string
+          description: If set the invoice's payment external ID will be set to this value.
+      description: Information to finalize the payment details of an invoice.
+    CustomInvoicingFinalizedRequest:
+      type: object
+      properties:
+        invoicing:
+          allOf:
+            - $ref: '#/components/schemas/CustomInvoicingFinalizedInvoicingRequest'
+          description: The result of the synchronization.
+        payment:
+          allOf:
+            - $ref: '#/components/schemas/CustomInvoicingFinalizedPaymentRequest'
+          description: The result of the payment synchronization.
+      description: |-
+        Information to finalize the invoice.
+
+        If invoicing.invoiceNumber is not set, then a new invoice number will be generated (INV- prefix).
+    CustomInvoicingLineDiscountExternalIdMapping:
+      type: object
+      required:
+        - lineDiscountId
+        - externalId
+      properties:
+        lineDiscountId:
+          type: string
+          pattern: ^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$
+          description: The line discount ID.
+          example: 01G65Z755AFWAKHE12NY0CQ9FH
+        externalId:
+          type: string
+          description: The external ID (e.g. custom invoicing system's ID).
+      description: Mapping between line discounts and external IDs.
+    CustomInvoicingLineExternalIdMapping:
+      type: object
+      required:
+        - lineId
+        - externalId
+      properties:
+        lineId:
+          type: string
+          pattern: ^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$
+          description: The line ID.
+          example: 01G65Z755AFWAKHE12NY0CQ9FH
+        externalId:
+          type: string
+          description: The external ID (e.g. custom invoicing system's ID).
+      description: Mapping between lines and external IDs.
+    CustomInvoicingPaymentTrigger:
+      type: string
+      enum:
+        - paid
+        - payment_failed
+        - payment_uncollectible
+        - payment_overdue
+        - action_required
+        - void
+      description: Payment trigger to execute on a finalized invoice.
+    CustomInvoicingSyncResult:
+      type: object
+      properties:
+        invoiceNumber:
+          allOf:
+            - $ref: '#/components/schemas/InvoiceNumber'
+          description: If set the invoice's number will be set to this value.
+        externalId:
+          type: string
+          description: If set the invoice's invoicing external ID will be set to this value.
+        lineExternalIds:
+          type: array
+          items:
+            $ref: '#/components/schemas/CustomInvoicingLineExternalIdMapping'
+          description: |-
+            If set the invoice's line external IDs will be set to this value.
+
+            This can be used to reference the external system's entities in the
+            invoice.
+        lineDiscountExternalIds:
+          type: array
+          items:
+            $ref: '#/components/schemas/CustomInvoicingLineDiscountExternalIdMapping'
+          description: |-
+            If set the invoice's line discount external IDs will be set to this value.
+
+            This can be used to reference the external system's entities in the
+            invoice.
+      description: |-
+        Information to synchronize the invoice.
+
+        Can be used to store external app's IDs on the invoice or lines.
     CustomInvoicingTaxConfig:
       type: object
       required:
@@ -12486,6 +12796,19 @@ components:
             The tax code should be interpreted by the custom invoicing provider.
           title: Tax code
       description: Custom invoicing tax config.
+    CustomInvoicingUpdatePaymentStatusRequest:
+      type: object
+      required:
+        - trigger
+      properties:
+        trigger:
+          allOf:
+            - $ref: '#/components/schemas/CustomInvoicingPaymentTrigger'
+          description: The trigger to be executed on the invoice.
+      description: |-
+        Update payment status request.
+
+        Can be used to manipulate invoice's payment status (when custominvoicing app is being used).
     CustomPlanInput:
       type: object
       allOf: