> ## 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.

# Invoice inbound file

# Tango Project Invoice Inbound (Payment Confirmation) — File

> Generated from `Tango Project Invoice Inbound (Payment Confirmation) Integration Design v0.7.docx` in SharePoint folder `04 Projects Integrations`.
> OAS spec: [`invoice-inbound-file.yaml`](./invoice-inbound-file.yaml)

## Overview

SFTP file-based inbound integration. Client drops a pipe-delimited text file with invoice payment confirmation rows to Tango's SFTP server; Tango's batch program reads the file, updates payment records in the Projects → Costs → Payments tab, and moves the file to the `Processed` folder.

**Owner:** Tango Analytics
**Spec version:** 0.7
**Status:** Draft (auto-generated from design doc — needs review)

## Transport

| Attribute | Value | |
| - | - | - |
| Direction | Inbound (Client → Tango) | |
| Mechanism | SFTP file drop | |
| File format | Pipe-delimited (\` | `) text, `.txt\` extension |
| File naming | `{ClientCode}_invoicepayments_MMDDYYYYHHMMSS.txt` | |
| Production host | `sftp.tangoanalytics.com` | |
| Test host | `sftpdev.tangoanalytics.com` (SIT/UAT) | |
| Path | `inbound/payments/` | |
| Auth | SFTP user/password (credentials TBD) | |
| Frequency | TBD | |

Tango moves picked-up files to `Processed/` with a timestamp suffix.

## Integration logic

* Uniqueness key: `(Invoice_ID, Payment_Number)`. Re-sending the same combination updates the existing payment record.
* Tango never deletes existing payments or invoices.
* After this integration, the invoice status transitions: `Approved` → `Exported` → `Paid`.
* An invoice can only become `Paid` if linked to a `Paid` payment.
* A payment linked to a `Paid` invoice cannot be modified (it must be voided first, then a new payment can be issued).
* When `Payment_Status = PAID`, `Invoice_Status` must also be `PAID`; if blank, it defaults to `PAID`.
* Tango does NOT validate that payment amounts sum to the invoice amount.
* Files containing only a header (no data rows) produce a `no records to process` service-log entry.

## Data fields

| Field | Type | Required | Sample | Description |
| - | - | - | - | - |
| `Client_ID` | NUMBER | ✅ | `111` | Tango-provided client identifier |
| `Invoice_ID` | NUMBER | ✅ | `1246` | Tango unique invoice ID (uniqueness key w/ Payment\_Number) |
| `Payment_Number` | VARCHAR | ✅ | `PN01` | |
| `Payment_Status` | VARCHAR | ✅ | `PAID` | `PAID` / `VOID` |
| `Payment_Date` | DATE | ✅ | `11/01/2023` | `MM/DD/YYYY` |
| `Payment_Reference` | VARCHAR | – | | |
| `Payment_Amount` | NUMBER | ✅ | `130.50` | |
| `Invoice_Status` | VARCHAR | – | `PAID` | Only `PAID` accepted; defaults to `PAID` when blank with `Payment_Status=PAID` |

## Status-transition matrix (source doc Appendix)

| # | File `Invoice_Status` | File `Payment_Status` | Existing `Invoice_Status` | Result |
| - | - | - | - | - |
| 1 | PAID | PAID | EXPORTED | Update → PAID |
| 2 | (blank) | PAID | EXPORTED | Update → PAID (defaulted) |
| 3 | Dummy | PAID | EXPORTED | Error, no update |
| 4 | Dummy | VOID | EXPORTED | Error, no update |
| 5 | PAID | VOID | EXPORTED | Error, no update |
| 6 | (blank) | VOID | EXPORTED | Error, no update |
| 7 | VOID/Dummy | VOID | EXPORTED | Error, no update |
| 8 | PAID/(blank) | PAID | PAID | Error, no update (paid-invoice's payment locked) |
| 9 | PAID/(blank) | VOID | PAID | Update → EXPORTED (void allowed) |
| 10 | PAID/(blank) | Dummy | PAID/EXPORTED | Error, no update |
| 11 | Dummy/VOID | Dummy | PAID/EXPORTED | Error, no update |

## Validations

| Condition | Error message |
| - | - |
| Client\_ID missing/invalid | `Fatal Error: Client ID is not available or Invalid` |
| Invoice\_ID null | `Fatal Error: Invoice ID is not available or Invalid` |
| Payment\_Status null/invalid | `Fatal Error: Payment Status is Missing or invalid` |
| Payment\_Number null/invalid | `Fatal Error: Payment number is missing or invalid` |
| Payment\_Date null | `Fatal Error: Payment Date missing` |
| Payment\_Amount null | `Fatal error: Paid Amount missing` |
| Payment\_Amount not numeric | `Paid Amount <> should be Number Value` |
| Payment\_Status not PAID/VOID | `Fatal error: Payment Status <> is not valid` |
| Invoice\_Status not PAID | `Fatal error: Invoice Status <> is not valid` |
| Invalid Payment+Invoice combination | `Fatal error: The combination of Payment Status and Invoice Status is not valid` |
| No data rows | `Warning: No records to process` |

## Open Questions / Assumptions

* [ ] SFTP credentials are `<TBD>` — supplied per environment.
* [ ] Timing/frequency is `<TBD>`.
* [ ] Header / Trailer row formats not defined — assumed only the data-mapping table describes Detail rows.
* [ ] `Client_ID` is described as "to be provided by Tango" but the doc doesn't say how — assumed it's a constant per client, embedded in every row.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1 | 1/25/2021 | Initial Draft | Vinay Malashetti |
| 0.2 | 3/25/2021 | Added Invoice Status field and updated integration logic | Vinay Malashetti |
| 0.3 | 06/30/2022 | Updated Data Mapping Section | Olivia Aneye |
| 0.4 | 09/14/2022 | Reformatting; added sections 6, 7, 8 | Jasmin Thasleem |
| 0.5 | 12/29/2022 | Updated Data Mapping (Client Label), Sample file | Jasmin Thasleem |
| 0.6 | 10/31/2023 | Reformatted several sections | Jasmin Thasleem |
| 0.7 | 10/02/2024 | Updated Data Mapping, Integration Logic, Appendix | Rahma Ouedraogo |