diff --git a/web/site/public/strr/platform.yaml b/web/site/public/strr/platform.yaml index 35578f69..cb4cd5e2 100644 --- a/web/site/public/strr/platform.yaml +++ b/web/site/public/strr/platform.yaml @@ -293,141 +293,198 @@ paths: parameters: [] '/permits/:batchValidate': post: - summary: BatchValidate - responses: - '202': - description: Accepted - '400': - description: Bad Request - '401': - description: Unauthorized + summary: Batch Validate Permits and Addresses operationId: batch-validate-permit x-stoplight: id: pxnr153m69yor - description: Processes a batch submission of permits and/or addresses. + description: | + Asynchronously validates a batch submission of Short-Term Rental (STR) permits and/or checks address exemptions under the *Short-Term Rental Accommodations Act* (STRAA). + + ### Integration Workflow: + 1. **Submit Batch (`POST /permits/:batchValidate`)**: + - Submit up to `50,000` permit or address records in the `data` array. + - Provide `control.count` matching the exact number of items in `data`. + - Provide a secure `control.callBackUrl` (recommended to include a secret token query parameter). + - The API returns `202 Accepted` immediately upon successfully queuing the request. + 2. **Receive Completion Webhook**: + - Once processing finishes, STRR dispatches an HTTP `POST` request to your `callBackUrl` with a temporary presigned Google Cloud Storage URL (`fileUrl`). + - Your endpoint must respond with `200 OK` within 10 seconds. + 3. **Download Result File**: + - Perform an HTTP `GET` on `fileUrl` (valid for 7 days) to download the batch validation result JSON file. + + ### Validation Modes per Record in `data`: + - **Permit Verification Mode (with `identifier`, e.g. `H1234567`)**: Validates the permit status (`ACTIVE`, `EXPIRED`, `SUSPENDED`, `CANCELLED`) and matches the submitted unit number, street number, and postal code against official registry records. + - **Address Exemption Mode (without `identifier`, address only)**: Checks provincial data to determine if the address is exempt from registration (`isStraaExempt: true | false`). + parameters: + - $ref: '#/components/parameters/Account-Id' requestBody: + description: Batch submission payload containing control directives and records to validate. + required: true content: application/json: schema: - type: object - x-examples: - Example 1: - control: - count: 100 - callBackUrl: 'http://example.com/jurisdiction/hostsBatch?token=e1231nk123bni12uhi1ub4k2jb3hi2ughri23br' - data: - - identifier: BC1234567 - address: - unitNumber: 101a - streetNumber: '101' - streetName: Test Street - postalCode: H0H0H0 - city: Test city - - address: - unitNumber: 101a - streetNumber: '101' - streetName: Test Street - postalCode: H0H0H0 - city: Test city - required: - - control - - data - properties: - control: - type: object - description: Directives for the submission. - required: - - count - - callBackUrl - properties: - count: - type: integer - description: |- - The total number of records submitted for processing. - Used as a transmission check. - callBackUrl: - type: string - description: An URL to callback and POST the response for long running responses. - data: - type: array - items: - type: object - required: - - address - properties: - identifier: - type: string - description: The registration number of the Permit. - address: - type: object - required: - - streetNumber - - postalCode - properties: - unitNumber: - type: string - description: Unit number must be included if it was included in the Registration. - streetNumber: - type: string - postalCode: - type: string - streetName: - type: string - city: - type: string + $ref: '#/components/schemas/batchValidationRequest' examples: - Example: + Mixed Batch (Permits & Address Exemptions): + summary: Batch containing permit validations and address exemption checks value: control: count: 2 - callBackUrl: 'http://example.com/jurisdiction/hostsBatch?token=e1231nk123bni12uhi1ub4k2jb3hi2ughri23br' + callBackUrl: 'https://platform.example.com/api/v1/strr-callback?token=sec_token_xyz123' data: - - identifier: H12345678 + - identifier: H1234567 address: - unitNumber: 12A - streetNumber: '234' - streetName: Test St - postalCode: H0H0H0 - city: Test City + unitNumber: 101A + streetNumber: '101' + streetName: Main St + city: Victoria + province: BC + postalCode: V8V 1A1 - address: - unitNumber: 12A - streetNumber: '234' - streetName: Test St - postalCode: H0H0H0 - city: Test City + streetNumber: '721' + streetName: Fort St + city: Victoria + province: BC + postalCode: V8W 1G8 + responses: + '202': + description: Batch submission accepted and queued for processing. + content: + application/json: + schema: + type: object + example: {} + '400': + description: Bad Request - Validation or transmission error (e.g. count mismatch, missing control/data). + content: + application/json: + schema: + $ref: '#/components/schemas/apiErrorResponse' + examples: + Count Mismatch: + summary: Count does not match number of records + value: + errors: + - code: INVALID_REQUEST + message: Value of 'count' does not match the number of permits submitted for verification. + Missing Control Attributes: + summary: Missing required control attributes + value: + errors: + - code: INVALID_REQUEST + message: "'control' object does not have required attributes." + '401': + description: Unauthorized - Missing or invalid authentication credentials. + content: + application/json: + schema: + $ref: '#/components/schemas/apiErrorResponse' + '403': + description: Forbidden - Account does not have permission to access batch validation. + content: + application/json: + schema: + $ref: '#/components/schemas/apiErrorResponse' callbacks: - notification: + batchCompletionNotification: '{$request.body#/control/callBackUrl}': post: - summary: Receive single notification about a batch + summary: Receive completion notification with presigned download URL + description: | + Dispatched by STRR upon completion of the batch validation job. Delivers a temporary presigned Google Cloud Storage URL (`fileUrl`) to download the complete batch validation result JSON file. requestBody: + required: true content: + application/x-www-form-urlencoded: + schema: + type: object + required: + - fileUrl + properties: + fileUrl: + type: string + format: uri + description: Temporary presigned URL to download the validation results JSON file. Valid for 7 days. + example: 'https://storage.googleapis.com/strr_bulk_validation_responses_prod/48ad98c4-38ce-426d-bf61-d722fa186f2b?X-Goog-Algorithm=...' application/json: schema: type: object + required: + - fileUrl properties: - control: - type: object - $ref: '#/components/schemas/control' - data: - type: array - x-stoplight: - id: u3550r8tzkckb - items: - $ref: '#/components/schemas/batchRecord' + fileUrl: + type: string + format: uri + description: Temporary presigned URL to download the validation results JSON file. Valid for 7 days. + example: 'https://storage.googleapis.com/strr_bulk_validation_responses_prod/48ad98c4-38ce-426d-bf61-d722fa186f2b?X-Goog-Algorithm=...' responses: '200': - description: Notification successfully processed + description: Notification successfully processed and acknowledged by client endpoint. content: text/plain: examples: ok: value: ok - parameters: - - $ref: '#/components/parameters/Account-Id' parameters: [] components: schemas: + batchValidationRequest: + title: batchValidationRequest + x-stoplight: + id: batch-val-req-001 + description: Request payload for batch validation submission. + type: object + required: + - control + - data + properties: + control: + $ref: '#/components/schemas/control' + data: + type: array + description: Array of permit/address validation items. Maximum 50,000 records per submission. + minItems: 1 + items: + type: object + required: + - address + properties: + identifier: + type: string + description: The Short-Term Rental Permit/Registration Number (e.g. H1234567, S1234567, P1234567). If omitted, address exemption is evaluated. + example: H1234567 + address: + $ref: '#/components/schemas/address' + batchValidationResultFile: + title: batchValidationResultFile + x-stoplight: + id: batch-val-res-file-001 + description: The JSON payload structure downloaded from the presigned fileUrl. + type: object + required: + - control + - data + properties: + control: + $ref: '#/components/schemas/control' + data: + type: array + description: Array of evaluated records with validation statuses, address mismatch errors, or STRAA exemptions. + items: + $ref: '#/components/schemas/batchRecord' + apiErrorResponse: + title: apiErrorResponse + x-stoplight: + id: api-err-resp-001 + description: Standard API error response. + type: object + required: + - errors + properties: + errors: + type: array + items: + $ref: '#/components/schemas/error' address: title: address description: 'Capture address information for an entity. If the country code is Canada or the US, city and postal code are required.' @@ -592,14 +649,14 @@ components: properties: code: type: string - pattern: '^[0-9]*[A-Za-z]?' - example: 101a + example: STREET_NUMBER_MISMATCH + description: Machine-readable error code. x-stoplight: id: wbr16i5f71u91 message: type: string - pattern: '^[0-9]*' - example: '101' + example: Street number does not match with the data in the permit. + description: Human-readable error description. x-stoplight: id: vtsqsw0p96lnp addressRequirements: