Tinvio Drafts API

openapi: 3.2.0
info:
  title: Tinvio Com Drafts API
  version: '1.0'
  contact:
    email: build.with@jaz.ai
    name: API Support
    url: https://jaz.ai
  description: 'Operations tagged Drafts across 2 of this provider''s published API definitions: tinvio-com-openapi-original.yaml, tinvio-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.getjaz.com
tags:
- description: Validate, activate, and submit draft transactions for approval in bulk, across invoices, bills, and credit notes.
  name: Drafts
paths:
  /api/v1/drafts/convert-to-active:
    post:
      description: 'Bulk-convert draft business transactions to active asynchronously.

        Returns a background-job descriptor (jobId, status, totalRecords) the caller

        can poll via /api/v1/background-jobs/search or subscribe to via the returned

        Firebase RTDB paths.'
      operationId: create-draft-convert-to-active
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - properties:
                    data:
                      $ref: '#/components/schemas/BulkLifecycleJobResponse'
                  type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Convert Draft Business Transactions to Active
      tags:
      - Drafts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessTransactionLifecycleRequest'
        description: Batch of draft business transactions to convert.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/drafts/submit-for-approval:
    post:
      description: 'Bulk-submit draft business transactions for approval asynchronously.

        Returns a background-job descriptor (jobId, status, totalRecords) the caller

        can poll via /api/v1/background-jobs/search or subscribe to via the returned

        Firebase RTDB paths.'
      operationId: create-draft-submit-for-approval
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - properties:
                    data:
                      $ref: '#/components/schemas/BulkLifecycleJobResponse'
                  type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Submit Draft Business Transactions for Approval
      tags:
      - Drafts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessTransactionLifecycleRequest'
        description: Batch of draft business transactions to submit.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/drafts/validate:
    post:
      description: 'Validate a batch of draft business transactions for conversion eligibility.

        Synchronous: returns per-draft eligibility, validation errors, table-ready

        display data, the Mid-7 contact-history insight (modal currency / payment terms /

        top-COA, amount outliers, cadence, outstanding-balance, severity bucketing) and

        a full transaction breakdown (line items + trx-level metadata) for the Balance panel.'
      operationId: create-draft-validate
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - properties:
                    data:
                      $ref: '#/components/schemas/ValidateDraftsBatchResponse'
                  type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Validate Draft Business Transactions
      tags:
      - Drafts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessTransactionLifecycleRequest'
        description: Batch of business transactions to validate.
        required: true
    servers:
    - url: https://api.getjaz.com
components:
  schemas:
    BaseResponse:
      properties:
        data:
          description: The response object.
      type: object
    DraftValidationError:
      properties:
        code:
          description: Stable error code (e.g. ITEM_CONVERSION_QUANTITY_MUST_BE_POSITIVE).
          example: ITEM_CONVERSION_QUANTITY_MUST_BE_POSITIVE
          type: string
        fieldPath:
          description: Field path the error refers to, when applicable (dot-notation, may be null).
          type: string
        message:
          description: Human-readable error message.
          example: Item inventory quantity must be positive
          type: string
      type: object
    DraftColumnDef:
      properties:
        key:
          description: Stable column key matching displayData[].key.
          example: contact
          type: string
        label:
          description: Translation key for the column header.
          example: magic_validation_column_contact
          type: string
        type:
          description: Column render type (matches DisplayField.type).
          enum:
          - TEXT
          - STRING_REFERENCE
          - STRING_STANDARD
          - DATE
          - NUMBER
          - MONEY
          - MONEY_ISO
          - CONTACT
          - INSIGHT
          example: CONTACT
          type: string
        visible:
          description: Whether the column is rendered (legacy columns may be hidden).
          example: true
          type: boolean
      type: object
    OutstandingSnapshot:
      properties:
        activeBillCount:
          description: 'Count of bills feeding totalAmount. Full-ledger count of qualifying-status open bills

            with positive remaining balance in the functional currency.'
          example: 12
          type: integer
        currencyCode:
          description: Organization base currency code (ISO 4217).
          example: VND
          type: string
        notYetDueAmount:
          description: 'Sum of remaining over the not-yet-due slice (totalAmount − pastDueAmount). Includes

            bills without terms since they have no due date, and all credit notes.'
          example: '444.00'
          type: string
        notYetDueCount:
          description: 'Count of bills not in the past-due slice (activeBillCount − pastDueCount). Includes

            bills without terms and all credit notes.'
          example: 2
          type: integer
        pastDueAmount:
          description: 'Sum of remaining over the past-due slice (today > value_date + terms_days). Always

            0 for credit notes (no due date).'
          example: '3000.00'
          type: string
        pastDueCount:
          description: 'Count of bills past their due date (today > value_date + terms_days). Only counted

            when terms is non-null and non-negative. Always 0 for credit notes.'
          example: 10
          type: integer
        totalAmount:
          description: 'Sum of total_amount − payment_recorded_amount over qualifying-status open bills in

            the contact''s functional currency. Full-ledger (no time bound), plain string.'
          example: '3444.00'
          type: string
      type: object
    ContactInsightsMeta:
      properties:
        unavailable:
          description: 'When true, contact insights were unavailable for this batch and every

            per-draft contactInsight field is null. The validation itself succeeded.'
          example: false
          type: boolean
      type: object
    ValidateDraftResult:
      properties:
        breakdown:
          allOf:
          - $ref: '#/components/schemas/TrxBreakdown'
          description: 'Full transaction breakdown: line items plus transaction-level metadata.

            Null when the draft is ineligible or the breakdown could not be built.'
        btResourceId:
          description: Resource ID of the validated business transaction.
          example: b7a2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        btType:
          description: Business transaction type.
          enum:
          - SALE
          - PURCHASE
          - SALE_CREDIT_NOTE
          - PURCHASE_CREDIT_NOTE
          example: SALE
          type: string
        contactInsight:
          allOf:
          - $ref: '#/components/schemas/ContactInsight'
          description: 'Mid 7 contact-history insight derived from the contact''s recent active bills.

            Null when the draft has no contact, the draft is ineligible, or the contact

            has no qualifying history in the 12-month window.'
        displayData:
          description: 'Cell content for table rendering (5 entries: contact, reference, date, item, balance).

            The Insight column data lives on contactInsight.severitySummary (sibling field).'
          items:
            $ref: '#/components/schemas/DraftDisplayField'
          type: array
        eligible:
          description: True when the draft passes all eligibility checks.
          example: true
          type: boolean
        errors:
          description: Validation errors that block conversion. Empty when eligible=true.
          items:
            $ref: '#/components/schemas/DraftValidationError'
          type: array
      type: object
    BusinessTransactionLifecycleRequest:
      properties:
        items:
          description: List of draft business transactions to act on (min 1, max 500 per call).
          items:
            $ref: '#/components/schemas/BtRef'
          maxItems: 500
          minItems: 1
          type: array
      required:
      - items
      type: object
    TrxMetaDetail:
      properties:
        balance:
          description: Total minus payments recorded, as a plain string.
          example: '300.00'
          type: string
        currencyCode:
          description: Transaction currency code.
          example: VND
          type: string
        discount:
          description: Trx-level discount amount. Null on credit notes.
          type: string
        exchangeRate:
          description: Cross-currency exchange rate (rateSourceToFunctional). Null when not cross-currency.
          type: string
        notes:
          description: Internal notes / memo. Null when empty.
          type: string
        paymentRecorded:
          description: Amount recorded as paid against this trx, plain string.
          example: '0.00'
          type: string
        paymentTerms:
          description: Payment terms in days. Null on credit notes (their entities lack this field).
          example: 30
          type: integer
        subtotal:
          description: Subtotal (sum of line totals before tax / discount), plain string.
          example: '300.00'
          type: string
        tax:
          description: Sum of line tax amounts, plain string.
          example: '0.00'
          type: string
        taxInclusion:
          description: Tax inclusion mode. Null when no line on the draft carries a tax profile.
          enum:
          - INCLUSIVE
          - EXCLUSIVE
          example: INCLUSIVE
          type: string
        total:
          description: Trx total amount, plain string.
          example: '300.00'
          type: string
        withholdingTax:
          description: Trx-level withholding tax. Only emitted on Purchase / PurchaseCreditNote.
          type: string
      type: object
    PatternDivergenceFlag:
      properties:
        draftValue:
          description: Draft's value for this dimension (rawValue form).
          example: 'true'
          type: string
        field:
          description: Pattern field that diverges.
          enum:
          - CURRENCY
          - PAYMENT_TERMS
          - TAX_INCLUSION
          - TAX_PRESENCE
          - TOP_COA
          - TOP_ITEM
          example: TAX_PRESENCE
          type: string
        modalValue:
          description: Contact's modal value for this dimension (rawValue form, matches the corresponding RevealedPattern.rawValue when the pattern fired).
          example: 'false'
          type: string
      type: object
    DraftDisplayField:
      properties:
        currencyCode:
          description: Currency code for MONEY / MONEY_ISO cells (null for non-money cells).
          example: VND
          type: string
        key:
          description: Cell key (contact, reference, date, item, balance).
          example: contact
          type: string
        rawValue:
          description: Cell raw value (machine-readable; e.g. resource ID for CONTACT, epoch ms for DATE).
          example: 99fe6f39-3426-44b8-bfc9-df877d8181de
          type: string
        type:
          description: Cell render type.
          enum:
          - TEXT
          - STRING_REFERENCE
          - STRING_STANDARD
          - DATE
          - NUMBER
          - MONEY
          - MONEY_ISO
          - CONTACT
          - INSIGHT
          example: CONTACT
          type: string
        value:
          description: Cell display value (formatted for end-user rendering).
          example: Trung Nguyen
          type: string
      type: object
    ValidateDraftsBatchResponse:
      properties:
        columns:
          description: Column definitions for the eligible-results table (contact, reference, date, item, balance, insight).
          items:
            $ref: '#/components/schemas/DraftColumnDef'
          type: array
        contactInsightsMeta:
          allOf:
          - $ref: '#/components/schemas/ContactInsightsMeta'
          description: 'Top-level metadata about contact-insight enrichment for this batch.

            Present only when the caller''s response includes contact-insight fields;

            surfaces cache or freshness-layer unavailability so the consumer can render

            a soft banner.'
        eligibleCount:
          description: Number of drafts that passed eligibility checks and are ready to convert.
          example: 3
          type: integer
        errorColumns:
          description: Column definitions for the error table (contact, reference, date, error).
          items:
            $ref: '#/components/schemas/DraftColumnDef'
          type: array
        ineligibleCount:
          description: Number of drafts that failed eligibility checks (see results[].errors).
          example: 2
          type: integer
        results:
          description: Per-draft validation result, in the same order as the request items.
          items:
            $ref: '#/components/schemas/ValidateDraftResult'
          type: array
      type: object
    TrxBreakdown:
      properties:
        items:
          description: Per-line items in the draft. Empty list when the draft has zero line items.
          items:
            $ref: '#/components/schemas/LineItemDetail'
          type: array
        meta:
          allOf:
          - $ref: '#/components/schemas/TrxMetaDetail'
          description: Trx-level metadata.
      type: object
    BtRef:
      properties:
        btResourceId:
          description: Resource ID of the business transaction (invoice, bill, or credit note).
          example: b7a2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        btType:
          description: Business transaction type.
          enum:
          - SALE
          - PURCHASE
          - SALE_CREDIT_NOTE
          - PURCHASE_CREDIT_NOTE
          example: SALE
          type: string
      required:
      - btResourceId
      - btType
      type: object
    CadenceInsight:
      properties:
        daysSinceLast:
          description: Days from the most-recent historical bill to the draft's value-date.
          example: 45
          type: integer
        intervalRatio:
          description: 'Ratio of daysSinceLast to medianIntervalDays. Near 1.0 is on cadence,

            well below 1.0 is early, well above 1.0 is overdue.'
          example: 1.5
          type: number
        medianIntervalDays:
          description: Median number of days between consecutive bills (clamped ≥1).
          example: 30
          type: integer
      type: object
    ErrorResponse:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/ErrorResponseData'
          description: Error details.
      type: object
    ContactInsight:
      properties:
        cadence:
          allOf:
          - $ref: '#/components/schemas/CadenceInsight'
          description: Billing-rhythm signal. Null when sampleSize < 10 or all historical intervals are zero.
        outlierFlags:
          description: '0-1 entries (V1: AMOUNT only). Empty when no flag fires.'
          items:
            $ref: '#/components/schemas/OutlierFlag'
          type: array
        outstanding:
          allOf:
          - $ref: '#/components/schemas/OutstandingSnapshot'
          description: 'Open-balance snapshot in the organization''s base currency. Null when the

            contact has no active unpaid bills in the sample window.'
        patterns:
          description: 'Up to four entries, one per pattern field with a definite signal.

            Low-confidence entries are suppressed (minimum 0.5 for currency,

            payment terms, and top account; 0.7 for tax inclusion).'
          items:
            $ref: '#/components/schemas/RevealedPattern'
          type: array
        revealedDivergences:
          description: 'Per-dimension divergences between this draft and the contact''s modal pattern.

            One entry per diverging pattern field (NEW_CURRENCY, NEW_TERMS, TAX_TYPE,

            NEW_GST, NEW_COA, or NEW_ITEM). Empty when nothing diverges.'
          items:
            $ref: '#/components/schemas/PatternDivergenceFlag'
          type: array
        sampleSize:
          description: Number of qualifying bills in the rolling 12-month window.
          example: 10
          type: integer
        severitySummary:
          allOf:
          - $ref: '#/components/schemas/SeveritySummary'
          description: Severity bucketing + dominant label for the Insight column cell.
        signalQuality:
          description: 'Quality bucket: SPARSE (<5), EMERGING (5-9), STABLE (10+), VOLATILE (V2 reserved).'
          enum:
          - SPARSE
          - EMERGING
          - STABLE
          - VOLATILE
          example: STABLE
          type: string
      type: object
    OutlierFlag:
      properties:
        currencyCode:
          description: Currency for monetary fields. Null for non-monetary fields.
          example: VND
          type: string
        currentValue:
          description: Draft value, plain string (no scientific notation).
          example: '9000.00'
          type: string
        direction:
          description: Direction relative to the median.
          enum:
          - ABOVE
          - BELOW
          example: ABOVE
          type: string
        field:
          description: Outlier field (V1 only emits AMOUNT).
          enum:
          - AMOUNT
          example: AMOUNT
          type: string
        medianValue:
          description: Contact's historical median in the 12-month window, plain string.
          example: '100.00'
          type: string
        severity:
          description: 'Absolute deviation of the draft from the median, divided by the median

            absolute deviation.'
          example: 45
          type: number
      type: object
    SeveritySummary:
      properties:
        additionalCount:
          description: 'Count of additional flags beyond the dominant one. Counts red + yellow only;

            gray (NEW/NORMAL) never contributes. Capped at 9.'
          example: 0
          type: integer
        dominantLabel:
          description: 'Highest-priority flag, used as the cell label. Priority (highest → lowest):

            PAST_DUE > ABOVE_USUAL > BELOW_USUAL > BIG_GAP > NEW_CURRENCY > SLIGHT_JUMP > LATE >

            EARLY_BILL > NEW_TERMS > TAX_TYPE > NEW_GST > NEW_COA > NEW_ITEM > NEW > NORMAL.

            NO_ALERTS is the failure-state sentinel emitted when compute could not produce a

            verdict; never produced by the priority chain.'
          enum:
          - PAST_DUE
          - ABOVE_USUAL
          - BELOW_USUAL
          - BIG_GAP
          - NEW_CURRENCY
          - SLIGHT_JUMP
          - LATE
          - EARLY_BILL
          - NEW_TERMS
          - TAX_TYPE
          - NEW_GST
          - NEW_COA
          - NEW_ITEM
          - NORMAL
          - NEW
          - NO_ALERTS
          example: PAST_DUE
          type: string
        high:
          description: 'Count of red flags: PAST_DUE, ABOVE_USUAL, BELOW_USUAL, BIG_GAP, NEW_CURRENCY.'
          example: 1
          type: integer
        info:
          description: Reserved for V2 gray-flag aggregation. Always 0 in V1.
          example: 0
          type: integer
        medium:
          description: 'Count of medium-severity flags: SLIGHT_JUMP, LATE, EARLY_BILL, NEW_TERMS,

            TAX_TYPE, NEW_GST, NEW_COA, and NEW_ITEM.'
          example: 0
          type: integer
      type: object
    RevealedPattern:
      properties:
        confidence:
          description: Ratio of matchCount to totalCount, from 0.0 to 1.0.
          example: 1
          type: number
        field:
          description: Pattern field.
          enum:
          - CURRENCY
          - PAYMENT_TERMS
          - TAX_INCLUSION
          - TOP_COA
          - TAX_PRESENCE
          - TOP_ITEM
          example: CURRENCY
          type: string
        matchCount:
          description: Number of historical bills matching this modal value.
          example: 10
          type: integer
        rawValue:
          description: Machine-readable value (currency code, terms days, account resourceId, etc.).
          example: VND
          type: string
        totalCount:
          description: Total historical bills considered for this pattern.
          example: 10
          type: integer
        value:
          description: Display label (e.g. "SGD", "Net 30", "Inclusive", "Office Supplies"). Null for TOP_COA / TOP_ITEM when the historical modal resourceId can't be resolved to a name (item not on any current draft, or soft-deleted).
          example: VND
          type: string
      type: object
    BulkLifecycleJobResponse:
      properties:
        jobId:
          description: Background job resource ID. Use this to poll job status.
          example: b7a2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        magicTransactionFBPath:
          description: Firebase RTDB path for the per-record magic-transaction stream.
          example: magicTransactions/<jobId>
          type: string
        status:
          description: Initial job status (typically QUEUED).
          example: QUEUED
          type: string
        subscriptionFBPath:
          description: Firebase RTDB path for live job-status subscription.
          example: backgroundJobTracking/JOBS/<jobId>
          type: string
        totalRecords:
          description: Total number of records the job will process.
          example: 10
          type: integer
      type: object
    LineItemDetail:
      properties:
        accountName:
          description: 'Account name resolved from the organization''s chart of accounts. Null

            when the account was soft-deleted or accountResourceId is null.'
          example: Sales Revenue
          type: string
        accountResourceId:
          description: COA resourceId. Null when the line was created without an account (legacy data).
          type: string
        currencyCode:
          description: Transaction currency code. The same on every line within a draft.
          example: VND
          type: string
        discount:
          description: Line-level discount amount, if any.
          type: string
        itemResourceId:
          description: Resource ID of the line item.
          example: f0a1b2c3-d4e5-6789-abcd-ef0123456789
          type: string
        lineTotal:
          description: Line total, plain string (sourced from persisted itemSubTotal).
          example: '300.00'
          type: string
        name:
          description: Item description or name. Blank source values render as a dash.
          example: Inventory Item
          type: string
        quantity:
          description: Line quantity, plain string.
          example: '3'
          type: string
        taxAmount:
          description: Computed line tax amount (persisted).
          type: string
        taxProfileName:
          description: Tax profile display name (e.g. "Standard-Rated GST 9%").
          type: string
        taxProfileResourceId:
          description: Tax profile resourceId. Null when no profile attached or JSON parse fails.
          type: string
        taxRate:
          description: Tax rate as a plain string (e.g. "9" for 9%).
          type: string
        unitPrice:
          description: Unit price, plain string.
          example: '100.00'
          type: string
      type: object
    ErrorResponseData:
      properties:
        error_type:
          description: Error category, for example validation_error, invalid_request_body, or internal_server_error.
          example: validation_error
          type: string
        errors:
          description: Error messages describing what went wrong.
          items:
            type: string
          type: array
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Organization API key. Pass it in the x-jk-api-key header on every request.
      in: header
      name: x-jk-api-key
      type: apiKey
x-refined-from:
- tinvio-com-openapi-original.yaml
- tinvio-com-openapi.yml