> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tangoanalytics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sales inbound file

# Tango Sales Inbound — File

> Generated from `Tango Sales Inbound Integration Design Specification V0.9.docx` in SharePoint folder `02 Lease Integrations`.
> OAS spec: [`sales-inbound-file.yaml`](./sales-inbound-file.yaml)

## Overview

SFTP file-based inbound. Client drops a pipe-delimited file containing monthly sales / exclusion rows; Tango processes and feeds Percent Rent calculations.

**Owner:** Tango Analytics
**Spec version:** 0.9
**Status:** Draft (auto-generated — needs review)

## Transport

| Attribute | Value | |
| - | - | - |
| Direction | Inbound (Client → Tango) | |
| Mechanism | SFTP file drop | |
| File format | Pipe-delimited (\` | `) text, `.txt\` |
| File naming | `{ClientCode}_sales_MMDDYYYYHHMMSS.txt` | |
| Path | `inbound/sales/` | |
| Auth | SFTP user/password (TBD) | |
| Frequency | TBD | |

## Integration logic

* Percent Rent is applied based on Calendar Period and Calendar Year (not fiscal).
* Sales can be loaded for multiple active percent rent agreements on the same lease.
* Sales code is optional; uniqueness is `(SALES_EXCLUSION, SALES_CATEGORY)`.
* Send sales as **positive**, exclusions as **negative**.
* `Gross Sales = Net Sales + Exclusion`; `Net Sales = Gross Sales − Exclusion`.
* Re-sending data for the same month overwrites prior data.
* Forecast is replaced by Actual when sent later for the same month/year/category.
* Sales adjustments for past periods (when payment was already generated) must be sent in future periods.
* Multiple concurrent files are processed in arrival order; all are moved to Processed.

## Data fields

| Field | Type | Required | Description |
| - | - | - | - |
| `STORE_NUMBER` | VARCHAR | ✅ | Mandatory |
| `LEASE_NUMBER` | VARCHAR | – | |
| `CALENDAR_MONTH` | NUMBER | ✅ | Calendar period |
| `CALENDAR_YEAR` | VARCHAR ⚠ | ✅ | Doc types as VARCHAR; numeric value |
| `EFFECTIVE_FROM_DATE` | DATE | – | Auto-populated |
| `EFFECTIVE_TO_DATE` | DATE | – | Auto-populated |
| `SALES_CODE` | VARCHAR | – | Lookup `PERCENT_RENT_SALES_CODE` |
| `SALES_CATEGORY` | VARCHAR | ✅ | Lookup `PERCENT_RENT_SALES_CATEGORY` |
| `SALES_EXCLUSION` | VARCHAR | ✅ | Lookup `PERCENT_RENT_SALES_EXCLUSION` |
| `PERIOD_AMOUNT` | NUMBER | ✅ | Positive for sales, negative for exclusions |
| `ACTUAL_FORECAST` | VARCHAR | ✅ | `ACTUAL` or `FORECAST` |

## Validations

| Condition | Error message |
| - | - |
| `STORE_NUMBER` missing/invalid | `Store Number is not present or invalid` |
| `LEASE_NUMBER` invalid | `Lease Number is invalid` |
| `CALENDAR_MONTH` missing | `Calendar Period is not present` |
| `CALENDAR_YEAR` missing | `Calendar Year is not present` |
| `EFFECTIVE_FROM_DATE` invalid | `Effective from date is invalid` |
| `EFFECTIVE_TO_DATE` invalid | `Effective to date is invalid` |
| `SALES_CATEGORY` missing/invalid | `Sales Category is not available or Invalid` |
| `SALES_EXCLUSION` missing/invalid | `Sales Or Exclusion is not available or Invalid` |
| `ACTUAL_FORECAST` missing/invalid | `Actual/Forecast is not available or Invalid` |
| `PERIOD_AMOUNT` missing | `Sales amount is not available` |

## Open Questions / Assumptions

* [ ] **`CALENDAR_YEAR` typed VARCHAR** in source mapping but treated as a year value. Schema mirrors the doc.
* [ ] **SFTP credentials** are `<TBD>`.
* [ ] **Timing/frequency** is `<TBD>`.
* [ ] **Cap logic** (Annual / Monthly) is detailed in the source's Functional Design — applied at processing time, not in the inbound row schema.
* [ ] **Lookup values** for `SALES_CODE`, `SALES_CATEGORY`, `SALES_EXCLUSION` are `<TBD>` in Appendix.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1–0.8 | 2020-2023 | (see source doc) | Various |
| 0.9 | 6/25/2024 | Functional Design CAP logic, Integration Logic, sample file | Rahma Ouedraogo |