openapi: 3.1.0
info:
  title: Tango Space Badge Inbound — File
  version: "0.4"
  description: |
    SFTP file-based inbound. Client drops a pipe-delimited file of badge
    (access-control) events to Tango's SFTP server; Tango picks up the file,
    upserts records by `person_id` (Employee ID), and moves the file to
    `Processed/`. Tango never deletes badge data.
  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}_BADGE_MMDDYYYYHHMMSS.txt"
servers:
  - url: sftp://sftp.tangoanalytics.com
    description: Production SFTP
    x-environment: production
    x-path: /inbound/badge
  - url: sftp://sftpdev.tangoanalytics.com
    description: Test SFTP (SIT/UAT)
    x-environment: test
    x-path: /inbound/badge
tags:
  - name: Badge Inbound File
paths:
  /inbound/badge:
    post:
      summary: Drop badge file at SFTP path
      operationId: deliverBadgeInboundFile
      tags: [Badge Inbound File]
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              format: binary
              x-record-schema:
                $ref: "#/components/schemas/BadgeInboundRow"
      responses:
        "200":
          description: File received and queued for processing.
components:
  securitySchemes:
    sftpUserPassword:
      type: http
      scheme: basic
  schemas:
    BadgeInboundRow:
      type: object
      required:
        - client_id
        - person_id
        - entry_type
        - building_id
        - badge_type
        - event_date
      properties:
        client_id:
          type: string
          description: |
            Tango-specific client identifier — static for the entire client;
            same value appears on every row.
          example: "324"
        person_id:
          type: string
          description: |
            Unique key. Employee ID for staff; visitor identifier for visitors.
            Tango recommends prefixing visitor IDs with `V-`.
          example: "12345"
        entry_type:
          type: string
          enum: [EMPLOYEE, VISITOR]
        building_id:
          type: string
          description: Must match a Building ID in Tango.
          example: "ABC"
        badge_type:
          type: string
          enum: [ENTRY, EXIT]
        event_type:
          type: string
          description: e.g., `Granted Access`.
        asset_number:
          type: string
          description: Asset ID of the reader (optional).
        reader_number:
          type: string
          example: "SD Ground / N Main Entry Door"
        event_date:
          type: string
          description: "DATETIME — `MM/DD/YYYY HH:MM:SS`."
          example: "6/21/2021 00:00:00"
security:
  - sftpUserPassword: []