AppZen Vat API

swagger: '2.0'
info:
  title: Autonomous AP APIs Chart of Accounts Vat API
  description: Public APIs for integrating with Autonomous AP
  version: 2.0.3
host: <env>.appzen.com
basePath: /dictionary-data-services
schemes:
- https
security:
- API Key Header: []
  Customer Id Header: []
  Customer Key Header: []
tags:
- name: Vat
paths:
  /vat:
    post:
      tags:
      - Vat
      summary: Creates/updates a Vat master item
      description: Creates a new Vat master item in AppZen. Returns a uuid for this vat item. When vat item -- with the same vat_code/vat_rate combination -- already exists, then the operation is an update (in this case, the `status` in the response will be `UPDATED`).
      parameters:
      - $ref: '#/parameters/vat-json-schema'
      responses:
        200:
          description: Updated
          schema:
            $ref: '#/definitions/uuid-updated'
        201:
          description: Created
          schema:
            $ref: '#/definitions/uuid'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/http-400-error-response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/http-401-error-response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/http-403-error-response'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/http-404-error-response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/http-500-error-response'
  /vat/{uuid}:
    get:
      tags:
      - Vat
      summary: Returns Vat master item details
      description: Returns the details of a Vat master item by uuid
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/uuid'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/vat-master-get'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/http-400-error-response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/http-401-error-response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/http-403-error-response'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/http-404-error-response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/http-500-error-response'
  /vat/vat-id/{vat-id}:
    get:
      tags:
      - Vat
      summary: Returns Vat master item details by vat-id
      description: Returns Vat master item details matching vat-id specified as path parameter
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/vat-id'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/vat-master-get'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/http-400-error-response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/http-401-error-response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/http-403-error-response'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/http-404-error-response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/http-500-error-response'
  /vat/vat-code/{vat-code}/vat-rate/{vat-rate}:
    get:
      deprecated: true
      tags:
      - Vat
      summary: Returns Vat master item details by vat-code and vat-rate
      description: Returns Vat master item details matching vat-code and vat-rate specified as path parameters
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/vat-code'
      - $ref: '#/parameters/vat-rate'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/vat-master-get'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/http-400-error-response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/http-401-error-response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/http-403-error-response'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/http-404-error-response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/http-500-error-response'
definitions:
  http-500-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 500
      error:
        type: string
        example: Internal Server Error
      message:
        type: string
        example: 'Error code : 17e3338d - Unable to process your request at this moment, please try again later'
  http-404-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 404
      error:
        type: string
        example: Not Found
      message:
        type: string
        example: 'Error code : 17e3338d - The resource you specified cannot be not found'
  http-403-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 403
      error:
        type: string
        example: Forbidden
      message:
        type: string
        example: 'Error code : 17e3338d - You do not have permission to access this resource'
  http-400-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 400
      error:
        type: string
        example: Bad Request
      message:
        type: string
        example: 'Error code : 17e3338d - Invalid request, please fix and resend'
  uuid-updated:
    type: object
    properties:
      uuid:
        type: string
        example: 5fc03087-d265-11e7-b8c6-83e29cd24f4c
      status:
        type: string
        example: UPDATED
  vat-master:
    properties:
      vat_code:
        description: Vat item code as mentioned in ERP system
        type: string
        example: VAT12
      vat_rate:
        example: 12
        description: Vat item rate in ERP system. Vat code/rate combination corresponds to a unique vat master item
        type: number
      vat_id:
        description: Vat item Id from ERP system
        type: string
        example: 1xsd2sd
      appzen_vat_code:
        type: string
        description: ERP Vat code maps to one of these predefined list of codes mantained by Appzen.
        example: VAT
      appzen_vat_rate:
        description: Appzen mapped Vat item code
        type: number
        example: 12
      appzen_vat_breakdown:
        type: array
        items:
          allOf:
          - $ref: '#/definitions/appzen-vat-breakdown-item'
          - description: The appzen break down of vat amount
      country:
        type: string
        example: Germany
      country_code_iso3:
        type: string
        description: ISO3 standard country code
        example: DEU
      is_active:
        description: Is Vat item active in ERP system.
        default: true
        type: boolean
      jurisdiction_code:
        type: string
        description: Standard tax jurisdiction code
        example: IN
    description: Combination of vat_code and vat_rate (optional) should be unique
    required:
    - vat_code
  vat-master-get:
    properties:
      vat_code:
        description: Vat item code as mentioned in ERP system
        type: string
        example: VAT12
      vat_rate:
        example: 12
        description: Vat item rate in ERP system. Vat code/rate combination corresponds to a unique vat master item
        type: number
      vat_id:
        description: Vat item Id from ERP system
        type: string
        example: vat_1xsd2sd
      appzen_vat_code:
        description: Appzen mapped Vat item code
        type: string
        example: VAT
      appzen_vat_rate:
        description: Appzen mapped Vat item rate
        type: number
        example: 12
      appzen_vat_breakdown:
        type: array
        items:
          allOf:
          - $ref: '#/definitions/appzen-vat-breakdown-item'
          - description: The appzen break down of vat amount
      country:
        type: string
        example: Germany
      country_code_iso3:
        type: string
        description: ISO3 standard country code
        example: DEU
      is_active:
        description: Is Vat item active in ERP system.
        default: true
        type: boolean
      last_updated_at:
        allOf:
        - $ref: '#/definitions/date-time'
      jurisdiction_code:
        type: string
        description: Standard tax jurisdiction code
        example: IN
  uuid:
    type: object
    properties:
      uuid:
        type: string
        example: 5fc03087-d265-11e7-b8c6-83e29cd24f4c
      status:
        type: string
        example: CREATED
  appzen-vat-breakdown-item:
    type: object
    properties:
      code:
        description: A customer vat code maps to one of these predefined list of vat codes mantained by Appzen.
        type: string
        example: VAT
      rate:
        type: number
        description: rate as percentage
        minimum: 0
        exclusiveMinimum: true
        example: 12
  date-time:
    type: string
    format: date-time
    example: '2024-03-01T11:01:00Z'
    description: date should be in UTC format
  http-401-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 401
      error:
        type: string
        example: Unauthorized
      message:
        type: string
        example: 'Error code : 17e3338d - Unable to authenticate credentials'
parameters:
  uuid:
    in: path
    description: Globally unique identifier for an uploaded document
    required: true
    name: uuid
    type: string
  vat-id:
    in: path
    description: customer vat id
    required: true
    name: vat-id
    type: string
  vat-rate:
    in: path
    description: customer vat rate. If vat record was loaded without a vat rate, set it to 0 in this request
    required: true
    name: vat-rate
    type: number
  vat-code:
    in: path
    description: customer vat code
    required: true
    name: vat-code
    type: string
  vat-json-schema:
    in: body
    required: true
    name: vat-json-schema
    schema:
      $ref: '#/definitions/vat-master'
securityDefinitions:
  API Key Header:
    type: apiKey
    in: header
    name: x-api-key
  Customer Id Header:
    type: apiKey
    in: header
    name: customer-id
  Customer Key Header:
    type: apiKey
    in: header
    name: customer-key