openapi: 3.0.3
info:
  title: Tratta Bulk Operations Tickets API
  description: The Tratta REST API enables programmatic integration with Tratta's debt collection and payment experience platform. Manage debt accounts, payment plans, transactions, customers, charges, and webhooks for collections workflows. Supports both sandbox and production environments.
  version: v1.0.0
  contact:
    name: Tratta Support
    url: https://docs.tratta.io/
  x-logo:
    url: https://www.tratta.io/logo.png
servers:
- url: https://{org-uuid}.production.tratta.io/api/v1
  description: Tratta Production Server
  variables:
    org-uuid:
      description: Your organization UUID provided by Tratta
      default: your-org-uuid
- url: https://{org-uuid}.sandbox.tratta.io/api/v1
  description: Tratta Sandbox Server
  variables:
    org-uuid:
      description: Your organization UUID provided by Tratta
      default: your-org-uuid
security:
- BearerAuth: []
tags:
- name: Tickets
  description: Support ticket management
paths:
  /tickets:
    get:
      operationId: listTickets
      summary: List Tickets
      description: Returns a paginated list of support tickets.
      tags:
      - Tickets
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: Successful response with ticket list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketListResponse'
    post:
      operationId: createTicket
      summary: Create Ticket
      description: Creates a new support ticket.
      tags:
      - Tickets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketRequest'
      responses:
        '201':
          description: Ticket created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketResponse'
components:
  schemas:
    TicketListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Ticket'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    TicketRequest:
      type: object
      required:
      - subject
      - description
      properties:
        subject:
          type: string
        description:
          type: string
        customer_id:
          type: string
        debt_account_id:
          type: string
    TicketResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Ticket'
    Ticket:
      type: object
      properties:
        id:
          type: string
        subject:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - open
          - in_progress
          - resolved
          - closed
        created_at:
          type: string
          format: date-time
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        current_page:
          type: integer
        per_page:
          type: integer
        total_pages:
          type: integer
    PaginationLinks:
      type: object
      properties:
        first:
          type: string
        prev:
          type: string
          nullable: true
        next:
          type: string
          nullable: true
        last:
          type: string
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
      description: Page number for pagination
    LimitParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
      description: Number of records per page (1-500)
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token provided by Tratta after organization setup