Background

Both of the automated interfaces currently in use (TDA and SFTP) depend on older technologies. The future DAS service should be upgraded to a more modern technology, which will simplify the implementation for offices, improve security and authentication mechanisms, and potentially allow for faster document exchange.
A new REST API is proposed to modernise the automated interfaces between offices and WIPO DAS:
REST Web Services.
OpenID Connect and asymmetric encryption for unpublished document content to secure the exchange process and content
Please click here to download the specification in yaml
Revision 2023-02-21
openapi: 3.0.0
info:
  description: |
    This is the draft version of DAS exchange API to be used by IP Offices to exchange priority documents.
    It is supported by the WIPO Industrial Property Business Solution Division. 
  version: "1.0"
  #----------------------------------------------------------
  # - Revised on 2023-02-21
  # added a service to retrieve registration certificate and an example fo 500 error details  
  # corrected a few paragraphs in description  
  # updated to handle error encountered in file upload using url-uploads service
  # updated to handle registration error details in response to the registration status check 
  # updated to add service to find retrievals that are in process or newly completed with details to download document 
  #----------------------------------------------------------
  title: DAS Core Service API
  #terms of use: 'https://intranet.wipo.int/confluence'
  contact:
    email: ipas@wipo.int
  license:
   name: Apache 2.0
    #url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
    
servers:
  - url: 'https://das.wipo.int:{port}'
    description: Production DAS exchange API
    variables:
      port:
        enum:
        - '443'
        default: '443'
  - url: 'https://das-acc.wipo.int:{port}'
    description: Test DAS exchange API
    variables:
      port:
        enum:
        - '443'
        default: '443'
  - url: 'https://das-dev.wipo.int:{port}'
    description: Development DAS exchange API
    variables:
      port:
        enum:
        - '443'
        default: '443'

tags:
  - name: information 
    description: >
      Health check of the DAS api
  - name: requests
    description: >
      Document Requests 

security: 
  - bearerAuth: [] 

paths:
  /am/v1/oauth2/access_token:
    post:
      tags:
        - authorization
      description: >
        Service to authorize use of the DAS api. This is the endpoint of a third party product that supports **OpenID Connect (OIDC)** authentication protocol based on the OAuth 2.0 family of specifications
      summary: retrieve the access token
      operationId: getTokens
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: 'client_credentials'
                  description: OAuth2 client_credentials authentication flow is used for machine to machine communication
                scope:
                  type: string
                  example: 'das-api/das-access'
                  description: Scopes (=roles), if any, separated by spaces which are required to use the DAS API
                client_assertion_type:
                  type: string
                  example: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
                  description: the client_assertion_type indicates to the authorization server the method used to authenticate, private_key_jwt requires jwt-bearer
                client_assertion:
                  type: string
                  example: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkYXMtYXBpLWF1dG giLCJzdWIiOiJkYXMtYXBpLWF1dGgiLCJhdWQiOiJodHRwczovL2xvZ2luZG V2LndpcG8uaW50OjQ0My9hbS9vYXV0aDIvYWNjZXNzX3Rva2VuIiwiZXh wIjoxNjIyNDUwNzI4fQ.BLA6k2kKKFVm6AG-DPDpRU_5JDFGRF1dHjKul7saWCv5OxXGg4EY-J9e1p8Dg0ngD2dZ2grkJ2su7jaHy67YEw'
                  description: private key of the JWT token
              required:
                - grant_type
                - scope
                - client_assertion_type
                - client_assertion

      security:
        - OAuth2: [read] 
      responses:
        '200':
          description: successful with the document audit trail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
              examples:
                exampleOfToken:
                  $ref: '#/components/examples/exampleOfToken'
        '400':
          description: invalid request
          content: 
            {}
        '403':
          description: resource access not found
          content: 
            {}
        '500':
          description: Internal system error
          content: 
            {}

  /das/v1/services:
    get:
      tags:
        - information
      description: >
        service to retrieve DAS service details information
      summary: retrieve DAS service information
      operationId: readInformation
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Information'
              examples:
                exampleOfServiceInformation:
                  $ref: '#/components/examples/exampleOfServiceInformation'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
  
  /das/v1/requests/files/url-uploads:
    post:
      tags:
        - requests
      description: >
        create a WIPO DAS presigned URL to upload a file without any limitation in file size. File content can be uploaded using the returned URL as a http PUT request
      summary: obtain file Id and a presigned URL to upload a big size document file for registration by OFF which does not have digital library
      operationId: createFileUploadUrl
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUploadRequest'
            examples:
              FileUploadRequest:
                $ref: '#/components/examples/example-FileUploadRequest'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
              examples:
                FileUploadResponse:
                  $ref: '#/components/examples/example-FileUploadResponse'
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created resource 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFileDetails:
                  $ref: '#/components/examples/exampleOfErrorFileDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    put:
      tags:
        - requests
      description: >
        update an existing upload request with a new WIPO DAS presigned URL to upload a file without any limitation in file size. File content can be uploaded using the returned URL as a http PUT request
      summary: obtain a new presigned URL related to an existing fileId to upload a big size document file for registration by OFF which does not have digital library
      operationId: updateFileUploadUrl
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileId'
            examples:
              FileId:
                $ref: '#/components/examples/example-FileId'
      responses:
        '204':
          description: successful operation
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created resource 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFileDetails:
                  $ref: '#/components/examples/exampleOfErrorFileDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/files/url-downloads:
    post:
      tags:
        - requests
      description: >
        retrieve WIPO DAS URLs to download document file contents without any limitation in file sizes.
      summary: retrieve WIPO DAS URLs to download document file contents 
      operationId: getFileDownloadUrl
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileDownloadRequest'
            examples:
              FileDownloadRequest:
                $ref: '#/components/examples/example-FileDownloadRequest'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDownloadResponse'
              examples:
                FileDownloadResponse:
                  $ref: '#/components/examples/example-FileDownloadResponse'
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created download URL
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFileDetails:
                  $ref: '#/components/examples/exampleOfErrorFileDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/files:
    get:
      tags:
        - requests
      description: >
        retrieve file details of a file content identified by the id given by the POST service of /requests/files/uploads
      summary: obtain file details identified by the given fileId 
      operationId: RetrieveFileDetailsById
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDetails'
              examples:
                exampleOfUploadFile:
                  $ref: '#/components/examples/example-FileDetails'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFileId:
                  $ref: '#/components/examples/exampleOfErrorFileId'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    delete:
      tags:
        - requests
      description: >
        delete the file from DAS transit identified by the id given by the POST service of /requests/files/uploads
      summary: delete from DAS transit the file by the given fileId 
      operationId: DeleteFileById
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: query
          required: true
          schema:
            type: string
      responses:
        '204':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFileId:
                  $ref: '#/components/examples/exampleOfErrorFileId'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/registrations:
    post:
      tags:
        - requests
      description: >
        register a document by OFF
      summary: register a document by OFF. Registration can be made with document details but without document content or with document content to be kept in WIPO DAS.
      operationId: registerDocument
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRegistrationRequest'
            examples:
              DocumentRegistrationRequest:
                $ref: '#/components/examples/exampleOfDocumentRegistrationRequest'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRegistrationResponse'
              examples:
                DocumentRegistrationResponse:
                  $ref: '#/components/examples/exampleOfDocumentRegistrationResponse'
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created resource 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorDocumentDetails:
                  $ref: '#/components/examples/exampleOfErrorDocumentDetails'
                exampleOfErrorFileId:
                  $ref: '#/components/examples/exampleOfErrorFileId'
                exampleOfErrorFileIncomplet:
                  $ref: '#/components/examples/exampleOfErrorFileIncomplet'
                exampleOfErrorEmailFormat:
                  $ref: '#/components/examples/exampleOfErrorEmailFormat'
                exampleOfErrorDocumentAlreadyRegistered:
                  $ref: '#/components/examples/exampleOfErrorDocumentAlreadyRegistered'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    put:
      tags:
        - requests
      description: >
        update a registered document content with a new fileId and/or correct the document date and/or parent application details.
        Note: Document number and DAS access code cannot be changed once the document is registered in WIPO DAS.
      summary: update a registered document content with a new fileId and/or correct the document date and/or parent application details
      operationId: updateRegisteredDocument
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRegistrationRequest'
            examples:
              DocumentRegistrationRequest:
                $ref: '#/components/examples/exampleOfDocumentRegistrationRequest'
      responses:
        '204':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorDocumentDetails:
                  $ref: '#/components/examples/exampleOfErrorDocumentDetails'
                exampleOfErrorFileId:
                  $ref: '#/components/examples/exampleOfErrorFileId'
                exampleOfErrorFileIncomplet:
                  $ref: '#/components/examples/exampleOfErrorFileIncomplet'
                exampleOfErrorEmailFormat:
                  $ref: '#/components/examples/exampleOfErrorEmailFormat'
                exampleOfErrorDocumentUpdate:
                  $ref: '#/components/examples/exampleOfErrorDocumentUpdate'
                exampleOfErrorDASAccessCode:
                  $ref: '#/components/examples/exampleOfErrorDASAccessCode'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    get:
      tags:
        - requests
      description: >
        get the status of a recorded request for document registration from OFF to WIPO DAS 
      summary: get the status of a recorded request for document registration from OFF to WIPO DAS 
      operationId: getStatusDocumentRegistrationRequest
      security:
        - bearerAuth: []
      parameters:
        - name: requestAckId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRegistrationResponse'
              examples:
                DocumentRegistrationResponse:
                  $ref: '#/components/examples/exampleOfDocumentRegistrationResponse'
        '303':
          description: see other
          headers:
            Location:
              schema:
                type: string
              description: URI to download the document
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorRetrievalDetails:
                  $ref: '#/components/examples/exampleOfErrorRetrievalDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/registrations/certificates:
    get:
      tags:
        - requests
      description: >
        download the binary content of the WIPO DAS document registration certificate page in PDF format 
      summary: get the WIPO DAS document registration certificate page in PDF format 
      operationId: getRegistrationCertificate
      security:
        - bearerAuth: []
      parameters:
        - name: documentKindCategory
          in: query
          required: true
          schema:
            type: string
        - name: documentCodeCategory
          in: query
          required: false
          schema:
            type: string
        - name: documentNumber
          in: query
          required: true
          schema:
            type: string
        - name: documentDate
          in: query
          required: true
          schema:
            type: string
        - name: dasAccessCode
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorRetrievalDetails:
                  $ref: '#/components/examples/exampleOfErrorRetrievalDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/retrievals:
    post:
      tags:
        - requests
      description: >
        create a request for document retrieval by OSF to WIPO DAS or WIPO DAS to OFF
      summary: create a document retrieval request by OSF to WIPO DAS or WIPO DAS to OFF
      operationId: createDocumentRetrievalRequest
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRetrievalRequest'
            examples:
              DocumentRetrievalRequest:
                $ref: '#/components/examples/exampleOfDocumentRetrievalRequest'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRetrievalResponse'
              examples:
                DocumentRetrievalResponse:
                  $ref: '#/components/examples/exampleOfDocumentRetrievalResponse'
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the created resource 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorRetrievalDetails:
                  $ref: '#/components/examples/exampleOfErrorRetrievalDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'
    get:
      tags:
        - requests
      description: >
        get the recorded requests for document retrievals from OSF to WIPO DAS or WIPO DAS to OFF 
      summary: get the recorded requests for document retrievals from OSF to WIPO DAS or WIPO DAS to OFF
      operationId: getDocumentRetrievals
      security:
        - bearerAuth: []
      parameters:
        - name: requestAckId
          in: query
          required: false
          schema:
            type: string
        - name: requestStatusCategory
          in: query
          required: false
          schema:
            type: string
            enum: [pending,ready for download]
      responses:
        '200':
          description: successful operation if requestAckId is provided but the requested document is not yet available for download or if status is provided in order to retrieve newly available document details or pending retrievals 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRetrievalBag'
              examples:
                DocumentRetrievalBag:
                  $ref: '#/components/examples/exampleOfDocumentRetrievalBag'
        '303':
          description: successful operation with redirection to download the document
          headers:
            Location:
              schema:
                type: string
              description: URI pointing to the URL to download the document 
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorRetrievalDetails:
                  $ref: '#/components/examples/exampleOfErrorRetrievalDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/notifications:  
    post:
      tags:
        - requests
      description: >
        send notification of the availability of documents that have been requested from OFF or WIPO DAS
      summary:  send notification of the availability of documents by OFF or WIPO DAS
      operationId: notifyOfDocumentAvailability
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentNotifications'
            examples:
              exampleOfDocumentNotifications:
                $ref: '#/components/examples/exampleOfDocumentNotifications'  
      responses:
        '201':
          description: successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorNotificationDetails:
                  $ref: '#/components/examples/exampleOfErrorNotificationDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests:
    get:
      tags:
        - requests
      description: >
        retrieve a collection of document requests by OFF or by OSF
      summary: retrieve a collection of recorded document requests (registration or retrieval) based on filter options
      operationId: retrieveDocumentRequests
      security:
        - bearerAuth: []
      parameters:
        - name: officeCode
          in: query
          required: false
          schema:
            type: string 
            description: "two-letter office code"
        - name: operationCategory
          in: query
          schema:
            type: string 
            enum: [registration,retrieval]
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date
            description: date format in the format of yyyy-mm-dd
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date
            description: date format in the format of yyyy-mm-dd
        - name: documentKindCategory
          in: query
          schema:
            type: string 
            enum: [design,patent,trademark,utility model]
        - name: documentNumber
          in: query
          required: false
          schema:
            type: string
            description: priority document number starting with the two-letter office code, but it may contain wildcard characters '*' and '?' 
        - name: requestStatusCategory
          in: query
          schema:
            type: string
            enum: [successful,awaiting off response, document awaiting security clearance,document number not available,document incomplete,unmatched document date, unmatched access code, unmatched document date and access code, invalid document details]
        - name: limit
          in: query
          schema:
            type: integer
            format: int32
            default: 1000
            description: number of documents to be provided in response if available
        - name: offset
          in: query
          schema:
            type: integer
            format: int32
            default: 0
            description: position of the collection of documents to retrieve
        - name: countOnly
          in: query
          schema:
            type: boolean
            default: true
            description: number of documents matching the given filter
        - name: sortedBy
          in: query
          schema:
            type: string
            enum: ['date:asc','date:desc']
            default: 'date:desc'
      
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordedDocumentRequestBag'
              examples:
                exampleOfRecordedDocumentRequests:
                  $ref: '#/components/examples/exampleOfRecordedDocumentRequests'
                exampleOfRecordedDocumentRequestCount:
                  $ref: '#/components/examples/exampleOfRecordedDocumentRequestCount'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorFilter:
                  $ref: '#/components/examples/exampleOfErrorFilter'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/requests/statistics:  
    get:
      tags:
        - requests
      description: >
        retrieve exchange statistics of offices. Statistics data of the consumer office can be retrieved by the office. Statistics of all offices can be retrieved by WIPO DAS.
        If no filter is specified for operationCategory, statistics includes registrations and retrievals
      summary:  retrieve exchange statistics of offices. 
      operationId: getRequestStatistics
      security:
        - bearerAuth: []
      parameters:
        - name: officeCode
          in: query
          required: false
          schema:
            type: string 
            description: "two-letter office code"
        - name: operationCategory
          in: query
          required: false
          schema:
            type: string 
            enum: [registration,retrieval]
        - name: startYear
          in: query
          required: false
          schema:
            type: integer
            format: int8
            description: year format in the format of yyyy
        - name: endYear
          in: query
          required: false
          schema:
            type: integer
            format: int8
            description: year format in the format of yyyy
        - name: documentKindCategory
          in: query
          schema:
            type: string 
            enum: [design,patent,trademark,utility model]
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequestStatistcis'
              examples:
                exampleOfDocumentRequestStatistcis:
                  $ref: '#/components/examples/exampleOfDocumentRequestStatistcis'  
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfErrorNotificationDetails:
                  $ref: '#/components/examples/exampleOfErrorNotificationDetails'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

  /das/v1/documents/numbers:  
    get:
      tags:
        - documents
      description: >
        Get the list of available application types (IP rights) and number formats
      summary: Get the list of available application types (IP rights) and number formats
      operationId: readNumberFormats
      parameters:
        - name: officeCode
          in: query
          required: true
          schema:
            type: string
        - name: documentKindCategory
          in: query
          required: false
          schema:
            type: string
        - name: input
          in: query
          required: false
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentNumberFormats'
              examples:
                exampleOfDocumentNumberFormats:
                  $ref: '#/components/examples/exampleOfDocumentNumberFormats'
            application/xml:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfInvalidOfficeCode:
                  $ref: '#/components/examples/exampleOfInvalidOfficeCode'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError401:
                  $ref: '#/components/examples/exampleOfError401'
        '500':
          description: Internal system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                exampleOfError500:
                  $ref: '#/components/examples/exampleOfError500'

externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'
  
components:
  schemas:

    Information:
      type: object
      properties:
        applicationName: 
          type: string
        applicationVersion:
          type: string
        buildDate:
          type: string
          format: date
        buildTime:
          type: string
        codeBranch: 
          type: string
        codeRevision:
          type: string

    DocumentRegistrationRequestStatistcis:
      type: object
      properties:
        officeFirstFiling:
          type: string
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        year:
          type: integer
          format: int8
        month:
          type: integer
          format: int8
        totalQuantity:
          type: integer
          format: int32

    DocumentRetrievalRequestStatistcis:
      type: object
      properties:
        officeFirstFiling:
          type: string
        officeSecondFiling:
          type: string
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        year:
          type: integer
          format: int8
        month:
          type: integer
          format: int8
        totalQuantity:
          type: integer
          format: int32

    DocumentRequestStatistcis:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/StatisticsFilter'
        registrations:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRegistrationRequestStatistcis'
        retrievals:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRetrievalRequestStatistcis'

    DocumentRequest:
      type: object
      properties:
        operationCategory:
          type: string
          enum: [registration,retrieval]
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        documentCodeCategory:
          type: string
          description: 'priority document'
        documentNumber:
          type: string
          description: in case of priority document, it contains the two-letter office code and the application number of which the certified copy should be made available
        documentDate:
          type: string
          format: date
          example: "2020-05-01"
          description: timestamp in the form of yyyy-mm-dd (i.e. filing date)
        dasAccessCode:
          type: string
          description: provided by office of first filing. Otherwise it will be issued by WIPO DAS
        applicationCategory:
          type: string
          enum: [design,patent,trademark,utility model]
          description: In case of registration, this may be used as IP type of the application in OFF which holds the foreign priority document. In case of retrieval, this may be used as IP type of the reference application in OSF for which the priority document is retrieved 
        applicationNumber:
          type: string
          description: In case of registration, this may be used as the application number in OFF which holds the foreign document. In case of retrieval, this may be used as the reference application number in OSF for which the priority document is retrieved
        applicationFilingDate:
          type: string
          format: date
          example: "2020-05-01"
          description: In case of registration, this may be used as the filing date of the application in OFF which holds the foreign document. In case of retrieval, this may be used as the reference application filing date in OSF for which the priority document is retrieved

    DocumentRegistrationRequest:
      allOf:
        - $ref: '#/components/schemas/DocumentRequest'
        - type: object
      type: object
      properties:
        email:
          type: string
          description: email becomes mandatory to receive the DAS access code if the DAS access code is not provided by the caller in the registration request
        fileId:
          type: string
          description: file Id of the requested document content which can be securely accessed in the transit area of WIPO DAS.

    DocumentRetrievalRequest:
      $ref: '#/components/schemas/DocumentRequest'
        
    DocumentRegistrationResponse:
      allOf:
        - $ref: '#/components/schemas/DocumentRetrievalRequest'
        - type: object
      properties:
        requestAckId:
          type: string
          description: acknowledgement id provided in the response of the service request call
        operationDateTime:
          type: string
          format: date-time
          example: '2020-05-01T14:00:08Z'
          description: operation date and time recorded and provided in response only
        requestStatusCategory:
          type: string
          enum: [document registered,document not registered]
        revocationDate:
          type: string
          format: date
          example: "2020-05-01"
          description: In case of removal of the registered document in exceptional scenario, this may be used as the date when the document is removed from the system
        error:
          type: string
          description: possible error details 

    RecordedDocumentRequest:
      allOf:
        - $ref: '#/components/schemas/DocumentRequest'
        - type: object
      type: object
      properties:
        email:
          type: string
          description: email becomes mandatory to receive the DAS access code if the DAS access code is not provided by the caller in the registration request
        fileId:
          type: string
          description: file Id of the requested document content which can be securely accessed in the transit area of WIPO DAS. by the authorized requestor.
        requestAckId:
          type: string
          description: acknowledgement id provided in the response of the service request call
        operationDateTime:
          type: string
          format: date-time
          example: '2020-05-01T14:00:08Z'
          description: operation date and time recorded and provided in response only
        requestStatusCategory:
          type: string
          enum: [pending,successful,awaiting off response,error]
        error:
          type: string
          description: error details -> document withdrawn, document awaiting security clearance,document number not available,document incomplete,unmatched document date,unmatched access code,unmatched document date and access code,invalid document details

    RecordedDocumentRequestFilter:
      type: object
      properties:
        officeCode:
          type: string
          description: two-letter office code
        operationCategory:
          type: string
          enum: [registration,retrieval]
        startDate:
          type: string
          format: date
          description: date format in the format of yyyy-mm-dd
        endDate:
          type: string
          format: date
          description: date format in the format of yyyy-mm-dd
        documentKindCategory:
          enum: [design,patent,trademark,utility model]
        documentNumber:
          type: string
        requestStatusCategory:
          type: string
          enum: [pending,successful,delivered,awaiting off response,document awaiting security clearance,document number not available,document incomplete,unmatched document date,unmatched access code,unmatched document date and access code,invalid document details]
        limit: 
          type: integer
          format: int32
          default: 1000
          description: number of documents to be provided in response if available, used only when output=documents
        offset: 
          type: integer
          format: int32
          default: 0
          description: position of the collection of documents to retrieve, used only when output=documents
        countOnly:
          type: boolean
          description: position of the collection of documents to retrieve, used only when output=documents
        sortedBy: 
          type: string
          enum: ['date:asc','date:desc']
          default: 'date:desc'

    StatisticsFilter:
      type: object
      properties:
        officeCode:
          type: string
          description: two-letter office code
        operationCategory:
          type: string
          enum: [registration,retrieval]
        startYear:
          type: integer
          format: int8
          description: year format in the format of yyyy
        endDate:
          type: integer
          format: int8
          description: year format in the format of yyyy
        documentKindCategory:
          enum: [design,patent,trademark,utility model]

    RecordedDocumentRequestBag:
      type: object
      properties:
        filter: 
          $ref: '#/components/schemas/RecordedDocumentRequestFilter'
        totalQuantity:
          type: integer
          description: total number of requests matching the filter options
        recordedDocumentRequestBag:
          type: array
          items:
            $ref: '#/components/schemas/RecordedDocumentRequest'

    DocumentRetrievalResponse:
      allOf:
        - $ref: '#/components/schemas/DocumentRetrievalRequest'
        - type: object
      properties:
        requestAckId:
          type: string
          description: acknowledgement id provided in the response of the service request call
        documentCodeCategory:
          type: string
        operationDateTime:
          type: string
          format: date-time
          example: '2020-05-01T14:00.00.000Z'
          description: operation date and time recorded and provided in response only
        requestStatusCategory:
          type: string
          enum: [pending,delivered,ready for download,awaiting off response,document awaiting security clearance,document number not available,document incomplete,unmatched document date,unmatched access code,unmatched document date and access code,invalid document details]
        error:
          type: string
          description: error details

    DocumentRetrievalBag:
      type: object
      properties:
        officeCode:
          type: string
        documentQuantity:
          type: integer
          format: int8
        documentRetrievalResponses:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRetrievalResponse'          

    DocumentRetrievalRequestStatus:
      type: object
      properties:
        requestAckId:
          type: string
          description: acknowledgement id provided in the response of the service request call
        requestStatusCategory:
          type: string
          enum: [pending,successful,awaiting off response,document awaiting security clearance,document number not available,document incomplete,unmatched document date,unmatched access code,unmatched document date and access code,invalid document details]

    DocumentNotifications:
      type: object
      properties:
        systemId:
          type: string
          example: "WIPO DAS"
        notificationCategory:
          type: string
          enum: [document availability]
          description: type of notification
        dateTime:
          type: string
          format: date-time
          description: "date and time when the notification was sent"
        totalQuantity:
          type: integer
          format: int8
        documentRetrievalRequestStatusBag:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRetrievalRequestStatus'

    FileId:
      type: object
      properties:
        fileId:
          type: string
          description: fileId of an existing upload request

    FileUploadRequest:
      type: object
      properties:
        fileReference:
          type: string
          description: optional reference used by the service consumer to identify the file
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
          description: this attribute is optional
        fileChecksum:
          type: string
          description: mandatory checksum of the file to upload for validation purpose 
        requestAckId:
          type: string
          description: This attribute should only be specified if the upload file is related to an existing DAS request identified by requestAckId. For example, the OFF uploads the file to WIPO DAS for exchange with another requestor office OSF

    FileUploadResponse:
      type: object
      properties:
        fileReference:
          type: string
          description: reference used by the service consumer to identify the file
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
        fileChecksum:
          type: string
          description: checksum of the file
        fileId:
          type: string
          description: "unique id to be issued by WIPO DAS"
        fileUploadUrl:
          type: string
          description: the pre-signed url created by WIPO DAS to upload file content 
        requestAckId:
          type: string
          description: ackId is provided for upload of a document hosted by the digital library of the OFF, which is requested by an OSF

    FileDetails:
      type: object
      properties:
        fileReference:
          type: string
          description: reference used by the service consumer to identify the file in the WIPO DAS transit area
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
        fileChecksum:
          type: string
          description: checksum of the file
        fileId:
          type: string
          description: "unique id to be issued by WIPO DAS"
        fileDateTime:
          type: string
          format: date-time
          description: "date and time when the file was created. It is empty if the file is not yet available"
        fileSizeQuantity:
          type: integer
          format: int64
          example: "size of the file in bytes"
        fileStatusCategory:
          type: string
          enum: [empty,error,validated,registered]
          description: content of the file has been validated by WIPO DAS with the expected checksum as specified in the upload request. File details can only be read or file content can be written or downloaded by the requestor.
        error:
          type: string
          description: error details if fileStatusCategory is error

    FileDownloadRequest:
      type: object
      properties:
        documentKindCategory:
          type: string
        documentNumber: 
          type: string
        documentDate:
          type: string
        osfAckId:
          type: string
          description: request acknowledgement id issued by WIPO upon reception of the document retrieval request from OSF

    FileDownloadResponse:
      allOf:
        - $ref: '#/components/schemas/FileDownloadRequest'
        - type: object
      type: object
      properties:
        fileDownloadUrl:
          type: string
          description: the pre-signed url created by WIPO DAS to upload file content 
        offAckId:
          type: string
          description: request acknowledgement id issued by the OFF upon reception of the document retrieval request from WIPO
        fileReference:
          type: string
          description: reference used by the service consumer to identify the file in the WIPO DAS transit area
        fileFormatCategory:
          type: string
          enum: [pdf,zip,xml]
        fileChecksum:
          type: string
          description: checksum of the file
        fileId:
          type: string
          description: "unique id to be issued by WIPO DAS"
        fileDateTime:
          type: string
          format: date-time
          description: "date and time when the file was created. It is empty if the file is not yet available"
        fileSizeQuantity:
          type: integer
          format: int64
          example: "size of the file in bytes"
        fileStatusCategory:
          type: string
          enum: [empty,error,validated,registered]
          description: content of the file has been validated by WIPO DAS with the expected checksum as specified in the upload request. File details can only be read or file content can be written or downloaded by the requestor.
        error:
          type: string
          description: error details if fileStatusCategory is error

    NumberFormat:
      type: object
      properties:
        value:
          type: string
        regex:
          type: string
        example:
          type: string

    DocumentNumberFormat:
      type: object
      properties:
        documentKindCategory:
          type: string
          enum: [design,patent,trademark,utility model]
        numberFormats:
          type: array
          items:
            $ref: '#/components/schemas/NumberFormat'

    DocumentNumberFormats:
      type: object
      properties:
        officeCode:
          type: string
        input:
          type: string
        valid:
          type: boolean
        documentNumberFormats:
          type: array
          items:
            $ref: '#/components/schemas/DocumentNumberFormat'

    Token:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT in base64
        scope:
          type: string
          description: das-api/das-access
        tokenType:
          type: string
          description: type of token (e.g. Bearer)
        expiresIn:
          type: integer
          format: int32
          description: expiration time in seconds

#-------------------------------Error Schemas------------------------------
    ServiceError:
      type: object
      example: ServiceError
      properties:
        code:
          type: string
        message:
          type: string
          example: 'consolidated error message if any' 
          description: error description
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'

    ErrorDetails:
      type: object
      example: ErrorDetails
      properties:
        code:
          type: string
        message:
          type: string
          example: 'document number does not exist: XX-TM-2020-299992' 
          description: error description

#---------------------------------------------------------------
#                Examples
#---------------------------------------------------------------
  examples:
    exampleOfToken:
      value:
        accessToken: 'eyJ0eXAiOiJKV1QiLCJraWQiOiJmVWRmbEJSa3c5bm1tejcrL3BmMWM5d2RYdXc9IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkYXMtYXBpLWF1dGgiLCJjdHMiOiJPQVVUSDJfU1RBVEVMRVNTX0dSQU5UIiwiYXVkaXRUcmFja2luZ0lkIjoiMTQyYjMwODEtZDNjNy00MjJjLWI4ZDQtNjU4NjkwNjVmMzQ4LTU0OTkxIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbmRldi53aXBvLmludDo0NDMvYW0vb2F1dGgyIiwidG9rZW5OYW1lIjoiYWNjZXNzX3Rva2VuIiwidG9rZW5fdHlwZSI6IkJlYXJlciIsImF1dGhHcmFudElkIjoibko4bmh5bEM4S3g5RFk4bDJTSGxvcHdDZmJnIiwiYXVkIjoiZGFzLWFwaS1hdXRoIiwibmJmIjoxNjIyNDU0OTUzLCJncmFudF90eXBlIjoiY2xpZW50X2NyZWRlbnRpYWxzIiwic2NvcGUiOlsiZGFzLWFwaS9kYXMtYWNjZXNzIl0sImF1dGhfdGltZSI6MTYyMjQ1NDk1MywicmVhbG0iOiIvIiwiZXhwIjoxNjIyNDU4NTUzLCJpYXQiOjE2MjI0NTQ5NTMsImV4cGlyZXNfaW4iOjM2MDAsImp0aSI6InJvRzhtcWE4WjFaM0YwME1kMjB2VW95aEEwSSJ9.d1EEdioprD2AxQxQcVj0zlN8hvSaIdtub0Lk887m52qEKFt9YiW3uGhpw8bMnhwsUyBbbdFq1flA3pVdKYAdNhQ2dRBIemTH8_NjA4l4giGpLeKJ7WRQA-ldsWrrLkLkVu7gbx7TmMLrTkXgL17kiLdPQ44S1O6LKX52v3KkT0XYEyMYIuzYlnMBs1GQWkoJEALZVIH3TtaAG22o4dxlCcMVxUCo-SyOctjRkfmLvuKEXpDvAG2F93o61Mz1sOtSC2m6nBQA9zd3MxtNd5vd0791QH16Of53IozPj7jRXblYCYq9SJyXzdHN7IEJWrT7C1vvwFVnq8c8QArKsMmgBw'
        scope: das-api/das-access
        tokenType: Bearer
        expiresIn: 3526

    exampleOfDocumentRequestStatistcis:
      value:
        filter:
          officeCode:
          operationCategory:
          startYear:
          endYear:
          documentKindCategory:
        registrations:
          - officeFirstFiling: US
            documentKindCategory: design
            year: 2021
            month: 3
            totalQuantity: 10
          - officeFirstFiling: US
            documentKindCategory: design
            year: 2021
            month: 2
            totalQuantity: 15
          - officeFirstFiling: US
            documentKindCategory: design
            year: 2021
            month: 1
            totalQuantity: 23
        retrievals:
          - officeFirstFiling: US
            officeSecondFiling: IN
            documentKindCategory: design
            year: 2021
            month: 54
            totalQuantity: 10
          - officeFirstFiling: US
            officeSecondFiling: IN
            documentKindCategory: design
            year: 2021
            month: 2
            totalQuantity: 57
          - officeFirstFiling: US
            officeSecondFiling: IN
            documentKindCategory: design
            year: 2021
            month: 1
            totalQuantity: 62

    exampleOfServiceInformation:
      value:
        applicationName: "DAS business service"
        applicationVersion: "3.2.2"
        buildDate: "2020-11-17"
        buildTime: "14:53:10Z"
        codeBranch: "3.2.2"
        codeRevision: "#109" 

    exampleOfDocumentRegistrationRequest:
      value:
        operationCategory: registration
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        revocationDate:
        email:
        fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751

    exampleOfDocumentRegistrationResponse:
      value:
        operationCategory: registration
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        revocationDate:
        email:
        fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751
        requestAckId: ESIB20210523120902201
        operationDateTime: "2020-05-23T12:23:24Z"
        requestStatusCategory: "document registered"
        error:

    exampleOfDocumentRetrievalRequest:
      value:
        operationCategory: retrieval
        documentKindCategory: 'design'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:

    exampleOfDocumentRetrievalResponse:
      value:
        operationCategory: retrieval
        documentKindCategory: 'design'
        documentCodeCategory: 'priority document'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-23"
        dasAccessCode: ABCD
        applicationCategory:
        applicationNumber:
        applicationFilingDate:
        requestAckId: USIB20210523120902201
        operationDateTime: "2020-05-23T12:23:24Z"
        requestStatusCategory: "pending"
        error:

    exampleOfDocumentRetrievalBag:
      value:
        officeCode: us
        documentQuantity: 1
        documentRetrievalResponses:
          - operationCategory: retrieval
            documentKindCategory: 'design'
            documentCodeCategory: 'priority document'
            documentNumber: 'ES U201230131'
            documentDate: "2020-01-23"
            dasAccessCode: ABCD
            applicationCategory:
            applicationNumber:
            applicationFilingDate:
            requestAckId: USIB20210523120902201
            operationDateTime: "2020-05-23T12:23:24Z"
            requestStatusCategory: "pending"
            error:

    exampleOfRecordedDocumentRequests:
      value:
        filter:
          officeCode:
          operationCategory: 
          startDate:
          endDate:
          documentKindCategory: 
          documentNumber:
          requestStatusCategory:
          limit: 50
          offset: 0
          countOnly: false
          sortedBy: 'date:desc'
        totalQuantity: 3
        recordedDocumentRequestBag:
        - operationCategory: registration
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: ES-b214d75e-34ad-46d6-968d-20be4e9ca751
          requestAckId: ESIB202105231120902201
          operationDateTime: "2020-05-23T12:23:24Z"
          requestStatusCategory: successful
          error:
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: 
          requestAckId: USIB20210323120902201
          operationDateTime: "2020-03-23T12:23:24Z"
          requestStatusCategory: successful
          error:
        - operationCategory: retrieval
          documentKindCategory: 'design'
          documentNumber: 'ES U201230131'
          documentDate: "2020-01-21"
          dasAccessCode: ABCD
          applicationCategory:
          applicationNumber:
          applicationFilingDate:
          email:
          fileId: 
          requestAckId: JPIB20210123120902201
          operationDateTime: "2020-01-23T12:23:24Z"
          requestStatusCategory: successful
          error:

    exampleOfRecordedDocumentRequestCount:
      value:
        filter:
          officeCode:
          operationCategory: 
          startDate:
          endDate:
          documentKindCategory: 
          documentNumber:
          requestStatusCategory:
          limit: 50
          offset: 0
          countOnly: true
          sortedBy: 'date:desc'
        total: 56
        recordedDocumentRequestBag:

    exampleOfDocumentRetrievalRequestAckIds:
      value:
        requestAckIdBag:
        - USIB20210523120902201

    exampleOfDocumentNotifications:
      value:
        systemId: WIPO DAS
        notificationCategory: Document availability
        dateTime: '2020-01-23T12:23:24Z'
        totalQuantity: 1
        documentRetrievalRequestStatusBag:
        - requestAckId: USIB20210523120902201
          requestStatusCategory: successful

  # 2 file upload for subsequent registration
    example-FileDetails:
      value:  
        fileReference: 2021060129292992020
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        fileId: JP-bf5f35ff-2a94-4082-8c1c-02e321178232
        fileDateTime: "2021-04-23T12:23:24Z"
        fileSizeQuantity: 419430400
        fileStatusCategory: validated
        error:

    example-FileId:
      value:  
        fileId: JP-bf5f35ff-2a94-4082-8c1c-02e321178232

    example-FileUploadRequest:
      value:  
        fileReference: 2021060129292992020
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        requestAckId:

    example-FileUploadResponse:
      value:  
        fileReference: 2021060129292992020
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        fileId: JP-bf5f35ff-2a94-4082-8c1c-02e321178232
        fileUploadUrl: https://s3.amazonaws.com/<your-bucket-id>/...
        requestAckId:

    example-FileDownloadRequest:
      value:  
        documentKindCategory: 'design'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-21"
        osfAckId: "KRIB20120121001111"

    example-FileDownloadResponse:
      value:  
        documentKindCategory: 'design'
        documentNumber: 'ES U201230131'
        documentDate: "2020-01-21"
        fileReference: "US 12/282,110 2012-01-22"
        fileFormatCategory: zip
        fileChecksum: EEC0DC195A8128F09460965A6111F6759236F90199F8F9D0CA55CCFE620D71A9
        fileId: US-bf5f35ff-2a94-4082-8c1c-02e321178232
        fileDownloadUrl: https://s3.amazonaws.com/<your-bucket-id>/...
        offAckId: "IBUS20130121001234"
        osfAckId: "KRIB20120121001111"
        fileDateTime: "2013-01-12T13:21:00Z"
        fileSizeQuantity: 328238821
        fileStatusCategory: validated
        error:

    exampleOfDocumentNumberFormats:
      value:
        officeCode: CL
        input:
        valid:
        documentNumberFormats:
        - documentKindCategory: 'design'
          numberFormats:
          - number: NNNN-YYYY
            regex: "^[0-9]{1,4}'-'(19|20)[0-9]{2}$"
            example: 1234-2018
        - documentKindCategory: 'patent'
          numberFormats:
          - number: NNNN-YYYY
            regex: "^[0-9]{1,4}'-'(19|20)[0-9]{2}$"
            example: 1234-2018
          - number: "PCT/CLYYYY/NNNNNN"
            regex: ^PCT\/CL(19|20)[0-9]{2}\/[0-9]{6}$"
            example: PCT/CL2018/123456

#----------------------Error Examples-----------------------        
    exampleOfErrorDocumentDetails:
      value:
        error:
          code: "INVALID_INPUT_PARAMETERS"
          message: 
          details:
          - code: '1001'
            message: 'Invalid input value: data.documentDate=2021202111'
          - code: '1002'
            message: 'Invalid input value: data.documentKindCategory=mark'

    exampleOfErrorFileIncomplet:
      value:
        error:
          code: "FILE_CONTENT_INCOMPLET"
          message: 'File content incomplete'
          details:

    exampleOfErrorEmailFormat:
      value:
        error:
          code: "INVALID_EMAIL"
          message: 'Invalid email format'
          details:

    exampleOfErrorDocumentAlreadyRegistered:
      value:
        error:
          code: "DOCUMENT_ALREADY_REGISTERED"
          message: 'Document already registered'
          details:

    exampleOfErrorDocumentUpdate:
      value:
        error:
          code: "DOCUMENT_NOT_AVAILABLE"
          message: 'Document not yet registered'
          details:

    exampleOfErrorDASAccessCode:
      value:
        error:
          code: "CANNOT_CHANGE_DAS_ACCESS_CODE"
          message: 'DAS access code cannot be changed'
          details:

    exampleOfErrorFilter:
      value:
        error:
          code: "INVALID_FILER"
          message: "Invalid filter values - sortedBy='date'&countOnly="
          details:

    exampleOfErrorNotificationDetails:
      value:
        error:
          code: "INVALID_NOTIFICATION_DETAILS"
          message: 'Invalid notification details'
          details:

    exampleOfErrorFileId:
      value:
        error:
          code: "INVALID_FILEID"
          message: 'Invalid file Id'
          details:

    exampleOfErrorRetrievalDetails:
      value:
        error:
          code: "INVALID_DOCUMENT_DETAILS"
          message: 'Invalid retrieval details'
          details:

    exampleOfErrorFileDetails:
      value:
        error:
          code: "INVALID_FILE_CHECKSUM"
          message: 'Invalid file format or checksum'
          details:

    exampleOfErrorRequestAckId:
      value:
        error:
          code: "INVALID_REQUEST_ACKID"
          message: 'Invalid request ack id'
          details:

    exampleOfErrorUnauthorizedOperation:
      value:
        error:
          code: "UNAUTHORIZED_OPERATION"
          message: 'unauthorized operation'
          details:

    exampleOfInvalidOfficeCode:
      value:
        error:
          code: "INVALID_INPUT_PARAMETERS"
          message: 'Invalid office code officeCode=2'
          details:

    exampleOfError401:
      value:
        error:
          code: "INVALID_CREDENTIALS"
          message: 'Authentication details are missing or invalid'
          details:

    exampleOfError500:
      value:
        error:
          code: "INTERNAL_ERROR"
          message: 'Internal system error'
          details:
          - code: '10001'
            message: 'Entity already exists'
            
  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # The client must send this token in the Authorization header (i.e. Authorization: Bearer <token>)
    OAuth2:
      type: oauth2
      flows: 
        clientCredentials: 
          tokenUrl: https://login.wipo.int/am/v1/oauth2/access_token
          scopes: {} # Getty Images does not use scopes
API Security

For advanced API Security, the FAPI (Financial grade API) – Part 2 standard adds an extra-layer on top of OAuth2.0 and OIDC.
private_key_jwt, if the client sends its credentials as a JWT.
tls_client_auth, if the client uses a CA-signed certificate for mutual TLS authentication.
self_signed_tls_client_auth, if the client uses a self-signed certificate for mutual TLS authentication.
Access control implementation

To allow safe, secure and trustable authentication, DAS API will have to implement one of the authentication permitted by FAPI part 2. In order not to the implementation of the backend infrastructure too complex, the proposed implementation will only support the private_key_jwt authentication method. The private_key_jwt authentication is based on the asymmetric key signature of the login information, those details – login info + signature - are sent to the authorization server which returns an access token if valid. The access token can then be used to call the DAS API.
Mutual TLS authentication
The other tls_client_auth and self_signed_tls_client_auth authentication methods defined in the FAPI part 2 standard leverages mutual TLS which necessitates tailored backend servers infrastructure. They are not proposed for DAS API authentication due the non-negligible additional costs and complexity that they will generate .
The following controls must be enforced to guaranty the same level of security than the TDA VPN connection
Network access-control
Decrease the threat surface and avoid data exfiltration:
Restrict communication between WIPO and IP Offices with white listed IP addresses
Perform egress/ingress filtering on the approved protocols to avoid data exfiltration.
Achieve non-disclosure countermeasure and information protection in transit by enabling TLS1.2 encryption.
API mandatory controls

Protect access to API
API DDOS protection
API –Threat protection
Possible setups

DAS protocol necessitates bi-directional communication between offices and WIPO, in practical terms it means that offices must also support private_key_jwt authentication. To ease integration and give freedom to office to choose, we propose two possible setups:
WIPO authorization server setup
Office will use the WIPO authorization server infrastructure for authentication:
Inbound traffic: whenever a call is received from the WIPO central DAS service the office will have to contact and verify the token against the WIPO authorization server.
Outbound traffic: office will authenticate using its client id registered in WIPO authorization server and will use the returned access_token to call the WIPO DAS API.

eyJleHRTcnZJbnRlZ1R5cGUiOiIiLCJnQ2xpZW50SWQiOiIiLCJjcmVhdG9yTmFtZSI6IkRhbmllbCBDSEVORyIsIm91dHB1dFR5cGUiOiJibG9jayIsImxhc3RNb2RpZmllck5hbWUiOiJEYW5pZWwgQ0hFTkciLCJsYW5ndWFnZSI6ImVuIiwiZGlhZ3JhbURpc3BsYXlOYW1lIjoiIiwic0ZpbGVJZCI6IiIsImF0dElkIjoiMTAyNTYwNjAyNSIsImRpYWdyYW1OYW1lIjoiV0lQTyBhdXRob3JpemF0aW9uIHNlcnZlciIsImFzcGVjdCI6IiIsImxpbmtzIjoiYXV0byIsImNlb05hbWUiOiJOZXcgREFTIGV4Y2hhbmdlIEFQSSIsInRic3R5bGUiOiJ0b3AiLCJjYW5Db21tZW50IjpmYWxzZSwiZGlhZ3JhbVVybCI6IiIsImNzdkZpbGVVcmwiOiIiLCJib3JkZXIiOnRydWUsIm1heFNjYWxlIjoiMSIsIm93bmluZ1BhZ2VJZCI6MTAyNTYwNTk5MywiZWRpdGFibGUiOmZhbHNlLCJjZW9JZCI6MTM3MTQ3MTkyOSwicGFnZUlkIjoiIiwibGJveCI6dHJ1ZSwic2VydmVyQ29uZmlnIjp7ImVtYWlscHJldmlldyI6IjEifSwib2RyaXZlSWQiOiIiLCJyZXZpc2lvbiI6MSwibWFjcm9JZCI6ImFhZGRhZjBjLTE2MTUtNGJiZS04NGE1LTY0YzZjYzczNTFhMiIsInByZXZpZXdOYW1lIjoiV0lQTyBhdXRob3JpemF0aW9uIHNlcnZlci5wbmciLCJsaWNlbnNlU3RhdHVzIjoiT0siLCJzZXJ2aWNlIjoiIiwiaXNUZW1wbGF0ZSI6IiIsIndpZHRoIjoiNjAwIiwic2ltcGxlVmlld2VyIjpmYWxzZSwibGFzdE1vZGlmaWVkIjoxNjI0NjU3MDIzOTY3LCJleGNlZWRQYWdlV2lkdGgiOmZhbHNlLCJvQ2xpZW50SWQiOiIifQ==
Mutual authorization server setup
Office wants to take care of the authentication by itself consequently provides the private_key_jwt authentication.
Inbound traffic: The WIPO central DAS service will authenticate against a client id registered in the office authorization server and will use the returned access_token to call the office DAS API
Outbound traffic: office will authenticate using its client id registered in WIPO authorization server and will use the returned access_token to call the WIPO DAS API.

eyJleHRTcnZJbnRlZ1R5cGUiOiIiLCJnQ2xpZW50SWQiOiIiLCJjcmVhdG9yTmFtZSI6IkRhbmllbCBDSEVORyIsIm91dHB1dFR5cGUiOiJibG9jayIsImxhc3RNb2RpZmllck5hbWUiOiJEYW5pZWwgQ0hFTkciLCJsYW5ndWFnZSI6ImVuIiwiZGlhZ3JhbURpc3BsYXlOYW1lIjoiIiwic0ZpbGVJZCI6IiIsImF0dElkIjoiMTAyNTYwNjAyNyIsImRpYWdyYW1OYW1lIjoiTXV0dWFsIGF1dGhvcml6YXRpb24gc2VydmVycyIsImFzcGVjdCI6IiIsImxpbmtzIjoiYXV0byIsImNlb05hbWUiOiJOZXcgREFTIGV4Y2hhbmdlIEFQSSIsInRic3R5bGUiOiJ0b3AiLCJjYW5Db21tZW50IjpmYWxzZSwiZGlhZ3JhbVVybCI6IiIsImNzdkZpbGVVcmwiOiIiLCJib3JkZXIiOnRydWUsIm1heFNjYWxlIjoiMSIsIm93bmluZ1BhZ2VJZCI6MTAyNTYwNTk5MywiZWRpdGFibGUiOmZhbHNlLCJjZW9JZCI6MTM3MTQ3MTkyOSwicGFnZUlkIjoiIiwibGJveCI6dHJ1ZSwic2VydmVyQ29uZmlnIjp7ImVtYWlscHJldmlldyI6IjEifSwib2RyaXZlSWQiOiIiLCJyZXZpc2lvbiI6MSwibWFjcm9JZCI6IjVjNmFmNTQ2LTNjOWYtNGE5Yi04NmUxLWIwOTRkMTE2YmM0MyIsInByZXZpZXdOYW1lIjoiTXV0dWFsIGF1dGhvcml6YXRpb24gc2VydmVycy5wbmciLCJsaWNlbnNlU3RhdHVzIjoiT0siLCJzZXJ2aWNlIjoiIiwiaXNUZW1wbGF0ZSI6IiIsIndpZHRoIjoiNjAwIiwic2ltcGxlVmlld2VyIjpmYWxzZSwibGFzdE1vZGlmaWVkIjoxNjI0NjU3MDgyMzA2LCJleGNlZWRQYWdlV2lkdGgiOmZhbHNlLCJvQ2xpZW50SWQiOiIifQ==
Space shortcuts

Page tree

Background

API Security

Access control implementation

API mandatory controls

Possible setups

WIPO authorization server setup

Mutual authorization server setup

Space shortcuts

Page tree

New DAS exchange API

Background

API Security

Access control implementation

API mandatory controls

Possible setups

WIPO authorization server setup

Mutual authorization server setup
