openapi: 3.0.0
info:
  title: Health Check API
  description: "You can use this API to test you are able to successfully connect to the DSG.\n\n**This API has the following endpoints:**\n\n- `GET {serverUrl}/healthcheck/v1/heartbeat`\nUse this endpoint to make a request to check your connection to the DSG\n\n- `GET {serverUrl}/healthcheck/v1/clients/ABN/{abn_business}/individuals/TFN/{tfn_individual}/heartbeat`\nUse this endpoint to make an authorized request to check your connection to the DSG using the payer ABN in sandbox environment\n\n- `GET {serverUrl}/healthcheck/v1/clients/WPN/{wpn_business}/individuals/TFN/{tfn_individual}/heartbeat`\nUse this endpoint to make an authorized request to check your connection to the DSG using the payer WPN in sandbox environment\n\n- `GET {serverUrl}/healthcheck/v1/`\nUse this endpoint to give the current version and status of the healthcheck API\n\n- `GET {serverUrl}/healthcheck/v1/specs/yaml`\nUse this endpoint to view the Healthcheck Open API specification in YAML format\n\n- `GET {serverUrl}/healthcheck/v1/specs/spec.yaml`\nUse this endpoint to download the Healthcheck Open API specification in YAML format\n\n**Note:** `{serverUrl}/healthcheck/v1/heartbeat` endpoint will check your connection to the DSG \nvia authentication but not authorization. The following endpoints `{serverUrl}/healthcheck/v1/clients/ABN/{abn_business}/individuals/TFN/{tfn_individual}/heartbeat` \nand `{serverUrl}/healthcheck/v1/clients/WPN/{wpn_business}/individuals/TFN/{tfn_individual}/heartbeat` \nwill check your connection to the DSG via authentication\nand authorization.\n\nFor more in-depth information refer to the endpoint paths in the specifications below around the \nuse of the endpoints and desired input path and query parameters.\n"
  version: 1.0.117
  x-status:
    status: Active
servers:
- url: https://{env}/healthcheck/v1
  description: Production Environment
  variables:
    env:
      default: api.ato.gov.au
      enum:
      - api.ato.gov.au
      - sandbox.api.ato.gov.au
security:
- ScopeAuth:
  - ato.healthcheck.*.*
paths:
  /heartbeat:
    get:
      tags:
      - Heartbeat
      summary: This will make sure that the DSG is running
      description: This endpoint will make sure the DSG is operational by returning a positive response
      operationId: GetHeartbeat
      responses:
        "200":
          description: "OK. \n\nThe request was successfully processed.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatInfoResponse'
              examples:
                HeartbeatSuccessfulResponseExample:
                  $ref: '#/components/examples/HeartbeatSuccessfulResponse'
        "400":
          content:
            application/json:
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/PathBadRequestResponse'
              schema:
                $ref: '#/components/schemas/ApiErrorsResponse'
          description: Bad Request
  /clients/ABN/{abn_business}/individuals/TFN/{tfn_individual}/heartbeat:
    get:
      tags:
      - Heartbeat
      summary: This will make sure your authorized and DSG is running
      description: Use this endpoint to check that the DSG is running and you are authorized to do so. You will have to provide the payer ABN and payee TFN in the request path, along with any intermediary details if required
      operationId: GetHeartbeatABN
      parameters:
      - $ref: '#/components/parameters/businessAbnParam'
      - $ref: '#/components/parameters/individualTfnParam'
      - $ref: '#/components/parameters/contextParam'
      responses:
        "200":
          description: "OK. \n\nThe request was successfully processed.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatInfoResponse'
              examples:
                HeartbeatSuccessfulResponseExample:
                  $ref: '#/components/examples/HeartbeatSuccessfulResponse'
        "400":
          content:
            application/json:
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/PathBadRequestResponse'
              schema:
                $ref: '#/components/schemas/ApiErrorsResponse'
          description: Bad Request
  /clients/WPN/{wpn_business}/individuals/TFN/{tfn_individual}/heartbeat:
    get:
      tags:
      - Heartbeat
      summary: This will make sure your authorized and DSG is running
      description: Use this endpoint to check that the DSG is running and your are authorized to do so. You will have to provide the payer WPN and payee TFN in the request path, along with any intermediary details if required
      operationId: GetHeartbeatWPN
      parameters:
      - $ref: '#/components/parameters/businessWpnParam'
      - $ref: '#/components/parameters/individualTfnParam'
      - $ref: '#/components/parameters/contextParam'
      responses:
        "200":
          description: "OK. \n\nThe request was successfully processed.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatInfoResponse'
              examples:
                HeartbeatSuccessfulResponseExample:
                  $ref: '#/components/examples/HeartbeatSuccessfulResponse'
        "400":
          content:
            application/json:
              examples:
                BadRequestExample:
                  $ref: '#/components/examples/PathBadRequestResponse'
              schema:
                $ref: '#/components/schemas/ApiErrorsResponse'
          description: Bad Request
  /:
    get:
      tags:
      - ApiInfo
      summary: Will give current status of this API
      description: This will return the details specifically for this API and the status of the API
      operationId: GetStatus
      responses:
        "200":
          $ref: '#/components/responses/ApiInfoResponse'
  /specs/yaml:
    get:
      tags:
      - Spec
      summary: Allows you to view the API spec in YAML format
      description: Allows you to view the YAML contents of the API straight within your browser without downloading
      operationId: GetSpecYaml
      responses:
        "200":
          $ref: '#/components/responses/RawSchemaResponse'
  /specs/spec.yaml:
    get:
      tags:
      - Spec
      summary: Allows you to download the API spec in YAML format
      description: This will allow you to download the API in yaml format
      operationId: DownloadSpecYaml
      responses:
        "200":
          $ref: '#/components/responses/DownloadSchemaResponse'
components:
  securitySchemes:
    ScopeAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.ato.gov.au/core2/connect/token
          scopes:
            ato.healthcheck.*.*: Grants ability to access the Healthcheck API
  parameters:
    businessAbnParam:
      name: abn_business
      in: path
      description: The payer's Australian Business Number (ABN)
      required: true
      schema:
        type: string
        pattern: '[0-9]{11}'
        example: 83091895966
    businessWpnParam:
      name: wpn_business
      in: path
      description: The payer's Withholding Payer Number (WPN)
      required: true
      schema:
        type: string
        pattern: '[0-9]{11}'
        example: 151994401
    individualTfnParam:
      name: tfn_individual
      in: path
      description: The payee's Tax File Number (TFN)
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 9
        pattern: '[0-9]*'
      examples:
        tfnExemptionCode:
          value: 111111111
          summary: Exempted TFN Code
        payeeTfn:
          value: 220114645
          summary: Payee Tax File Number (TFN)
    contextParam:
      name: context
      required: false
      in: query
      description: "\nThe `context` parameter specifies then ABN of the intermediary, the Tax Agent Number (TAN),\nor Registered Agent Number (RAN)\n\n- When a payer is submitting a request: context not required.\n- When an intermediary that is not an agent is acting on behalf of the payer submitting a request: \n`context=\"ABN={abn_intermediary}\";` note the intermediary doesn't have a TAN or RAN as it's not an agent\n- When an agent is acting on behalf of the payer submitting a request, TAN or RAN\nof the intermediary has to be provided in the context, e.g.: `context=\"TAN={TAN}\"` or `context=\"RAN={RAN}\"`.\n"
      schema:
        type: string
      examples:
        tan:
          value: '"TAN=17801003"'
          summary: Tax Agent - TAN
        ran:
          value: '"RAN=17801003"'
          summary: Tax Agent - RAN
        abn_intermediary:
          value: '"ABN=18083973826"'
          summary: Intermediary that is not a tax agent
  responses:
    ApiInfoResponse:
      description: ""
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiInfo'
          examples:
            successful:
              summary: API Status Example
              description: Example of the response that will be returned
              value: |-
                {
                  "api_version": "1.0.0",
                  "api_status": "Proposed"
                }
    RawSchemaResponse:
      description: ""
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/SpecResponse'
          examples:
            exampleSpecResponse:
              $ref: '#/components/examples/SpecResponse'
    DownloadSchemaResponse:
      description: ""
      headers:
        Content-Deposition:
          schema:
            type: string
          description: attachment; filename="spec.yaml"
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/SpecResponse'
          examples:
            exampleSpecResponse:
              $ref: '#/components/examples/SpecResponse'
  schemas:
    ApiInfo:
      description: This will hold infomation of the version of the API as well as the status
      type: object
      additionalProperties: false
      properties:
        api_version:
          type: string
          nullable: true
          example: 1.0.0
        api_status:
          type: string
          nullable: true
          enum:
          - Proposed
          - Cancelled
          - Active
          - Deprecated
          - Deactivated
          example: Proposed
    SpecResponse:
      type: object
      additionalProperties: false
      properties:
        specResponse:
          type: string
          nullable: true
    HeartbeatInfo:
      description: This will hold information of the successful return response and the time received
      type: object
      additionalProperties: false
      properties:
        systemTimeUTC:
          type: string
          format: date-time
          nullable: true
          example: 2021-08-26T16:00:40.0000000+10:00
    HeartbeatInfoResponse:
      description: This will hold data of the successful return response and the time received
      type: object
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/HeartbeatInfo'
        messages:
          items:
            $ref: '#/components/schemas/ApiMessage'
          type: array
        errors:
          items:
            $ref: '#/components/schemas/ApiError'
          type: array
      required:
      - data
    ApiError:
      description: This will hold the response error details.
      type: object
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          example: '{request.uri} not found'
          type: string
          nullable: true
        code:
          description: An application-specific error code
          example: ATO.GEN.404000
          type: string
          nullable: true
        source:
          $ref: '#/components/schemas/Source'
      title: ApiError
    ApiMessage:
      description: This will hold the response message details
      type: object
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          example: ""
          type: string
          nullable: true
        code:
          description: An application-specific error code
          example: ""
          type: string
          nullable: true
        source:
          $ref: '#/components/schemas/Source'
        severity:
          description: The severity level of the message.
          example: information
          type: string
          enum:
          - information
          - warning
      title: ApiMessage
    Source:
      description: An object containing references to the source of the error
      type: object
      properties:
        pointer:
          description: JSON Pointer points to the associated entity in the request document
          example: ""
          type: string
          nullable: true
        parameter:
          description: A string indicating which URI query parameter caused the error.
          example: ""
          type: string
          nullable: true
      title: Source
    ApiErrorsResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/ApiError'
          type: array
      description: ""
  examples:
    SpecResponse:
      summary: Example API Response
      description: Example OAS 3.0 yaml
      value: "openapi: 3.0.0 info:\n  title: ATO API Name\n  description: A short description about the API.\n  termsOfService: http://softwaredevelopers.ato.gov.au/api/terms-of-use\n  contact:\n    name: ATO DPO Support\n    url: http://softwaredevelopers.ato.gov.au/support\n    email: dpo@ato.gov.au\n  license:\n    name: Apache 2.0\n    url: http://www.apache.org/licenses/LICENSE-2.0.html\n  version: 1.0.0\nservers: - url: \"https://api.ato.gov.au/ato-api-name/v1\"\n  description: Production Envrionment\n...  "
    HeartbeatSuccessfulResponse:
      summary: ATO DSG Successful Response
      description: Example of the heartbeat response that will be returned
      value: "{\n  \"data\": {\n    \"systemTimeUTC\": \"2022-06-22T06:00:40Z\"\n  }\n}      "
    PathBadRequestResponse:
      summary: Schema API Path Bad Request response
      description: Example Schema API Path Bad Request response
      value: |-
        {
          "errors": [
          {
            "code": "RSF.00000",
            "detail": "No API path found that matches request '{entered_API_Path}'."
          }
          ]
        }
tags:
- name: ApiInfo
  description: This will return the status and version of the API
- name: Spec
  description: This will allow the specs to be viewed either in a browser or do a file download of the API spec
- name: Heartbeat
  description: This will make sure the DSG is running successfully and will return a successful response

