openapi: 3.0.0
info:
  title: Cleavr Connect API
  version: 2026-01-02
  description: |
    Professional debt recovery API for platforms.

    Base URLs:
    - Production: `https://api.cleavr.fr`
    - Test: `https://api-test.cleavr.fr`
  contact:
    email: platform@cleavr.fr
  x-logo:
    url: https://cleavr.fr/logo.png

servers:
  - url: https://api.cleavr.fr
    description: Production
  - url: https://api-test.cleavr.fr
    description: Test

security:
  - bearerAuth: []

tags:
  - name: Authentication
    description: OAuth 2.0 authentication
  - name: Users
    description: User account management
  - name: Receivables
    description: Receivable submission and management
  - name: Webhooks
    description: Webhook configuration
  - name: Reports
    description: Recovery statistics and reports

paths:
  /oauth/authorize:
    get:
      tags: [Authentication]
      summary: Initiate OAuth flow
      security: []
      parameters:
        - name: client_id
          in: query
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum: [code]
        - name: scope
          in: query
          required: true
          schema:
            type: string
        - name: state
          in: query
          required: true
          schema:
            type: string
      responses:
        302:
          description: Redirect to consent screen

  /oauth/token:
    post:
      tags: [Authentication]
      summary: Exchange code for token
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: [authorization_code, refresh_token]
                code:
                  type: string
                refresh_token:
                  type: string
                client_id:
                  type: string
                client_secret:
                  type: string
                redirect_uri:
                  type: string
      responses:
        200:
          description: Access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'

  /v1/users:
    post:
      tags: [Users]
      summary: Create user account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        201:
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /v1/users/{id}:
    get:
      tags: [Users]
      summary: Get user details
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /v1/users/{id}/onboarding-status:
    get:
      tags: [Users]
      summary: Check onboarding status
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Onboarding status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingStatus'

  /v1/users/{id}/requirements:
    get:
      tags: [Users]
      summary: Get missing requirements
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Requirements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requirements'

  /v1/receivables:
    post:
      tags: [Receivables]
      summary: Submit receivable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReceivableRequest'
      responses:
        201:
          description: Receivable created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receivable'
        400:
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

    get:
      tags: [Receivables]
      summary: List receivables
      parameters:
        - name: user_id
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/ReceivableStatus'
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: starting_after
          in: query
          schema:
            type: string
      responses:
        200:
          description: Receivables list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Receivable'
                  has_more:
                    type: boolean

  /v1/receivables/ocr:
    post:
      tags: [Receivables]
      summary: Extract data from PDF
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                user_id:
                  type: string
      responses:
        200:
          description: Extraction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionResult'

  /v1/receivables/{id}:
    get:
      tags: [Receivables]
      summary: Get receivable details
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Receivable details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receivable'

    patch:
      tags: [Receivables]
      summary: Update receivable
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReceivableRequest'
      responses:
        200:
          description: Updated receivable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receivable'

  /v1/receivables/{id}/cancel:
    post:
      tags: [Receivables]
      summary: Cancel recovery
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  enum: [paid_directly, disputed_valid, business_decision, incorrect_submission]
                notes:
                  type: string
      responses:
        200:
          description: Cancelled

  /v1/receivables/{id}/contacts:
    post:
      tags: [Receivables]
      summary: Add contact
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        201:
          description: Contact added

  /v1/receivables/{id}/evidence:
    post:
      tags: [Receivables]
      summary: Submit dispute evidence
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvidenceSubmission'
      responses:
        200:
          description: Evidence submitted

  /v1/receivables/{id}/partial-payment:
    post:
      tags: [Receivables]
      summary: Handle partial payment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum: [continue_recovery, mark_complete]
                notes:
                  type: string
      responses:
        200:
          description: Decision recorded

  /v1/webhooks:
    post:
      tags: [Webhooks]
      summary: Register webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        201:
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'

    get:
      tags: [Webhooks]
      summary: List webhooks
      responses:
        200:
          description: Webhooks list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'

  /v1/webhooks/{id}:
    delete:
      tags: [Webhooks]
      summary: Delete webhook
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        204:
          description: Deleted

  /v1/webhooks/{id}/rotate-secret:
    post:
      tags: [Webhooks]
      summary: Rotate webhook secret
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: New secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  secret:
                    type: string

  /v1/reports/stats:
    get:
      tags: [Reports]
      summary: Get recovery statistics
      parameters:
        - name: period
          in: query
          schema:
            type: string
            enum: [last_month, last_quarter, last_year, all_time]
      responses:
        200:
          description: Statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecoveryStats'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        refresh_token:
          type: string
        scope:
          type: string

    CreateUserRequest:
      type: object
      required: [email]
      properties:
        email:
          type: string
          format: email
        company:
          $ref: '#/components/schemas/Company'
        contact:
          $ref: '#/components/schemas/UserContact'
        platform:
          type: object
          properties:
            callback_url:
              type: string
            metadata:
              type: object

    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        status:
          type: string
          enum: [pending_onboarding, onboarding, active, suspended]
        onboarding_url:
          type: string
        capabilities:
          type: object
          properties:
            send_receivables:
              type: boolean
            receive_payments:
              type: boolean
        created_at:
          type: string
          format: date-time

    Company:
      type: object
      properties:
        name:
          type: string
        siret:
          type: string
        vat_number:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        website:
          type: string
        phone:
          type: string

    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        postal_code:
          type: string
        country:
          type: string

    UserContact:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        phone:
          type: string
        job_title:
          type: string

    OnboardingStatus:
      type: object
      properties:
        user_id:
          type: string
        status:
          type: string
        kyb_status:
          type: string
        stripe_account_status:
          type: string
        requirements:
          type: array
          items:
            type: string

    Requirements:
      type: object
      properties:
        currently_due:
          type: array
          items:
            type: string
        eventually_due:
          type: array
          items:
            type: string
        past_due:
          type: array
          items:
            type: string

    CreateReceivableRequest:
      type: object
      required: [user_id, invoice, debtor]
      properties:
        user_id:
          type: string
        invoice:
          $ref: '#/components/schemas/Invoice'
        debtor:
          $ref: '#/components/schemas/Debtor'
        metadata:
          type: object
        force_proceed:
          type: boolean

    Invoice:
      type: object
      required: [numbers, issue_date, due_date, amount, service_description]
      properties:
        numbers:
          type: array
          items:
            type: string
        issue_date:
          type: string
          format: date
        due_date:
          type: string
          format: date
        service_description:
          type: string
        amount:
          type: number
        amount_before_tax:
          type: number
        tax_amount:
          type: number
        currency:
          type: string
          default: EUR

    Debtor:
      type: object
      required: [company_name, contacts]
      properties:
        company_name:
          type: string
        company_type:
          type: string
          enum: [company, individual]
        siret:
          type: string
        vat_number:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'

    Contact:
      type: object
      required: [email]
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        job_title:
          type: string
        level:
          type: integer
          minimum: 0
          maximum: 10

    Receivable:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
        status:
          $ref: '#/components/schemas/ReceivableStatus'
        amount:
          type: number
        currency:
          type: string
        recovery_progress:
          type: object
        created_at:
          type: string
          format: date-time

    ReceivableStatus:
      type: string
      enum:
        - pending
        - in_process
        - payment_received
        - recovered
        - disputed
        - evidence_requested
        - cancelled

    UpdateReceivableRequest:
      type: object
      properties:
        metadata:
          type: object

    ExtractionResult:
      type: object
      properties:
        extraction_id:
          type: string
        confidence:
          type: number
        data:
          type: object
        missing_fields:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: object

    EvidenceSubmission:
      type: object
      properties:
        documents:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              file:
                type: string
              description:
                type: string
        statement:
          type: string

    CreateWebhookRequest:
      type: object
      required: [url, events]
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        description:
          type: string

    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        secret:
          type: string
        events:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time

    RecoveryStats:
      type: object
      properties:
        total_sent:
          type: integer
        total_recovered:
          type: integer
        total_amount_sent:
          type: number
        total_amount_recovered:
          type: number
        avg_days_to_recovery:
          type: number
        with_phone_success_rate:
          type: number
        without_phone_success_rate:
          type: number

    ValidationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            field:
              type: string
            details:
              type: object