# Partner Identification

## Overview

Partner Identification allows storing official registration numbers — such as tax IDs, VAT numbers, DUNS numbers, and company registry codes — against a business partner. Each identification record captures the type, value, and optional metadata including issuing country and validity period. A single partner can hold multiple identification records of different types, reflecting the reality that organisations are often registered across multiple jurisdictions or recognised by more than one authority.

Identifications are child entities of a business partner and can be added at any point in the partner's lifecycle. Uniqueness is enforced on the combination of type and value within a company scope, preventing the same registration number from being attached to duplicate partner records. This scoping is intentionally company-level; cross-company deduplication is out of scope for the initial implementation and may be introduced as a future enhancement if shared-counterparty scenarios arise.

## Business Purpose

Accurate partner identification data is required for legal compliance and operational integrity:

- **Tax reporting and invoicing**: Tax ID and VAT number must appear on invoices in many jurisdictions. Storing them on the partner record ensures they are available for document generation without manual entry
- **Know Your Customer (KYC)**: Onboarding processes in regulated industries require verified registration numbers to confirm a partner's legal identity before commencing trade
- **Duplicate detection**: Enforcing uniqueness on (type, value) within a company scope prevents the same real-world entity from existing as multiple partner records
- **Cross-border trade**: A partner operating in multiple countries may hold a domestic tax ID, a regional VAT number (e.g., EU VAT), and an international identifier (e.g., DUNS). All can be stored concurrently
- **Audit trail and compliance**: Validity dates on identification records support time-bounded compliance checks and historical audit requirements

## Process Flow

The typical flow for recording and using partner identifications:

```mermaid
flowchart TD
    A[Select Business Partner] --> B[Add Identification]
    B --> C{Type already present\nwith same value?}
    C -->|Yes - duplicate| D[Reject: uniqueness violation]
    C -->|No| E[Store Identification\ntype + value + metadata]
    E --> F{More IDs to add?}
    F -->|Yes| B
    F -->|No| G[Partner Identifications Complete]
    G --> H[Use in invoicing / tax reporting / KYC]
```

Identification validity is checked at the point of use:

```mermaid
flowchart TD
    A[Retrieve Partner Identification] --> B{validFrom / validTo set?}
    B -->|No| C[Identification is always valid]
    B -->|Yes| D{Current date within range?}
    D -->|Yes| E[Identification is valid]
    D -->|No| F[Identification is expired or not yet active]
```

## Scenario Patterns

- **Domestic tax registration**: A supplier is onboarded for a single country. A `TAX_ID` identification is added with the national tax number and the issuing country set to the supplier's home country
- **EU VAT number**: A European partner holds both a domestic `TAX_ID` and an EU-wide `VAT` number. Both are stored as separate identification records on the same partner
- **DUNS for procurement**: A large enterprise uses DUNS numbers in its supplier qualification process. A `DUNS` identification is added and used to cross-reference the partner against third-party credit and risk databases
- **Company registry reference**: A partner's legal registration number from a national company registry is stored as `COMPANY_REGISTRY`, enabling verification against public registers
- **National ID for individual partners**: An individual business partner (e.g., a sole trader) has a `NATIONAL_ID` stored as their primary identification
- **Time-bounded VAT registration**: A partner's VAT registration is valid from a specific date. The `validFrom` field is set so that downstream processes can determine whether the VAT number applies to a given transaction date
- **Duplicate partner prevention**: An operator attempts to add a `TAX_ID` with a value already recorded on another partner. The system rejects the entry, surfacing the conflict so the operator can merge or review the existing partner record
- **Other / custom identifiers**: A partner holds an identifier that does not fit any standard type (e.g., an industry-specific accreditation number). It is stored under type `OTHER` with a descriptive value

## Test Cases

- An identification requires both `type` and `value`; records missing either field are rejected
- Supported types are: `TAX_ID`, `VAT`, `DUNS`, `COMPANY_REGISTRY`, `NATIONAL_ID`, `OTHER`
- The combination of (type, value) must be unique within the company scope (intentionally company-level; cross-company deduplication is not enforced); attempting to create a duplicate within the same company is rejected
- A single partner can hold multiple identification records with different types
- Two partners may not share an identification record with the same (type, value) combination
- `issuingCountry`, `validFrom`, and `validTo` are optional and may be omitted
- When both `validFrom` and `validTo` are set, `validTo` must be equal to or later than `validFrom`
- Identifications can be added to partners in any lifecycle state (DRAFT, ACTIVE, INACTIVE)
- An identification record can be deleted without affecting the parent partner or other identifications
- `type` is immutable after creation; changing the identification type requires deleting the existing record and creating a new one
- Updating an identification's value must re-validate the (type, value) uniqueness constraint

## Reference Links

- [SAP Business Partner — Tax Numbers and Identification](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f544846954f24b9183edd4ca52275847/d6a0de9fd00f4ab2843e013d7a8f5380.html)
- [Odoo Fiscal Information — VAT and Company Registry](https://www.odoo.com/documentation/19.0/applications/accounting/accounting/taxes/taxcloud.html)
- [Oracle Supplier Tax Registrations](https://docs.oracle.com/en/cloud/saas/financials/24a/fappp/supplier-registration.html)
- [DUNS Number — Dun & Bradstreet](https://www.dnb.com/duns-number.html)
