openapi: 3.0.3
info:
  title: Targhe API - Vehicle Data Lookup
  description: |
    API for Italian vehicle license plate data retrieval.

    ## Platform URLs
    - **API Endpoint**: `https://api.tuttotarghe.it` - Use this for all API requests
    - **Web Dashboard**: `https://panel.tuttotarghe.it` - Access your account, view usage, manage billing
    - **Main Website**: `https://www.tuttotarghe.it` - Public website

    ## Features
    - Multi-type job processing (RCA, theft, environmental, details, etc.)
    - Asynchronous and synchronous job submission
    - Real-time status checking
    - Webhook callbacks support
    - Rate limiting on synchronous endpoint (10 requests/minute)

    ## Getting Started
    1. Visit `https://panel.tuttotarghe.it` to access the web dashboard
    2. Generate your API token from the dashboard
    3. Start making requests to `https://api.tuttotarghe.it`

    ## Available Job Types
    - **rca**: RCA insurance lookup
    - **theft**: Theft verification
    - **details**: Vehicle details (Allianz API)
    - **environmental**: Environmental class
    - **newlylicensed**: Newly licensed driver restrictions
    - **inspections**: Vehicle inspections (disabled - requires captcha)
  version: 3.0.0
  contact:
    name: API Support
    email: support@tuttotarghe.it
    url: https://www.tuttotarghe.it
  license:
    name: Proprietary

servers:
  - url: https://api.tuttotarghe.it
    description: Production API server (recommended for API requests)
  - url: https://panel.tuttotarghe.it
    description: Production Panel server (web dashboard)
  - url: http://localhost:8000
    description: Development server

tags:
  - name: Jobs
    description: Submit and retrieve vehicle data lookup jobs

components:
  securitySchemes:
    ApiToken:
      type: apiKey
      in: query
      name: api_token
      description: API token for authentication (get from https://panel.tuttotarghe.it/dashboard)
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication (use your API token from the dashboard)

  schemas:
    Job:
      type: object
      properties:
        job_id:
          type: string
          example: "abc123def456"
        completed:
          type: boolean
          example: false
        pending:
          type: integer
          example: 2

    JobResult:
      type: object
      properties:
        targa:
          type: string
          example: "AB123CD"
        op:
          type: string
          example: "rca"
        type:
          type: array
          items:
            type: string
          example: ["rca", "theft"]
        data:
          type: object
          description: "Aggregated results for all requested types"
        completed:
          type: boolean
          example: true

    Error:
      type: object
      properties:
        error:
          type: string
          example: "Insufficient credits"
        message:
          type: string
          example: "You don't have enough credits to complete this request"
        details:
          type: object

paths:
  # Job Endpoints
  /job/submit:
    post:
      tags: [Jobs]
      summary: Submit asynchronous job
      description: |
        Submit a job for processing. The job will be queued and processed by background workers.

        **Job Types:**
        - `rca`: RCA insurance lookup
        - `theft`: Theft verification
        - `details`: Vehicle details (Allianz API)
        - `environmental`: Environmental class
        - `newlylicensed`: Newly licensed driver restrictions
        - `inspections`: Vehicle inspections (disabled)

        **Pricing:** Each type costs 1 credit (additive). Example: `["rca", "theft"]` = 2 credits
      security:
        - ApiToken: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - op
                - targhe
              properties:
                op:
                  type: string
                  enum: [rca]
                  example: "rca"
                targhe:
                  type: array
                  items:
                    type: string
                  example: ["AB123CD", "EF456GH"]
                type:
                  type: array
                  items:
                    type: string
                    enum: [rca, theft, details, environmental, newlylicensed, inspections]
                  example: ["rca", "theft"]
      responses:
        '200':
          description: Job submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                    example: "abc123def456"
          headers:
            X-RapidAPI-Billing:
              description: Billing count for RapidAPI
              schema:
                type: string
                example: "Targa=4"
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /job/jobsync:
    post:
      tags: [Jobs]
      summary: Submit synchronous job
      description: |
        Submit a job and wait for results (max 60 seconds). Supports priority processing and callbacks.

        **Rate Limit:** 10 requests/minute
      security:
        - ApiToken: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - op
                - targhe
              properties:
                op:
                  type: string
                  enum: [rca]
                targhe:
                  type: array
                  items:
                    type: string
                  example: ["AB123CD"]
                type:
                  type: array
                  items:
                    type: string
                  example: ["rca", "environmental"]
                priority:
                  type: boolean
                  example: false
                  description: "Process with higher priority"
                callback_url:
                  type: string
                  format: uri
                  example: "https://your-site.com/webhook"
                callback_method:
                  type: string
                  enum: [GET, POST]
                  default: POST
      responses:
        '200':
          description: Job completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/JobResult'
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
                example: 10
            X-RateLimit-Remaining:
              schema:
                type: integer
                example: 9
            X-RateLimit-Reset:
              schema:
                type: integer
                example: 1640000000
        '429':
          description: Rate limit exceeded
        '408':
          description: Request timeout

  /job/status:
    get:
      tags: [Jobs]
      summary: Check job status
      security:
        - ApiToken: []
        - BearerAuth: []
      parameters:
        - name: job
          in: query
          required: true
          schema:
            type: string
          example: "abc123def456"
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'

  /job/retrieve:
    get:
      tags: [Jobs]
      summary: Retrieve job results
      security:
        - ApiToken: []
        - BearerAuth: []
      parameters:
        - name: job
          in: query
          required: true
          schema:
            type: string
          example: "abc123def456"
      responses:
        '200':
          description: Job results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobResult'

