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

# Tango Project Invoice Inbound (Payment Confirmation) API

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

## Overview

Async REST API for posting **invoice payment confirmations** into Tango. The client `PUT`s a batch of payment records; Tango records them under Projects → Costs → Payments. Tango returns a `gu_id`; the client polls the Status endpoint for processing outcomes.

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

## Base URLs

| Environment | URL |
| - | - |
| Production | `https://api.tangoanalytics.com` |
| Test (SIT/UAT) | `https://testapi.tangoanalytics.com` |

## Authentication

`x-client` and `x-api-key` headers, required on every call.

## Endpoints

| Method | Path | Summary |
| - | - | - |
| PUT | `/v1/projectmgmt/batch/invoicepayments` | Submit batch of payment confirmations. |
| GET | `/v1/batch/status?gu_id=...` | Poll processing status. |

### `PUT /v1/projectmgmt/batch/invoicepayments`

**Request**

```json theme={null}
{
  "records": [
    {
      "inv_number": "INV-1234",
      "inv_id": "78968",
      "payment_number": "PAY-2344",
      "invoice_amount": 3000.34,
      "status": "PAID",
      "payment_method": "CHECK",
      "payment_reference": "23456775443",
      "payment_date": "03/14/2021",
      "payment_amount": 3000.34,
      "comments": "good"
    }
  ]
}
```

**Response — 200 OK**

```json theme={null}
{
  "status": "OK/Error",
  "status_message": "",
  "gu_id": "cc70b809-5142-4ebe-9dcc-6ca59fa01122"
}
```

Optional fields may be omitted entirely or sent with empty values.

### `GET /v1/batch/status?gu_id=...`

Three response shapes: `PROCESSING`, `COMPLETED` (with `total_records`), or `ERROR` (with per-record errors).

## Data model

| Field | Type | Required | Notes |
| - | - | - | - |
| `inv_number` | VARCHAR | one-of ⚠ | Client's invoice number |
| `inv_id` | NUMBER | one-of ⚠ | Tango's unique Invoice ID — at least one of `inv_id` / `inv_number` is required |
| `payment_number` | VARCHAR | ✅ | |
| `invoice_amount` | NUMBER | – | |
| `status` | VARCHAR | ✅ | `PAID` / `VOID` |
| `payment_method` | VARCHAR | – (but see validation #4) | |
| `payment_reference` | VARCHAR | – | |
| `payment_date` | DATE | ✅ | `MM/DD/YYYY` |
| `payment_amount` | NUMBER | ✅ | |
| `comments` | VARCHAR | – | |

## Validations (per source doc)

| # | Condition | Error message |
| - | - | - |
| 1 | Both `inv_id` and `inv_number` absent | `Either inv_id or inv_num is required` |
| 2 | `payment_number` missing | `required field: payment_number is missing or empty` |
| 3 | `status` missing | `required field: status is missing or empty` |
| 4 | `payment_method` missing | `required field: payment_method is missing or empty` |
| 5 | `payment_date` missing | `required field: payment_date is missing or empty` |
| 6 | `payment_amount` missing | `required field: payment_amount is missing or empty` |

## Open Questions / Assumptions

* [ ] **`payment_method` field is contradictory** — the data-mapping table marks it optional, but validation #4 rejects payloads missing it. Treat as required pending clarification.
* [ ] **`status` enum**: source lists `PAID`/`VOID` as the "default value" — interpreted as the allowed set; confirm.
* [ ] **One-of constraint** (`inv_id` XOR `inv_number`) cannot be expressed natively in OAS 3.1 properties; documented in the schema description and runtime validators must enforce it.
* [ ] Date strings use `MM/DD/YYYY` (not ISO 8601). Confirm intentional.
* [ ] Error payload's `record_key` type varies between string and integer in the doc's examples — modeled as `oneOf`.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1 | 4/2/2021 | Initial version | Michael Phoenix |
| 0.2 | 4/9/2021 | Updated Architecture and Response Body | Shalmali Patil |
| 0.3 | 07/18/2022 | Updated Request & Integration Status | Olivia Aneye |
| 0.4 | 09/02/2022 | Updated Headers and formatting | Jasmin Thasleem |
| 0.5 | 11/22/2022 | Updated Integration Status | Jasmin Thasleem |
| 0.6 | 12/29/2022 | Updated Data mapping | Jasmin Thasleem |
| 0.7 | 10/30/2023 | Reformatted sections, added Functional design & Validations | Jasmin Thasleem |
| 0.8 | 03/06/2025 | Updated Data mapping & removed Payment Reference – Validation | Jasmin Thasleem |
| 0.9 | 04/23/2026 | Updated API Architecture | Jasmin Thasleem |