openapi: 3.0.3
info:
  title: Tratta Bulk Operations Debt Accounts 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: Debt Accounts
  description: Debt account operations and management
paths:
  /debt_accounts:
    get:
      operationId: listDebtAccounts
      summary: List Debt Accounts
      description: Returns a paginated list of debt accounts.
      tags:
      - Debt Accounts
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/IncludeParam'
      responses:
        '200':
          description: Successful response with debt account list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebtAccountListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDebtAccount
      summary: Create Debt Account
      description: Creates a new debt account for a customer.
      tags:
      - Debt Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DebtAccountRequest'
      responses:
        '201':
          description: Debt account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebtAccountResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /debt_accounts/{id}:
    get:
      operationId: getDebtAccount
      summary: Get Debt Account
      description: Returns a single debt account by ID.
      tags:
      - Debt Accounts
      parameters:
      - $ref: '#/components/parameters/IdParam'
      - $ref: '#/components/parameters/IncludeParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebtAccountResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DebtAccountRequest:
      type: object
      required:
      - customer_id
      - original_balance
      properties:
        customer_id:
          type: string
        account_number:
          type: string
        original_balance:
          type: number
          format: float
        description:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        errorCode:
          type: string
          description: Optional error code
    PaginationLinks:
      type: object
      properties:
        first:
          type: string
        prev:
          type: string
          nullable: true
        next:
          type: string
          nullable: true
        last:
          type: string
    DebtAccount:
      type: object
      properties:
        id:
          type: string
        customer_id:
          type: string
        account_number:
          type: string
        original_balance:
          type: number
          format: float
        current_balance:
          type: number
          format: float
        status:
          type: string
          enum:
          - active
          - resolved
          - closed
        created_at:
          type: string
          format: date-time
    DebtAccountResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DebtAccount'
    DebtAccountListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DebtAccount'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        current_page:
          type: integer
        per_page:
          type: integer
        total_pages:
          type: integer
  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)
    IncludeParam:
      name: include
      in: query
      required: false
      schema:
        type: string
      description: Comma-delimited list of related resources to include in response (e.g., customers,payment_methods)
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource unique identifier
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Unprocessable entity - missing parameters or invalid data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token provided by Tratta after organization setup