CHNLSYNC Customer Bills API

openapi: 3.2.0
info:
  title: Chnlsync Com Customer Bills API
  version: 0.1.0
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged customer-bills across 2 of this provider''s published API definitions: chnlsync-com-openapi.json, chnlsync-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.chnlsync.dev
  description: CHNLSYNC API host advertised in https://chnlsync.com/llms.txt (servers[] absent in the served spec; added here)
tags:
- name: customer-bills
paths:
  /api/v1/customer/bills:
    get:
      tags:
      - customer-bills
      summary: Get Bills
      description: The caller's bills with open-finding counts.
      operationId: get_bills_api_v1_customer_bills_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillListRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - customer-bills
      summary: Post Bill
      description: Add a typed bill; it is checked right away.
      operationId: post_bill_api_v1_customer_bills_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customer/bills/from-artifact:
    post:
      tags:
      - customer-bills
      summary: Post Bill From Artifact
      description: Read a draft bill from one of the caller's own documents.
      operationId: post_bill_from_artifact_api_v1_customer_bills_from_artifact_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillFromArtifact'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customer/bills/{bill_id}:
    get:
      tags:
      - customer-bills
      summary: Get Bill
      description: One bill with its lines and findings.
      operationId: get_bill_api_v1_customer_bills__bill_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: bill_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Bill Id
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - customer-bills
      summary: Patch Bill
      description: Correct the header or link the service; a confirmed bill is checked again.
      operationId: patch_bill_api_v1_customer_bills__bill_id__patch
      security:
      - APIKeyHeader: []
      parameters:
      - name: bill_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Bill Id
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customer/bills/{bill_id}/lines/{line_id}:
    patch:
      tags:
      - customer-bills
      summary: Patch Bill Line
      description: Fix one line; a confirmed bill is checked again.
      operationId: patch_bill_line_api_v1_customer_bills__bill_id__lines__line_id__patch
      security:
      - APIKeyHeader: []
      parameters:
      - name: bill_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Bill Id
      - name: line_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Line Id
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillLineUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customer/bills/{bill_id}/confirm:
    post:
      tags:
      - customer-bills
      summary: Confirm Bill
      description: Confirm a draft read from a document, then check it.
      operationId: confirm_bill_api_v1_customer_bills__bill_id__confirm_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: bill_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Bill Id
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customer/bills/findings/{finding_id}/dismiss:
    post:
      tags:
      - customer-bills
      summary: Dismiss Finding
      description: Mark a finding as fine.
      operationId: dismiss_finding_api_v1_customer_bills_findings__finding_id__dismiss_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: finding_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Finding Id
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customer/bills/findings/{finding_id}/dispute:
    post:
      tags:
      - customer-bills
      summary: Dispute Finding
      description: 'Ask CHNLSYNC to dispute a finding with the provider (opens a billing request).


        Operators are paged only when this call opened the ticket; a repeat returns

        the existing one without paging again.'
      operationId: dispute_finding_api_v1_customer_bills_findings__finding_id__dispute_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: finding_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Finding Id
      - name: X-Sync2-Member
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member
      - name: X-Sync2-Member-Email
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Member-Email
      - name: X-Sync2-Company
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sync2-Company
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BillSummaryRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        provider:
          type: string
          title: Provider
        invoice_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Invoice Date
        total:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Total
        status:
          type: string
          enum:
          - draft
          - confirmed
          title: Status
        open_findings:
          type: integer
          title: Open Findings
        high_findings:
          type: integer
          title: High Findings
      type: object
      required:
      - id
      - provider
      - invoice_date
      - total
      - status
      - open_findings
      - high_findings
      title: BillSummaryRead
      description: A bill row in the list.
    BillUpdate:
      properties:
        provider:
          anyOf:
          - type: string
            maxLength: 120
            minLength: 1
          - type: 'null'
          title: Provider
        account_number:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Account Number
        invoice_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Invoice Date
        period_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Period Start
        period_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Period End
        total:
          anyOf:
          - type: number
            maximum: 100000000.0
            minimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
          - type: 'null'
          title: Total
        service_line_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Line Id
          description: The inventory line this bill is for; unlinked lines follow.
      additionalProperties: false
      type: object
      title: BillUpdate
      description: Correct only the header fields sent; linking a service also names the provider.
    BillLineInput:
      properties:
        label:
          type: string
          maxLength: 160
          minLength: 1
          title: Label
        kind:
          type: string
          enum:
          - recurring
          - one_time
          - usage
          - tax_fee
          - credit
          - other
          title: Kind
          default: recurring
        amount:
          anyOf:
          - type: number
            maximum: 10000000.0
            minimum: -10000000.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
          title: Amount
        quantity:
          anyOf:
          - type: integer
            maximum: 100000.0
            minimum: 1.0
          - type: 'null'
          title: Quantity
        service_line_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Line Id
        page_ref:
          anyOf:
          - type: integer
            maximum: 500.0
            minimum: 1.0
          - type: 'null'
          title: Page Ref
      additionalProperties: false
      type: object
      required:
      - label
      - amount
      title: BillLineInput
      description: One charge on a bill.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BillFromArtifact:
      properties:
        artifact_id:
          type: string
          format: uuid
          title: Artifact Id
        service_line_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Line Id
      additionalProperties: false
      type: object
      required:
      - artifact_id
      title: BillFromArtifact
      description: Read a bill from one of the buyer's own uploaded documents (as a draft).
    DisputeResult:
      properties:
        finding:
          $ref: '#/components/schemas/BillFindingRead'
        ticket_id:
          type: string
          format: uuid
          title: Ticket Id
        created:
          type: boolean
          title: Created
          description: True only when this call opened the ticket.
      type: object
      required:
      - finding
      - ticket_id
      - created
      title: DisputeResult
      description: A finding turned into a billing request CHNLSYNC works.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BillLineRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        label:
          type: string
          title: Label
        kind:
          type: string
          enum:
          - recurring
          - one_time
          - usage
          - tax_fee
          - credit
          - other
          title: Kind
        amount:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount
        quantity:
          anyOf:
          - type: integer
          - type: 'null'
          title: Quantity
        service_line_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Line Id
        service_provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Service Provider
        page_ref:
          anyOf:
          - type: integer
          - type: 'null'
          title: Page Ref
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
      type: object
      required:
      - id
      - label
      - kind
      - amount
      - quantity
      - service_line_id
      - service_provider
      - page_ref
      - confidence
      title: BillLineRead
      description: One charge as the buyer sees it.
    BillFindingRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        kind:
          type: string
          enum:
          - above_contract
          - after_disconnect
          - closed_site
          - out_of_contract
          - duplicate_line
          - fee_jump
          - total_jump
          - copper_line
          title: Kind
        label:
          type: string
          title: Label
        severity:
          type: string
          enum:
          - info
          - warn
          - high
          title: Severity
        status:
          type: string
          enum:
          - open
          - dismissed
          - disputed
          title: Status
        amount:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Amount
        detail:
          type: string
          title: Detail
        bill_line_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Bill Line Id
        line_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Line Label
        ticket_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Ticket Id
      type: object
      required:
      - id
      - kind
      - label
      - severity
      - status
      - amount
      - detail
      - bill_line_id
      - line_label
      - ticket_id
      title: BillFindingRead
      description: One finding, citing the line it is about.
    BillListRead:
      properties:
        open_findings:
          type: integer
          title: Open Findings
        bills:
          items:
            $ref: '#/components/schemas/BillSummaryRead'
          type: array
          title: Bills
      type: object
      required:
      - open_findings
      - bills
      title: BillListRead
      description: The buyer's bills, newest first.
    BillInput:
      properties:
        provider:
          type: string
          maxLength: 120
          minLength: 1
          title: Provider
        account_number:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Account Number
        invoice_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Invoice Date
        period_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Period Start
        period_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Period End
        total:
          anyOf:
          - type: number
            maximum: 100000000.0
            minimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
          - type: 'null'
          title: Total
        service_line_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Line Id
          description: Default inventory line for lines that don't name one.
        lines:
          items:
            $ref: '#/components/schemas/BillLineInput'
          type: array
          maxItems: 200
          title: Lines
      additionalProperties: false
      type: object
      required:
      - provider
      title: BillInput
      description: A bill the buyer types in (counts as confirmed by them).
    BillRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        provider:
          type: string
          title: Provider
        account_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Number
        invoice_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Invoice Date
        period_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Period Start
        period_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Period End
        total:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Total
        lines_total:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Lines Total
        currency:
          type: string
          title: Currency
        status:
          type: string
          enum:
          - draft
          - confirmed
          title: Status
        source:
          type: string
          enum:
          - manual
          - buyer_document
          - operator
          title: Source
        source_artifact_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Source Artifact Id
        service_line_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Line Id
        confirmed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Confirmed At
        checked_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Checked At
        created_at:
          type: string
          format: date-time
          title: Created At
        lines:
          items:
            $ref: '#/components/schemas/BillLineRead'
          type: array
          title: Lines
        findings:
          items:
            $ref: '#/components/schemas/BillFindingRead'
          type: array
          title: Findings
      type: object
      required:
      - id
      - provider
      - account_number
      - invoice_date
      - period_start
      - period_end
      - total
      - lines_total
      - currency
      - status
      - source
      - source_artifact_id
      - service_line_id
      - confirmed_at
      - checked_at
      - created_at
      - lines
      - findings
      title: BillRead
      description: A bill with its lines and findings.
    BillLineUpdate:
      properties:
        label:
          anyOf:
          - type: string
            maxLength: 160
            minLength: 1
          - type: 'null'
          title: Label
        kind:
          anyOf:
          - type: string
            enum:
            - recurring
            - one_time
            - usage
            - tax_fee
            - credit
            - other
          - type: 'null'
          title: Kind
        amount:
          anyOf:
          - type: number
            maximum: 10000000.0
            minimum: -10000000.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
          - type: 'null'
          title: Amount
        quantity:
          anyOf:
          - type: integer
            maximum: 100000.0
            minimum: 1.0
          - type: 'null'
          title: Quantity
        service_line_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Line Id
      additionalProperties: false
      type: object
      title: BillLineUpdate
      description: Change only the fields sent on one bill line.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-Agent-API-Key
x-refined-from:
- chnlsync-com-openapi.json
- chnlsync-com-openapi.yml