trans tasman e invoicing digital capability locator ... · trans-tasman e-invoicing digital...

UNCLASSIFIED

Trans-Tasman e-Invoicing

Digital Capability Locator

Implementation Guide

Version 2.1

20 Feburary 2019

Trans-Tasman e-Invoicing Digital Capability Locator Implementation Guide v2.1 of 62

Disclaimer & Copyright

Disclaimer

This document is based on a publication of the Digital Business Council (Council) and has been updated by

the Trans-Tasman Working Group to include New Zealand particulars.

The policy outlined in this paper has not received final Government approval. Therefore, this publication

should be treated as a guide on how this policy may apply and operate.

Whilst every effort has been made to ensure that the material contained in the document and related

attachments are correct, the Trans-Tasman Working Group and any other party involved in the creation of

the document hereby state that the document is provided without warranty, either expressed or implied,

of accuracy or fitness for purpose, and hereby disclaim any liability, direct or indirect, for damages or loss

relating to the use of the document.

The document may be modified, subject to developments in technology, changes to the standards, or new

legal requirements without notice. Any product and company name mentioned herein may be trademarks

and/or registered trademarks of its respective company.

Copyright

You are free to copy, adapt, modify, transmit and distribute this material as you wish (but not in any way

that suggests the Commonwealth endorses you or any of your services or products).

The document that this publication is based on is the copyright of the Digital Business Council. That work is

licensed under a under a Creative Commons Attribution 4.0 International Licence.

The Business Document Metadata Service Location Version 1.0 OASIS Standard is Copyright © OASIS Open

2017. All Rights Reserved.

Acknowledgements

The Trans-Tasman Working Group would like to acknowledge the work of the Council, its working groups

and other contributors (Superstream, Pan European Public Procurement Online (PEPPOL) and Electronic

Simple Electronic Networked Services (e-SENS) projects)) for their leadership and contributions in the

development of this Policy.

http://creativecommons.org/licenses/by/4.0/

https://www.ato.gov.au/Super/SuperStream/



http://www.peppol.eu/

http://www.peppol.eu/

http://www.esens.eu/




Version Control

Version Date Change Description

1.0.0 27/07/2016 Initial version

2.0.0 09/01/2017 This version is considered a MAJOR update as it makes corrections to the API

URL definitions. This will result in a breaking change for any version 1.0.0.

implementers.

Applied typographic updates from post-release feedback.

Section 8.1.1.3 – updated DNS Name, added not on the use of optional

[scheme] element.

Sections 8.3.1.3, 8.3.2.3, 8.4.2.3 – updated URI to replace

capabilityRegister with capabilityPublisher.

Section 8.3.1.11 – Updated example with correct hash value.

Section 8.4.1.6 and 8.4.1.12 – updated xml examples to include

<UpdateCapabilityPublisherEndpoint> tag.

Applied additional business rules identitied in PoC testing:

Updated section 7.1 to add additional business rules for MD5 pre-

processing of URN.

Applied cosmetic formatting improvements.

2.0.1 24/07/2017 This version is considered a MINOR PATCH as it makes corrections to example

data, typographic and readability issues. These corrections include:

Section 7.2 - updated example.

Section 3 – corrected section numbers in conformance statement.

Section 8 – fixed typographic error in samples

All sections – corrected table formatting.

Updated references to remove redundancy and reference the latest

update of the OASIS BDXL specification.

2.0.2 25/10/2017 This version is considered a PATCH as it makes corrections based on the

outcomes of DCL testing.

Section 2 - the OASIS Business Document Metadata Service Location

Candidate updated to the OASIS Standard Version 1.0 (OASIS, 2017) that

was issued by OASIS on 1st August 2017.

Section 6 extracted into a separate document - Trans-Tasman e-Invoicing

Use Cases document.

Sub -section 7.1 - the OASIS Business Document Metadata Service Location

Standard updated to Version 1.0 (2018).

https://softwaredevelopers.ato.gov.au/Trans-Tasman-eInvoicing



Sub- section 8.3.1.4 - Request headers updated.

Sub-section 8.3.1.5 - Example Request Body - application/json updated

Sub-section 8.3.1.6 - Example Request Body - application/xml assumption

updated.

Sub-section 8.3.1.6 - Request Field Reference - capabilityPublisherID

element updated.

Sub-section - 8.3.1.10 - Response Headers - Heade Content-Type updated.

Sub-section 8.3.1.13 - Example Error Response - application/json - Error

DCL error code reference updated to 0422.

Sub-section 8.3.1.14 - DCL Error Code Reference updated to 0422.

Sub-section 8.3.2.3 – Sequence diagram - Table attributes JSON support

and XML support updated.

Sub-section 8.3.2.4 - 8.3.2.7 and 8.3.2.10 - deleted.

Sub-section 8.3.2.8 (previously 8.3.2.12) - DCL error code reference

updated to 0409.

Sub-section 8.3.2.9 (previouslky 8.3.2.13) - DCL Error code reference

updated to 0409.

Sub-section 8.4.1.2 - Behaviour of API updated.

Sub-section 8.4.1.4 - Request Headers updated.

Sub-section 8.4.1.5 - Example Request Body - application/json updated.

Sub-section 8.4.1.6 - Example Request Body - application/xml updated.

Sub-section 8.4.1.7 - Request Field Reference - DomainName element

name updated

Sub-section 8.4.1.10 - Response Headers – Content type element

description updated.

Sub-section 8.4.1.11 - Response Body - application/json code updated.

Sub-section 8.4.1.12 - Response Body - application/xml code updated.

Subsection 8.4.1.3 - Response Field Reference - DomainName element

description updated

Sub-section 8.4.1.14 - Example Error Response - application/json- DCL error

code reference updated to 0422.

Sub-section 8.4.1.15 - Error Code Reference - DCl error code reference

updated to 0422.

Sub-section 8.4.2 - Sequence diagram table attribute ‘Authetication

mechanism’ description updated to Client Certificate (Mutual TLS)

Sub-section 8.4.2.4 - Example Request Headers description updated

Subsection 8.4.2.5 - Request field reference – new table added.

Sub-section 8.4.2.7 - Example response – new Header added - Date.

Sub-section 8.4.2.9 - Response Body - application/json - code updated.

Sub-section 8.4.2.11 - Response Field Reference – new elements ‘LegalId’

and ‘AccreditationStatus’ added, elements ‘URL’, ‘ Client certificates’ and

‘Server certificates’ updated.


Sub-section 8.4.3.3 – Sequence diagram - table attribute ‘Authentication

mechanism’ updated to Client Certificate (Mutual TLS).

Sub-section 8.4.3.4 - Example Request Headers - Description

Sub-section 8.4.3.5 - Request field reference - new table added.

Sub-section 8.4.3.8 - Response headers - ‘Date’ element added.

Sub-section 8.4.3.9 - Example response body - application/json - code

updated.

Sub-section 8.4.3.10 - Example response body - application/xml - code

updated.

Sub-section 8.4. 3.11 - Response Field Reference - new elements ‘LegalId’

and ‘AccreditationStatus’ added, elements ‘URL’, ‘ Client certificates’ and

‘Server certificates’ updated.

Appendix A (Use Cases) - deleted

Sub-section - 8.1.1 - Update Digital Capability Publisher details updated.

Sub-section 8.2.2 - Update Access Point Details updated

Sub-section 8.1.3 - Who I am updated.

Section 9 - Appendix - Digital capapbility locator codes updated.

Section References - updated.

Applied cosmetic editorial and formatting improvements.

2.1 20/02/2019 Industry feedback incorporated.

Inconsistencies on identifiers fixed.

Minor wording changes that have no material impact on framework.

Minor updates in ‘Copyright’ section.


Contents

Disclaimer & Copyright ................................................................................................................ 2

Version Control ............................................................................................................................. 3

1 Audience ................................................................................................................................. 7

2 Overview ................................................................................................................................. 8

3 Conformance ........................................................................................................................ 10

4 Distribution Package ............................................................................................................ 10

5 Terms and Definitions (Normative) ..................................................................................... 10

6 Use Case Summary .............................................................................................................. 12

7 Business Document Metadata Service Location Profile (Normative) ............................... 13

7.1 Conformance ................................................................................................................... 13

7.2 Non-DNS Participant Identifiers ....................................................................................... 13

7.3 DNS Query String ............................................................................................................ 14

7.4 Use of Regular Expressions in U-NAPTR Record ............................................................ 14

7.5 Security Consideration ..................................................................................................... 14

8 Services provided by the Digital Capability Locator .......................................................... 15

8.1 Discovery API .................................................................................................................. 15

8.1.1 Lookup Participant Capability Address ....................................................................... 15

8.2 API Security ..................................................................................................................... 17

8.3 Management API - Mandatory Services ........................................................................... 17

8.3.1 Register Participant Capability Address ..................................................................... 17

8.3.2 Delete Participant Capability Address ........................................................................ 22

8.4 Management API - Optional Services .............................................................................. 25

8.4.1 Update Digital Capability Publisher End-Point ........................................................... 25

8.4.2 List Accredited Digital Capability Publishers .............................................................. 30

8.4.3 List Accredited Access Points .................................................................................... 36

8.5 Management API - Additional Services ............................................................................ 42

8.5.1 Update Digital Capability Publisher Details ................................................................ 42

8.5.2 Update Access Point Details ...................................................................................... 48

8.5.3 Who am I ................................................................................................................... 54

APPENDIX A: Digital Capability Locator Error Codes .............................................................. 58

References .................................................................................................................................. 62


1 Audience

BUSINESS ANALYSTS APPLICATION DEVELOPERS

Business Analysts:

Those who analyse and document business or

processes or systems, assessing the business

model or its integration with technology

Those involved in the identification of business

requirements for solutions to support accounts

receivable, accounts payable and the electronic

transmission of the associated documents

between businesses.

Application Developers:

Those involved in the design, operation and

implementation of software and services for the

exchange of electronic documents or messages, or

Those involved in the design, integration and

operation of business applications dealing with

invoicing.

Audience Reading Guide

BUSINESS

ANALYSTS

APPLICATION

DEVELOPERS

Overview 2

Conformance 3

Distribution Package 4

Terms and Definitions (Normative) 5

Use Case Summary 6

Business Document Metadata Service

Location Profile (Normative)

7

Services provided by the Digital Capability

Register

8

Primary Audience Secondary Audience


2 Overview

The Trans-Tasman e-Invoicing Interoperability Framework provides a framework for interoperability in

digital business, expressed as a set of technical specifications (‘Profiles’) and usage guidelines

(‘Implementation Guidance’). Profiles and Implementation Guidance are designed to facilitate effective

business based on a modular approach for implementation, with a focus on global interoperability.

These Profiles can be seen as ‘agreements’ on standards for message contents and business processes. The

profile descriptions focus on the core information elements that typically cater to the majority of user

requirements applicable across Australia and lower the need for detailed bilateral agreements between the

trading partners.

The Metadata Service Location Profile describes a technical specification for the automated lookup of

digital address information for a participant's capability data.

Invoice


Access PointDigital Capability

PublisherDigital Business

Document

e-Invoicing

Interoperability Framework

Figure 1: Context of Digital Capability Locator within the Interoperability Framework

The context diagram Figure 1 shows the components included in the Trans-Tasman e-Invoicing

Interoperability Framework and where the Digital Capability Locator sits. The Digital Capability Locator is

used by Access Points to enable the e-Invoicing process.

The scope of this Implementation Guide is to:

• Provide an overview of the operating model for maintaining a Participant's Digital Capability

Address,

• Provide an overview of the key use cases that are supported by the Digital Capability Locator,

• Describe how the Profile of Business Document Metadata Service Location is applied within the

Interoperability Framework, and


• Provide implementation guidance for consumers of services provided by the Digital Capability

Locator.

This Implementation Guide incorporates the Profile of Business Document Metadata Service Location

(Section 7) which describes a technical specification for the automated lookup of digital address

information for a participant's capability data. This profile is based on the OASIS Business Document

Metadata Service Location Version 1.0 OASIS Standard (OASIS, 2017) that was issued by OASIS on the 1st

August 2017. The specification is based on the successful implementation and learning outcomes within

the PEPPOL program.

Section 8 provides further guidance for service consumers, specifically in relation to the management of

participant and Digital Capability Publisher information stored in the Digital Capability Locator.

Figure 2 highlights the role of the Digital Capability Locator within the standard 4-corner model.

Figure 2: Four Corner Model

Business Document Metadata Service Location (OASIS, 2017) standardises retrieval of information about a

participant's digital address. A single Digital Capability Locator will exist in a four-corner model community

and the community MUST implement this profile.

The Digital Capability Locator and Digital Capability Publisher are needed for an Access Point to determine

the destination of a message in a dynamic environment. The Digital Capability Locator is a mapping of

participant identifiers to the address of the Digital Capability Publisher.

After retrieving this address, the Access Point accesses the capability of the recipient. Capabilities (i.e. the

document types and business processes that a business can participate in, and information how to interact

electronically with a business) of a business are stored in the Digital Capability Publisher and retrieved by

the Access Points. The Digital Capability Publishers expose an interface that can be used by Access Points to

retrieve this information based on the business identifier, the document type and the business process

being invoked.


Details about the Digital Capability Publisher are described in a separate document published by the Trans-

Tasman Working Group (2018).

3 Conformance

Conformance to the Digital Capability Locator Implementation Guide means conformance with the sections

marked as ‘Normative’ in this Implementation Guide.

The Trans-Tasman e-Invoicing Interoperability Framework (Framework) specifies that dynamic discovery of

a participant's Digital Capability Publisher must conform to this Business Document Metadata Service

Location Profile. Access Points are required to send conformant DNS queries to the Digital Capability

Locator.

Conformance to the Business Document Metadata Service Location Profile does not require conformance

to Section 8.2 onwards.

The keywords ‘MUST’, ‘MUST NOT’, ‘REQUIRED’, ‘SHALL’, ‘SHALL NOT’, ‘SHOULD’, ‘SHOULD NOT’,

‘RECOMMENDED’, ‘MAY’, and ‘OPTIONAL’ in this specification are to be interpreted as described in

RFC2119 (Bradner, 1997).

4 Distribution Package

The Digital Capability Locator Implementation Guide is published at:

https://softwaredevelopers.ato.gov.au/Trans-Tasman-eInvoicing/.

5 Terms and Definitions (Normative)

The terms listed in Table 1 are used as defined throughout this specification.

Table 1: Terms and Definitions

Term Definition

Business Identifier See participant identifier.

Data Format A machine-readable language, syntax or dialect used to present the Information

Elements contained in an electronic Document (for example, an e-Invoice).

Digital Capability

Locator

The Digital Capability Locator holds the electronic address of the digital capability

of a Participant.

Digital Capability

Publisher

The Digital Capability Publisher is a register that stores information regarding the

capabilities of a business entity including information such as the type of business

documents it is equipped to send and receive. It also stores the electronic address

of the business entity’s Access Point.

https://softwaredevelopers.ato.gov.au/Trans-Tasman-eInvoicing/


Digital Capability

Publisher Provider

The Digital Capability Publisher Provider means the service provider of the Digital

Capability Publisher services to a Client.

Distribution Package A packaged file that contains the technical artefacts to support conformant

implementation of the Profile.

e-Invoice An Invoice, RCTI, Credit Note or Adjustment Note that has been created,

transmitted and received in the Trans-Tasman e-Invoicing Data Format.

e-Invoicing The set of processes required to exchange e-Invoices.

Identification Scheme The collection of Identifiers applicable for a given type of Information Element

governed under a common set of rules.

Identifier A character string used to establish the identity of, and distinguish uniquely, one

instance of an object within an Identification Scheme from all other objects within

the same scheme. An Identifier may be a word, number, letter, symbol, or any

combination of those.

Information Element A semantic concept that can be defined independent of any particular data format.

Normative Sections of a document conveying criteria to be fulfilled if compliance with the

document is to be claimed and from which no deviation is permitted.

Participant Means Trans-Tasman e-Invoicing Accredited Access Point Providers, Digital

Capability Publisher and Digital Capability Locator services and the businesses,

organisations and other entities who have adopted the Framework.

Participant Identifier An identifier for a participant.

Profile A conformant subset of a standard specification.

Schema A World Wide Web Consortium (W3C) recommendation that specifies how to

formally describe the XML Elements in an XML Document.

Service An application able to process specific document types for specific business

transactions.

Service Interface A software interface to support a service.


6 Use Case Summary

The Digital Capability Locator supports several capabilities.

Use Cases describe the method of exchange for business documents between two Access Points. Access

Points use business discovery services, implemented by DCL and DCP, to determine the receiver of an

electronic business document. Access Points therefore act as clients to business discovery services. The DCP

and DCL business discovery services are detailed in separate implementation guides.

The Use Cases are divided into two logical groups which represent the separation between normal

execution of e-Delivery activities and the management of the e-Delivery network, specifically the

maintenance of Dynamic Discovery information.

Further details can be found in the Trans-Tasman e-Invoicing Use Cases document.



7 Business Document Metadata Service Location Profile

(Normative)

Business Document Metadata Service Location (OASIS, 2017) defines a mechanism to determine the

location of a metadata service using the well adopted Domain Name System (DNS). The specification

provides mandatory and optional guidance that enables the use of DNS’ Dynamic Delegation Discovery

System (DDDS) (Mealling, 2002) to support resolution of DNS query strings, which identify a unique

individual or organisation. The use of the NAPTR Resource Record (Daigle, 2007) is specified to support this

lookup service.

The use of DNS as the base technology provides a scalable, robust and proven platform for address

resolution. However, it is subject to all the security threats and attack vectors inherit in any DNS-based

solution.

Business Document Metadata Service Location (OASIS, 2017) also provides additional guidance on ‘Special

Use Cases’, which outline the application of participant identifiers in the context of the PEPPOL and GS1

initiatives. These implementations and their associated guidance have a clear parallel to the Australian

context.

Most of the Business Document Metadata Service Location (OASIS, 2017) standard applies verbatim. The

following sub-sections explain how Business Document Metadata Service Location (OASIS, 2017) is used

within the Interoperability Framework.

7.1 Conformance

The e-Delivery implementation MUST meet the requirements for Core Implementation Conformance as

defined in section 4 of Business Document Metadata Service Location. (OASIS, 2017)

7.2 Non-DNS Participant Identifiers

Business Document Metadata Service Location (OASIS, 2017) supports the resolution of party specific

metadata endpoint through the use of a MD5 (see below) hashed IETF/IANA Registered NID format

identifiers.

Use of the Australian Business Number (ABN) would result in the following:

Pre-Hash Example:

urn:oasis:names:tc:ebcore:partyid-type:iso6523:0151::51824753556

Post-Hash Example:

ef1067ff41f0b4885eea42ab0548659e

The e-Delivery implementation of Business Document Metadata Service Location applies the following pre-

processing business rules to ensure interoperability:

1. The client solution MUST use MD5 hashed IETF/IANA Registered NID format identifiers to identify

all participants

2. The client solution MUST ensure the pre-hash URN is UTF-8 encoded.


3. The client solution MUST ensure the pre-hash URN is converted to lower-case.

Further information on the use of IETF/IANA Registered NID format identifiers is contained in the Trans-

Tasman e-Invoicing Policy for the use of Business Identifiers (2018).

7.3 DNS Query String

For use within the Interoperability Framework, the DNS query string MUST adhere to the following

structure:

b-<hash over participantID>.<Digital Capability Locator Domain Name>

This query string will ensure that all IEFT/IANA Registered NID format identifiers can be encoded, stored

and retrieved from a compliant DNS solution.

This structure overcomes the naming restrictions imposed on the hostname portion of a Domain Name,

specifically the 63 character maximum length and various interoperability issues with host names that do

not contain an alphabetical character.

The OASIS standard specifies a schemeID which MUST NOT be used in this context.

7.4 Use of Regular Expressions in U-NAPTR Record

Business Document Metadata Service Location (OASIS, 2017) provides guidance on the structure of the U-

NAPTR including the use of Regular Expressions to transform address structures. This feature SHALL NOT be

used by this profile.

The implementation of this profile as part of the Digital Capability Locator MUST only return base URI of the

Digital Capability Register. All additional URI path information required for a query to the Digital Capability

Register SHOULD be constructed by the Access Point.

7.5 Security Consideration

The Business Document Metadata Service Location (OASIS, 2017) specification recommends the use of

Domain Name System Security Extensions (DNSSEC) to improve the overall security of an implementation.

DNSSEC can help to mitigate common DNS attack vectors such as DNS Spoofing. DNSSEC is able to provide

origin authority, data integrity and authenticated denial of existence through the use of zone signing and

trust anchors.

The implementation of this profile as part of the Digital Capability Locator SHOULD use DNSSEC when

supported in the .AU zone.


8 Services provided by the Digital Capability Locator

8.1 Discovery API

8.1.1 Lookup Participant Capability Address

Purpose of API 8.1.1.1

This Application Programming Interface is used to lookup the Digital Address (URI) of the Digital Capability

Publisher (DCP) for a specified participant, based on the provided Participant Identifier.

Behaviour of API 8.1.1.2

This API will result in the following behaviours:

• Search the DNS and return the U-NAPTR Record that match the provided DNS query.

• The NAPTR record will contain the URI for the Digital Capability Publisher. This URI may include an

hostname component that is either a CNAME or A Type DNS Resource Record that will resolve to

the actual Digital Capability Publisher IP Address as per normal DNS name resolution.

See the Business Document Metadata Service Location Profile (Section 7) for further information.

Sequence Diagram 8.1.1.3

The following sequence diagram demonstrates the flow of control between each solution component:


Supplier’s Access point

DNS Resolver

Lookup digital addressfor participant

Return NAPTR record

Extract URI

Figure 3 Lookup participant's DCP


Attribute Value

DNS Name

Structure

b-<Hash over participantID>.<DCL-Domain>

DNS Example b-ef1067ff41f0b4885eea42ab0548659e.locator.dcl.ato.gov.au

Protocol DNS

DNSSEC Yes (when supported in the .au TLD)

Authentication

Mechanism

None

Status Codes & Error Conditions 8.1.1.4

Response

Code

Additional Information

NOERROR This response code is provided when the DNS query has been successfully resolved.

REFUSED This response code is provided when the DNS DCL-Domain value is incorrect.

NXDOMAIN This response code is provided when the ParticipantID cannot be found.


8.2 API Security

The management APIs must only be made available over HTTPS using TLS1.2 (Dierks & Rescorla, 2008) as a

minimum. Fallback to earlier versions of TLS or SSL must not be used. TLS versions with known

vulnerabilities must not be used.

The management APIs are protected and requires clients to authenticate using a client certificate. The

client as well as server certificates for both Access Points and Digital Capability Publishers are published in

the Digital Capability Locator and should be used to verify peer certificates.

8.3 Management API - Mandatory Services

8.3.1 Register Participant Capability Address


This Application Programming Interface is used to register a relationship between a Participant Identifier

and a Digital Capability Publisher.



• Create a DNS U-NAPTR Record using a hash of the Participant’s Unique Identifier and Issuer,

prefixed by ‘b-‘ and suffixed by the Digital Capability Locator’s Domain Name.





Digital Capability Publisher

Register Participant

Capability Address API

DNS

POST participant

Authenticate

Authorise

Validate

Apply business logic

Create DNS entry

Create DNS U-NAPTR record

Response message

Response message

Figure 4: Sequence Diagram for Components

Attribute Value

Request URL https://<Digital Capability Locator Domain

Name>/api/v1/capabilityPublishers/{capabilityPublisherID}/participants

HTTP Method POST

SSL/TLS Yes

Authentication

Mechanism

Client Certificate (Mutual TLS)

JSON Support Yes

XML Support Yes

Request Headers 8.3.1.4

Header Optional Type Description

Content-Type Mandatory String The MIME type of the body sent to the API.


application/json, application/xml

Accept Optional String application/json, application/xml

Defaults to the Content-Type setting.

Example Request Body - application/json 8.3.1.5

{ "capabilityPublisherID": "1", "participantIdentifierScheme": "urn:oasis:names:tc:ebcore:partyid-type:iso6523:0151", "participantIdentifier": "51824753556" }

Example Request Body - application/xml 8.3.1.6

<RegisterCapabilityAddressForParticipant xmlns="http://busdox.org/serviceMetadata/locator/1.0/" xmlns:ids="http://busdox.org/transport/identifiers/1.0/"> <CapabilityPublisherID>1</CapabilityPublisherID > <ids:ParticipantIdentifier scheme="urn:oasis:names:tc:ebcore:partyid-type:iso6523:0151"> 51824753556 </ids:ParticipantIdentifier> </RegisterCapabilityAddressForParticipant >

Request Field Reference 8.3.1.7

Element Name Description Optional /

Mandatory

Type

participantIdentifier The unique identifier for the Participant. Mandatory String

JSON representation:

participantIdentifierScheme

XML representation:

ParticipantIdentifier/@scheme

The Identifier Scheme which applied to the

participantIdentifier.

Mandatory String

capabilityPublisherID The unique ID assigned to the Digital

Capability Publisher during the

accreditation process. Passed in the

request body as well as the URL.

Mandatory String

HTTP Status Codes & Error Conditions 8.3.1.8

HTTP Status

Code

Message Category Additional Info


201 Created Success The request has been fulfilled and has resulted in one

or more new resources being created.

400 Bad Request Error The server cannot or will not process the request due

to something that is perceived to be a client error.

403 Forbidden Error The server understood the request, but is refusing to

fulfill it. Return this if there is a problem with the

client certificate.

404 Not Found Error The origin server did not find a current representation

for the target resource or is not willing to disclose

that one exists.

422 Unprocessable

Entity

Error The server understands the content type of the

request entity, and the syntax of the request entity is

correct but was unable to process the contained

instructions (see error code reference).

5xx Server Error Error Any appropriate HTTP server error.

Example Responses 8.3.1.9

HTTP RESPONSE CODE: 201 (Created)

Response Headers 8.3.1.10


Content-Type Mandatory String Depending on request:

• application/json (default when not specified in

the Accept request header)

• application/xml

Date Mandatory String The date and time that the message was originated.

Response Body- application/json 8.3.1.11

{ "hash": "b-ef1067ff41f0b4885eea42ab0548659e" }

Response Field Reference 8.3.1.12

Element Name Description Type


hash The hash generated for the Participant Identifier and participantIDScheme

combination. Prefixed with 'b-'.

String

errors The error codes and descriptions related to the action attempted. Array

code The code associated with the error. String

name The name category for the error. String

userMessage The human readable error message. String

Example Error Response - application/json 8.3.1.13

HTTP RESPONSE CODE: 422

{ "errors": [ { "code":"DCL-0422", "name":" Digital Capability Publisher Accreditation Not Valid.", "userMessage":" The accreditation for the nominated Digital Capability Publisher is not valid." }] }

Error Code Reference 8.3.1.14

Code Name User Message More Info

DCL-0422 Digital Capability

Publisher

Accreditation Not

Valid.

The accreditation for the

nominated Digital Capability

Publisher is not valid.

The accreditation of the Digital

Capability Publisher may still be in

underway, or the accreditation may

have been suspended or revoked.


8.3.2 Delete Participant Capability Address


This Application Programming Interface is used to delete a relationship between an Australian Business and

a Digital Capability Publisher.



• Confirmation that the Digital Capability Publisher ID is valid.

• Search for a DNS U-NAPTR Record using a hash of the Participant’s Unique Identifier and Issuer,

suffixed by the Digital Capability Locator’s Domain Name.

• The Participant’s Digital Address history will be updated to flag the relationship as ‘Cancelled’.





Register Participant

Capability Address API

DNS

DELETE participant

Authenticate

Authorise

Validate

Apply business logic

Delete DNS entry

Delete DNS U-NAPTR record

Response message

Response message

Figure 5: Flow of Control Diagram


Attribute Value

Request URL https://<Digital Capability Locator Domain

Name>/api/v1/capabilityPublishers/{capabilityPublisherID}/participants/{participantId}

HTTP Method DELETE

SSL/TLS Yes

Authentication

Mechanism


JSON Support N/A

XML Support N/A

Example Request URL 8.3.2.4

https://api.dcl.ato.gov.au/api/v1/capabilitypublishers/001/participants/urn%3Aoasis%3Anames%3Atc%3Aebcore%3Apartyid-type%3Aiso6523%3A0151%3A%3A51824753556


HTTP Status

Code


204 No Content Success The resource has been removed.

400 Bad Request Error The server cannot or will not process the request

due to something that is perceived to be a client

error.

403 Forbidden Error The server understood the request, but is refusing

to fulfill it. Return this if there is a problem with the

client certificate

404 Not Found Error The origin server did not find a current

representation for the target resource or is not

willing to disclose that one exists.

409 Conflict Error The request could not be completed due to a

conflict with the current state of the target resource

(see error code reference).





Example response 8.3.2.6

HTTP RESPONSE CODE: 204 (No Content)




Response field reference 8.3.2.8




Name The name category for the error. String


Example error response - application/json 8.3.2.9


{ "errors": [ { "code":"DCL-0409", "name":"Resource Mismatch.", "userMessage":" A resource already exists for the participant's unique identifier but contains an alternative Digital Capability Publisher ID." }] }

Error code reference 8.3.2.10


DCL-0409 Resource

Mismatch

A resource already exists for the

participant's unique identifier but

contains an alternative Digital Capability

Publisher ID.

Digital Capability Publishers

are only allowed to delete

their own participant

relationships.


8.4 Management API - Optional Services

8.4.1 Update Digital Capability Publisher End-Point


This Application Programming Interface is used to update the URL for a Digital Capability Publisher.



• A successful API call will overwrite any existing DNS U-NAPTR Record for the Digital Capability

Publisher and replace the DCP URL with the provided URL.


The following sequence diagram demonstrates the flow of control between each solution component for:



Update DCP endpoint API

DCP Status management logic

DNS

PUT endpoint details

Authenticate

Authorise

Validate

Transform

Invoke business logicUpdate resource record

Update DNS RR record

Response message

Process complete

Response message



Attribute Value

Request URL https://<DCL Domain Name>/api/v1/capabilityPublishers/{capabilityPublisherID}

HTTP Method PUT

SSL/TLS Yes

Authentication

Mechanism


JSON Support Yes

XML Support Yes








{

"capabilityPublisherID": "1",

"URL": "www.mysmp.com.au"

}


<UpdateCapabilityPublisherEndpoint>

<CapabilityPublisherID>1</CapabilityPublisherID>

<URL>http://www.mysmp.com.au</URL>

</UpdateCapabilityPublisherEndpoint>



Mandatory

Type

capabilityPublisherID The unique ID assigned to the Digital Capability

Publisher during the accreditation process.

Mandatory String


URL The HTTP URL for the Digital Capability Publisher. Mandatory String


HTTP Status

Code


200 OK Success

400 Bad Request Error The server cannot or will not process the request due to

something that is perceived to be a client error.

403 Forbidden Error The server understood the request, but is refusing to fulfill

it. Return this if there is a problem with the client

certificate.

404 Not Found Error The origin server did not find a current representation for

the target resource or is not willing to disclose that one

exists.

422 Unprocessable

Entity

Error The server understands the content type of the request

entity, and the syntax of the request entity is correct but

was unable to process the contained instructions (see

error code reference).


Example Response 8.4.1.9

HTTP RESPONSE CODE: 200 (OK)



Content-Type Mandatory String Depends on Accept request header:

• application/json (default)

• application/xml



Response Body - application/json 8.4.1.11

{


"URL": "http://www.mysmp.com.au"

}

Response Body - application/xml 8.4.1.12

<UpdateCapabilityPublisherEndpoint>

<CapabilityPublisherID>1</CapabilityPublisherID>

<URL>www.mysmp.com.au</URL>

</UpdateCapabilityPublisherEndpoint>



capabilityPublisherID The unique ID assigned to the Digital Capability Publisher during the

accreditation process.

String

domainName The HTTP URL for the Digital Capability Publisher. String

Errors The error codes and descriptions related to the action attempted. Array






{ "errors": [ { "code": "DCL-0422", "name": "Digital Capability Publisher Accreditation Not Valid.", "userMessage": "The accreditation for the nominated Digital Capability Publisher is not valid." }] }




DCL-0422 Digital Capability

Publisher

Accreditation Not

Valid.

The accreditation for the

nominated Digital Capability

Publisher is not valid.

The accreditation of the Digital

Capability Publisher may still be in

underway, or the accreditation may

have been revoked.


8.4.2 List Accredited Digital Capability Publishers


This Application Programming Interface is used to generate a list of Digital Capability Publishers that hold

current accreditation.



• A look up of all currently accredited Digital Capability Publishers.

• A return list up to the maximum number of specified results or the default limit of 50 records.




API clientList accredited

digital capability publisher API

Accreditation management

module

GET Accredited DCP

Invoke business logic

Return list based onSearch filters

Response message

Figure7: Flow of Control Diagram


Attribute Value

Request URL https://<DCL Domain>/api/v1/capabilitypublishers?limit=<limit value>&offset=<offset

value>

Example URL https://<DCL Domain>/api/v1/capabilitypublishers?limit=25&offset=50

HTTP Method GET

SSL/TLS Yes

Authentication

Mechanism


JSON Support Yes

XML Support Yes

Example Request Headers 8.4.2.4



Defaults to application/json

Request field reference 8.4.2.5

Element

Name

Description Optional/Mandatory Type

offset The index from where to start the response list. Default is

0

Optional Query

String

limit The maximum number of records returned in the

response. Default is 50.

Optional Query

String



HTTP Status

Code


200 OK Success








Content-Type Mandatory String Depending on Accept request header:


• application/xml




"metadata": { "resultset": { "count": 227, "offset": 50, "limit": 25 } }, "results": [ { "capabilityPublisherID":"445", "name":"Australian Taxation Office", "contactEmail":"", "URL":"http://dcp.ato.gov.au", "ClientCertificates": ["",""], "ServerCertificates": ["",""] }, { "capabilityPublisherID":"", "legalId":"", "name":"", "accreditationStatus":"Active", "contactEmail":"", "URL":"", "ClientCertificates": ["",""], "ServerCertificates": ["",""] }] }


<AccreditedProviders> <Metadata> <ResultSet> <Count>227</Count> <Offset>50</Offset> <Limit>25</Limit> </ResultSet> </Metadata> <Results> <Provider> <CapabilityPublisherID>1</CapabilityPublisherID> <Name>Provider 1</Name> <ContactEmail>[email protected]</ContactEmail> <Url>www.provider1.com.au<Url> <ClientCertificates> <ClientCertificate></ClientCertificate> <ClientCertificate></ClientCertificate> </ClientCertificates> <ServerCertificates> <ServerCertificate></ServerCertificate> <ServerCertificate></ServerCertificate> </ServerCertificates> </Provider> <Provider> <CapabilityPublisherID>2</CapabilityPublisherID> <Name>Provider 2</Name> <ContactEmail>[email protected]</ContactEmail> <Url>www.provider2.com.au<Url> <ClientCertificates>


<ClientCertificate></ClientCertificate> <ClientCertificate></ClientCertificate> </ClientCertificates> <ServerCertificates> <ServerCertificate></ServerCertificate> <ServerCertificate></ServerCertificate> </ServerCertificates> </Provider> </Results> </AccreditedProviders>



Metadata An array containing ResultSet metadata. Array

ResultSet An array containing information on the result set returned by the

API.

Array

Count Total number of records matching the request criteria. Int

Offset The offset of the first record contained in the result set within the

total number of records matching the request criteria.

Int

Limit The maximum number of records returned in the result set. Int

CapabilityPublisherID The unique id for the Digital Capability Publisher issued by the

accreditation authority.

String

LegalId The business identifier of the service provider as the owner of the

DCP service.

String

Name The trading name of the provider listed on the accreditation

record.

String

AccreditationStatus The accreditation status of the DCP service. String

ContactEmail A contact email for the DCP. String

Url The URL of the Digital Capability Publisher. String

Client Certificates A PEM base 64 encoded DER formatted X509 client certificate

chain for the server certificates. Up to two certificates are

supported.

Array

Server Certificates A PEM base 64 encoded DER formatted X509 certificate chain for Array


the server certificates. Up to two certificates are supported.






8.4.3 List Accredited Access Points


This Application Programming Interface is used to generate a list of e-Delivery Access Points that hold

current accreditation.



• A look up of all currently accredited Access Points.

• A return list up to the maximum number of specified results or the default limit of 50 records.




API clientList accredited

access point API


module

GET Accredited AP



Response message


Attribute Value

Request URL https://<DCL Domain>/api/v1/accesspoints?limit=<limit value>&offset=<offset value>

Example URL https://<DCL Domain>/api/v1/accesspoints?limit=25&offset=50

HTTP Method GET

SSL/TLS Yes


Authentication

Mechanism


JSON Support Yes

XML Support Yes

Example Request Headers 8.4.3.4




Request field reference 8.4.3.5

Element

Name

Description Optional/Mandatory Type

offset The index from where to start the response list. Default is

0

Optional Query

String

limit The maximum number of records returned in the

response. Default is 50.

Optional Query

String


HTTP Status

Code


200 OK Success









Content-Type Mandatory String Depending on Accept request header:


• application/xml



Example response body - application/json 8.4.3.9

{ "metadata": { "resultset": { "count": 227, "offset": 50, "limit": 25 } }, "results": [ { "accessPointID": "", "legalId":"", "name": "", "accreditationStatus":"", "contactEmail": "", "URL": "", "ClientCertificates": ["",""], "ServerCertificates": ["",""] }, { "accessPointID": "", "legalId":"", "name": "", "accreditationStatus":"", "contactEmail": "", "URL": "", "ClientCertificates": ["",""], "ServerCertificates": ["",""] }] }

Example response body - application/xml 8.4.3.10

<AccreditedProviders> <Metadata> <ResultSet> <Count>227</Count> <Offset>50</Offset> <Limit>25</Limit> </ResultSet> </Metadata> <Results> <Provider> <ServiceProviderID>1</ServiceProviderID> <LegalId></LegalId> <Name>Provider 1</Name> <AccreditationStatus></AccreditationStatus> <ContactEmail>[email protected]</ContactEmail> <URL>https://ap.provider1.com.au<URL> <ClientCertificates> <ClientCertificate></ClientCertificate> <ClientCertificate></ClientCertificate> </ClientCertificates> <ServerCertificates> <ServerCertificate></ServerCertificate> <ServerCertificate></ServerCertificate> </ServerCertificates> </Provider> <Provider> <ServiceProviderID>2</ServiceProviderID> <LegalId></LegalId> <Name>Provider 2</Name>


<AccreditationStatus></AccreditationStatus> <ContactEmail>[email protected]</ContactEmail> <URL>https://ap.provider2.com.au<URL> <ClientCertificates> <ClientCertificate></ClientCertificate> <ClientCertificate></ClientCertificate> </ClientCertificates> <ServerCertificates> <ServerCertificate></ServerCertificate> <ServerCertificate></ServerCertificate> </ServerCertificates> </Provider> </Results> </AccreditedProviders>



Metadata An array containing ResultSet metadata. Array

ResultSet An array containing information on the result set returned by the API. Array

Count Total number of records matching the request criteria. Int

Offset The offset of the first record contained in the result set within the total

number of records matching the request criteria.

Int

Limit The maximum number of records returned in the result set. Int

AccessPointID The unique id for the Access Point issued by the accreditation

authority.

String

LegalId The business identifier of the service provider as the owner of the

Access Point service.

Name The trading name of the provider listed on the accreditation record. String

AccreditationStatus The accreditation status of the Access Point service. String

ContactEmail A contact email for the Access Point. String

URL The URL of the Access Point. String

Client Certificates A PEM base 64 encoded DER formatted X509 certificate chain for the

client certificate. Up to two client certificates are supported.

Array

Server Certificates A PEM base 64 encoded DER formatted X509 certificate chain for the

server certificate. Up to two certificates are supported.

Array



8.5 Management API - Additional Services

8.5.1 Update Digital Capability Publisher Details


This Application Programming Interface is used to update information for a Digital Capability Publisher

additional to the URL. This is the same API as described in 8.4.1 with additional request body parameters.



• A successful API call will overwrite information for the Digital Capability Publisher.





Update DCP details API

DCP Status management logic

PUT DCP details

Authenticate

Authorise

Validate

Transform


Process complete

Response message



Attribute Value

Request URL https://<DCL Domain Name>/api/v1/capabilityPublishers/{capabilityPublisherID}

HTTP Method PUT

SSL/TLS Yes

Authentication

Mechanism


JSON Support Yes

XML Support Yes









{


"contactEmail": [email protected]",

"ClientCertificates":"",

"ClientCertficateStatus":"active",

"ServerCertificates":"",

"ServerCertificateStatus":"active"

}


<UpdateCapabilityPublisherEndpoint> <CapabilityPublisherID>1</CapabilityPublisherID> <contactEmail>[email protected]</contactEmail> <ClientCertificates>QmF...S0t=</ClientCertificates> <ClientCertificateStatus>active</ClientCertificateStatus> <ServerCertificates>U2...LQ0K==</ServerCertificates> <ServerCertificateStatus>active</ServerCertificateStatus> </UpdateCapabilityPublisherEndpoint>



Mandatory

Type

capabilityPublisherID The unique ID assigned to the Digital Capability

Publisher during the accreditation process. Passed

as a query parameter and in the request body.

Mandatory String

contactEmail The contact email for the Digital Capability Publisher

service.

Optional String

ClientCertificates Base 64 encoded PEM format of X509 client

certificate. May include one or more certificates

which belong to one valid certificate chain e.g. Root,

Intermediate, End User certificates.

Optional String

ClientCertificateStatus The status of provided ClientCertificates. One of:

- Active

- Revoked

- Inactive.

Optional String

ServerCertificates Base 64 encoded PEM format of X509 server




Optional String

ServerCertificateStatus The status of provided ServerCertificates. One of: Optional String


- Active

- Revoked

- Inactive.


HTTP Status

Code


200 OK Success





certificate.



exists.

422 Unprocessable

Entity












• application/xml




{ "capabilityPublisherID": "1", "contactEmail": "[email protected]", "ClientCertificates": "QmF...S0t=", "ClientCertificateStatus": "active", "ServerCertificates": "U2...LQ0K==", "ServerCertificateStatus": "active" }


<UpdateCapabilityPublisherEndpoint> <CapabilityPublisherID>1</CapabilityPublisherID> <contactEmail>[email protected]</contactEmail> <ClientCertificates>QmF...S0t=</ClientCertificates> <ClientCertificateStatus>active</ClientCertificateStatus> <ServerCertificates>U2...LQ0K==</ServerCertificates> <ServerCertificateStatus>active</ServerCertificateStatus> </UpdateCapabilityPublisherEndpoint>



capabilityPublisherID The unique ID assigned to the Digital Capability Publisher during

the accreditation process.

String

contactEmail A contact email for the provider. String

ClientCertificates Base 64 encoded PEM format of X509 client certificate. May

include one or more certificates which belong to one valid

certificate chain e.g. Root, Intermediate, End User certificates

String

ClientCertificateStatus The status of provided ClientCertificates e.g. Active, Revoked,

Inactive

String

ServerCertificates Base 64 encoded PEM format of X509 server certificate. May



String

ServerCertificateStatus The status of provided ServerCertificates e.g. Active, Revoked,

Inactive

String








{ "errors": [ { "code": "DCL-0033", "name": "Client Certificate chain cannot verify.", "userMessage": "Client Certificate chain cannot verify." }] }




DCL-0033 Client Certificate

chain cannot verify.

Client Certificate chain cannot

verify.

The provided Client Certificates

cannot build successful chain of

trust.

8.5.2 Update Access Point Details


This Application Programming Interface is used to update information for an Access Point.



• A successful API call will overwrite information for the Access Point.





Access PointUpdate AP details

APIAP Status

management logic

PUT AP details

Authenticate

Authorise

Validate

Transform


Process complete

Response message


Attribute Value

Request URL https://<DCL Domain Name>/api/v1/accesspoints/{accessPointID}

HTTP Method PUT

SSL/TLS Yes

Authentication

Mechanism


JSON Support Yes

XML Support Yes









{ "accessPointID": "1", "URL": “http://www.mysmp.com.au”, "contactEmail": "[email protected]", "ClientCertificates": "QmF...S0t=", "ClientCertificateStatus": "active", "ServerCertificates": "U2...LQ0K==", "ServerCertificateStatus": "active" }


<UpdateAccessPointEndpoint> <AccessPointID>1</AccessPointID> <URL>http://www.mysmp.com.au</URL> <contactEmail>[email protected]</contactEmail> <ClientCertificates>QmFnI...tLS0t</ClientCertificates> <ClientCertificateStatus>active</ClientCertificateStatus> <ServerCertificates>U2Vyd...LQ0K</ServerCertificates> <ServerCertificateStatus>active</ServerCertificateStatus> </UpdateAccessPointEndpoint>



Mandatory

Type

accessPointID The unique ID assigned to the Access Point during

the accreditation process.

Mandatory String

URL The URL of the Access Point Optional String

contactEmail The contact email for the Access Point service. Optional String

ClientCertificates Base 64 encoded PEM format of X509 client




Optional String


ClientCertificateStatus The status of provided ClientCertificates. One of:

- Active

- Revoked

- Inactive.

Optional String

ServerCertificates Base 64 encoded PEM format of X509 server




Optional String

ServerCertificateStatus The status of provided ServerCertificates. One of:

- Active

- Revoked

- Inactive.

Optional String


HTTP Status

Code


200 OK Success





certificate.



exists.

422 Unprocessable

Entity













• application/xml


Example response body - application/json 8.5.2.11

{ "accessPointID": "1", "URL": “http://www.mysmp.com.au”, "contactEmail": "[email protected]", "ClientCertificates": "QmF...S0t=", "ClientCertificateStatus": "active", "ServerCertificates": "U2...LQ0K==", "ServerCertificateStatus": "active" }

Example response body - application/xml 8.5.2.12

<UpdateAccessPointEndpoint> <AccessPointID>1</AccessPointID> <URL>http://www.mysmp.com.au</URL> <contactEmail>[email protected]</contactEmail> <ClientCertificates>QmFnI...tLS0t</ClientCertificates> <ClientCertificateStatus>active</ClientCertificateStatus> <ServerCertificates>U2Vyd...LQ0K</ServerCertificates> <ServerCertificateStatus>active</ServerCertificateStatus> </UpdateAccessPointEndpoint>



accessPointID The unique ID assigned to the Access Point during the accreditation

process.

String

URL The HTTP URL for the Access Point. String

contactEmail A contact email for the Access Point service. String

ClientCertificates Base 64 encoded PEM format of X509 client certificate. May include

one or more certificates which belong to one valid certificate chain

e.g. Root, Intermediate, End User certificates

String

ClientCertificateStatus The status of provided ClientCertificates e.g. Active, Revoked,

Inactive String


ServerCertificates Base 64 encoded PEM format of X509 server certificate. May



String

ServerCertificateStatus The status of provided ServerCertificates e.g. Active, Revoked,

Inactive String





Example error response - application/json 8.5.2.14


{ "errors": [ { "code": "DCL-0056", "name": "URL parameters not match with body parameters", "userMessage": "URL parameters not match with body parameters" }] }




DCL-0056 URL parameters not

match with body

parameters.

URL parameters not match with

body parameters

The access point ID in URL do not

match with access point ID into the

body.

8.5.3 Who am I


This API returns the current client certificate information as recorded in the service provider database

associated with the private key used to connect to the API. Included in the response is the system assigned

identifier for the service if the certificate is stored in the system and the certificate is active. This identifier

is used in other API requests.


This API will results in the following behaviours:

• Based on the client certificate used for the request, the system will retrieve information for the

certificate used in the request. It will return the unique system identifier which is used in the other

API's.

• If the certificate is not recorded in the system, or the certificate is inactive, the API will return the

certificate details with blank identifiers.


The following sequence diagram demonstrated the flow of control between each solution component.


API clientRetrieve credential

details


module

GET Accredited SP(client certificate)



Response message



Attribute Value

Request URL https://<DCL Domain>/api/v1/whoami

Example URL https://<DCL Domain>/api/v1/whoami

HTTP Method GET

SSL/TLS Yes

Authentication

Mechanism


JSON Support Yes

XML Support Yes

Request headers 8.5.3.4




HTTP Status codes & error conditions 8.5.3.5

HTTP Status

Code


200 OK Success

403 Forbidden Error The server understood the request, but is refusing to

fulfill it. Return this if there is a problem with the client

certificate.


Example response 8.5.3.6


Response headers 8.5.3.7





• application/xml


Example response body – application/json 8.5.3.8

{ "ServiceID": "1", "DigitalCapabilityPublisherID": "1", "ServiceStatus": "Active", "Fingerprint": "1e:0f:e7:16:a1:0c:14:9e:50:14:f8:0e:d3:27:ce:ec:37:5c:fd:60", "Serial": "02:38:65:36:14:cd:91:9a:d2:e3:49:9b:3f:a3:d9:79", "Subject": "email.mysmp.com.au", "Issuer": "GeoTrust RSA CA 2018", "NotBefore": "2017-12-15 00:00:00 GMT", "NotAfter": "2020-01-14 12:00:00 GMT" }

Example response body – application/xml 8.5.3.9

<DCL-WhoAmI> <ServiceID>1</ServiceID> <DigitalCapabilityPublisherID>1</DigitalCapabilityPublisherID> <ServiceStatus>Active</ServiceStatus> <Fingerprint>1e:0f:e7:16:a1:0c:14:9e:50:14:f8:0e:d3:27:ce:ec:37:5c:fd:60</Fingerprint> <Serial>02:38:65:36:14:cd:91:9a:d2:e3:49:9b:3f:a3:d9:79</Serial> <Subject>email.mysmp.com.au</Subject> <Issuer>GeoTrust RSA CA 2018</Issuer> <NotBefore>2017-12-15 00:00:00 GMT</NotBefore> <NotAfter>2020-01-14 12:00:00 GMT</NotAfter> </DCL-WhoAmI>

Response field reference 8.5.3.10


ServiceID The unique id for the Service Provider issued by the

accreditation authority.

String

DigitalCapabilityPublisherID The unique id for the Digital Capability Publisher issued by the

accreditation authority. Only included when the certificate

belongs to a DCP.

String

AccessPointID The unique id for the Access Point issued by the accreditation

authority. Only included when the certificate belongs to a

Access Point, or if the certificate is not recorded in the system.

String

ServiceStatus The status the provider listed on the accreditation record. String

Fingerprint A fingerprint of provider’s digital certificate. String



Serial A serial number of provider’s digital certificate. String

Subject A subject name of provider’s digital certificate. String

Issuer An issuer name of provider’s digital certificate. String

NotBefore A starting date of provider’s digital certificate. String

NotAfter An end date of provider’s digital certificate. String

errors The error codes and descriptions related to the action

attempted.

Array




Example error response – application/json 8.5.3.11


If the certificate is not available in the system, or the certificate is inactive, the response only includes

details about the client certificate.

{ "ServiceID": "", "DigitalCapabilityPublisherID": "", "ServiceStatus": "", "Fingerprint": "1e:0f:e7:16:a1:0c:14:9e:50:14:f8:0e:d3:27:ce:ec:37:5c:fd:60", "Serial": "02:38:65:36:14:cd:91:9a:d2:e3:49:9b:3f:a3:d9:79", "Subject": "email.mysmp.com.au", "Issuer": "GeoTrust RSA CA 2018", "NotBefore": "2017-12-15 00:00:00 GMT", "NotAfter": "2020-01-14 12:00:00 GMT" }


APPENDIX A: Digital Capability Locator Error Codes

This error set describes all expected error conditions and responses that might be returned from the Digital

Capability Locator.

HTTP

Status

Code

DCL Code Name User Message

422 DCL-9991 Digital Capability Publisher

ParticipantDcpRelationship Relationship

already exists with future period

ParticipantDcpRelationship Relationship already exists

with future period


ParticipantDcpRelationship Invalid Participant

ID. New Participant need to be added without

relationship date

ParticipantDcpRelationship Invalid Participant ID. New

Participant need to be added without relationship date


ParticipantDcpRelationship End date must be

later than start date

ParticipantDcpRelationship End date must be later than

start date


ParticipantDcpRelationship End date can only

be in future

ParticipantDcpRelationship End date can only be in

future


ParticipantDcpRelationship Start date can only

be in future

ParticipantDcpRelationship Start date can only be in

future


ParticipantDcpRelationship Start date must be

provided

ParticipantDcpRelationship Start date must be provided


ParticipantDcpRelationship Invalid service id

ParticipantDcpRelationship Invalid service id


ParticipantDcpRelationship Relationship

already exists

ParticipantDcpRelationship Relationship already exists

500 DCL-9999 Digital Capability Locator internal Unknown

error

internal Unknown error

400 DCL-0000 json schema mismatch json schema mismatch

400 DCL-0001 json object mismatch json object mismatch

400 DCL-0002 json elements mismatch json elements mismatch

400 DCL-0003 xml schema mismatch xml schema mismatch

400 DCL-0004 xml elements mismatch xml elements mismatch

400 DCL-0005 Missing element value Missing element value

501 DCL-0006 Digital Capability Publisher Post to DNS failed. Post to DNS failed

400 DCL-0007 Resource Mismatch json schema mismatch json schema mismatch

400 DCL-0008 Resource Mismatch json object mismatch json object mismatch

400 DCL-0009 Resource Mismatch json elements mismatch json elements mismatch

400 DCL-0010 Resource Mismatch xml schema mismatch xml schema mismatch

400 DCL-0011 Resource Mismatch xml elements mismatch xml elements mismatch


HTTP

Status

Code


400 DCL-0012 Resource Mismatch missing element value Missing element value

541 DCL-0013 Resource Mismatch Delete to DNS failed Delete to DNS failed

542 DCL-0014 Accreditation Not Valid Put to DNS failed

400 DCL-0015 Digital Capability Locator Resource Not Found Digital Capability Locator Resource Not Found

400 DCL-0016 Accreditation Not Valid Bad Request parameters mismatch

403 DCL-0017 Accreditation Not Valid CurrentActiveClientCertificates have duplicated

fingerprint for same ServiceId

403 DCL-0018 Accreditation Not Valid Verify Fingerprint cannot find certificate

403 DCL-0019 Accreditation Not Valid Verify Fingerprint duplicate cannot be found in DB

certificate

403 DCL-0020 Accreditation Not Valid Verify Fingerprint user cert missing CommonName or

Issuer

403 DCL-0021 Accreditation Not Valid json certificate Pem Fingerprint mismatch

531 DCL-0022 Accreditation Service Not Valid GetActiveServicesClientServerCertificates failed

532 DCL-0023 Accreditation Service Not Valid GetActiveAccessPointClientServerCertificates failed

533 DCL-0024 Accreditation Service Not Valid GetActivePublisherClientServerCertificates failed

534 DCL-0025 Accreditation Service check by LegalId failed GetActiveServicesClientServerCertificatesByLegalId

failed

535 DCL-0026 Accreditation Service check by LegalName

failed

GetActiveServicesClientServerCertificatesByLegalName

failed

404 DCL-0027 Accreditation Service resource not found Resource not found.

514 DCL-0028 Commit DNS participant not found or

lastModifiedDate is not set

Participant not found or lastModifiedDate not set

403 DCL-0029 UpdateService not allowed to update current

connection certificate

Not allowed to update current in use certificate

516 DCL-0030 UpdateService ServiceId is not Active or dsoes

not exist

ServiceId is not Active or does not exist

517 DCL-0031 UpdateService returned error UpdateService returned error

400 DCL-0032 Error not found single valid object Not found single valid object

403 DCL-0033 Client Certificate chain cannot verify Client Certificate chain cannot verify

403 DCL-0034 Server Certificate chain cannot verify Server Certificate chain cannot verify

403 DCL-0035 Client Certificate Status is not valid, expect

Active, Revoked or Inactive, etc..

Client Certificate Status is not valid

403 DCL-0036 Server Certificate Status is not valid, expect

Active, Revoked or Inactive, etc..

Server Certificate Status is not valid

403 DCL-0037 Client Certificate and Server Certificate cannot

be the same

Client Certificate and Server Certificate cannot be the

same

422 DCL-0038 Not allowed to update with existing domain

name URI

Not allowed to update with existing domain name URI

422 DCL-0039 Domain name URI protocol not http or https Domain name URI protocol not http or https or contain


HTTP

Status

Code


or contain forbidden characters forbidden characters

519 DCL-0040 Digital Capability Publisher Add

ParticipantDcpRelationship DB error

Add ParticipantDcpRelationship DB error

543 DCL-0041 Digital Capability Publisher Add

ParticipantDcpRelationship internal DB error

Add ParticipantDcpRelationship internal DB error

400 DCL-0042 Digital Capability Publisher Start Date

incorrect format

Start Date incorrect format

400 DCL-0043 Digital Capability Publisher End Date incorrect

format

End Date incorrect format

400 DCL-0044 Digital Capability Publisher Start Date and End

Date cannot be same

Start Date and End Date cannot be same

400 DCL-0045 Digital Capability Publisher start date has been

set too far in the future

Start date has been set too far in the future

422 DCL-0046 Digital Capability Publisher Not allowed to

update with existing dcp public ID

Not allowed to update with existing DCP public ID

529 DCL-0047 Cannot log to DB InjectEvent Cannot log to DB

400 DCL-0048 Input parameters oversize limit Input parameters oversize limit

400 DCL-0049 Input parameters incorrect format Input parameters incorrect format

403 DCL-0050 Accredited Service status not Active Service status not Active.

544 DCL-0051 GetServiceContacts cannot return old contacts

for update

GetServiceContacts cannot return old contacts for

update


capabilityPublisherID not valid.

capabilityPublisherID not valid


capabilityPublisherID (DCP) not valid

CapabilityPublisherID (DCP) not valid

403 DCL-0054 Digital Capability Publisher you can add

participants only to your own DCPs

You can add participants only to your own DCPs

400 DCL-0055 Digital Capability Locator URL parameters

mismatch

Digital Capability Locator URL parameters mismatch

400 DCL-0056 URL parameters not match with body

parameters

URL parameters not match with body parameters

403 DCL-0057 Tear Down Service Relationships Not Enabled Tear Down Service Relationships Not Enabled

400 DCL-0058 (UpdateCapabilityPublisherEndpoint)

capabilityPublisherID OR

(UpdateAccessPointEndpoint) accessPointID

must be specified in the body

(UpdateCapabilityPublisherEndpoint)

capabilityPublisherID OR (UpdateAccessPointEndpoint)

accessPointID must be specified in the body

403 DCL-0059 accessPointID not valid accessPointID not valid

400 DCL-0060 End date must be later than start date End date must be later than start date

400 DCL-0061 capabilityPublisherID is different than your

Service Provider Id

capabilityPublisherID is different than your Service

Provider Id

400 DCL-0062 AccessPointID is different than your Service

Provider Id

AccessPointID is different than your ServiceProviderId


HTTP

Status

Code


403 DCL-0063 Tear Down Service capabilityPublisherID is

different to the certificate registration

Tear Down Service capabilityPublisherID is different to

the certificate registration

403 DCL-0064 Tear Down Service capabilityPublisherID is

rejected

Tear Down Service capabilityPublisherID is rejected

400 DCL-0065 participant Scheme is not valid participant Scheme is not valid

536 DCL-0101 Digital Capability Locator DB issue Could not init DB

537 DCL-0102 Digital Capability Locator DB issue Could not initialize dblogin structure

538 DCL-0103 Digital Capability Locator DB issue Could not connect to DB Server

539 DCL-0104 Digital Capability Locator DB issue Could not switch to database on DB Server

540 DCL-0105 Digital Capability Locator DB issue Could not execute the SQL statement

403 DCL-0403 Digital Capability Publisher Accreditation Not

Valid.

json certificate Pem Fingerprint mismatch

404 DCL-0404 Resource Mismatch Participant's unique identifier cannot be found

404 DCL-0405 Relationship does not exists to this participant Relationship does not exists to this participant

409 DCL-0409 Resource Mismatch A resource already exists for the participant's unique

identifier but belongs to alternative Digital Capability

Publisher ID

422 DCL-0422 Digital Capability Publisher Accreditation Not

Valid

The accreditation for the nominated Digital Capability

Publisher is not valid


References

1. Berners-Lee, T., Fielding, R., & Masinter, L. (2005, January). Uniform Resource Identifier (URI): Generic

Syntax. From https://tools.ietf.org/html/rfc3986#section-2.1

2. Bradner, S. (1997, March). Key words for use in RFCs to Indicate Requirement Levels. From

https://www.ietf.org/rfc/rfc2119.txt

3. Daigle, L. (2007, April). Domain-Based Application Service Location Using URIs and the Dynamic

Delegation Discovery Service (DDDS). From https://tools.ietf.org/html/rfc4848

4. Dierks, T., & Rescorla, E. (2008, August). The Transport Layer Security (TLS) Protocol Version 1.2. From

https://tools.ietf.org/html/rfc5246

5. Trans-Tasman Working Group. (2018). Trans-Tasman e-Invoicing Access Point Implementation Guide. Canberra: https://softwaredevelopers.ato.gov.au/Trans-Tasman-eInvoicing.

6. Trans-Tasman Working Group. (2018). Trans-Tasman e-Invoicing Digital Capability Publisher

Implementation Guide. Canberra: https://softwaredevelopers.ato.gov.au/Trans-Tasman-eInvoicing.

7. Trans-Tasman Working Group. (2018). Trans-Tasman e-Invoicing policy for using business identifiers. Retrieved from https://softwaredevelopers.ato.gov.au/Trans-Tasman-eInvoicing.

8. Trans-Tasman Working Group. (2019). Trans-Tasman e-Invoicing - Use cases . Canberra:

https://softwaredevelopers.ato.gov.au/Trans-Tasman-eInvoicing.

9. Leach, P., Mealling, M., & Salz, R. (2005, July). A Universally Unique IDentifier (UUID) URN Namespace.

From https://www.ietf.org/rfc/rfc4122.txt

10. Mealling, M. (2002, October). Dynamic Delegation Discovery System (DDDS) - Part One: The

Comprehensive DDDS. From https://www.ietf.org/rfc/rfc3401.txt

11. OASIS. (2017). Business Document Metadata Service Location Version 1.0 Candidate OASIS Standard

02. From http://docs.oasis-open.org/bdxr/BDX-Location/v1.0/cos02/BDX-Location-v1.0-cos02.html

12. OASIS. (2010, September 28). OASIS ebCore Party Id Type Technical Specification Version 1.0

Committee Specification 01. From http://docs.oasis-

open.org/ebcore/PartyIdType/v1.0/CS01/PartyIdType-1.0.html

13. OASIS. (2014, December 18). Service Metadata Publishing (SMP) Version 1.0. (J. Aabol, K. Bengtsson, S.

Fieten, & S. Rasmussen, Eds.) From http://docs.oasis-open.org/bdxr/bdx-smp/v1.0/cs01/bdx-smp-v1.0-

cs01.html

14. Object Management Group. (2015). Unified Modeling Language™ (UML®). From

http://www.omg.org/spec/UML/

15. Schematron. (2004). A language for making assertions about patterns found in XML documents. From

http://schematron.com/spec.html

16. W3C. (2012, April 5). W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. From

http://www.w3.org/TR/xmlschema11-2/

http://www.w3.org/TR/xmlschema11-2/

trans tasman e invoicing digital capability locator ... · trans-tasman e-invoicing digital...

Documents