openapi: 3.0.3
info:
  title: Grana.ai Credores API
  version: "0.1.0"
  description: |
    OpenAPI specification for the **Grana.ai Credores** service.
    This initial version covers four endpoints:
      * Novo contrato de antecipação de recebíveis
      * Novo contrato de crédito fumaça
      * Nova consulta de agenda de recebíveis (assíncrona)
      * Busca resultado da consulta de agenda por ID
servers:
  - url: https://api.grana.ai/credores/v1
paths:
  /contracts/anticipation:
    post:
      summary: Novo contrato de antecipação de recebíveis
      operationId: createAnticipationContract
      tags: [Contrato]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceivablesAdvanceContractRequest'
      responses:
        "201":
          description: Contrato criado com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractCreationResponse'
  /contracts/forecasted:
    post:
      summary: Novo contrato de crédito fumaça
      operationId: createForecastedContract
      tags: [Contrato]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmokeCreditContractRequest'
      responses:
        "201":
          description: Contrato criado com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractCreationResponse'
  /receivables-schedule-requests:
    post:
      summary: Nova consulta de agenda de recebíveis (assíncrona)
      operationId: createReceivablesScheduleRequest
      tags: [Agenda]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceivablesScheduleRequest'
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivablesScheduleRequestResponse'
  /receivables-schedule-requests/{scheduleRequestId}:
    get:
      summary: Busca resultado da consulta de agenda por ID
      operationId: getReceivablesScheduleResult
      tags: [Agenda]
      parameters:
        - name: scheduleRequestId
          in: path
          required: true
          description: UUID referente à consulta criada.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        "404":
          description: Consulta não encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    # ---------- Generic Schemas ----------
    GenericResponse:
      type: object
      properties:
        message:
          type: string
      example:
        message: Operação concluída.
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      properties:
        message:
          type: string
      required: [message]
    ContractCreationResponse:
      type: object
      properties:
        contractId:
          type: string
          description: ID do contrato criado
      required: [contractId]
      example:
        contractId: "b221e49d-7d8f-4c8c-9248-2d87a5e4d978"
    # ---------- Enum Schemas ----------
    EffectType:
      type: string
      enum: [ownershipAssignment, collateral]
    Periodicity:
      type: string
      enum: [daily, weekly, biweekly, monthly, bimonthly, quarterly, semiannual, annual]
    # ---------- Core Schemas ----------
    ReceivableUnit:
      type: object
      properties:
        acquirerDocument:
          type: string
          description: CNPJ da credenciadora/subcredenciadora
        paymentScheme:
          type: string
          description: |
            Arranjo de pagamento (ex: "VCC", "MCC", "VCD", "MCD";
            respectivamente: Visa Cartão de Crédito, Mastercard Cartão de Crédito,
            Visa Cartão de Débito, Mastercard Cartão de Débito)
        value:
          type: number
          format: double
          description: Valor monetário
      required: [acquirerDocument, paymentScheme, value]
    Commitment:
      type: object
      properties:
        divisionMethod:
          type: string
          enum: [FIXED, PERCENTAGE]
        committedAmount:
          type: number
          format: double
        committedEffectAmount:
          type: number
          format: double
        priority:
          type: integer
      required: [divisionMethod, committedAmount, committedEffectAmount, priority]
    UniversalReceivableUnit:
      type: object
      properties:
        key:
          type: string
        assetHolderDocument:
          type: string
          description: CPF/CNPJ do titular da UR
        paymentScheme:
          type: string
        acquirerDocument:
          type: string
        expectedSettlementDate:
          type: string
          format: date
        totalAmount:
          type: number
          format: double
        committedAmount:
          type: number
          format: double
        availableAmount:
          type: number
          format: double
        commitments:
          type: array
          items:
            $ref: '#/components/schemas/Commitment'
      required:
        [key, assetHolderDocument, paymentScheme, acquirerDocument, expectedSettlementDate,
         totalAmount, committedAmount, availableAmount, commitments]
    Schedule:
      type: object
      properties:
        units:
          type: array
          items:
            $ref: '#/components/schemas/UniversalReceivableUnit'
        error:
          $ref: '#/components/schemas/Error'
      required: [units]
    # ---------- Request Schemas ----------
    ReceivablesAdvanceContractRequest:
      type: object
      properties:
        assetHolderDocument:
          type: string
        reference:
          type: string
        effectType:
          $ref: '#/components/schemas/EffectType'
        receivingBankAccountId:
          type: string
        interestRate:
          type: number
          format: double
        receivableUnits:
          type: array
          items:
            $ref: '#/components/schemas/ReceivableUnit'
        signatureDate:
          type: string
          format: date
      required:
        [assetHolderDocument, reference, effectType, receivingBankAccountId,
         interestRate, receivableUnits, signatureDate]
    SmokeCreditContractRequest:
      type: object
      properties:
        assetHolderDocument:
          type: string
        reference:
          type: string
        effectType:
          $ref: '#/components/schemas/EffectType'
        receivingBankAccountId:
          type: string
        receivableUnits:
          type: array
          items:
            $ref: '#/components/schemas/ReceivableUnit'
        signatureDate:
          type: string
          format: date
        totalValue:
          type: number
          format: double
        installments:
          type: integer
        periodicity:
          $ref: '#/components/schemas/Periodicity'
        startDate:
          type: string
          format: date
      required:
        [assetHolderDocument, reference, effectType, receivingBankAccountId,
         signatureDate, totalValue, installments, periodicity, startDate]
    ReceivablesScheduleRequest:
      type: object
      properties:
        assetHolderDocument:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
      required: [assetHolderDocument, startDate, endDate]
    ReceivablesScheduleRequestResponse:
      type: object
      properties:
        scheduleRequestId:
          type: string
          format: uuid
      required: [scheduleRequestId]
