openapi: 3.1.0
info:
  title: Tango CO Outbound
  version: "0.5"
  description: |
    SFTP file-based outbound integration. Tango exports approved Change Order (CO)
    records to the client target system as a pipe-delimited text file dropped to
    Tango's SFTP server. One-way batch.

    The OpenAPI document models this non-HTTP delivery as a single virtual POST
    operation against the SFTP path. The row-level field definitions live in the
    `COOutboundRecord` schema.
  contact:
    name: Tango Analytics
  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}_coout_MMDDYYYYHHMMSS.txt"
  x-frequency: pre-agreed batch schedule (not stated in design doc)
servers:
  - url: sftp://sftp.tangoanalytics.com
    description: Production SFTP host
    x-environment: production
    x-path: /outbound/CO
  - url: sftp://sftpdev.tangoanalytics.com
    description: Test SFTP host (SIT/UAT)
    x-environment: test
    x-path: /outbound/CO
tags:
  - name: CO Outbound
    description: Change Order outbound file delivery.
paths:
  /outbound/CO:
    post:
      summary: Drop approved CO file at SFTP path
      description: |
        Virtual operation representing Tango writing the CO outbound file to
        `/outbound/CO` on the SFTP server. Each file contains header + detail rows,
        one line per CO line item, pipe-delimited. Files are produced only when
        there is data; zero-dollar lines are excluded, negative COs are included.
        After successful generation all exported COs are flagged as `Exported` in
        Tango. The prior file is moved to the `Processed` subfolder with a
        timestamp suffix before the new file is written.
      operationId: deliverCOOutboundFile
      tags: [CO Outbound]
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              format: binary
              description: Pipe-delimited rows; one CO line item per row.
              x-record-schema:
                $ref: "#/components/schemas/COOutboundRecord"
      responses:
        "200":
          description: File delivered (SFTP put succeeded).
components:
  securitySchemes:
    sftpUserPassword:
      type: http
      scheme: basic
      description: |
        SFTP user/password credentials. Concrete values are <TBD> in the source
        design doc — provided per environment via secure channel.
  schemas:
    COOutboundRecord:
      type: object
      description: |
        One pipe-delimited row from the CO Outbound file. The source design doc
        did NOT mark any fields as required, so the required[] array is empty
        here and the gap is flagged in the companion Markdown's Open Questions.
      properties:
        CO_ID:
          type: number
          description: Tango-generated unique identifier for the Change Order.
        CO_NUMBER:
          type: string
          description: Unique CO number; round-tripped back via CO Inbound for reconciliation.
        PO_NUMBER:
          type: string
        PROJECT_NUMBER:
          type: string
        CHANGE_REASON:
          type: string
        CHANGE_ORDER_DATE:
          type: string
          description: Date in MM/DD/YYYY (file emits text).
        APPROVED_DATE:
          type: string
          description: Date in MM/DD/YYYY.
        APPROVED_BY:
          type: string
        RETAINAGE_PCT:
          type: number
        CO_AMOUNT:
          type: number
        ITEM_NUMBER:
          type: number
        CO_QUANTITY:
          type: number
        CO_RATE:
          type: number
        LINE_AMOUNT:
          type: number
        UOM:
          type: string
        ACCOUNT_CODE:
          type: string
        SEGMENT1:
          type: string
          description: Budget segment 1; sent as blank when NA.
        SEGMENT2:
          type: string
        SEGMENT3:
          type: string
        SEGMENT4:
          type: string
        SEGMENT5:
          type: string
        SEGMENT6:
          type: string
        LINE_COMMENTS:
          type: string
security:
  - sftpUserPassword: []