swagger: '2.0'
info:
  title: APRP Implementation Upload API
  description: Upload + validate (dry-run) and import APRP Implementation Excel templates,
    and download the APRP Implementation upload template.
  contact:
    email: eomoro@krb.go.ke
  license:
    name: BSD License
  version: v1
host: aprpms.devsgraphics.com
schemes:
- http
basePath: /api/planning
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  Basic:
    type: basic
security:
- Basic: []
paths:
  /aprp-implementation-activities/:
    get:
      operationId: aprp-implementation-activities_list
      description: ''
      parameters:
      - name: search
        in: query
        description: A search term.
        required: false
        type: string
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
      - name: authority_code
        in: query
        required: false
        type: string
      - name: financial_year
        in: query
        required: false
        type: string
      - name: quarter_period
        in: query
        required: false
        type: string
      - name: funding_source
        in: query
        required: false
        type: string
      - name: fund_type
        in: query
        required: false
        type: string
      responses:
        '200':
          description: ''
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: uri
                x-nullable: true
              previous:
                type: string
                format: uri
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/AprpImplementationActivity'
      tags:
      - aprp-implementation-activities
    post:
      operationId: aprp-implementation-activities_create
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationActivity'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationActivity'
      tags:
      - aprp-implementation-activities
    parameters: []
  /aprp-implementation-activities/{id}/:
    get:
      operationId: aprp-implementation-activities_read
      description: ''
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationActivity'
      tags:
      - aprp-implementation-activities
    put:
      operationId: aprp-implementation-activities_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationActivity'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationActivity'
      tags:
      - aprp-implementation-activities
    patch:
      operationId: aprp-implementation-activities_partial_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationActivity'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationActivity'
      tags:
      - aprp-implementation-activities
    delete:
      operationId: aprp-implementation-activities_delete
      description: ''
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - aprp-implementation-activities
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this APRP Implementation Activity.
      required: true
      type: string
      format: uuid
  /aprp-implementation-details/:
    get:
      operationId: aprp-implementation-details_list
      description: ''
      parameters:
      - name: search
        in: query
        description: A search term.
        required: false
        type: string
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
      - name: authority_code
        in: query
        required: false
        type: string
      - name: financial_year
        in: query
        required: false
        type: string
      - name: quarter_period
        in: query
        required: false
        type: string
      - name: funding_source
        in: query
        required: false
        type: string
      - name: fund_type
        in: query
        required: false
        type: string
      responses:
        '200':
          description: ''
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: uri
                x-nullable: true
              previous:
                type: string
                format: uri
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/AprpImplementationDetail'
      tags:
      - aprp-implementation-details
    post:
      operationId: aprp-implementation-details_create
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationDetail'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationDetail'
      tags:
      - aprp-implementation-details
    parameters: []
  /aprp-implementation-details/{id}/:
    get:
      operationId: aprp-implementation-details_read
      description: ''
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationDetail'
      tags:
      - aprp-implementation-details
    put:
      operationId: aprp-implementation-details_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationDetail'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationDetail'
      tags:
      - aprp-implementation-details
    patch:
      operationId: aprp-implementation-details_partial_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationDetail'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationDetail'
      tags:
      - aprp-implementation-details
    delete:
      operationId: aprp-implementation-details_delete
      description: ''
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - aprp-implementation-details
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this APRP Implementation Detail.
      required: true
      type: string
      format: uuid
  /aprp-implementation-exports/:
    get:
      operationId: aprp-implementation-exports_list
      summary: Get active APRP Implementation headers
      description: Lists active APRP Implementation headers (IDs + metadata) to help
        users pick an ID to export.
      parameters:
      - name: authority_code
        in: query
        description: Filter by authority code
        required: false
        type: string
        example: KWS
      - name: financial_year
        in: query
        description: Filter by financial year
        required: false
        type: string
        example: 2025-26
      - name: quarter_period
        in: query
        description: Filter by quarter period
        required: false
        type: string
        example: Q2
      responses:
        '200':
          description: List of available headers
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                  example: a1b2c3d4-1111-2222-3333-444455556666
                authority:
                  type: string
                  example: Kenya Wildlife Service
                authority_code:
                  type: string
                  example: KWS
                financial_year:
                  type: string
                  example: 2025-26
                quarter_period:
                  type: string
                  example: Q2
                report_date:
                  type: string
                  example: '2026-01-02'
                is_active:
                  type: boolean
                  example: true
                created_at:
                  type: string
                  example: '2026-01-02T10:00:00Z'
                updated_at:
                  type: string
                  example: '2026-01-03T10:00:00Z'
                details_count:
                  type: integer
                  example: 128
      tags:
      - aprp-implementation-exports
    parameters: []
  /aprp-implementation-exports/download-by-keys/:
    get:
      operationId: aprp-implementation-exports_download_excel_by_keys
      summary: Download APRP Implementation Excel export by filter keys
      description: |-
        Downloads the APRP Implementation Excel by keys:
        - authority_code
        - financial_year
        - quarter_period

        Optional filters:
        - funding_source
        - fund_type
      parameters:
      - name: authority_code
        in: query
        description: Authority code (e.g., KeRRA, KURA, KWS, KeNHA)
        required: true
        type: string
        example: KWS
      - name: financial_year
        in: query
        description: Financial year (e.g., 2025-26 or 2024/2025 depending on your
          data)
        required: true
        type: string
        example: 2025-26
      - name: quarter_period
        in: query
        description: Quarter period (e.g., Q1, Q2, Q3, Q4)
        required: true
        type: string
        example: Q2
      - name: funding_source
        in: query
        description: Optional funding source filter
        required: false
        type: string
        example: 1% RMLF KWS Portion
      - name: fund_type
        in: query
        description: Optional fund type filter
        required: false
        type: string
        example: Current Financial Year Allocation
      responses:
        '200':
          description: XLSX file download
          schema:
            type: file
        '400':
          description: Missing required keys
          schema:
            required:
            - success
            - message
            - statusCode
            - data
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Not found.
              statusCode:
                type: integer
                example: 404
              data:
                type: array
                items:
                  type: object
                example: []
        '404':
          description: No data found
          schema:
            required:
            - success
            - message
            - statusCode
            - data
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Not found.
              statusCode:
                type: integer
                example: 404
              data:
                type: array
                items:
                  type: object
                example: []
      tags:
      - aprp-implementation-exports
    parameters: []
  /aprp-implementation-exports/{id}/download-excel/:
    get:
      operationId: aprp-implementation-exports_download_excel_by_id
      summary: Download APRP Implementation Excel export by Header ID
      description: |-
        Downloads the APRP Implementation Excel for the given header id.

        Optional filters:
        - funding_source
        - fund_type

        Example:
        `/api/planning/aprp-implementation-exports/<id>/download-excel/?funding_source=RMLF&fund_type=Current Financial Year Allocation`
      parameters:
      - name: id
        in: path
        description: APRP Implementation Header UUID
        required: true
        type: string
        example: a1b2c3d4-1111-2222-3333-444455556666
      - name: funding_source
        in: query
        description: Optional funding source filter (exact value used by export engine)
        required: false
        type: string
        example: 1% RMLF KWS Portion
      - name: fund_type
        in: query
        description: Optional fund type filter (exact value used by export engine)
        required: false
        type: string
        example: Current Financial Year Allocation
      responses:
        '200':
          description: XLSX file download
          schema:
            type: file
        '404':
          description: Header not found
          schema:
            required:
            - success
            - message
            - statusCode
            - data
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Not found.
              statusCode:
                type: integer
                example: 404
              data:
                type: array
                items:
                  type: object
                example: []
        '400':
          description: Bad request
          schema:
            required:
            - success
            - message
            - statusCode
            - data
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Not found.
              statusCode:
                type: integer
                example: 404
              data:
                type: array
                items:
                  type: object
                example: []
      tags:
      - aprp-implementation-exports
    parameters:
    - name: id
      in: path
      required: true
      type: string
  /aprp-implementation-headers/:
    get:
      operationId: aprp-implementation-headers_list
      description: ''
      parameters:
      - name: search
        in: query
        description: A search term.
        required: false
        type: string
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
      - name: authority_code
        in: query
        required: false
        type: string
      - name: financial_year
        in: query
        required: false
        type: string
      - name: quarter_period
        in: query
        required: false
        type: string
      - name: funding_source
        in: query
        required: false
        type: string
      - name: fund_type
        in: query
        required: false
        type: string
      responses:
        '200':
          description: ''
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: uri
                x-nullable: true
              previous:
                type: string
                format: uri
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/AprpImplementationHeader'
      tags:
      - aprp-implementation-headers
    post:
      operationId: aprp-implementation-headers_create
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationHeader'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationHeader'
      tags:
      - aprp-implementation-headers
    parameters: []
  /aprp-implementation-headers/{id}/:
    get:
      operationId: aprp-implementation-headers_read
      description: ''
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationHeaderDetail'
      tags:
      - aprp-implementation-headers
    put:
      operationId: aprp-implementation-headers_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationHeader'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationHeader'
      tags:
      - aprp-implementation-headers
    patch:
      operationId: aprp-implementation-headers_partial_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationHeader'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationHeader'
      tags:
      - aprp-implementation-headers
    delete:
      operationId: aprp-implementation-headers_delete
      description: ''
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - aprp-implementation-headers
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this APRP Implementation Header.
      required: true
      type: string
      format: uuid
  /aprp-implementation-summaries-export/available_filters/:
    get:
      operationId: aprp-implementation-summaries-export_available_filters
      summary: Get available filter options for the APRP summaries.
      description: |-
        Returns a list of possible values for each filter field.
        This helps frontend applications build filter dropdowns.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries-export
    parameters: []
  /aprp-implementation-summaries-export/bulk_export/:
    post:
      operationId: aprp-implementation-summaries-export_bulk_export
      summary: Export multiple summary types in a single request.
      description: |-
        Request Body (JSON):
        {
            "summary_types": ["overall", "compliance", "work-category"],
            "filters": {
                "authority_code": "ABC",
                "financial_year": "2024",
                "quarter_period": "Q1"
            },
            "format": "excel"  # or "zip" for multiple files
        }
      parameters: []
      responses:
        '201':
          description: ''
      tags:
      - aprp-implementation-summaries-export
    parameters: []
  /aprp-implementation-summaries-export/export/all/:
    get:
      operationId: aprp-implementation-summaries-export_export_export_all_summaries
      summary: Export ALL APRP implementation summaries to a single Excel file.
      description: |-
        The Excel file will contain 7 sheets:
        1. Report Metadata
        2. 1. Overall Summary
        3. 2. Compliance Summary
        4. 3. Level of Implementation
        5. 4. Ongoing Commitments
        6. 5. Road Condition
        7. 6. Work Category

        Query Parameters:
        - authority_code: Filter by authority code
        - financial_year: Filter by financial year
        - quarter_period: Filter by quarter (Q1, Q2, Q3, Q4)
        - funding_source: Filter by funding source
        - fund_type: Filter by fund type
        - filename: Optional custom filename (without extension)
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries-export
    parameters: []
  /aprp-implementation-summaries-export/export/{summary_type}/:
    get:
      operationId: aprp-implementation-summaries-export_export_specific_summary
      summary: Export a specific APRP summary type to Excel.
      description: |-
        Path Parameter:
        - summary_type: Type of summary to export (overall, compliance, level, ongoing, road-condition, work-category)

        Query Parameters:
        - Same as export_all_summaries
        - format: Optional output format (excel, csv, json). Default: excel
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries-export
    parameters:
    - name: summary_type
      in: path
      required: true
      type: string
  /aprp-implementation-summaries-export/preview/:
    get:
      operationId: aprp-implementation-summaries-export_preview
      summary: Preview summary data without downloading.
      description: |-
        Returns a preview of the data (first 10 rows) for a specific summary type.
        Useful for verifying data before export.

        Query Parameters:
        - summary_type: The type of summary to preview
        - limit: Number of rows to return (default: 10)
        - ... plus all filter parameters
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries-export
    parameters: []
  /aprp-implementation-summaries-export/summary_types/:
    get:
      operationId: aprp-implementation-summaries-export_summary_types
      summary: Get available summary types with descriptions.
      description: |-
        Returns metadata about each summary type including:
        - Name and description
        - Number of sheets in the Excel output
        - Required filters (if any)
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries-export
    parameters: []
  /aprp-implementation-summaries/achievement-of-outputs-per-road-condition-summary/:
    get:
      operationId: aprp-implementation-summaries_achievement_per_road_condition_summary
      summary: Achievement of outputs per road condition
      description: Groups by road_condition_status and returns planned km vs achieved
        km (from progress%).
      parameters:
      - name: financial_year
        in: query
        description: 'Financial year string. Example: 2024-25 or 2024-2025 (use your
          AprpImplementationHeader format).'
        required: true
        type: string
      - name: authority_code
        in: query
        description: Road Authority code (e.g. KENHA, KERRA, KURA). Optional.
        type: string
      - name: quarter
        in: query
        description: 'Quarter period: Q1, Q2, Q3, Q4. Optional. Alias: periods=Q1'
        type: string
      - name: funding_source
        in: query
        description: Optional funding source (limits results).
        type: string
      - name: fund_type
        in: query
        description: Optional fund type (limits results).
        type: string
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries
    parameters: []
  /aprp-implementation-summaries/achievement-of-outputs-per-work-category-summary/:
    get:
      operationId: aprp-implementation-summaries_achievement_per_work_category_summary
      summary: Achievement of outputs per work category
      description: Groups by work_category and returns planned amount/km vs achieved
        km and balances.
      parameters:
      - name: financial_year
        in: query
        description: 'Financial year string. Example: 2024-25 or 2024-2025 (use your
          AprpImplementationHeader format).'
        required: true
        type: string
      - name: authority_code
        in: query
        description: Road Authority code (e.g. KENHA, KERRA, KURA). Optional.
        type: string
      - name: quarter
        in: query
        description: 'Quarter period: Q1, Q2, Q3, Q4. Optional. Alias: periods=Q1'
        type: string
      - name: funding_source
        in: query
        description: Optional funding source (limits results).
        type: string
      - name: fund_type
        in: query
        description: Optional fund type (limits results).
        type: string
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries
    parameters: []
  /aprp-implementation-summaries/compliance-summary/:
    get:
      operationId: aprp-implementation-summaries_compliance_summary
      summary: Compliance summary (Within + Omitted)
      description: Shows what was within workplan, what was omitted from implementation,
        and % procured.
      parameters:
      - name: financial_year
        in: query
        description: 'Financial year string. Example: 2024-25 or 2024-2025 (use your
          AprpImplementationHeader format).'
        required: true
        type: string
      - name: authority_code
        in: query
        description: Road Authority code (e.g. KENHA, KERRA, KURA). Optional.
        type: string
      - name: quarter
        in: query
        description: 'Quarter period: Q1, Q2, Q3, Q4. Optional. Alias: periods=Q1'
        type: string
      - name: funding_source
        in: query
        description: Optional funding source (limits results).
        type: string
      - name: fund_type
        in: query
        description: Optional fund type (limits results).
        type: string
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries
    parameters: []
  /aprp-implementation-summaries/level-of-implementation-summary/:
    get:
      operationId: aprp-implementation-summaries_level_of_implementation_summary
      summary: Level of implementation summary
      description: Budget/contracted/certified/payments/achieved + % metrics.
      parameters:
      - name: financial_year
        in: query
        description: 'Financial year string. Example: 2024-25 or 2024-2025 (use your
          AprpImplementationHeader format).'
        required: true
        type: string
      - name: authority_code
        in: query
        description: Road Authority code (e.g. KENHA, KERRA, KURA). Optional.
        type: string
      - name: quarter
        in: query
        description: 'Quarter period: Q1, Q2, Q3, Q4. Optional. Alias: periods=Q1'
        type: string
      - name: funding_source
        in: query
        description: Optional funding source (limits results).
        type: string
      - name: fund_type
        in: query
        description: Optional fund type (limits results).
        type: string
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries
    parameters: []
  /aprp-implementation-summaries/ongoing-commitments-summary/:
    get:
      operationId: aprp-implementation-summaries_ongoing_commitments_summary
      summary: Ongoing commitments summary
      description: Interprets ongoing commitments as prior-years/carry-over fund types.
      parameters:
      - name: financial_year
        in: query
        description: 'Financial year string. Example: 2024-25 or 2024-2025 (use your
          AprpImplementationHeader format).'
        required: true
        type: string
      - name: authority_code
        in: query
        description: Road Authority code (e.g. KENHA, KERRA, KURA). Optional.
        type: string
      - name: quarter
        in: query
        description: 'Quarter period: Q1, Q2, Q3, Q4. Optional. Alias: periods=Q1'
        type: string
      - name: funding_source
        in: query
        description: Optional funding source (limits results).
        type: string
      - name: fund_type
        in: query
        description: Optional fund type (limits results).
        type: string
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries
    parameters: []
  /aprp-implementation-summaries/overall-implementation-summary/:
    get:
      operationId: aprp-implementation-summaries_overall_implementation_summary
      summary: Overall implementation summary
      description: Overall + Within/Outside totals (uses reconciliation).
      parameters:
      - name: financial_year
        in: query
        description: 'Financial year string. Example: 2024-25 or 2024-2025 (use your
          AprpImplementationHeader format).'
        required: true
        type: string
      - name: authority_code
        in: query
        description: Road Authority code (e.g. KENHA, KERRA, KURA). Optional.
        type: string
      - name: quarter
        in: query
        description: 'Quarter period: Q1, Q2, Q3, Q4. Optional. Alias: periods=Q1'
        type: string
      - name: funding_source
        in: query
        description: Optional funding source (limits results).
        type: string
      - name: fund_type
        in: query
        description: Optional fund type (limits results).
        type: string
      responses:
        '200':
          description: ''
      tags:
      - aprp-implementation-summaries
    parameters: []
  /aprp-implementation-templates/download-template/:
    get:
      operationId: aprp-implementation-templates_download_template
      summary: Download APRP Implementation upload template (KRb branded, conditional
        columns)
      description: |-
        Download the KRb branded APRP Implementation upload template.
        authority_code is REQUIRED here (template only).
      parameters:
      - name: authority_code
        in: query
        description: KERRA | KURA | KWS | KENHA (controls conditional columns + RA
          fields)
        required: true
        type: string
      responses:
        '200':
          description: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
      tags:
      - aprp-implementation-templates
    parameters: []
  /aprp-implementation-uploads/:
    get:
      operationId: aprp-implementation-uploads_list
      description: ''
      parameters:
      - name: search
        in: query
        description: A search term.
        required: false
        type: string
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
      - name: authority_code
        in: query
        required: false
        type: string
      - name: financial_year
        in: query
        required: false
        type: string
      - name: quarter_period
        in: query
        required: false
        type: string
      - name: funding_source
        in: query
        required: false
        type: string
      - name: fund_type
        in: query
        required: false
        type: string
      responses:
        '200':
          description: ''
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: uri
                x-nullable: true
              previous:
                type: string
                format: uri
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/AprpImplementationUpload'
      tags:
      - aprp-implementation-uploads
    post:
      operationId: aprp-implementation-uploads_create
      summary: Upload APRP Implementation Excel
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationUploadCreate'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationUpload'
      tags:
      - aprp-implementation-uploads
    parameters: []
  /aprp-implementation-uploads/{id}/:
    get:
      operationId: aprp-implementation-uploads_read
      description: ''
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationUpload'
      tags:
      - aprp-implementation-uploads
    put:
      operationId: aprp-implementation-uploads_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationUpload'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationUpload'
      tags:
      - aprp-implementation-uploads
    patch:
      operationId: aprp-implementation-uploads_partial_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/AprpImplementationUpload'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationUpload'
      tags:
      - aprp-implementation-uploads
    delete:
      operationId: aprp-implementation-uploads_delete
      description: ''
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - aprp-implementation-uploads
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this APRP Implementation Upload.
      required: true
      type: string
      format: uuid
  /aprp-implementation-uploads/{id}/mark-failed/:
    post:
      operationId: aprp-implementation-uploads_mark_failed
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          type: object
          properties:
            note:
              type: string
            errors:
              type: array
              items:
                type: object
      - name: authority_code
        in: query
        required: false
        type: string
      - name: financial_year
        in: query
        required: false
        type: string
      - name: quarter_period
        in: query
        required: false
        type: string
      - name: funding_source
        in: query
        required: false
        type: string
      - name: fund_type
        in: query
        required: false
        type: string
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationUpload'
      tags:
      - aprp-implementation-uploads
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this APRP Implementation Upload.
      required: true
      type: string
      format: uuid
  /aprp-implementation-uploads/{id}/mark-validated/:
    post:
      operationId: aprp-implementation-uploads_mark_validated
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          type: object
          properties:
            note:
              type: string
      - name: authority_code
        in: query
        required: false
        type: string
      - name: financial_year
        in: query
        required: false
        type: string
      - name: quarter_period
        in: query
        required: false
        type: string
      - name: funding_source
        in: query
        required: false
        type: string
      - name: fund_type
        in: query
        required: false
        type: string
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationUpload'
      tags:
      - aprp-implementation-uploads
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this APRP Implementation Upload.
      required: true
      type: string
      format: uuid
  /aprp-implementation/import/:
    post:
      operationId: aprp-implementation_import_create
      summary: Import APRP Implementation (validate or commit)
      description: Upload the APRP Implementation Excel. Use dry_run=true to validate
        only.
      parameters:
      - name: file
        in: formData
        description: Excel .xlsx file
        required: true
        type: file
      - name: dry_run
        in: formData
        description: true = validate only (no DB writes); false = import/commit
        required: false
        type: boolean
        default: true
      - name: max_errors
        in: formData
        description: Global cap of errors collected/returned
        required: false
        type: integer
        default: 500
        maximum: 10000
        minimum: 10
      - name: row_error_limit
        in: formData
        description: Per-row cap of returned errors
        required: false
        type: integer
        default: 12
        maximum: 100
        minimum: 1
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationImportResponse'
        '422':
          description: ''
          schema:
            $ref: '#/definitions/AprpImplementationImportResponse'
      consumes:
      - multipart/form-data
      - application/x-www-form-urlencoded
      tags:
      - Planning • APRP Implementation Import
    parameters: []
  /aprp-implementation/import/template/:
    get:
      operationId: aprp-implementation_import_template
      summary: Download APRP Implementation template
      description: Downloads the APRP Implementation Excel template.
      parameters: []
      responses:
        '200':
          description: Excel file
      consumes:
      - multipart/form-data
      - application/x-www-form-urlencoded
      tags:
      - Planning • APRP Implementation Import
    parameters: []
definitions:
  AprpImplementationActivity:
    required:
    - detail
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      detail:
        title: Detail
        type: string
        format: uuid
      activity_code:
        title: Activity code
        type: string
        maxLength: 50
        x-nullable: true
      activity_description:
        title: Activity description
        type: string
        x-nullable: true
      amount_ksh:
        title: Amount ksh
        type: string
        format: decimal
        x-nullable: true
      activity_date:
        title: Activity date
        type: string
        format: date
        x-nullable: true
      created_at:
        title: Created at
        type: string
        format: date-time
        readOnly: true
  AprpImplementationDetail:
    required:
    - header
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      header:
        title: Header
        type: string
        format: uuid
      funding_source:
        title: Funding source
        type: string
        x-nullable: true
      fund_type:
        title: Fund type
        type: string
        x-nullable: true
      region_or_county:
        title: Region or county
        type: string
        x-nullable: true
      constituency:
        title: Constituency
        type: string
        x-nullable: true
      city_or_municipality:
        title: City or municipality
        type: string
        x-nullable: true
      national_park_or_game_reserve:
        title: National park or game reserve
        type: string
        x-nullable: true
      road_id:
        title: Road id
        type: string
        x-nullable: true
      section_id:
        title: Section id
        type: string
        x-nullable: true
      section_or_road_name:
        title: Section or road name
        type: string
        x-nullable: true
      work_category:
        title: Work category
        type: string
        x-nullable: true
      budget_amount:
        title: Budget amount
        type: string
        format: decimal
      planned_section_length_km:
        title: Planned section length km
        type: string
        format: decimal
      surface_type:
        title: Surface type
        type: string
        x-nullable: true
      road_condition_status:
        title: Road condition status
        type: string
        x-nullable: true
      date_of_procurement:
        title: Date of procurement
        type: string
        format: date
        x-nullable: true
      name_of_contractor:
        title: Name of contractor
        type: string
        x-nullable: true
      tender_package_contract_number:
        title: Tender package contract number
        type: string
        x-nullable: true
      contract_award_date:
        title: Contract award date
        type: string
        format: date
        x-nullable: true
      commencement_date:
        title: Commencement date
        type: string
        format: date
        x-nullable: true
      contract_period_months:
        title: Contract period months
        type: integer
        maximum: 2147483647
        minimum: -2147483648
        x-nullable: true
      expected_completion_date:
        title: Expected completion date
        type: string
        format: date
        x-nullable: true
      actual_completion_date:
        title: Actual completion date
        type: string
        format: date
        x-nullable: true
      award_contract_sum:
        title: Award contract sum
        type: string
        format: decimal
      savings_overruns:
        title: Savings overruns
        type: string
        format: decimal
      last_certified_amount:
        title: Last certified amount
        type: string
        format: decimal
      last_payment_certificate_date:
        title: Last payment certificate date
        type: string
        format: date
        x-nullable: true
      defects_liability_period_months:
        title: Defects liability period months
        type: integer
        maximum: 2147483647
        minimum: -2147483648
        x-nullable: true
      payments_made_in_current_financial_year:
        title: Payments made in current financial year
        type: string
        format: decimal
      cummulative_payments_made_to_date:
        title: Cummulative payments made to date
        type: string
        format: decimal
      achieve_out_puts:
        title: Achieve out puts
        type: string
        x-nullable: true
      progress_status:
        title: Progress status
        type: string
        format: decimal
      remark:
        title: Remark
        type: string
        x-nullable: true
      created_at:
        title: Created at
        type: string
        format: date-time
        readOnly: true
      updated_at:
        title: Updated at
        type: string
        format: date-time
        readOnly: true
      activities:
        type: array
        items:
          $ref: '#/definitions/AprpImplementationActivity'
        readOnly: true
  AprpImplementationHeader:
    required:
    - authority_code
    - financial_year
    - quarter_period
    - report_date
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      authority:
        title: Authority
        type: string
        maxLength: 255
      authority_code:
        title: Authority code
        type: string
        pattern: ^[A-Za-z0-9_\-\.]+$
        maxLength: 50
        minLength: 1
      financial_year:
        title: Financial year
        type: string
        maxLength: 20
        minLength: 1
      quarter_period:
        title: Quarter period
        type: string
        maxLength: 10
        minLength: 1
      report_date:
        title: Report date
        type: string
        format: date
      revision_status:
        title: Revision status
        type: integer
        enum:
        - 0
        - 1
        readOnly: true
      revision_number:
        title: Revision number
        type: integer
        maximum: 2147483647
        minimum: 0
      is_active:
        title: Is active
        type: boolean
        readOnly: true
      source_upload:
        title: Source upload
        type: string
        format: uuid
        x-nullable: true
      created_by:
        title: Created by
        type: string
        maxLength: 255
      created_at:
        title: Created at
        type: string
        format: date-time
        readOnly: true
        x-nullable: true
      updated_at:
        title: Updated at
        type: string
        format: date-time
        readOnly: true
        x-nullable: true
      details_count:
        title: Details count
        type: integer
        readOnly: true
  AprpImplementationHeaderDetail:
    required:
    - authority_code
    - financial_year
    - quarter_period
    - report_date
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      authority:
        title: Authority
        type: string
        maxLength: 255
      authority_code:
        title: Authority code
        type: string
        pattern: ^[A-Za-z0-9_\-\.]+$
        maxLength: 50
        minLength: 1
      financial_year:
        title: Financial year
        type: string
        maxLength: 20
        minLength: 1
      quarter_period:
        title: Quarter period
        type: string
        maxLength: 10
        minLength: 1
      report_date:
        title: Report date
        type: string
        format: date
      revision_status:
        title: Revision status
        type: integer
        enum:
        - 0
        - 1
        readOnly: true
      revision_number:
        title: Revision number
        type: integer
        maximum: 2147483647
        minimum: 0
      is_active:
        title: Is active
        type: boolean
        readOnly: true
      source_upload:
        title: Source upload
        type: string
        format: uuid
        x-nullable: true
      created_by:
        title: Created by
        type: string
        maxLength: 255
      created_at:
        title: Created at
        type: string
        format: date-time
        readOnly: true
        x-nullable: true
      updated_at:
        title: Updated at
        type: string
        format: date-time
        readOnly: true
        x-nullable: true
      details_count:
        title: Details count
        type: integer
        readOnly: true
      details:
        type: array
        items:
          $ref: '#/definitions/AprpImplementationDetail'
        readOnly: true
  AprpImplementationUpload:
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      file:
        title: File
        type: string
        readOnly: true
        format: uri
      file_url:
        title: File url
        type: string
        readOnly: true
      original_name:
        title: Original name
        type: string
        readOnly: true
        minLength: 1
      content_type:
        title: Content type
        type: string
        readOnly: true
        minLength: 1
      size:
        title: Size
        type: integer
        readOnly: true
      sha256:
        title: Sha256
        type: string
        readOnly: true
        minLength: 1
      status:
        title: Status
        type: string
        enum:
        - draft
        - validated
        - imported
        - failed
        readOnly: true
      uploaded_by:
        title: Uploaded by
        type: string
        maxLength: 255
      uploaded_at:
        title: Uploaded at
        type: string
        format: date-time
        readOnly: true
      header_id_hint:
        title: Header id hint
        type: string
        format: uuid
        readOnly: true
        x-nullable: true
      financial_year_hint:
        title: Financial year hint
        type: string
        maxLength: 50
      quarter_hint:
        title: Quarter hint
        type: string
        maxLength: 20
      notes:
        title: Notes
        type: string
      result_json:
        title: Result json
        type: object
        readOnly: true
        x-nullable: true
      log_json:
        title: Log json
        type: object
        readOnly: true
  AprpImplementationUploadCreate:
    type: object
    properties:
      file:
        title: File
        type: string
        readOnly: true
        format: uri
      uploaded_by:
        title: Uploaded by
        type: string
        default: ''
      financial_year_hint:
        title: Financial year hint
        type: string
        default: ''
      quarter_hint:
        title: Quarter hint
        type: string
        default: ''
      notes:
        title: Notes
        type: string
        default: ''
  AprpImplementationImportResponse:
    required:
    - dry_run
    - upload_id
    - uploaded_file_url
    - created_header_id
    - created_details
    - created_activities
    type: object
    properties:
      dry_run:
        title: Dry run
        type: boolean
      upload_id:
        title: Upload id
        type: string
        format: uuid
        x-nullable: true
      uploaded_file_url:
        title: Uploaded file url
        type: string
        minLength: 1
        x-nullable: true
      errors_csv_url:
        title: Errors csv url
        type: string
        minLength: 1
        x-nullable: true
      created_header_id:
        title: Created header id
        type: string
        format: uuid
        x-nullable: true
      created_details:
        title: Created details
        type: integer
      created_activities:
        title: Created activities
        type: integer
      error_summary:
        title: Error summary
        type: object
        additionalProperties:
          type: string
          x-nullable: true
      errors:
        type: array
        items:
          type: object
          additionalProperties:
            type: string
            x-nullable: true
