openapi: 3.1.0
info:
  title: Tango Project Invoice Inbound (Payment Confirmation) — File
  version: "0.7"
  description: |
    SFTP file-based inbound integration. Client drops a pipe-delimited text file
    of invoice payment confirmations to Tango's SFTP server. Tango's internal
    batch program picks up the file, updates the Payments tab under Projects →
    Costs → Payments, and moves the source file to the `Processed` folder.

    Uniqueness key: `(Invoice_ID, Payment_Number)`.
  x-direction: inbound
  x-source: Client System
  x-destination: Tango
  x-transport: sftp
  x-file-format: pipe-delimited text (.txt)
  x-file-naming-convention: "{ClientCode}_invoicepayments_MMDDYYYYHHMMSS.txt"
servers:
  - url: sftp://sftp.tangoanalytics.com
    description: Production SFTP host
    x-environment: production
    x-path: inbound/payments/
  - url: sftp://sftpdev.tangoanalytics.com
    description: Test SFTP host (SIT/UAT)
    x-environment: test
    x-path: inbound/payments/
tags:
  - name: Invoice Payment Inbound
paths:
  /inbound/payments:
    post:
      summary: Drop invoice payment confirmation file at SFTP path
      description: |
        Virtual operation. Tango picks up the file from `inbound/payments/`,
        processes each row, and updates the matching invoice's payment record.
        Existing payment records can be updated by re-sending the same
        `(Invoice_ID, Payment_Number)` combination.
      operationId: deliverInvoicePaymentFile
      tags: [Invoice Payment Inbound]
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              format: binary
              x-record-schema:
                $ref: "#/components/schemas/InvoicePaymentRow"
      responses:
        "200":
          description: File received and queued for processing.
components:
  securitySchemes:
    sftpUserPassword:
      type: http
      scheme: basic
      description: SFTP user/password — provisioned per environment (values <TBD> in source).
  schemas:
    InvoicePaymentRow:
      type: object
      description: One pipe-delimited row from the invoice payment confirmation file.
      required:
        - Client_ID
        - Invoice_ID
        - Payment_Number
        - Payment_Status
        - Payment_Date
        - Payment_Amount
      properties:
        Client_ID:
          type: number
          description: Tango-provided client identifier.
        Invoice_ID:
          type: number
          description: Tango unique invoice reference; combined with Payment_Number for uniqueness.
        Payment_Number:
          type: string
        Payment_Status:
          type: string
          enum: [PAID, VOID]
          description: |
            Allowed values per the doc: `PAID` / `VOID`. The Payment_Status / Invoice_Status
            interaction rules from the Integration Logic / Appendix scenarios apply at
            processing time (see companion Markdown).
        Payment_Date:
          type: string
          description: "Format MM/DD/YYYY."
          example: "11/01/2023"
        Payment_Reference:
          type: string
        Payment_Amount:
          type: number
        Invoice_Status:
          type: string
          description: |
            Only accepted value is `PAID`. If blank and Payment_Status is `PAID`,
            it defaults to `PAID`.
security:
  - sftpUserPassword: []