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

# Unified Tax Calculation & Validation (Sandbox)

> Simulate tax calculation and tax ID validation in a single unified request.

Use this endpoint in the **Sandbox environment** to simulate both tax rate calculation and tax ID validation in a single call. It is useful for validating your end-to-end integration during development for workflows such as checkout, invoice generation, or regulatory compliance.

***

### Valid Tax ID Scenarios

The Sandbox supports **specific Tax IDs** for deterministic test cases. Use only the values listed below for expected behavior.

<Expandable title="Valid Tax ID – Sandbox">
  | Country | Tax ID            | Simulated Outcome    |
  | :------ | :---------------- | :------------------- |
  | DE      | `DE123456789`     | Valid, name matches  |
  | IN      | `29ABCDE1234F1Z5` | Valid, name mismatch |
  | US      | `123-45-6789`     | Invalid ID           |
</Expandable>

***

### Tax Rate Simulation

These combinations return predictable tax calculations in the Sandbox.

<Expandable title="Valid Tax Rates – Sandbox">
  | Country | Product Category | Customer Type | Outcome Description    |
  | :------ | :--------------- | :------------ | :--------------------- |
  | DE      | `SAAS`           | `B2B`         | Reverse charge applied |
  | IN      | `PRSFT`          | `B2C`         | Standard GST 18%       |
  | US      | `CSS`            | `NGO`         | Tax-exempt scenario    |

  > Use these combinations to simulate edge cases such as exemption, reverse charge, and invalid IDs.
</Expandable>

***

### Request Parameters

<Accordion title="Request Parameters">
  <Accordion title="Product & Delivery">
    * `product_id`: *(string, optional)* – Internal product identifier.
    * `product_category`: *(string, optional)* – Required if `product_id` is absent. Acceptable values include: `CSS`, `DTSP`, `DAW`, `DAVW`, `DB`, `DP`, `IAAS`, `PAAS`, `SAAS`, `PRSFT`, `RNGT`, `DSWS`, `GMO`, `SSS`, `DTSS`, `INGMO`
    * `is_security`: *(boolean, optional)* – Indicates if product is classified as a financial/security item.
    * `delivery_method`: *(string, required)* – One of: `CLOUD`, `PHYSICAL`, `DOWN`
  </Accordion>

  <Accordion title="Customer">
    * `customer_id`: *(string, optional)* – Internal customer identifier.
    * `customer_type`: *(string, optional)* – Used if no `customer_id` is provided. One of: `B2C`, `B2B`, `PRISCH`, `PRIEDUI`, `GOV`, `PUBSCH`, `PUBEDU`, `PRIHOS`, `PUBHOS`, `NGO`
  </Accordion>

  <Accordion title="Location">
    * `country`: *(string, required)* – ISO country code.
    * `state`, `county`, `postal_code`, `ip_address`: *(optional)* – Additional location context.
  </Accordion>

  <Accordion title="Tax ID Validation">
    * `tax_id`: *(string, required)* – The tax identifier to validate.
    * `customer_name`: *(string, optional)* – Used for name matching with registry.
  </Accordion>
</Accordion>

***

### Response Fields

<Accordion title="Response Fields">
  <Accordion title="Tax Calculation">
    * `taxability`: *(boolean)* – Whether the product is taxable.
    * `country_rate`, `state_rate`, `county_rate`, `special_rate`, `additional_rate`, `total_rate`: *(integer)* – Tax rates in basis points.
    * `reverse_charge_applicable`: *(boolean)* – Reverse charge status.
    * `exempt`: *(boolean)* – Whether tax is fully exempt.
  </Accordion>

  <Accordion title="Tax ID Validation">
    * `tax_id_valid`: *(boolean)* – Whether the ID is valid.
    * `customer_name_registry`: *(string)* – Name returned by registry.
    * `customer_name_match`: *(boolean)* – If provided name matches registry.
    * `customer_type`: *(string)* – Inferred customer type.
    * `validated_country`, `validated_state`: *(string)* – Jurisdictional confirmation.
    * `registry_address`: *(string)* – Registry’s address (if available).
    * `validation_source`: *(string)* – Validation source such as `VIES`, `GSTN`.
    * `validation_timestamp`: *(string)* – ISO timestamp of the validation.
    * `request_id`: *(string)* – Internal reference for debugging and audits.
  </Accordion>
</Accordion>

***

### Notes

<Card>
  <Warning>All rate fields are returned in basis points. `18000` = 18%.</Warning>
  <Warning>Only specific test combinations and IDs work in the Sandbox. Any other inputs may yield default or empty responses.</Warning>
  <Note>`product_id` takes precedence over `product_category` if both are present.</Note>
  <Note>`customer_id` takes precedence over `customer_type` if both are present.</Note>
  <Check>Reverse charge is computed automatically based on customer classification and location.</Check>
  <Tip>This unified endpoint is ideal for **real-time compliance**, especially in invoicing or payment workflows.</Tip>
</Card>


## OpenAPI

````yaml api-reference/openapi_sandbox.json post /v1/tax/unify
openapi: 3.0.1
info:
  title: Antei Sandbox API
  description: >-
    Test and simulate integrations using Antei's sandbox environment. This is a
    sandbox-specific version exposing only limited endpoints for safe testing.
  version: 1.0.0
  license:
    name: MIT
  contact:
    name: Antei Developer Support
    email: support@antei.com
    url: https://antei.com
  x-sandbox: true
servers:
  - url: https://sandbox.antei.com
security:
  - bearerAuth: []
tags:
  - name: Tax Rate
    description: Calculate applicable tax rates based on product and customer details.
  - name: Tax ID Validation
    description: Validate tax identification numbers for compliance checks.
  - name: Taxation
    description: Unified tax calculation and validation workflows.
paths:
  /v1/tax/unify:
    post:
      tags:
        - Taxation
      summary: Unified Tax Rate + Tax ID Validation
      description: >-
        Calculate applicable tax rates and validate a customer's Tax ID using a
        single unified request.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxUnifyRequest'
      responses:
        '200':
          description: Unified tax result and tax ID validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxUnifyResponse'
        '400':
          description: Invalid input or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Optional. Unique key to ensure idempotent operations (e.g., retry-safe
        requests).
      required: false
      schema:
        type: string
  schemas:
    TaxUnifyRequest:
      type: object
      required:
        - country
        - product_id
        - customer_id
        - tax_id
      properties:
        product_id:
          type: string
          description: ID of the product
        product_category:
          type: string
          description: Product category if ID is unavailable
          enum:
            - CSS
            - DTSP
            - DAW
            - DAVW
            - DB
            - DP
            - IAAS
            - PAAS
            - SAAS
            - PRSFT
            - RNGT
            - DSWS
            - GMO
            - SSS
            - DTSS
            - INGMO
        is_security:
          type: boolean
          description: Is the product a financial security?
        delivery_method:
          type: string
          enum:
            - CLOUD
            - PHYSICAL
            - DOWN
          description: Product delivery mode
        customer_id:
          type: string
          description: Customer ID
        customer_type:
          type: string
          enum:
            - B2C
            - B2B
            - PRISCH
            - PRIEDUI
            - GOV
            - PUBSCH
            - PUBEDU
            - PRIHOS
            - PUBHOS
            - NGO
          description: Customer type if ID not provided
        country:
          type: string
          description: Country code (ISO Alpha-2)
        state:
          type: string
          description: State/region
        county:
          type: string
          description: County/district
        postal_code:
          type: string
          description: Postal code
        ip_address:
          type: string
          description: IP address for geolocation
        tax_id:
          type: string
          description: Tax Identification Number
        customer_name:
          type: string
          description: Customer name (for validation match)
      example:
        product_id: prod_abc123
        delivery_method: CLOUD
        customer_id: cust_xyz456
        tax_id: US123456789
        country: US
        state: CA
        postal_code: '94016'
        ip_address: 192.168.1.1
        customer_name: Acme Inc.
    TaxUnifyResponse:
      type: object
      properties:
        taxability:
          type: boolean
          description: Whether the product is taxable
        country_rate:
          type: integer
          description: Country-level tax rate (×1000)
        state_rate:
          type: integer
          description: State-level tax rate (×1000)
        county_rate:
          type: integer
          description: County-level tax rate (×1000)
        additional_rate:
          type: integer
          description: Any additional surcharge (×1000)
        special_rate:
          type: integer
          description: Special tax rate (×1000)
        total_rate:
          type: integer
          description: Final total rate (×1000)
        reverse_charge_applicable:
          type: boolean
          description: Is reverse charge applicable?
        exempt:
          type: boolean
          description: Is this transaction exempt from tax?
        tax_id_valid:
          type: boolean
          description: Whether the tax ID is valid
        customer_name_registry:
          type: string
          description: Name retrieved from tax registry
        customer_name_match:
          type: boolean
          description: Does the input name match registry?
        customer_type:
          type: string
        validated_country:
          type: string
        validated_state:
          type: string
        registry_address:
          type: string
        validation_source:
          type: string
          description: Source used for validation
        validation_timestamp:
          type: string
          format: date-time
        request_id:
          type: string
          description: Internal ID for auditing and tracing
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````