openapi: 3.1.0
info:
  title: Tango Project Invoice Outbound — File
  version: "0.7"
  description: |
    SFTP file-based outbound integration. Tango writes approved invoices as a
    pipe-delimited text file to its SFTP server; the client reads the file from
    that location. After successful export, invoice statuses are set to `Exported`
    in Tango.

    `INVOICE_ID` (header) and `INVOICE_DETAIL_ID` (line) are Tango-generated
    unique identifiers; `INVOICE_ID` is the reconciliation key when the client
    later sends payment confirmations back via the Invoice Inbound file.
  x-direction: outbound
  x-source: Tango
  x-destination: Client System
  x-transport: sftp
  x-file-format: pipe-delimited text (.txt)
  x-file-naming-convention: "{ClientName}_Invoice_Out_MMDDYYYYHHMMSS.txt"
servers:
  - url: sftp://sftp.tangoanalytics.com
    description: Production SFTP host
    x-environment: production
    x-path: /outbound/invoice
  - url: sftp://sftpdev.tangoanalytics.com
    description: Test SFTP host (SIT/UAT)
    x-environment: test
    x-path: /outbound/invoice
tags:
  - name: Invoice Outbound
paths:
  /outbound/invoice:
    post:
      summary: Drop approved invoice file at SFTP path
      description: |
        Virtual operation. Tango selects newly approved invoices, writes them to
        the file, moves the prior file to `Processed/<timestamp>`, and marks the
        exported invoices as `Exported`. No file is written when there is no data.
        Lines with `Net Amount = 0` are excluded.
      operationId: deliverInvoiceOutboundFile
      tags: [Invoice Outbound]
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              format: binary
              x-record-schema:
                $ref: "#/components/schemas/InvoiceOutboundRow"
      responses:
        "200":
          description: File delivered.
components:
  securitySchemes:
    sftpUserPassword:
      type: http
      scheme: basic
      description: SFTP user/password — values not specified in the source design doc.
  schemas:
    InvoiceOutboundRow:
      type: object
      description: One pipe-delimited row from the Invoice Outbound file.
      required:
        - INVOICE_ID
        - INVOICE_NUMBER
        - PROJECT_NUMBER
        - PO_NUMBER
        - INVOICE_DETAIL_ID
        - LINE_ITEM_SEQ
        - LINE_ITEM_NAME
        - INV_DATE
        - TOTAL_INVOICE_AMOUNT
        - SUPPLIER_NUMBER
        - INVOICE_TYPE
      properties:
        INVOICE_ID:
          type: number
          description: Tango-generated unique invoice ID; reconciliation key.
        INVOICE_NUMBER:
          type: string
          description: Client-defined invoice number.
        PROJECT_NUMBER:
          type: number
          description: Client-defined project number.
        PO_NUMBER:
          type: string
          description: |
            Maintenance — Tango generates the value.
            Construction Projects — client may enter the value.
        INVOICE_DETAIL_ID:
          type: number
          description: Tango-generated unique invoice detail ID.
        LINE_ITEM_SEQ:
          type: number
          description: Budget line sequence number.
        LINE_ITEM_NAME:
          type: string
        INV_DATE:
          type: string
          description: "MM/DD/YYYY."
          example: "01/21/2021"
        TOTAL_INVOICE_AMOUNT:
          type: number
        TAX_AMOUNT:
          type: number
          description: Tax amount rounded to 2 decimals.
        INVOICE_AMOUNT:
          type: number
          description: Invoice amount rounded to 2 decimals.
        CURRENCY:
          type: string
          description: ISO 4217 3-char code.
        LOCATION_NUMBER:
          type: string
        SUPPLIER_NUMBER:
          type: string
          description: Client-defined supplier number.
        SUPPLIER_SITE_NUMBER:
          type: string
        INVOICE_TYPE:
          type: string
          description: Tango standard codes — `REGULAR` / `RETAINAGE`.
        PAYMENT_TERMS:
          type: string
        SEGMENT1: { type: string }
        SEGMENT2: { type: string }
        SEGMENT3: { type: string }
        SEGMENT4: { type: string }
        SEGMENT5: { type: string }
        SEGMENT6: { type: string }
        H_COMMENTS:
          type: string
          description: Header-level comments.
        D_COMMENTS:
          type: string
          description: Detail-level comments.
        STATE:
          type: string
        ZIP:
          type: string
security:
  - sftpUserPassword: []