openapi: 3.1.0
info:
  title: API do Kobana Dunning
  version: 1.0.0
  description: Collection Flow — Kobana’s collection engine public API. Manage customers, charges, collection rules, agreements, disputes and webhooks programmatically. Authenticate with an API key (Bearer) created in the dashboard under Settings → Security; access is limited by the key’s scopes (`dunning.dashboard.<resource>.<action>`).
  license:
    name: Proprietário — Kobana
    url: https://kobana.com.br
servers:
  - url: https://api.dunning.kobana.com.br
    description: Production
  - url: https://api.dunning.sandbox.kobana.com.br
    description: Sandbox — isolated testing environment, separate from production.
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable message describing the error.
        code:
          type: string
          description: Stable error code (e.g. VALIDATION_ERROR, NOT_FOUND).
          example: VALIDATION_ERROR
        details:
          description: Additional details (e.g. per-field validation errors).
      required:
        - message
        - code
      description: "API error envelope: human-readable message + stable code."
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total records matching the filter.
        page:
          type: integer
          description: Current page.
        limit:
          type: integer
          description: Items per page applied.
        totalPages:
          type: integer
          description: Total pages.
      required:
        - total
        - page
        - limit
        - totalPages
      description: List pagination metadata.
    PersonAddress:
      type: object
      properties:
        street:
          type: string
          description: Street.
        number:
          type: string
          description: Number.
        complement:
          type: string
          description: Complement.
        neighborhood:
          type: string
          description: Neighborhood.
        city:
          type: string
          description: City.
        state:
          type: string
          minLength: 2
          maxLength: 2
          description: State (2 letters).
          example: SP
        zipCode:
          type: string
          description: ZIP code (8 digits).
          example: "01310100"
      required:
        - street
        - number
        - neighborhood
        - city
        - state
        - zipCode
    PersonPhone:
      type: object
      properties:
        kind:
          type: string
          enum:
            - mobile
            - landline
            - commercial
            - whatsapp
          description: Kind (`mobile` | `landline` | `commercial` | `whatsapp`).
        countryCode:
          type: string
          description: Country code.
          example: "55"
        areaCode:
          type: string
          description: Area code.
          example: "11"
        number:
          type: string
          description: Number.
          example: "999998888"
      required:
        - kind
        - countryCode
        - areaCode
        - number
    PersonEmail:
      type: object
      properties:
        label:
          type: string
          enum:
            - personal
            - commercial
            - financial
          description: Label (`personal` | `commercial` | `financial`).
        address:
          type: string
          format: email
          description: Email address.
      required:
        - label
        - address
    Person:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Company (creditor) associated with the customer.
        classificationId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer classification (rule segmentation).
        documentNumber:
          type:
            - string
            - "null"
          description: CPF/CNPJ (digits only).
          example: "12345678901"
        documentType:
          type:
            - string
            - "null"
          enum:
            - cpf
            - cnpj
            - null
          description: Document type (`cpf` | `cnpj`).
        kind:
          type:
            - string
            - "null"
          enum:
            - natural
            - juridical
            - null
          description: Nature (`natural` person or `juridical` entity).
        name:
          type: string
          description: Customer name.
          example: Maria da Silva
        legalName:
          type:
            - string
            - "null"
          description: Legal name.
        nickname:
          type:
            - string
            - "null"
          description: Nickname/trade name.
        birthday:
          type:
            - string
            - "null"
          description: Birth date (ISO 8601).
        addresses:
          type: array
          items:
            $ref: "#/components/schemas/PersonAddress"
          description: Addresses.
        phones:
          type: array
          items:
            $ref: "#/components/schemas/PersonPhone"
          description: Phone numbers.
        emails:
          type: array
          items:
            $ref: "#/components/schemas/PersonEmail"
          description: Email addresses.
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        notes:
          type:
            - string
            - "null"
          description: Internal notes.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        createdViaApi:
          type: boolean
          description: true when the record was created via API.
        flaggedThirdPartyAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the person flagged "not me" in the portal (full suppression).
        metadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - classificationId
        - documentNumber
        - documentType
        - kind
        - name
        - legalName
        - nickname
        - birthday
        - addresses
        - phones
        - emails
        - externalId
        - tags
        - notes
        - customData
        - createdViaApi
        - flaggedThirdPartyAt
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: Customer (natural or legal person) in the collection portfolio.
    PersonCreateRequest:
      type: object
      properties:
        classificationId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer classification (rule segmentation).
        documentNumber:
          type:
            - string
            - "null"
          maxLength: 20
          description: CPF/CNPJ (digits only).
        documentType:
          type:
            - string
            - "null"
          enum:
            - cpf
            - cnpj
            - null
          description: Document type (`cpf` | `cnpj`).
        kind:
          type:
            - string
            - "null"
          enum:
            - natural
            - juridical
            - null
          description: Nature (`natural` person or `juridical` entity).
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Customer name.
        legalName:
          type:
            - string
            - "null"
          description: Legal name.
        nickname:
          type:
            - string
            - "null"
          maxLength: 120
          description: Nickname/trade name.
        birthday:
          type:
            - string
            - "null"
          format: date-time
          description: Birth date (ISO 8601).
        addresses:
          type: array
          items:
            $ref: "#/components/schemas/PersonAddress"
          description: Addresses.
        phones:
          type: array
          items:
            $ref: "#/components/schemas/PersonPhone"
          description: Phone numbers.
        emails:
          type: array
          items:
            $ref: "#/components/schemas/PersonEmail"
          description: Email addresses.
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        notes:
          type:
            - string
            - "null"
          description: Internal notes.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
      required:
        - name
      description: Payload to create a customer.
    PersonUpdateRequest:
      type: object
      properties:
        classificationId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer classification (rule segmentation).
        documentNumber:
          type:
            - string
            - "null"
          maxLength: 20
          description: CPF/CNPJ (digits only).
        documentType:
          type:
            - string
            - "null"
          enum:
            - cpf
            - cnpj
            - null
          description: Document type (`cpf` | `cnpj`).
        kind:
          type:
            - string
            - "null"
          enum:
            - natural
            - juridical
            - null
          description: Nature (`natural` person or `juridical` entity).
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Customer name.
        legalName:
          type:
            - string
            - "null"
          description: Legal name.
        nickname:
          type:
            - string
            - "null"
          maxLength: 120
          description: Nickname/trade name.
        birthday:
          type:
            - string
            - "null"
          format: date-time
          description: Birth date (ISO 8601).
        addresses:
          type: array
          items:
            $ref: "#/components/schemas/PersonAddress"
          description: Addresses.
        phones:
          type: array
          items:
            $ref: "#/components/schemas/PersonPhone"
          description: Phone numbers.
        emails:
          type: array
          items:
            $ref: "#/components/schemas/PersonEmail"
          description: Email addresses.
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        notes:
          type:
            - string
            - "null"
          description: Internal notes.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
      description: Fields to update (partial — send only what changes).
    PersonListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Person"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    ChargePolicy:
      type: object
      properties:
        fine:
          anyOf:
            - type: object
              properties:
                disabled:
                  type: boolean
                  enum:
                    - true
              required:
                - disabled
            - type: object
              properties:
                mode:
                  type: string
                  enum:
                    - percent
                    - fixed
                value:
                  type: number
                  minimum: 0
                graceDays:
                  type: integer
                  minimum: 0
              required:
                - mode
                - value
          description: "Late fine: applied ONCE after `graceDays` past the due date. `mode` = `percent` (of the original amount) or `fixed` (absolute value); `value` ≥ 0."
        interest:
          anyOf:
            - type: object
              properties:
                disabled:
                  type: boolean
                  enum:
                    - true
              required:
                - disabled
            - type: object
              properties:
                mode:
                  type: string
                  enum:
                    - percent_month
                    - percent_day
                    - fixed_day
                value:
                  type: number
                  minimum: 0
                graceDays:
                  type: integer
                  minimum: 0
              required:
                - mode
                - value
          description: "Late interest: pro-rata die, accrues per day from the due date (respecting `graceDays`). `mode` = `percent_month`, `percent_day` or `fixed_day`; `value` ≥ 0."
        discount:
          anyOf:
            - type: object
              properties:
                disabled:
                  type: boolean
                  enum:
                    - true
              required:
                - disabled
            - type: array
              items:
                type: object
                properties:
                  mode:
                    type: string
                    enum:
                      - percent
                      - fixed
                  value:
                    type: number
                    minimum: 0
                  limitDate:
                    type: string
                required:
                  - mode
                  - value
          description: "Early-payment discount: list of bands `{ mode, value, limitDate? }` by cut-off date (earlier = bigger discount). `mode` = `percent` or `fixed`. Missing `limitDate` (`YYYY-MM-DD`) = valid while not past due."
        correction:
          type: object
          properties:
            index:
              type: string
              enum:
                - none
                - ipca
                - igpm
              description: Monetary correction index (`none` | `ipca` | `igpm`).
          required:
            - index
          description: Monetary correction applied to the amount.
      description: 'Per-charge fees policy (engine). Overrides, at the charge level, the inherited policy (organization → collection rule → charge), merged field by field. Each block accepts `{ "disabled": true }` to turn that fee off. Absent/null = inherit everything from the parent.'
    ChargeEncargos:
      type: object
      properties:
        fineAmount:
          type: number
          description: Computed fine.
          example: 30
        interestAmount:
          type: number
          description: Computed late interest.
          example: 15
        correctionAmount:
          type: number
          description: Computed monetary correction.
          example: 0
        discountAmount:
          type: number
          description: Computed discount.
          example: 0
        currentAmount:
          type: number
          description: Current amount = original + fine + interest + correction − discount.
          example: 1545
        daysOverdue:
          type: integer
          description: Days overdue computed in the organization’s timezone (0 while not past due).
          example: 12
      required:
        - fineAmount
        - interestAmount
        - correctionAmount
        - discountAmount
        - currentAmount
        - daysOverdue
      description: Fees breakdown derived by the engine in the organization’s timezone (additive to the charge). Values are numbers (not decimal strings).
    Charge:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Company (creditor) of the charge.
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Business unit (BU) of the charge.
        personId:
          type: string
          format: uuid
          description: Customer (debtor) of the charge.
        collectionRuleId:
          type:
            - string
            - "null"
          format: uuid
          description: Collection rule tracking the charge. If omitted on create, the organization’s default rule is used.
        documentNumber:
          type:
            - string
            - "null"
          description: Source document number (invoice, contract, etc.).
          example: NF-2026-0042
        description:
          type:
            - string
            - "null"
          description: Free-form charge description.
        originalAmount:
          type: string
          description: Original charge amount.
          example: "1500.00"
        interestAmount:
          type: string
          description: Accrued interest (default 0).
          example: "15.00"
        fineAmount:
          type: string
          description: Fine amount (default 0).
          example: "30.00"
        discountAmount:
          type: string
          description: Applied discount (default 0).
          example: "0.00"
        correctionAmount:
          type: string
          description: Accrued monetary correction (IPCA/IGP-M index, default 0). Serialized as a decimal string.
          example: "0.00"
        paidAmount:
          type:
            - string
            - "null"
          description: Amount actually paid.
          example: "1545.00"
        currentAmount:
          type:
            - string
            - "null"
          description: Current amount (original + interest + fine − discount). Recalculated automatically on create and update.
          example: "1545.00"
        issueDate:
          type: string
          format: date-time
          description: Issue date.
        dueDate:
          type: string
          format: date-time
          description: Due date.
        paidAt:
          type:
            - string
            - "null"
          format: date-time
          description: Payment date.
        daysOverdue:
          type: integer
          description: Days overdue (0 while not past due). Recalculated on read.
          example: 12
        status:
          type: string
          enum:
            - pending
            - paid
            - overdue
            - cancelled
            - negotiated
            - protested
            - negatived
            - written_off
          description: Status (`pending` | `paid` | `overdue` | `cancelled` | `negotiated` | `protested` | `negatived` | `written_off`).
        paymentMethod:
          type:
            - string
            - "null"
          enum:
            - boleto
            - pix
            - credit_card
            - transfer
            - null
          description: Payment method (`boleto` | `pix` | `credit_card` | `transfer`).
        barcode:
          type:
            - string
            - "null"
          description: Boleto barcode/digitable line.
        pixEmv:
          type:
            - string
            - "null"
          description: Pix copy-and-paste code (EMV).
        paymentUrl:
          type:
            - string
            - "null"
          description: Payment page URL.
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        currentStep:
          type:
            - integer
            - "null"
          description: Current collection rule step (0 = none executed).
        lastNotificationAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the last notification was sent.
        negativedAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the charge was reported to credit bureaus.
        protestedAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the charge was protested at the notary.
        source:
          type: string
          enum:
            - kobana
            - erp
            - api
            - spreadsheet
            - manual
          description: Charge source (`kobana` | `erp` | `api` | `spreadsheet` | `manual`).
        lastVerifiedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Last payment verification against the source.
        paymentClaimed:
          type: boolean
          description: true when the debtor claimed "already paid" in the portal — the rule pauses and verification opens.
        legalHold:
          type: boolean
          description: "Legal hold (statute of limitations, court order): suspends collection."
        legalHoldReason:
          type:
            - string
            - "null"
          description: Legal hold reason.
        encargoSource:
          type: string
          enum:
            - computed
            - boleto
          description: "Source of the charges/fees: `computed` (calculated by the engine from the policy) or `boleto` (mirrored from a registered boleto, which is the source of truth and is not recalculated)."
          example: computed
        chargePolicy:
          allOf:
            - $ref: "#/components/schemas/ChargePolicy"
            - type:
                - object
                - "null"
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        encargos:
          $ref: "#/components/schemas/ChargeEncargos"
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - personId
        - collectionRuleId
        - documentNumber
        - description
        - originalAmount
        - interestAmount
        - fineAmount
        - discountAmount
        - correctionAmount
        - paidAmount
        - currentAmount
        - issueDate
        - dueDate
        - paidAt
        - daysOverdue
        - status
        - paymentMethod
        - barcode
        - pixEmv
        - paymentUrl
        - externalId
        - customData
        - tags
        - currentStep
        - lastNotificationAt
        - negativedAt
        - protestedAt
        - source
        - lastVerifiedAt
        - paymentClaimed
        - legalHold
        - legalHoldReason
        - encargoSource
        - chargePolicy
        - deletedAt
        - metadata
        - createdAt
        - updatedAt
        - encargos
      description: Charge (receivable) linked to a customer and tracked by the collection rule. Monetary values are serialized as decimal strings (e.g. "1500.00").
    ChargeCreateRequest:
      type: object
      properties:
        personId:
          type: string
          format: uuid
          description: Customer (debtor) of the charge.
        collectionRuleId:
          type:
            - string
            - "null"
          format: uuid
          description: Collection rule tracking the charge. If omitted on create, the organization’s default rule is used.
        documentNumber:
          type:
            - string
            - "null"
          maxLength: 50
          description: Source document number (invoice, contract, etc.).
        description:
          type:
            - string
            - "null"
          maxLength: 500
          description: Free-form charge description.
        originalAmount:
          type: number
          exclusiveMinimum: 0
          description: Original charge amount.
          example: 1500
        interestAmount:
          type: number
          minimum: 0
          description: Accrued interest (default 0).
        fineAmount:
          type: number
          minimum: 0
          description: Fine amount (default 0).
        discountAmount:
          type: number
          minimum: 0
          description: Applied discount (default 0).
        issueDate:
          type: string
          description: Issue date.
          example: 2026-07-01
        dueDate:
          type: string
          description: Due date.
          example: 2026-08-01
        status:
          type: string
          enum:
            - pending
            - paid
            - overdue
            - cancelled
            - negotiated
            - protested
            - negatived
            - written_off
          description: Status (`pending` | `paid` | `overdue` | `cancelled` | `negotiated` | `protested` | `negatived` | `written_off`).
        paymentMethod:
          type:
            - string
            - "null"
          enum:
            - boleto
            - pix
            - credit_card
            - transfer
            - null
          description: Payment method (`boleto` | `pix` | `credit_card` | `transfer`).
        barcode:
          type:
            - string
            - "null"
          maxLength: 100
          description: Boleto barcode/digitable line.
        pixEmv:
          type:
            - string
            - "null"
          maxLength: 500
          description: Pix copy-and-paste code (EMV).
        paymentUrl:
          type:
            - string
            - "null"
          format: uri
          description: Payment page URL.
        externalId:
          type:
            - string
            - "null"
          maxLength: 100
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        chargePolicy:
          allOf:
            - $ref: "#/components/schemas/ChargePolicy"
            - type:
                - object
                - "null"
      required:
        - personId
        - originalAmount
        - issueDate
        - dueDate
      description: Payload to create a charge. Monetary values are sent as numbers; dates accept `YYYY-MM-DD` or ISO 8601 datetime.
    ChargeUpdateRequest:
      type: object
      properties:
        personId:
          type: string
          format: uuid
          description: Customer (debtor) of the charge.
        collectionRuleId:
          type:
            - string
            - "null"
          format: uuid
          description: Collection rule tracking the charge. If omitted on create, the organization’s default rule is used.
        documentNumber:
          type:
            - string
            - "null"
          maxLength: 50
          description: Source document number (invoice, contract, etc.).
        description:
          type:
            - string
            - "null"
          maxLength: 500
          description: Free-form charge description.
        originalAmount:
          type: number
          exclusiveMinimum: 0
          description: Original charge amount.
          example: 1500
        interestAmount:
          type: number
          minimum: 0
          description: Accrued interest (default 0).
        fineAmount:
          type: number
          minimum: 0
          description: Fine amount (default 0).
        discountAmount:
          type: number
          minimum: 0
          description: Applied discount (default 0).
        issueDate:
          type: string
          description: Issue date.
          example: 2026-07-01
        dueDate:
          type: string
          description: Due date.
          example: 2026-08-01
        status:
          type: string
          enum:
            - pending
            - paid
            - overdue
            - cancelled
            - negotiated
            - protested
            - negatived
            - written_off
          description: Status (`pending` | `paid` | `overdue` | `cancelled` | `negotiated` | `protested` | `negatived` | `written_off`).
        paymentMethod:
          type:
            - string
            - "null"
          enum:
            - boleto
            - pix
            - credit_card
            - transfer
            - null
          description: Payment method (`boleto` | `pix` | `credit_card` | `transfer`).
        barcode:
          type:
            - string
            - "null"
          maxLength: 100
          description: Boleto barcode/digitable line.
        pixEmv:
          type:
            - string
            - "null"
          maxLength: 500
          description: Pix copy-and-paste code (EMV).
        paymentUrl:
          type:
            - string
            - "null"
          format: uri
          description: Payment page URL.
        externalId:
          type:
            - string
            - "null"
          maxLength: 100
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        chargePolicy:
          allOf:
            - $ref: "#/components/schemas/ChargePolicy"
            - type:
                - object
                - "null"
        paidAmount:
          type:
            - number
            - "null"
          minimum: 0
          description: Amount actually paid.
        paidAt:
          type:
            - string
            - "null"
          description: Payment date.
          example: 2026-08-03
      description: Fields to update (partial — send only what changes). `currentAmount` and `daysOverdue` are recalculated automatically.
    ChargeListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Charge"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    ChargeDeleteResponse:
      type: object
      properties:
        message:
          type: string
          description: Deletion confirmation message.
      required:
        - message
    ChargeNotifyRequest:
      type: object
      properties:
        channel:
          type: string
          enum:
            - email
            - sms
            - whatsapp
            - voice
            - manual
          description: Channel (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        recipient:
          type: string
          minLength: 1
          description: "Recipient: email for `email`, phone for `sms`/`whatsapp`/`voice`; free-form for `manual`."
          example: maria@exemplo.com.br
        subject:
          type: string
          maxLength: 200
          description: Subject (used for email).
        body:
          type: string
          minLength: 1
          description: Message body.
        collectionRuleStepId:
          type: string
          format: uuid
          description: Collection rule step to associate (updates the charge’s `currentStep`).
        metadata:
          type: object
          additionalProperties: {}
          description: Free-form metadata stored on the notification.
      required:
        - channel
        - recipient
        - body
      description: Manual notification payload to send to the debtor.
    ChargeNotifyResponse:
      type: object
      properties:
        message:
          type: string
          description: Queueing confirmation message.
        notification:
          type: object
          additionalProperties: {}
          description: Created notification (`queued` status), including the related customer and charge.
      required:
        - message
        - notification
    AgreementInstallment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        agreementId:
          type: string
          format: uuid
          description: Agreement that owns the installment.
        installmentNumber:
          type: integer
          description: Installment number (starts at 1).
          example: 1
        dueDate:
          type: string
          format: date-time
          description: Installment due date.
        amount:
          type: string
          description: Installment amount.
          example: "200.00"
        paidAmount:
          type:
            - string
            - "null"
          description: Amount paid for the installment.
          example: "200.00"
        paidAt:
          type:
            - string
            - "null"
          format: date-time
          description: Installment payment date.
        status:
          type: string
          enum:
            - pending
            - paid
            - overdue
            - cancelled
          description: Status (`pending` | `paid` | `overdue` | `cancelled`).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
        customMetadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
      required:
        - id
        - publicId
        - agreementId
        - installmentNumber
        - dueDate
        - amount
        - paidAmount
        - paidAt
        - status
        - deletedAt
        - customMetadata
        - metadata
        - externalId
        - createdAt
        - updatedAt
      description: Agreement installment. Created automatically on acceptance, with monthly due dates starting at `firstDueDate`.
    Agreement:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Company (creditor) of the agreement.
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Business unit (BU) of the agreement.
        personId:
          type: string
          format: uuid
          description: Customer (debtor) of the agreement.
        negotiationOfferId:
          type:
            - string
            - "null"
          format: uuid
          description: Negotiation offer that originated the agreement.
        originalTotal:
          type: string
          description: Original total of the renegotiated debt.
          example: "1500.00"
        discountAmount:
          type: string
          description: Granted discount (default 0).
          example: "300.00"
        finalTotal:
          type: string
          description: Final total (`originalTotal` − `discountAmount`). Computed server-side.
          example: "1200.00"
        numberOfInstallments:
          type: integer
          description: Number of installments (1 to 120).
          example: 6
        installmentValue:
          type: string
          description: Value of each installment (`finalTotal` / `numberOfInstallments`). Computed server-side.
          example: "200.00"
        firstDueDate:
          type: string
          format: date-time
          description: First installment due date (the rest fall due monthly).
        status:
          type: string
          enum:
            - proposed
            - accepted
            - active
            - completed
            - cancelled
            - defaulted
          description: Status (`proposed` | `accepted` | `active` | `completed` | `cancelled` | `defaulted`).
        acceptedAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the agreement was accepted.
        acceptedIp:
          type:
            - string
            - "null"
          description: IP recorded on acceptance (audit trail).
        termsAccepted:
          type:
            - string
            - "null"
          description: Terms accepted by the debtor (text/version).
        cancelledAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the agreement was cancelled.
        cancellationReason:
          type:
            - string
            - "null"
          description: Cancellation reason.
        completedAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the agreement was completed (all installments paid).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - personId
        - negotiationOfferId
        - originalTotal
        - discountAmount
        - finalTotal
        - numberOfInstallments
        - installmentValue
        - firstDueDate
        - status
        - acceptedAt
        - acceptedIp
        - termsAccepted
        - cancelledAt
        - cancellationReason
        - completedAt
        - externalId
        - customData
        - tags
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: 'Installment renegotiation agreement made with a customer. Monetary values are serialized as decimal strings (e.g. "1200.00"). Lifecycle: `proposed` → `accepted` → `active` → `completed`; may end as `cancelled` or `defaulted`.'
    AgreementCreateRequest:
      type: object
      properties:
        personId:
          type: string
          format: uuid
          description: Customer (debtor) of the agreement.
        negotiationOfferId:
          type:
            - string
            - "null"
          format: uuid
          description: Negotiation offer that originated the agreement.
        originalTotal:
          type: number
          exclusiveMinimum: 0
          description: Original total of the renegotiated debt.
          example: 1500
        discountAmount:
          type: number
          minimum: 0
          description: Granted discount (default 0).
          example: 300
        numberOfInstallments:
          type: integer
          exclusiveMinimum: 0
          maximum: 120
          description: Number of installments (1 to 120).
          example: 6
        firstDueDate:
          type: string
          description: First installment due date (the rest fall due monthly).
          example: 2026-08-01
        termsAccepted:
          type:
            - string
            - "null"
          description: Terms accepted by the debtor (text/version).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      required:
        - personId
        - originalTotal
        - numberOfInstallments
        - firstDueDate
      description: Payload to create an agreement (starts as `proposed`). `finalTotal` and `installmentValue` are computed server-side. Monetary values are sent as numbers.
    AgreementUpdateRequest:
      type: object
      properties:
        originalTotal:
          type: number
          exclusiveMinimum: 0
          description: Original total of the renegotiated debt.
        discountAmount:
          type: number
          minimum: 0
          description: Granted discount (default 0).
        numberOfInstallments:
          type: integer
          exclusiveMinimum: 0
          maximum: 120
          description: Number of installments (1 to 120).
        firstDueDate:
          type: string
          description: First installment due date (the rest fall due monthly).
          example: 2026-08-01
        termsAccepted:
          type:
            - string
            - "null"
          description: Terms accepted by the debtor (text/version).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      description: Fields to update (partial). Changing amounts or number of installments recalculates `finalTotal` and `installmentValue`.
    AgreementListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Agreement"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    AgreementAcceptRequest:
      type: object
      properties:
        acceptedIp:
          type: string
          description: IP recorded on acceptance (audit trail).
        termsAccepted:
          type: string
          description: Terms accepted by the debtor (text/version).
      description: Acceptance payload (body optional). Without `acceptedIp`, the IP is taken from the request headers.
    AgreementCancelRequest:
      type: object
      properties:
        reason:
          type: string
          minLength: 1
          description: Cancellation reason (required; stored in `cancellationReason`).
      required:
        - reason
      description: Cancellation payload.
    AgreementInstallmentSummary:
      type: object
      properties:
        total:
          type: integer
          description: Total installments.
        pending:
          type: integer
          description: Pending installments.
        paid:
          type: integer
          description: Paid installments.
        overdue:
          type: integer
          description: Overdue installments.
        cancelled:
          type: integer
          description: Cancelled installments.
        totalAmount:
          type: number
          description: Sum of installment amounts.
          example: 1200
        paidAmount:
          type: number
          description: Sum of paid amounts.
          example: 400
      required:
        - total
        - pending
        - paid
        - overdue
        - cancelled
        - totalAmount
        - paidAmount
      description: Aggregated summary of the agreement’s installments. Unlike resource fields, the monetary totals here are numbers.
    AgreementInstallmentListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AgreementInstallment"
          description: Agreement installments, ordered by number.
        summary:
          $ref: "#/components/schemas/AgreementInstallmentSummary"
      required:
        - data
        - summary
    AgreementInstallmentUpdateRequest:
      type: object
      properties:
        installmentNumber:
          type: integer
          exclusiveMinimum: 0
          description: Installment number (starts at 1).
          example: 1
        paidAmount:
          type: number
          exclusiveMinimum: 0
          description: Amount paid for the installment.
        paidAt:
          type: string
          description: Installment payment date.
          example: 2026-08-03
        status:
          type: string
          enum:
            - pending
            - paid
            - overdue
            - cancelled
          description: Status (`pending` | `paid` | `overdue` | `cancelled`).
      required:
        - installmentNumber
      description: Settle/update an installment, identified by `installmentNumber`. Marking as `paid` without `paidAt`/`paidAmount` fills in the current date and the installment amount.
    AgreementInstallmentUpdateResponse:
      type: object
      properties:
        installment:
          $ref: "#/components/schemas/AgreementInstallment"
        agreement:
          $ref: "#/components/schemas/Agreement"
      required:
        - installment
        - agreement
    DisputeChargeSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        documentNumber:
          type:
            - string
            - "null"
          description: Charge document number.
        currentAmount:
          type:
            - string
            - "null"
          description: Current charge amount (decimal string).
          example: "150.00"
        status:
          type: string
          description: Charge status.
      required:
        - id
        - documentNumber
        - currentAmount
        - status
      description: Summary of the disputed charge (in listings).
    DisputePersonSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          description: Customer name.
        documentNumber:
          type:
            - string
            - "null"
          description: Customer CPF/CNPJ (present in the detail view).
      required:
        - id
        - name
      description: Summary of the dispute’s customer.
    DisputeAssigneeSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          description: Assignee name.
        email:
          type: string
          format: email
          description: Assignee email.
      required:
        - id
        - name
        - email
      description: Summary of the assigned user.
    Dispute:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Company (creditor) of the record.
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Business unit of the record.
        chargeId:
          type: string
          format: uuid
          description: Disputed charge.
        personId:
          type: string
          format: uuid
          description: Customer (debtor) of the disputed charge.
        type:
          type: string
          enum:
            - already_paid
            - not_recognized
            - wrong_amount
            - service_not_provided
            - incorrect_invoice
            - wrong_recipient
            - other
          description: Dispute type (`already_paid` | `not_recognized` | `wrong_amount` | `service_not_provided` | `incorrect_invoice` | `wrong_recipient` | `other`).
        reason:
          type:
            - string
            - "null"
          description: Debtor/operator account of the issue.
        disputedAmount:
          type:
            - string
            - "null"
          description: Disputed amount, as a decimal string; null when the whole charge is disputed.
          example: "150.00"
        isFullDispute:
          type: boolean
          description: true when the dispute covers the full charge amount.
        documents:
          type:
            - array
            - "null"
          items:
            type: object
            additionalProperties: {}
          description: Evidence attachments/references.
        status:
          type: string
          enum:
            - open
            - under_review
            - resolved_valid
            - resolved_invalid
            - canceled
          description: Status (`open` | `under_review` | `resolved_valid` | `resolved_invalid` | `canceled`).
        assignedToId:
          type:
            - string
            - "null"
          format: uuid
          description: User assigned to the review (must belong to the organization).
        slaDueAt:
          type:
            - string
            - "null"
          format: date-time
          description: Resolution deadline (SLA).
        resolution:
          type:
            - string
            - "null"
          description: Reasoned resolution decision.
        resolutionEffect:
          type:
            - string
            - "null"
          enum:
            - resume_rule
            - adjust_amount
            - cancel_charge
            - write_off
            - null
          description: Effect applied on resolution (`resume_rule` | `adjust_amount` | `cancel_charge` | `write_off`).
        resolvedById:
          type:
            - string
            - "null"
          format: uuid
          description: User who resolved the dispute.
        openedAt:
          type: string
          format: date-time
          description: Dispute opening time (ISO 8601).
        resolvedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Dispute resolution time (ISO 8601; null while open).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customMetadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - chargeId
        - personId
        - type
        - reason
        - disputedAmount
        - isFullDispute
        - documents
        - status
        - assignedToId
        - slaDueAt
        - resolution
        - resolutionEffect
        - resolvedById
        - openedAt
        - resolvedAt
        - externalId
        - customMetadata
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: Dispute raised by the debtor or an operator against a charge. While open, the collection rule stays paused.
    DisputeListItem:
      allOf:
        - $ref: "#/components/schemas/Dispute"
        - type: object
          properties:
            charge:
              $ref: "#/components/schemas/DisputeChargeSummary"
            person:
              $ref: "#/components/schemas/DisputePersonSummary"
          required:
            - charge
            - person
      description: "List item: dispute with charge and customer summaries."
    DisputeDetail:
      allOf:
        - $ref: "#/components/schemas/Dispute"
        - type: object
          properties:
            charge:
              type: object
              additionalProperties: {}
              description: Full charge associated with the dispute.
            person:
              $ref: "#/components/schemas/DisputePersonSummary"
            assignedTo:
              allOf:
                - $ref: "#/components/schemas/DisputeAssigneeSummary"
                - type:
                    - object
                    - "null"
                  description: Review assignee (null when unassigned).
          required:
            - charge
            - person
            - assignedTo
      description: "Dispute detail: includes the full charge, the customer and the assignee."
    DisputeCreateRequest:
      type: object
      properties:
        chargeId:
          type: string
          format: uuid
          description: Disputed charge.
        type:
          type: string
          enum:
            - already_paid
            - not_recognized
            - wrong_amount
            - service_not_provided
            - incorrect_invoice
            - wrong_recipient
            - other
          description: Dispute type (`already_paid` | `not_recognized` | `wrong_amount` | `service_not_provided` | `incorrect_invoice` | `wrong_recipient` | `other`).
        reason:
          type: string
          maxLength: 2000
          description: Debtor/operator account of the issue.
        disputedAmount:
          type: number
          exclusiveMinimum: 0
          description: Disputed amount (number). Omit to dispute the full amount.
          example: 150
        documents:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: Evidence attachments/references.
        assignedToId:
          type: string
          format: uuid
          description: User assigned to the review (must belong to the organization).
        slaDays:
          type: integer
          exclusiveMinimum: 0
          maximum: 60
          description: SLA days to resolve (max 60; system default when omitted).
          example: 5
      required:
        - chargeId
        - type
      description: Payload to open a dispute against a charge.
    DisputeStartReviewRequest:
      type: object
      properties:
        action:
          type: string
          enum:
            - start_review
          description: "Action: start review (`start_review`)."
        assignedToId:
          type: string
          format: uuid
          description: User assigned to the review (must belong to the organization).
      required:
        - action
      description: Moves the dispute from `open` to `under_review`, optionally assigning an owner.
    DisputeResolveRequest:
      type: object
      properties:
        action:
          type: string
          enum:
            - resolve
          description: "Action: resolve the dispute (`resolve`)."
        decision:
          type: string
          enum:
            - valid
            - invalid
          description: "Decision: `valid` (upheld) or `invalid` (rejected)."
        resolution:
          type: string
          minLength: 1
          maxLength: 2000
          description: Reasoned resolution decision.
        effect:
          type: string
          enum:
            - resume_rule
            - adjust_amount
            - cancel_charge
            - write_off
          description: Resolution effect (`resume_rule` | `adjust_amount` | `cancel_charge` | `write_off`).
        adjustedAmount:
          type: number
          exclusiveMinimum: 0
          description: New charge amount when the effect is `adjust_amount`.
          example: 120
      required:
        - action
        - decision
        - resolution
      description: Resolves the dispute with a reasoned decision and an effect on the charge/rule.
    DisputeCancelRequest:
      type: object
      properties:
        action:
          type: string
          enum:
            - cancel
          description: "Action: cancel the dispute (`cancel`)."
        reason:
          type: string
          maxLength: 2000
          description: Cancellation reason.
      required:
        - action
      description: Cancels the dispute (e.g., opened by mistake); the charge rule resumes.
    DisputeActionRequest:
      oneOf:
        - $ref: "#/components/schemas/DisputeStartReviewRequest"
        - $ref: "#/components/schemas/DisputeResolveRequest"
        - $ref: "#/components/schemas/DisputeCancelRequest"
      discriminator:
        propertyName: action
        mapping:
          start_review: "#/components/schemas/DisputeStartReviewRequest"
          resolve: "#/components/schemas/DisputeResolveRequest"
          cancel: "#/components/schemas/DisputeCancelRequest"
      description: Action on the dispute, discriminated by the `action` field (`start_review` | `resolve` | `cancel`).
    DisputeResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Dispute"
      required:
        - data
    DisputeDetailResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/DisputeDetail"
      required:
        - data
    DisputeListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/DisputeListItem"
        pagination:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - pagination
      description: "Dispute list envelope. Note: uses the `pagination` key (same fields as `meta`)."
    TaskPersonSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          description: Customer name.
        documentNumber:
          type:
            - string
            - "null"
          description: Customer CPF/CNPJ.
      required:
        - id
        - name
        - documentNumber
      description: Summary of the linked customer.
    TaskAssigneeSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          description: Assignee name.
        email:
          type: string
          format: email
          description: Assignee email.
        avatarUrl:
          type:
            - string
            - "null"
          description: Assignee avatar URL.
      required:
        - id
        - name
        - email
        - avatarUrl
      description: Summary of the assigned user.
    TaskChargeSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        documentNumber:
          type:
            - string
            - "null"
          description: Charge document number.
        originalAmount:
          type: string
          description: Original charge amount (decimal string).
          example: "350.00"
        dueDate:
          type: string
          description: Charge due date.
          example: 2026-08-01T00:00:00.000Z
        status:
          type: string
          description: Charge status.
      required:
        - id
        - documentNumber
        - originalAmount
        - dueDate
        - status
      description: Summary of the linked charge.
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Company (creditor) of the record.
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Business unit of the record.
        personId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer linked to the task.
        chargeId:
          type:
            - string
            - "null"
          format: uuid
          description: Charge linked to the task.
        assignedToId:
          type:
            - string
            - "null"
          format: uuid
          description: User assigned to the task.
        title:
          type: string
          description: Task title.
          example: Ligar para negociar parcela
        description:
          type:
            - string
            - "null"
          description: Detailed description.
        taskType:
          type: string
          enum:
            - call
            - email
            - visit
            - review
            - follow_up
          description: Type (`call` | `email` | `visit` | `review` | `follow_up`).
        priority:
          type: string
          enum:
            - low
            - medium
            - high
            - urgent
          description: Priority (`low` | `medium` | `high` | `urgent`).
        status:
          type: string
          enum:
            - pending
            - in_progress
            - completed
            - cancelled
          description: Status (`pending` | `in_progress` | `completed` | `cancelled`).
        dueAt:
          type:
            - string
            - "null"
          format: date-time
          description: Task due date (ISO 8601).
        completedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Task completion time (ISO 8601; null while pending).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
        person:
          anyOf:
            - $ref: "#/components/schemas/TaskPersonSummary"
            - type: "null"
          description: Linked customer (present on create/show or with `include=person`).
        assignedTo:
          anyOf:
            - $ref: "#/components/schemas/TaskAssigneeSummary"
            - type: "null"
          description: Assignee (present on create/show or with `include=assignedTo`).
        charge:
          anyOf:
            - $ref: "#/components/schemas/TaskChargeSummary"
            - type: "null"
          description: Linked charge (present on create/show or with `include=charge`).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - personId
        - chargeId
        - assignedToId
        - title
        - description
        - taskType
        - priority
        - status
        - dueAt
        - completedAt
        - externalId
        - customData
        - tags
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: Manual collection task (call, email, visit, review, follow-up) assignable to an operator. Single-item responses are not wrapped in `{ data }`.
    TaskCreateRequest:
      type: object
      properties:
        personId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer linked to the task.
        chargeId:
          type:
            - string
            - "null"
          format: uuid
          description: Charge linked to the task.
        assignedToId:
          type:
            - string
            - "null"
          format: uuid
          description: User assigned to the task.
        title:
          type: string
          minLength: 1
          maxLength: 255
          description: Task title.
        description:
          type:
            - string
            - "null"
          description: Detailed description.
        taskType:
          type: string
          enum:
            - call
            - email
            - visit
            - review
            - follow_up
          description: Type (`call` | `email` | `visit` | `review` | `follow_up`).
        priority:
          type: string
          enum:
            - low
            - medium
            - high
            - urgent
          default: medium
          description: Initial priority (`low` | `medium` | `high` | `urgent`; default `medium`).
        status:
          type: string
          enum:
            - pending
            - in_progress
            - completed
            - cancelled
          default: pending
          description: Initial status (default `pending`).
        dueAt:
          type:
            - string
            - "null"
          format: date-time
          description: Task due date (ISO 8601).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      required:
        - title
        - taskType
      description: Payload to create a task.
    TaskUpdateRequest:
      type: object
      properties:
        personId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer linked to the task.
        chargeId:
          type:
            - string
            - "null"
          format: uuid
          description: Charge linked to the task.
        assignedToId:
          type:
            - string
            - "null"
          format: uuid
          description: User assigned to the task.
        title:
          type: string
          minLength: 1
          maxLength: 255
          description: Task title.
        description:
          type:
            - string
            - "null"
          description: Detailed description.
        taskType:
          type: string
          enum:
            - call
            - email
            - visit
            - review
            - follow_up
          description: Type (`call` | `email` | `visit` | `review` | `follow_up`).
        priority:
          type: string
          enum:
            - low
            - medium
            - high
            - urgent
          description: Priority (`low` | `medium` | `high` | `urgent`).
        status:
          type: string
          enum:
            - pending
            - in_progress
            - completed
            - cancelled
          description: New status; `completed` auto-fills `completedAt`.
        dueAt:
          type:
            - string
            - "null"
          format: date-time
          description: Task due date (ISO 8601).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      description: Fields to update (partial — send only what changes). Setting status to `completed` fills `completedAt`; leaving `completed` clears it.
    TaskListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Task"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    InteractionPersonSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          description: Customer name.
        documentNumber:
          type:
            - string
            - "null"
          description: Customer CPF/CNPJ.
      required:
        - id
        - name
        - documentNumber
      description: Summary of the interaction’s customer.
    InteractionUserSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          description: User name.
        email:
          type: string
          format: email
          description: User email.
        avatarUrl:
          type:
            - string
            - "null"
          description: User avatar URL.
      required:
        - id
        - name
        - email
        - avatarUrl
      description: Summary of the authoring user.
    InteractionChargeSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        documentNumber:
          type:
            - string
            - "null"
          description: Charge document number.
        originalAmount:
          type: string
          description: Original charge amount (decimal string).
          example: "350.00"
        dueDate:
          type: string
          description: Charge due date.
          example: 2026-08-01T00:00:00.000Z
        status:
          type: string
          description: Charge status.
      required:
        - id
        - documentNumber
        - originalAmount
        - dueDate
        - status
      description: Summary of the related charge.
    Interaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Company (creditor) of the record.
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Business unit of the record.
        personId:
          type: string
          format: uuid
          description: Customer of the interaction.
        chargeId:
          type:
            - string
            - "null"
          format: uuid
          description: Charge related to the interaction.
        userId:
          type:
            - string
            - "null"
          format: uuid
          description: User who logged the interaction (inferred from the session/token).
        interactionType:
          type: string
          enum:
            - call
            - email
            - whatsapp
            - meeting
            - note
          description: Type (`call` | `email` | `whatsapp` | `meeting` | `note`).
        direction:
          type: string
          enum:
            - inbound
            - outbound
          description: Direction (`inbound` = customer reached out, `outbound` = we contacted the customer).
        summary:
          type:
            - string
            - "null"
          description: Interaction summary/notes.
        outcome:
          type:
            - string
            - "null"
          enum:
            - promise_to_pay
            - negotiation
            - dispute
            - no_contact
            - callback_requested
            - payment_confirmed
            - null
          description: Outcome (`promise_to_pay` | `negotiation` | `dispute` | `no_contact` | `callback_requested` | `payment_confirmed`).
        promiseDate:
          type:
            - string
            - "null"
          description: Promised payment date.
          example: 2026-08-15T00:00:00.000Z
        promisedAmount:
          type:
            - string
            - "null"
          description: Promised amount (decimal string).
          example: "200.00"
        contactedAt:
          type: string
          format: date-time
          description: Contact time (ISO 8601).
        durationSeconds:
          type:
            - integer
            - "null"
          description: Contact duration in seconds.
        metadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Free-form interaction metadata.
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
        person:
          allOf:
            - $ref: "#/components/schemas/InteractionPersonSummary"
            - description: Customer (present on create/show or with `include=person`).
        user:
          anyOf:
            - $ref: "#/components/schemas/InteractionUserSummary"
            - type: "null"
          description: Authoring user (present on create/show or with `include=user`).
        charge:
          anyOf:
            - $ref: "#/components/schemas/InteractionChargeSummary"
            - type: "null"
          description: Related charge (present on create/show or with `include=charge`).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - personId
        - chargeId
        - userId
        - interactionType
        - direction
        - summary
        - outcome
        - promiseDate
        - promisedAmount
        - contactedAt
        - durationSeconds
        - metadata
        - externalId
        - customData
        - tags
        - createdAt
        - updatedAt
        - deletedAt
      description: Customer interaction (call, email, WhatsApp, meeting, note) logged in the collection workflow. Single-item responses are not wrapped in `{ data }`.
    InteractionCreateRequest:
      type: object
      properties:
        personId:
          type: string
          format: uuid
          description: Customer of the interaction.
        chargeId:
          type:
            - string
            - "null"
          format: uuid
          description: Charge related to the interaction.
        interactionType:
          type: string
          enum:
            - call
            - email
            - whatsapp
            - meeting
            - note
          description: Type (`call` | `email` | `whatsapp` | `meeting` | `note`).
        direction:
          type: string
          enum:
            - inbound
            - outbound
          description: Direction (`inbound` = customer reached out, `outbound` = we contacted the customer).
        summary:
          type:
            - string
            - "null"
          description: Interaction summary/notes.
        outcome:
          type:
            - string
            - "null"
          enum:
            - promise_to_pay
            - negotiation
            - dispute
            - no_contact
            - callback_requested
            - payment_confirmed
            - null
          description: Outcome (`promise_to_pay` | `negotiation` | `dispute` | `no_contact` | `callback_requested` | `payment_confirmed`).
        promiseDate:
          type:
            - string
            - "null"
          format: date-time
          description: Promised payment date.
        promisedAmount:
          type:
            - number
            - "null"
          exclusiveMinimum: 0
          description: Promised amount (positive number).
          example: 200
        contactedAt:
          type: string
          format: date-time
          description: Contact time (ISO 8601; defaults to now).
        durationSeconds:
          type:
            - integer
            - "null"
          minimum: 0
          description: Contact duration in seconds.
        metadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Free-form interaction metadata.
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      required:
        - personId
        - interactionType
        - direction
      description: Payload to log an interaction. The authoring user is inferred from the session/token.
    InteractionUpdateRequest:
      type: object
      properties:
        summary:
          type:
            - string
            - "null"
          description: Interaction summary/notes.
        notes:
          type:
            - string
            - "null"
          description: Alias for `summary` (stored in the same field; when both are sent, `notes` wins).
        outcome:
          type:
            - string
            - "null"
          enum:
            - promise_to_pay
            - negotiation
            - dispute
            - no_contact
            - callback_requested
            - payment_confirmed
            - null
          description: Outcome (`promise_to_pay` | `negotiation` | `dispute` | `no_contact` | `callback_requested` | `payment_confirmed`).
        promiseDate:
          type:
            - string
            - "null"
          format: date-time
          description: Promised payment date.
        promisedAmount:
          type:
            - number
            - "null"
          exclusiveMinimum: 0
          description: Promised amount (positive number).
        metadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Free-form interaction metadata.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      description: "Fields editable after logging: summary/notes, outcome, promise and metadata. Type, direction and links are immutable."
    InteractionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Interaction"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    Notification:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        personId:
          type: string
          format: uuid
          description: Recipient customer.
        chargeId:
          type:
            - string
            - "null"
          format: uuid
          description: Charge related to the notification.
        collectionRuleStepId:
          type:
            - string
            - "null"
          format: uuid
          description: Collection rule step that originated the notification.
        channel:
          type: string
          enum:
            - email
            - sms
            - whatsapp
            - voice
            - manual
          description: Channel (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        status:
          type: string
          enum:
            - pending
            - queued
            - sent
            - delivered
            - read
            - failed
            - bounced
          description: Lifecycle status (`pending` | `queued` | `sent` | `delivered` | `read` | `failed` | `bounced`).
        recipient:
          type: string
          description: "Recipient: email for the `email` channel, phone for `sms`/`whatsapp`/`voice`."
          example: maria@example.com
        subject:
          type:
            - string
            - "null"
          description: Subject (for channels that support it, e.g., email).
        body:
          type: string
          description: Message body.
        idempotencyKey:
          type:
            - string
            - "null"
          description: Send idempotency key (generated by the rule engine).
        stepExecutionId:
          type:
            - string
            - "null"
          format: uuid
          description: Rule step execution that generated the notification.
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system or in the delivery provider.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        sentAt:
          type:
            - string
            - "null"
          format: date-time
          description: Send time (ISO 8601).
        deliveredAt:
          type:
            - string
            - "null"
          format: date-time
          description: Delivery time (ISO 8601).
        readAt:
          type:
            - string
            - "null"
          format: date-time
          description: Read time (ISO 8601).
        clickedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Click time (ISO 8601).
        failedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Failure time (ISO 8601).
        failureReason:
          type:
            - string
            - "null"
          description: Failure reason reported by the provider.
        cost:
          type:
            - string
            - "null"
          description: Send cost (decimal string).
          example: "0.0450"
        metadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: System-written metadata (e.g., `resendOf` on resends).
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        person:
          type: object
          additionalProperties: {}
          description: Full customer (with `include=person`).
        charge:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Full charge (with `include=charge`).
        collectionRuleStep:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Rule step with its message template (with `include=step` or `include=template`).
      required:
        - id
        - publicId
        - organizationId
        - personId
        - chargeId
        - collectionRuleStepId
        - channel
        - status
        - recipient
        - subject
        - body
        - idempotencyKey
        - stepExecutionId
        - externalId
        - customData
        - tags
        - sentAt
        - deliveredAt
        - readAt
        - clickedAt
        - failedAt
        - failureReason
        - cost
        - metadata
        - createdAt
        - updatedAt
      description: Notification sent (or to be sent) to a customer via email, SMS, WhatsApp, voice or a manual channel — usually triggered by a collection rule step. Single-item responses are not wrapped in `{ data }`.
    NotificationCreateRequest:
      type: object
      properties:
        personId:
          type: string
          format: uuid
          description: Recipient customer.
        chargeId:
          type:
            - string
            - "null"
          format: uuid
          description: Charge related to the notification.
        collectionRuleStepId:
          type:
            - string
            - "null"
          format: uuid
          description: Collection rule step that originated the notification.
        channel:
          type: string
          enum:
            - email
            - sms
            - whatsapp
            - voice
            - manual
          description: Channel (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        recipient:
          type: string
          minLength: 1
          description: Recipient; validated according to the channel (email for `email`, phone for `sms`/`whatsapp`/`voice`).
        subject:
          type:
            - string
            - "null"
          maxLength: 500
          description: Subject (for channels that support it, e.g., email).
        body:
          type: string
          minLength: 1
          description: Message body.
        externalId:
          type:
            - string
            - "null"
          maxLength: 100
          description: Identifier in YOUR system or in the delivery provider.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: System-written metadata (e.g., `resendOf` on resends).
      required:
        - personId
        - channel
        - recipient
        - body
      description: Payload to create a manual notification (starts with `pending` status).
    NotificationUpdateRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - queued
            - sent
            - delivered
            - read
            - failed
            - bounced
          description: New status; fills the matching timestamp (sentAt/deliveredAt/readAt/failedAt) when not provided.
        sentAt:
          type:
            - string
            - "null"
          description: ISO 8601 timestamp or `YYYY-MM-DD` date; null clears the field.
        deliveredAt:
          type:
            - string
            - "null"
          description: ISO 8601 timestamp or `YYYY-MM-DD` date; null clears the field.
        readAt:
          type:
            - string
            - "null"
          description: ISO 8601 timestamp or `YYYY-MM-DD` date; null clears the field.
        failedAt:
          type:
            - string
            - "null"
          description: ISO 8601 timestamp or `YYYY-MM-DD` date; null clears the field.
        failureReason:
          type:
            - string
            - "null"
          maxLength: 500
          description: Failure reason reported by the provider.
        externalId:
          type:
            - string
            - "null"
          maxLength: 100
          description: Identifier in YOUR system or in the delivery provider.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: System-written metadata (e.g., `resendOf` on resends).
        cost:
          type:
            - number
            - "null"
          minimum: 0
          description: Send cost (number, minimum 0).
      description: Fields to update (partial). Changing the status auto-fills the matching timestamp when it is not provided.
    NotificationListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Notification"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    ClassificationCriteria:
      type: object
      properties:
        minOnTimePercentage:
          type: number
          minimum: 0
          maximum: 100
          description: Minimum on-time payment percentage (0-100).
        maxOnTimePercentage:
          type: number
          minimum: 0
          maximum: 100
          description: Maximum on-time payment percentage (0-100).
        maxConsecutiveDelays:
          type: integer
          minimum: 0
          description: Maximum tolerated consecutive delays.
        maxCurrentOverdueDays:
          type: integer
          minimum: 0
          description: Maximum current overdue days.
        evaluationPeriodMonths:
          type: integer
          minimum: 1
          description: Evaluation window, in months.
        minChargesCount:
          type: integer
          minimum: 0
          description: Minimum charges in the period.
        maxChargesCount:
          type: integer
          minimum: 0
          description: Maximum charges in the period.
        hasNegativationHistory:
          type: boolean
          description: Requires (true) or forbids (false) negativation history.
        hasProtestHistory:
          type: boolean
          description: Requires (true) or forbids (false) protest history.
      description: Automatic assignment criteria (payment behavior).
    Classification:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Associated company (creditor).
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Record business unit.
        name:
          type: string
          description: Classification name.
          example: Bom pagador
        code:
          type: string
          description: Stable code (lowercase, digits and underscore; unique within the organization).
          example: good_payer
        description:
          type:
            - string
            - "null"
          description: Classification description.
        color:
          type:
            - string
            - "null"
          description: Hex color shown in the UI (e.g. `#22c55e`).
          example: "#22c55e"
        priority:
          type: integer
          description: Evaluation priority (lower evaluates first).
        isDefault:
          type: boolean
          description: true when this is the organization’s default classification (only one).
        autoAssign:
          type: boolean
          description: true when customers are auto-assigned by the criteria.
        criteria:
          allOf:
            - $ref: "#/components/schemas/ClassificationCriteria"
            - type:
                - object
                - "null"
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
        _count:
          type: object
          properties:
            people:
              type: integer
              description: Customers with this classification.
            collectionRules:
              type: integer
              description: Collection rules using this classification.
          required:
            - people
            - collectionRules
          description: Related counters (present with `include=_count` and in create/update responses).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - name
        - code
        - description
        - color
        - priority
        - isDefault
        - autoAssign
        - criteria
        - activatedAt
        - externalId
        - customData
        - tags
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: "Customer classification: segments the portfolio (e.g. good payer) and drives which collection rule applies."
    ClassificationCreateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Classification name.
        code:
          type: string
          minLength: 1
          maxLength: 100
          pattern: ^[a-z0-9_]+$
          description: Stable code (lowercase, digits and underscore; unique within the organization).
          example: good_payer
        description:
          type:
            - string
            - "null"
          maxLength: 1000
          description: Classification description.
        color:
          type:
            - string
            - "null"
          pattern: ^#[0-9A-Fa-f]{6}$
          description: Hex color shown in the UI (e.g. `#22c55e`).
          example: "#22c55e"
        priority:
          type: integer
          minimum: 0
          description: Evaluation priority (lower evaluates first).
        isDefault:
          type: boolean
          description: true when this is the organization’s default classification (only one).
        autoAssign:
          type: boolean
          description: true when customers are auto-assigned by the criteria.
        criteria:
          type:
            - object
            - "null"
          properties:
            minOnTimePercentage:
              type: number
              minimum: 0
              maximum: 100
              description: Minimum on-time payment percentage (0-100).
            maxOnTimePercentage:
              type: number
              minimum: 0
              maximum: 100
              description: Maximum on-time payment percentage (0-100).
            maxConsecutiveDelays:
              type: integer
              minimum: 0
              description: Maximum tolerated consecutive delays.
            maxCurrentOverdueDays:
              type: integer
              minimum: 0
              description: Maximum current overdue days.
            evaluationPeriodMonths:
              type: integer
              minimum: 1
              description: Evaluation window, in months.
            minChargesCount:
              type: integer
              minimum: 0
              description: Minimum charges in the period.
            maxChargesCount:
              type: integer
              minimum: 0
              description: Maximum charges in the period.
            hasNegativationHistory:
              type: boolean
              description: Requires (true) or forbids (false) negativation history.
            hasProtestHistory:
              type: boolean
              description: Requires (true) or forbids (false) protest history.
          description: Automatic assignment criteria (payment behavior).
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      required:
        - name
        - code
      description: Payload to create a classification. `code` is unique within the organization.
    ClassificationUpdateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Classification name.
        code:
          type: string
          minLength: 1
          maxLength: 100
          pattern: ^[a-z0-9_]+$
          description: Stable code (lowercase, digits and underscore; unique within the organization).
          example: good_payer
        description:
          type:
            - string
            - "null"
          maxLength: 1000
          description: Classification description.
        color:
          type:
            - string
            - "null"
          pattern: ^#[0-9A-Fa-f]{6}$
          description: Hex color shown in the UI (e.g. `#22c55e`).
          example: "#22c55e"
        priority:
          type: integer
          minimum: 0
          description: Evaluation priority (lower evaluates first).
        isDefault:
          type: boolean
          description: true when this is the organization’s default classification (only one).
        autoAssign:
          type: boolean
          description: true when customers are auto-assigned by the criteria.
        criteria:
          type:
            - object
            - "null"
          properties:
            minOnTimePercentage:
              type: number
              minimum: 0
              maximum: 100
              description: Minimum on-time payment percentage (0-100).
            maxOnTimePercentage:
              type: number
              minimum: 0
              maximum: 100
              description: Maximum on-time payment percentage (0-100).
            maxConsecutiveDelays:
              type: integer
              minimum: 0
              description: Maximum tolerated consecutive delays.
            maxCurrentOverdueDays:
              type: integer
              minimum: 0
              description: Maximum current overdue days.
            evaluationPeriodMonths:
              type: integer
              minimum: 1
              description: Evaluation window, in months.
            minChargesCount:
              type: integer
              minimum: 0
              description: Minimum charges in the period.
            maxChargesCount:
              type: integer
              minimum: 0
              description: Maximum charges in the period.
            hasNegativationHistory:
              type: boolean
              description: Requires (true) or forbids (false) negativation history.
            hasProtestHistory:
              type: boolean
              description: Requires (true) or forbids (false) protest history.
          description: Automatic assignment criteria (payment behavior).
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      description: Fields to update (partial — send only what changes).
    ClassificationListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Classification"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    MessageTemplate:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Associated company (creditor).
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Record business unit.
        name:
          type: string
          description: Template name (unique within the organization).
          example: Lembrete 3 dias antes
        channel:
          type: string
          enum:
            - email
            - sms
            - whatsapp
            - voice
            - manual
          description: Delivery channel (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        category:
          type: string
          enum:
            - reminder
            - overdue
            - negotiation
            - negativation_warning
            - protest_warning
            - payment_confirmation
          description: Category (`reminder` | `overdue` | `negotiation` | `negativation_warning` | `protest_warning` | `payment_confirmation`).
        tone:
          type:
            - string
            - "null"
          enum:
            - friendly
            - neutral
            - firm
            - urgent
            - null
          description: Message tone (`friendly` | `neutral` | `firm` | `urgent`).
        subject:
          type:
            - string
            - "null"
          description: Subject (used for email).
        body:
          type: string
          description: Message body, with variables in `{{variable}}` format.
        variables:
          type: array
          items:
            type: string
          description: Variables available in the body/subject.
          example:
            - customer_name
            - amount
            - due_date
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key; unique within the organization).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - name
        - channel
        - category
        - tone
        - subject
        - body
        - variables
        - activatedAt
        - externalId
        - customData
        - tags
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: Message template reused by collection rule steps.
    MessageTemplateCreateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Template name (unique within the organization).
        channel:
          type: string
          enum:
            - email
            - sms
            - whatsapp
            - voice
            - manual
          description: Delivery channel (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        category:
          type: string
          enum:
            - reminder
            - overdue
            - negotiation
            - negativation_warning
            - protest_warning
            - payment_confirmation
          description: Category (`reminder` | `overdue` | `negotiation` | `negativation_warning` | `protest_warning` | `payment_confirmation`).
        tone:
          type:
            - string
            - "null"
          enum:
            - friendly
            - neutral
            - firm
            - urgent
            - null
          description: Message tone (`friendly` | `neutral` | `firm` | `urgent`).
        subject:
          type:
            - string
            - "null"
          maxLength: 255
          description: Subject (used for email).
        body:
          type: string
          minLength: 1
          description: Message body, with variables in `{{variable}}` format.
        variables:
          type: array
          items:
            type: string
          description: Variables available in the body/subject.
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key; unique within the organization).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      required:
        - name
        - channel
        - category
        - body
      description: Payload to create a template. `name` and `externalId` are unique within the organization.
    MessageTemplateUpdateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Template name (unique within the organization).
        channel:
          type: string
          enum:
            - email
            - sms
            - whatsapp
            - voice
            - manual
          description: Delivery channel (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        category:
          type: string
          enum:
            - reminder
            - overdue
            - negotiation
            - negativation_warning
            - protest_warning
            - payment_confirmation
          description: Category (`reminder` | `overdue` | `negotiation` | `negativation_warning` | `protest_warning` | `payment_confirmation`).
        tone:
          type:
            - string
            - "null"
          enum:
            - friendly
            - neutral
            - firm
            - urgent
            - null
          description: Message tone (`friendly` | `neutral` | `firm` | `urgent`).
        subject:
          type:
            - string
            - "null"
          maxLength: 255
          description: Subject (used for email).
        body:
          type: string
          minLength: 1
          description: Message body, with variables in `{{variable}}` format.
        variables:
          type: array
          items:
            type: string
          description: Variables available in the body/subject.
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key; unique within the organization).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      description: Fields to update (partial — send only what changes).
    MessageTemplateDuplicateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Template name (unique within the organization).
      required:
        - name
      description: Name of the new template produced by duplication (unique within the organization).
    MessageTemplateListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/MessageTemplate"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    CollectionRuleStep:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        collectionRuleId:
          type: string
          format: uuid
          description: Collection rule that owns the step.
        messageTemplateId:
          type:
            - string
            - "null"
          format: uuid
          description: Message template used by the step (must belong to the organization).
        position:
          type: integer
          description: Step position in the rule (starts at 1).
          example: 1
        name:
          type: string
          description: Step name.
          example: Lembrete 3 dias antes
        triggerType:
          type: string
          enum:
            - before_due
            - on_due
            - after_due
            - after_issue
            - after_payment
          description: Trigger (`before_due` | `on_due` | `after_due` | `after_issue` | `after_payment`).
        triggerDays:
          type: integer
          description: Days relative to the trigger (0 = same day).
          example: 3
        actionType:
          type: string
          enum:
            - notification
            - negativation
            - protest
            - manual_task
            - negotiation_offer
            - judicial
          description: Action (`notification` | `negativation` | `protest` | `manual_task` | `negotiation_offer` | `judicial`).
        channels:
          type: array
          items:
            type: string
            enum:
              - email
              - sms
              - whatsapp
              - voice
              - manual
          description: Delivery channels (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        tone:
          type:
            - string
            - "null"
          enum:
            - friendly
            - neutral
            - firm
            - urgent
            - null
          description: Message tone (`friendly` | `neutral` | `firm` | `urgent`).
        preferredTime:
          type:
            - string
            - "null"
          description: Preferred send time (e.g. `09:00`).
          example: 09:00
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
        messageTemplate:
          type:
            - object
            - "null"
          properties:
            id:
              type: string
              format: uuid
              description: Resource identifier (UUID).
            publicId:
              type: string
              description: Stable public identifier (shown in the UI).
            organizationId:
              type: string
              format: uuid
              description: Organization that owns the record.
            workspaceId:
              type:
                - string
                - "null"
              format: uuid
              description: Record workspace (multi-tenant hierarchy).
            companyId:
              type:
                - string
                - "null"
              format: uuid
              description: Associated company (creditor).
            businessUnitId:
              type:
                - string
                - "null"
              format: uuid
              description: Record business unit.
            name:
              type: string
              description: Template name (unique within the organization).
              example: Lembrete 3 dias antes
            channel:
              type: string
              enum:
                - email
                - sms
                - whatsapp
                - voice
                - manual
              description: Delivery channel (`email` | `sms` | `whatsapp` | `voice` | `manual`).
            category:
              type: string
              enum:
                - reminder
                - overdue
                - negotiation
                - negativation_warning
                - protest_warning
                - payment_confirmation
              description: Category (`reminder` | `overdue` | `negotiation` | `negativation_warning` | `protest_warning` | `payment_confirmation`).
            tone:
              type:
                - string
                - "null"
              enum:
                - friendly
                - neutral
                - firm
                - urgent
                - null
              description: Message tone (`friendly` | `neutral` | `firm` | `urgent`).
            subject:
              type:
                - string
                - "null"
              description: Subject (used for email).
            body:
              type: string
              description: Message body, with variables in `{{variable}}` format.
            variables:
              type: array
              items:
                type: string
              description: Variables available in the body/subject.
              example:
                - customer_name
                - amount
                - due_date
            activatedAt:
              type:
                - string
                - "null"
              format: date-time
              description: Activation timestamp (null = inactive).
            externalId:
              type:
                - string
                - "null"
              description: Identifier in YOUR system (integration key; unique within the organization).
            customData:
              type:
                - object
                - "null"
              additionalProperties: {}
              description: API-consumer custom metadata.
            tags:
              type: array
              items:
                type: string
              description: Free-form tags.
            metadata:
              type: object
              additionalProperties: {}
              description: System-written metadata.
            createdAt:
              type: string
              format: date-time
              description: Created at (ISO 8601).
            updatedAt:
              type: string
              format: date-time
              description: Updated at (ISO 8601).
            deletedAt:
              type:
                - string
                - "null"
              format: date-time
              description: Deleted at (soft delete; null while active).
          required:
            - id
            - publicId
            - organizationId
            - workspaceId
            - companyId
            - businessUnitId
            - name
            - channel
            - category
            - tone
            - subject
            - body
            - variables
            - activatedAt
            - externalId
            - customData
            - tags
            - metadata
            - createdAt
            - updatedAt
            - deletedAt
          description: Embedded message template (present on step endpoints).
      required:
        - id
        - publicId
        - collectionRuleId
        - messageTemplateId
        - position
        - name
        - triggerType
        - triggerDays
        - actionType
        - channels
        - tone
        - preferredTime
        - activatedAt
        - externalId
        - customData
        - tags
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: "Rule step: action triggered relative to the due date (notification, negativation, protest, etc.)."
    CollectionRule:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Associated company (creditor).
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Record business unit.
        classificationId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer classification served by the rule (segmentation).
        name:
          type: string
          description: Rule name.
          example: Régua padrão
        description:
          type:
            - string
            - "null"
          description: Rule description.
        isDefault:
          type: boolean
          description: true when this is the organization’s default rule (only one).
        priority:
          type: integer
          description: Priority when selecting a rule (higher wins).
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
        classification:
          allOf:
            - $ref: "#/components/schemas/Classification"
            - type:
                - object
                - "null"
              description: Associated classification (full object; null when not segmented).
        steps:
          type: array
          items:
            $ref: "#/components/schemas/CollectionRuleStep"
          description: Rule steps ordered by `position` (present with `include=steps` and in create/update responses).
        _count:
          type: object
          properties:
            charges:
              type: integer
              description: Active charges on the rule (pending, overdue or negotiated status).
          required:
            - charges
          description: Related counters.
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - classificationId
        - name
        - description
        - isDefault
        - priority
        - activatedAt
        - externalId
        - customData
        - tags
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
        - classification
      description: "Collection rule: sequence of automated steps applied to the portfolio charges."
    CollectionRuleStepInput:
      type: object
      properties:
        messageTemplateId:
          type:
            - string
            - "null"
          format: uuid
          description: Message template used by the step (must belong to the organization).
        position:
          type: integer
          exclusiveMinimum: 0
          description: Step position in the rule (starts at 1).
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Step name.
        triggerType:
          type: string
          enum:
            - before_due
            - on_due
            - after_due
            - after_issue
            - after_payment
          description: Trigger (`before_due` | `on_due` | `after_due` | `after_issue` | `after_payment`).
        triggerDays:
          type: integer
          minimum: 0
          description: Days relative to the trigger (0 = same day).
        actionType:
          type: string
          enum:
            - notification
            - negativation
            - protest
            - manual_task
            - negotiation_offer
            - judicial
          description: Action (`notification` | `negativation` | `protest` | `manual_task` | `negotiation_offer` | `judicial`).
        channels:
          type: array
          items:
            type: string
            enum:
              - email
              - sms
              - whatsapp
              - voice
              - manual
          minItems: 1
          description: Delivery channels (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        tone:
          type:
            - string
            - "null"
          enum:
            - friendly
            - neutral
            - firm
            - urgent
            - null
          description: Message tone (`friendly` | `neutral` | `firm` | `urgent`).
        preferredTime:
          type:
            - string
            - "null"
          maxLength: 10
          description: Preferred send time (e.g. `09:00`).
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      required:
        - name
        - triggerType
        - triggerDays
        - actionType
        - channels
      description: Step created together with the rule. Without `position`, steps are numbered in array order.
    CollectionRuleStepUpsert:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Step name.
        position:
          type: integer
          minimum: 1
          description: Step position in the rule (starts at 1).
        triggerType:
          type: string
          enum:
            - before_due
            - on_due
            - after_due
            - after_issue
            - after_payment
          description: Trigger (`before_due` | `on_due` | `after_due` | `after_issue` | `after_payment`).
        triggerDays:
          type: integer
          minimum: 0
          description: Days relative to the trigger (0 = same day).
        actionType:
          type: string
          enum:
            - notification
            - negativation
            - protest
            - manual_task
            - negotiation_offer
            - judicial
          description: Action (`notification` | `negativation` | `protest` | `manual_task` | `negotiation_offer` | `judicial`).
        channels:
          type: array
          items:
            type: string
            enum:
              - email
              - sms
              - whatsapp
              - voice
              - manual
          description: Delivery channels (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        messageTemplateId:
          type:
            - string
            - "null"
          format: uuid
          description: Message template used by the step (must belong to the organization).
        tone:
          type:
            - string
            - "null"
          enum:
            - friendly
            - neutral
            - firm
            - urgent
            - null
          description: Message tone (`friendly` | `neutral` | `firm` | `urgent`).
        preferredTime:
          type:
            - string
            - "null"
          description: Preferred send time (e.g. `09:00`).
      required:
        - name
        - position
        - triggerType
        - triggerDays
        - actionType
      description: "Step in the rule PUT: with `id` it updates the existing one; without `id` it creates; steps missing from the array are soft-deleted."
    CollectionRuleCreateRequest:
      type: object
      properties:
        classificationId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer classification served by the rule (segmentation).
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Rule name.
        description:
          type:
            - string
            - "null"
          maxLength: 1000
          description: Rule description.
        isDefault:
          type: boolean
          description: true when this is the organization’s default rule (only one).
        priority:
          type: integer
          minimum: 0
          description: Priority when selecting a rule (higher wins).
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        steps:
          type: array
          items:
            $ref: "#/components/schemas/CollectionRuleStepInput"
          description: Rule steps ordered by `position` (present with `include=steps` and in create/update responses).
      required:
        - name
      description: Payload to create a collection rule, optionally with inline steps.
    CollectionRuleUpdateRequest:
      type: object
      properties:
        classificationId:
          type:
            - string
            - "null"
          format: uuid
          description: Customer classification served by the rule (segmentation).
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Rule name.
        description:
          type:
            - string
            - "null"
          maxLength: 1000
          description: Rule description.
        isDefault:
          type: boolean
          description: true when this is the organization’s default rule (only one).
        priority:
          type: integer
          minimum: 0
          description: Priority when selecting a rule (higher wins).
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        steps:
          type: array
          items:
            $ref: "#/components/schemas/CollectionRuleStepUpsert"
          description: "Full step set (upsert): with `id` updates, without `id` creates, missing ones are removed."
      description: Fields to update (partial). If `steps` is sent, the array replaces the step set (upsert).
    CollectionRuleStepCreateRequest:
      allOf:
        - $ref: "#/components/schemas/CollectionRuleStepInput"
        - type: object
          properties:
            triggerType:
              type: string
              enum:
                - before_due
                - on_due
                - after_due
              description: Trigger (`before_due` | `on_due` | `after_due`). The `after_issue`/`after_payment` triggers can only be set via the rule.
      description: Payload to create a step. This endpoint only accepts due-date triggers (`before_due` | `on_due` | `after_due`).
    CollectionRuleStepUpdateRequest:
      type: object
      properties:
        messageTemplateId:
          type:
            - string
            - "null"
          format: uuid
          description: Message template used by the step (must belong to the organization).
        position:
          type: integer
          exclusiveMinimum: 0
          description: Step position in the rule (starts at 1).
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Step name.
        triggerType:
          type: string
          enum:
            - before_due
            - on_due
            - after_due
          description: Trigger (`before_due` | `on_due` | `after_due`). The `after_issue`/`after_payment` triggers can only be set via the rule.
        triggerDays:
          type: integer
          minimum: 0
          description: Days relative to the trigger (0 = same day).
        actionType:
          type: string
          enum:
            - notification
            - negativation
            - protest
            - manual_task
            - negotiation_offer
            - judicial
          description: Action (`notification` | `negativation` | `protest` | `manual_task` | `negotiation_offer` | `judicial`).
        channels:
          type: array
          items:
            type: string
            enum:
              - email
              - sms
              - whatsapp
              - voice
              - manual
          minItems: 1
          description: Delivery channels (`email` | `sms` | `whatsapp` | `voice` | `manual`).
        tone:
          type:
            - string
            - "null"
          enum:
            - friendly
            - neutral
            - firm
            - urgent
            - null
          description: Message tone (`friendly` | `neutral` | `firm` | `urgent`).
        preferredTime:
          type:
            - string
            - "null"
          maxLength: 10
          description: Preferred send time (e.g. `09:00`).
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = inactive).
        externalId:
          type:
            - string
            - "null"
          maxLength: 60
          description: Identifier in YOUR system (integration key).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      description: Step fields to update (partial — send only what changes).
    CollectionRuleListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/CollectionRule"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    CollectionRuleShowResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/CollectionRule"
      required:
        - data
    CollectionRuleStepListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/CollectionRuleStep"
      required:
        - data
    NegotiationCampaign:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        name:
          type: string
          description: Campaign name.
          example: 30% à vista · 30-60 dias
        discountPercentage:
          type:
            - string
            - "null"
          description: Discount percentage (0-100). Returned as a decimal string.
          example: "30"
        maxInstallments:
          type:
            - integer
            - "null"
          description: Maximum number of installments allowed (1 = single payment).
          example: 1
        minDaysOverdue:
          type:
            - integer
            - "null"
          description: Start of the overdue-days range where the campaign applies (null = no minimum).
          example: 30
        maxDaysOverdue:
          type:
            - integer
            - "null"
          description: End of the overdue-days range where the campaign applies (null = no maximum).
          example: 60
        validUntil:
          type:
            - string
            - "null"
          format: date-time
          description: Campaign expiration date (null = no deadline).
        terms:
          type:
            - string
            - "null"
          description: Terms shown to the debtor.
        activatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Activation timestamp (null = campaign ended).
      required:
        - id
        - publicId
        - name
        - discountPercentage
        - maxInstallments
        - minDaysOverdue
        - maxDaysOverdue
        - validUntil
        - terms
        - activatedAt
      description: "Negotiation campaign: reusable discount offer, valid organization-wide and segmented by overdue-days range. The debtor portal automatically offers the applicable active campaign."
    NegotiationCampaignDetail:
      allOf:
        - $ref: "#/components/schemas/NegotiationCampaign"
        - type: object
          properties:
            organizationId:
              type: string
              format: uuid
              description: Organization that owns the record.
            workspaceId:
              type:
                - string
                - "null"
              format: uuid
              description: Record workspace (multi-tenant hierarchy).
            companyId:
              type:
                - string
                - "null"
              format: uuid
              description: Associated company (creditor).
            businessUnitId:
              type:
                - string
                - "null"
              format: uuid
              description: Record business unit.
            chargeId:
              type:
                - string
                - "null"
              format: uuid
              description: Linked charge. Always null for campaigns (the offer is org-wide).
            offerType:
              type: string
              enum:
                - discount
                - installment
                - extension
              description: Offer type (`discount` | `installment` | `extension`). Campaigns created via API use `discount`.
            minimumEntryPercentage:
              type:
                - string
                - "null"
              description: Minimum down-payment percentage (decimal string; null when not applicable).
            externalId:
              type:
                - string
                - "null"
              description: Identifier in YOUR system (integration key).
            customData:
              type:
                - object
                - "null"
              additionalProperties: {}
              description: API-consumer custom metadata.
            tags:
              type: array
              items:
                type: string
              description: Free-form tags.
            metadata:
              type: object
              additionalProperties: {}
              description: System-written metadata.
            createdAt:
              type: string
              format: date-time
              description: Created at (ISO 8601).
            updatedAt:
              type: string
              format: date-time
              description: Updated at (ISO 8601).
            deletedAt:
              type:
                - string
                - "null"
              format: date-time
              description: Deleted at (soft delete; null while active).
          required:
            - organizationId
            - workspaceId
            - companyId
            - businessUnitId
            - chargeId
            - offerType
            - minimumEntryPercentage
            - externalId
            - customData
            - tags
            - metadata
            - createdAt
            - updatedAt
            - deletedAt
      description: Full campaign record returned on creation (entire negotiation offer model).
    NegotiationCampaignCreateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 120
          description: Campaign name.
        discountPercentage:
          type: number
          minimum: 0
          maximum: 100
          description: Discount percentage (0-100). Returned as a decimal string.
          example: 30
        maxInstallments:
          type: integer
          minimum: 1
          maximum: 36
          description: Maximum number of installments allowed (1 = single payment).
          example: 1
        minDaysOverdue:
          type:
            - integer
            - "null"
          minimum: 0
          description: Start of the overdue-days range where the campaign applies (null = no minimum).
        maxDaysOverdue:
          type:
            - integer
            - "null"
          minimum: 0
          description: End of the overdue-days range where the campaign applies (null = no maximum).
        validUntil:
          type:
            - string
            - "null"
          format: date
          description: Campaign expiration date (null = no deadline).
          example: 2026-12-31
        terms:
          type:
            - string
            - "null"
          maxLength: 500
          description: Terms shown to the debtor.
      required:
        - name
        - discountPercentage
      description: Payload to create the campaign. It starts active; `minDaysOverdue` cannot exceed `maxDaysOverdue`.
    NegotiationCampaignListResponse:
      type: object
      properties:
        campaigns:
          type: array
          items:
            $ref: "#/components/schemas/NegotiationCampaign"
      required:
        - campaigns
    NegotiationCampaignCreateResponse:
      type: object
      properties:
        campaign:
          $ref: "#/components/schemas/NegotiationCampaignDetail"
      required:
        - campaign
    NegativationPersonSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          description: Customer name.
        documentNumber:
          type:
            - string
            - "null"
          description: Customer CPF/CNPJ (digits only).
        documentType:
          type:
            - string
            - "null"
          enum:
            - cpf
            - cnpj
            - null
          description: Document type (`cpf` | `cnpj`).
      required:
        - id
        - name
        - documentNumber
        - documentType
      description: Customer summary (present with `include=person` and in create/show responses).
    NegativationChargeSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        documentNumber:
          type:
            - string
            - "null"
          description: Charge document number.
        description:
          type:
            - string
            - "null"
          description: Charge description.
        originalAmount:
          type: string
          description: Original charge amount (decimal as string).
          example: "150.00"
        currentAmount:
          type:
            - string
            - "null"
          description: Current charge amount (decimal as string).
          example: "175.50"
        dueDate:
          type: string
          format: date-time
          description: Charge due date (ISO 8601).
        status:
          type: string
          description: Charge status.
          example: overdue
      required:
        - id
        - documentNumber
        - description
        - originalAmount
        - currentAmount
        - dueDate
        - status
      description: Charge summary (present with `include=charge` and in create/show responses).
    Negativation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Company (creditor) of the record.
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Business unit (BU) of the record.
        chargeId:
          type: string
          format: uuid
          description: Reported charge (UUID).
        personId:
          type: string
          format: uuid
          description: Reported customer (UUID).
        bureau:
          type: string
          enum:
            - serasa
            - spc
            - boa_vista
          description: Credit bureau (`serasa` | `spc` | `boa_vista`).
        status:
          type: string
          enum:
            - pending
            - active
            - removed
            - failed
          description: Status (`pending` = awaiting mandatory human review, `active` = live at the bureau, `removed` = withdrawn, `failed` = failed).
        amount:
          type: string
          description: Reported amount (decimal serialized as string).
          example: "150.00"
        registeredAt:
          type:
            - string
            - "null"
          format: date-time
          description: Date the report went live at the bureau (ISO 8601).
        removedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Date the report was removed from the bureau (ISO 8601).
        removalReason:
          type:
            - string
            - "null"
          description: Reason for removing the report.
        responseData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Raw bureau response (integration payload).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system or the bureau protocol number.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        person:
          $ref: "#/components/schemas/NegativationPersonSummary"
        charge:
          $ref: "#/components/schemas/NegativationChargeSummary"
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - chargeId
        - personId
        - bureau
        - status
        - amount
        - registeredAt
        - removedAt
        - removalReason
        - responseData
        - externalId
        - customData
        - tags
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: "Credit-bureau report record for a charge (Serasa, SPC or Boa Vista). Legal workflow: every record starts as `pending` and requires mandatory human review before being submitted to the bureau (`negativation.review_required` event)."
    NegativationCreateRequest:
      type: object
      properties:
        personId:
          type: string
          format: uuid
          description: Reported customer (UUID).
        chargeId:
          type: string
          format: uuid
          description: Reported charge (UUID).
        bureau:
          type: string
          enum:
            - serasa
            - spc
            - boa_vista
          description: Credit bureau (`serasa` | `spc` | `boa_vista`).
        amount:
          type: number
          exclusiveMinimum: 0
          description: Amount to report (positive decimal number).
          example: 150
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system or the bureau protocol number.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      required:
        - personId
        - chargeId
        - bureau
        - amount
      description: Payload to create a bureau report. The charge must belong to the given customer.
    NegativationUpdateRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - active
            - removed
            - failed
          description: Status (`pending` = awaiting mandatory human review, `active` = live at the bureau, `removed` = withdrawn, `failed` = failed).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system or the bureau protocol number.
        registeredAt:
          type:
            - string
            - "null"
          format: date-time
          description: Date the report went live at the bureau (ISO 8601).
        removedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Date the report was removed from the bureau (ISO 8601).
        removalReason:
          type:
            - string
            - "null"
          description: Reason for removing the report.
        responseData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Raw bureau response (integration payload).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      description: Fields to update (partial). Used by human review to approve the record and by integrations to store the bureau response.
    NegativationRemoveRequest:
      type: object
      properties:
        removalReason:
          type: string
          description: Reason for removing the report.
      description: Optional body with the reason for removing the report.
    NegativationListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Negativation"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    ProtestPersonSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type: string
          description: Customer name.
        documentNumber:
          type:
            - string
            - "null"
          description: Customer CPF/CNPJ (digits only).
        documentType:
          type:
            - string
            - "null"
          enum:
            - cpf
            - cnpj
            - null
          description: Document type (`cpf` | `cnpj`).
      required:
        - id
        - name
        - documentNumber
        - documentType
      description: Customer summary (present with `include=person` and in create/show responses).
    ProtestChargeSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        documentNumber:
          type:
            - string
            - "null"
          description: Charge document number.
        description:
          type:
            - string
            - "null"
          description: Charge description.
        originalAmount:
          type: string
          description: Original charge amount (decimal as string).
          example: "150.00"
        currentAmount:
          type:
            - string
            - "null"
          description: Current charge amount (decimal as string).
          example: "175.50"
        dueDate:
          type: string
          format: date-time
          description: Charge due date (ISO 8601).
        status:
          type: string
          description: Charge status.
          example: overdue
      required:
        - id
        - documentNumber
        - description
        - originalAmount
        - currentAmount
        - dueDate
        - status
      description: Charge summary (present with `include=charge` and in create/show responses).
    Protest:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the record.
        workspaceId:
          type:
            - string
            - "null"
          format: uuid
          description: Record workspace (multi-tenant hierarchy).
        companyId:
          type:
            - string
            - "null"
          format: uuid
          description: Company (creditor) of the record.
        businessUnitId:
          type:
            - string
            - "null"
          format: uuid
          description: Business unit (BU) of the record.
        chargeId:
          type: string
          format: uuid
          description: Protested charge (UUID).
        personId:
          type: string
          format: uuid
          description: Protested customer (UUID).
        notary:
          type:
            - string
            - "null"
          description: Notary office name.
        notaryCode:
          type:
            - string
            - "null"
          description: Notary office code/identifier.
        status:
          type: string
          enum:
            - pending
            - sent
            - intimated
            - protested
            - paid
            - cancelled
          description: Status (`pending` = awaiting mandatory human review, `sent` = sent to the notary, `intimated` = debtor notified, `protested` = protested, `paid` = paid, `cancelled` = cancelled).
        amount:
          type: string
          description: Protested amount (decimal serialized as string).
          example: "150.00"
        fees:
          type:
            - string
            - "null"
          description: Notary fees/costs (decimal as string).
          example: "12.50"
        sentAt:
          type:
            - string
            - "null"
          format: date-time
          description: Date sent to the notary (ISO 8601).
        intimationDate:
          type:
            - string
            - "null"
          format: date-time
          description: Debtor notification date (ISO 8601).
        protestDate:
          type:
            - string
            - "null"
          format: date-time
          description: Protest registration date (ISO 8601).
        paymentDate:
          type:
            - string
            - "null"
          format: date-time
          description: Payment date at the notary (ISO 8601).
        cancellationDate:
          type:
            - string
            - "null"
          format: date-time
          description: Protest cancellation date (ISO 8601).
        responseData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Raw notary response (integration payload).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system or the notary protocol number.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        person:
          $ref: "#/components/schemas/ProtestPersonSummary"
        charge:
          $ref: "#/components/schemas/ProtestChargeSummary"
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
      required:
        - id
        - publicId
        - organizationId
        - workspaceId
        - companyId
        - businessUnitId
        - chargeId
        - personId
        - notary
        - notaryCode
        - status
        - amount
        - fees
        - sentAt
        - intimationDate
        - protestDate
        - paymentDate
        - cancellationDate
        - responseData
        - externalId
        - customData
        - tags
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: "Notary protest record for a charge. Legal workflow: every record starts as `pending` and requires mandatory human review before being sent to the notary (`protest.review_required` event)."
    ProtestCreateRequest:
      type: object
      properties:
        personId:
          type: string
          format: uuid
          description: Protested customer (UUID).
        chargeId:
          type: string
          format: uuid
          description: Protested charge (UUID).
        amount:
          type: number
          exclusiveMinimum: 0
          description: Amount to protest (positive decimal number).
          example: 150
        notary:
          type:
            - string
            - "null"
          description: Notary office name.
        notaryCode:
          type:
            - string
            - "null"
          description: Notary office code/identifier.
        fees:
          type:
            - number
            - "null"
          description: Notary fees/costs (decimal number).
          example: 12.5
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system or the notary protocol number.
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      required:
        - personId
        - chargeId
        - amount
      description: Payload to create a protest. The charge must belong to the given customer.
    ProtestUpdateRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - sent
            - intimated
            - protested
            - paid
            - cancelled
          description: Status (`pending` = awaiting mandatory human review, `sent` = sent to the notary, `intimated` = debtor notified, `protested` = protested, `paid` = paid, `cancelled` = cancelled).
        notary:
          type:
            - string
            - "null"
          description: Notary office name.
        notaryCode:
          type:
            - string
            - "null"
          description: Notary office code/identifier.
        fees:
          type:
            - number
            - "null"
          description: Notary fees/costs (decimal number).
        externalId:
          type:
            - string
            - "null"
          description: Identifier in YOUR system or the notary protocol number.
        sentAt:
          type:
            - string
            - "null"
          format: date-time
          description: Date sent to the notary (ISO 8601).
        intimationDate:
          type:
            - string
            - "null"
          format: date-time
          description: Debtor notification date (ISO 8601).
        protestDate:
          type:
            - string
            - "null"
          format: date-time
          description: Protest registration date (ISO 8601).
        paymentDate:
          type:
            - string
            - "null"
          format: date-time
          description: Payment date at the notary (ISO 8601).
        cancellationDate:
          type:
            - string
            - "null"
          format: date-time
          description: Protest cancellation date (ISO 8601).
        responseData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Raw notary response (integration payload).
        customData:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: API-consumer custom metadata.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags.
      description: Fields to update (partial). Used by human review to approve/advance the record and by integrations to store notary dates and responses.
    ProtestCancelRequest:
      type: object
      properties:
        cancellationReason:
          type: string
          description: Cancellation reason.
      description: Optional body with the cancellation reason (stored in `responseData.cancellationReason`).
    ProtestListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Protest"
        meta:
          $ref: "#/components/schemas/PaginationMeta"
      required:
        - data
        - meta
    ImportRowError:
      type: object
      properties:
        line:
          type: integer
          description: Line number in the file (line 1 is the header; data starts at 2).
          example: 2
        error:
          type: string
          description: Reason the row was rejected.
          example: Nome obrigatório
      required:
        - line
        - error
      description: Error for a rejected file row.
    ImportSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        resourceType:
          type: string
          enum:
            - people
            - charges
          description: Imported resource type (`people` = customers | `charges` = charges).
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Processing status (`pending` | `processing` | `completed` | `failed`).
        fileName:
          type:
            - string
            - "null"
          description: Uploaded file name.
        totalRows:
          type:
            - integer
            - "null"
          description: Total data rows in the file (null until processing starts).
        processedRows:
          type: integer
          description: Rows processed so far.
        createdCount:
          type: integer
          description: Records created.
        updatedCount:
          type: integer
          description: Records updated (deduplicated by `external_id`/document).
        errorCount:
          type: integer
          description: Rejected rows.
        errorMessage:
          type:
            - string
            - "null"
          description: Error message when the whole batch fails.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        completedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Processing completion time (ISO 8601).
      required:
        - id
        - publicId
        - resourceType
        - status
        - fileName
        - totalRows
        - processedRows
        - createdCount
        - updatedCount
        - errorCount
        - errorMessage
        - createdAt
        - completedAt
      description: Import summary (the listing omits the file content and per-row errors).
    Import:
      allOf:
        - $ref: "#/components/schemas/ImportSummary"
        - type: object
          properties:
            errors:
              type: array
              items:
                $ref: "#/components/schemas/ImportRowError"
              description: Per-row rejection errors (`[{ line, error }]`).
            startedAt:
              type:
                - string
                - "null"
              format: date-time
              description: Processing start time (ISO 8601).
          required:
            - errors
            - startedAt
      description: CSV file import (customers or charges), including per-row rejection errors.
    ImportCreateRequest:
      type: object
      properties:
        resourceType:
          type: string
          enum:
            - people
            - charges
          description: Imported resource type (`people` = customers | `charges` = charges).
        fileName:
          type: string
          maxLength: 200
          description: Uploaded file name.
          example: clientes.csv
        content:
          type: string
          minLength: 10
          description: Raw CSV content as plain text (UTF-8), including the header row. Max 2 MB.
          example: |-
            nome,documento,email
            Maria da Silva,12345678901,maria@example.com
      required:
        - resourceType
        - content
      description: "JSON upload: the CSV content goes as PLAIN TEXT in the `content` field (not multipart, not base64). 2 MB limit (~10-20k rows); larger payloads get a 413."
    ImportCreated:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        resourceType:
          type: string
          enum:
            - people
            - charges
          description: Imported resource type (`people` = customers | `charges` = charges).
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Processing status (`pending` | `processing` | `completed` | `failed`).
        fileName:
          type:
            - string
            - "null"
          description: Uploaded file name.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
      required:
        - id
        - publicId
        - resourceType
        - status
        - fileName
        - createdAt
      description: Newly created import (queued for processing).
    ImportListResponse:
      type: object
      properties:
        imports:
          type: array
          items:
            $ref: "#/components/schemas/ImportSummary"
      required:
        - imports
      description: "`{ imports }` envelope with the most recent imports."
    ImportShowResponse:
      type: object
      properties:
        import:
          $ref: "#/components/schemas/Import"
      required:
        - import
      description: "`{ import }` envelope with the import detail."
    ImportCreatedResponse:
      type: object
      properties:
        import:
          $ref: "#/components/schemas/ImportCreated"
      required:
        - import
      description: "`{ import }` envelope with the newly created job."
    ExportJobFilters:
      type: object
      properties:
        status:
          type: string
          maxLength: 40
          description: Filter charges by status.
          example: overdue
        from:
          type: string
          format: date
          description: Due date from (ISO date `YYYY-MM-DD`).
          example: 2026-01-01
        to:
          type: string
          format: date
          description: Due date until (ISO date `YYYY-MM-DD`).
          example: 2026-06-30
      description: Filters applied to the export (only for `charges`); stored on the job for auditing.
    ExportJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        resourceType:
          type: string
          enum:
            - people
            - charges
          description: Exported resource type (`people` = customers | `charges` = charges).
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Processing status (`pending` | `processing` | `completed` | `failed`).
        fileName:
          type:
            - string
            - "null"
          description: "Generated file name (default: `{resourceType}.csv`)."
        rowCount:
          type:
            - integer
            - "null"
          description: Total rows in the generated CSV (null until finished).
        truncated:
          type: boolean
          description: true when the CSV hit the safety cap and came out partial.
        errorMessage:
          type:
            - string
            - "null"
          description: Error message when generation fails.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        completedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Generation completion time (ISO 8601).
        expiresAt:
          type:
            - string
            - "null"
          format: date-time
          description: Download expiry (ISO 8601); afterwards the content is purged and the download route responds 410.
      required:
        - id
        - publicId
        - resourceType
        - status
        - fileName
        - rowCount
        - truncated
        - errorMessage
        - createdAt
        - completedAt
        - expiresAt
      description: Asynchronous CSV export job (without the 10k-row cap of the synchronous mode). The finished CSV is served by GET /exports/jobs/{id}/download until it expires.
    ExportJobCreateRequest:
      type: object
      properties:
        resourceType:
          type: string
          enum:
            - people
            - charges
          description: Exported resource type (`people` = customers | `charges` = charges).
        fileName:
          type: string
          maxLength: 200
          description: "Generated file name (default: `{resourceType}.csv`)."
          example: cobrancas-junho.csv
        filters:
          $ref: "#/components/schemas/ExportJobFilters"
      required:
        - resourceType
      description: Payload to schedule an asynchronous export. `filters` only applies to `charges`.
    ExportJobCreated:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier (shown in the UI).
        resourceType:
          type: string
          enum:
            - people
            - charges
          description: Exported resource type (`people` = customers | `charges` = charges).
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Processing status (`pending` | `processing` | `completed` | `failed`).
        fileName:
          type:
            - string
            - "null"
          description: "Generated file name (default: `{resourceType}.csv`)."
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
      required:
        - id
        - publicId
        - resourceType
        - status
        - fileName
        - createdAt
      description: Newly scheduled export (queued for processing).
    ExportJobListResponse:
      type: object
      properties:
        exports:
          type: array
          items:
            $ref: "#/components/schemas/ExportJob"
      required:
        - exports
      description: "`{ exports }` envelope with the most recent exports."
    ExportJobCreatedResponse:
      type: object
      properties:
        export:
          $ref: "#/components/schemas/ExportJobCreated"
      required:
        - export
      description: "`{ export }` envelope with the newly created job."
    WebhookEventType:
      type: string
      enum:
        - person.created
        - person.updated
        - person.deleted
        - person.classification_changed
        - charge.created
        - charge.updated
        - charge.deleted
        - charge.paid
        - charge.overdue
        - agreement.created
        - agreement.updated
        - agreement.deleted
        - agreement.accepted
        - agreement.cancelled
        - agreement.broken
        - agreement.completed
        - dispute.created
        - dispute.updated
        - dispute.resolved
        - dispute.cancelled
        - task.created
        - task.updated
        - task.completed
        - task.deleted
        - collection_rule.created
        - collection_rule.updated
        - collection_rule.deleted
        - template.created
        - template.updated
        - template.deleted
        - classification.created
        - classification.updated
        - classification.deleted
        - interaction.created
        - notification.sent
        - notification.delivered
        - notification.read
        - notification.failed
        - negativation.review_required
        - negativation.registered
        - negativation.removed
        - protest.review_required
        - protest.registered
        - protest.paid
        - protest.cancelled
      description: Subscribable event type from the catalog (e.g. `charge.paid`).
      example: charge.paid
    WebhookDeliveryEventType:
      type: string
      enum:
        - person.created
        - person.updated
        - person.deleted
        - person.classification_changed
        - charge.created
        - charge.updated
        - charge.deleted
        - charge.paid
        - charge.overdue
        - agreement.created
        - agreement.updated
        - agreement.deleted
        - agreement.accepted
        - agreement.cancelled
        - agreement.broken
        - agreement.completed
        - dispute.created
        - dispute.updated
        - dispute.resolved
        - dispute.cancelled
        - task.created
        - task.updated
        - task.completed
        - task.deleted
        - collection_rule.created
        - collection_rule.updated
        - collection_rule.deleted
        - template.created
        - template.updated
        - template.deleted
        - classification.created
        - classification.updated
        - classification.deleted
        - interaction.created
        - notification.sent
        - notification.delivered
        - notification.read
        - notification.failed
        - negativation.review_required
        - negativation.registered
        - negativation.removed
        - protest.review_required
        - protest.registered
        - protest.paid
        - protest.cancelled
        - webhook.test
      description: "Event type of a delivery: subscribable catalog + `webhook.test` (triggered on demand via `POST /webhook-endpoints/{id}/test`)."
      example: charge.paid
    WebhookDeliveryStats:
      type: object
      properties:
        total:
          type: integer
          description: Total deliveries.
        pending:
          type: integer
          description: Deliveries awaiting processing.
        success:
          type: integer
          description: Confirmed deliveries (2xx).
        failed:
          type: integer
          description: Failed deliveries (retry scheduled).
        exhausted:
          type: integer
          description: Deliveries with exhausted attempts (dead letter).
      required:
        - total
      description: Endpoint delivery counters, by status.
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier.
        url:
          type: string
          format: uri
          description: HTTPS destination URL for deliveries (validated against internal addresses — SSRF).
          example: https://example.com/webhooks/kobana
        description:
          type:
            - string
            - "null"
          description: Free-form endpoint description.
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
          description: Subscribed event types. Empty list = all events.
        isActive:
          type: boolean
          description: Active endpoints receive deliveries; inactive ones are skipped by the worker.
        authType:
          type: string
          enum:
            - none
            - basic
            - bearer
            - header
          description: Request authentication against your endpoint (`none` | `basic` | `bearer` | `header`), in addition to the HMAC signature (always sent).
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        deliveries:
          $ref: "#/components/schemas/WebhookDeliveryStats"
      required:
        - id
        - publicId
        - url
        - description
        - events
        - isActive
        - authType
        - createdAt
        - deliveries
      description: 'Webhook endpoint: receives the organization’s events via HTTP POST (JSON). Every delivery sends the headers `X-Webhook-Event` (event type), `X-Webhook-Event-Id`, `X-Webhook-Delivery-Id`, `X-Webhook-Attempt`, `X-Webhook-Timestamp` (ISO 8601) and `X-Webhook-Signature` formatted as `t=<unix>,v1=<hex>` — HMAC-SHA256 of `"{t}.{body}"` with the endpoint secret; verify the signature and reject `t` outside a 5-minute window (anti-replay) before processing. Besides the signature (always sent), the request can authenticate against your endpoint per `authType`: `none`, `basic` (username/password), `bearer` (token) or `header` (custom header); credentials live in `authConfig`, encrypted at rest and never returned. Empty `events` = subscribed to all events. Failed deliveries are retried with exponential backoff and every attempt is recorded.'
    WebhookDeliverySummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        status:
          type: string
          enum:
            - pending
            - success
            - failed
            - exhausted
          description: "Delivery status: `pending` | `success` | `failed` (retry scheduled) | `exhausted` (attempts exhausted)."
        attempts:
          type: integer
          description: Number of attempts made so far.
        responseStatus:
          type:
            - integer
            - "null"
          description: HTTP status returned by the destination (null when no response).
          example: 200
        error:
          type:
            - string
            - "null"
          description: Last error message (null on success).
        eventType:
          $ref: "#/components/schemas/WebhookDeliveryEventType"
        eventAt:
          type: string
          format: date-time
          description: When the event occurred (ISO 8601).
        deliveredAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the delivery was confirmed (2xx); null if not yet delivered.
        lastAttemptAt:
          type:
            - string
            - "null"
          format: date-time
          description: Last attempt (ISO 8601).
      required:
        - id
        - status
        - attempts
        - responseStatus
        - error
        - eventType
        - eventAt
        - deliveredAt
        - lastAttemptAt
      description: Summary of a recent endpoint delivery.
    WebhookEndpointDetail:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier.
        url:
          type: string
          format: uri
          description: HTTPS destination URL for deliveries (validated against internal addresses — SSRF).
          example: https://example.com/webhooks/kobana
        description:
          type:
            - string
            - "null"
          description: Free-form endpoint description.
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
          description: Subscribed event types. Empty list = all events.
        isActive:
          type: boolean
          description: Active endpoints receive deliveries; inactive ones are skipped by the worker.
        authType:
          type: string
          enum:
            - none
            - basic
            - bearer
            - header
          description: Request authentication against your endpoint (`none` | `basic` | `bearer` | `header`), in addition to the HMAC signature (always sent).
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        deliveries:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDeliverySummary"
          description: The endpoint’s latest 20 deliveries.
      required:
        - id
        - publicId
        - url
        - description
        - events
        - isActive
        - authType
        - createdAt
        - deliveries
      description: 'Webhook endpoint: receives the organization’s events via HTTP POST (JSON). Every delivery sends the headers `X-Webhook-Event` (event type), `X-Webhook-Event-Id`, `X-Webhook-Delivery-Id`, `X-Webhook-Attempt`, `X-Webhook-Timestamp` (ISO 8601) and `X-Webhook-Signature` formatted as `t=<unix>,v1=<hex>` — HMAC-SHA256 of `"{t}.{body}"` with the endpoint secret; verify the signature and reject `t` outside a 5-minute window (anti-replay) before processing. Besides the signature (always sent), the request can authenticate against your endpoint per `authType`: `none`, `basic` (username/password), `bearer` (token) or `header` (custom header); credentials live in `authConfig`, encrypted at rest and never returned. Empty `events` = subscribed to all events. Failed deliveries are retried with exponential backoff and every attempt is recorded.'
    WebhookDelivery:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        eventId:
          type: string
          format: uuid
          description: Delivered event (UUID).
        eventType:
          $ref: "#/components/schemas/WebhookDeliveryEventType"
        status:
          type: string
          enum:
            - pending
            - success
            - failed
            - exhausted
          description: "Delivery status: `pending` | `success` | `failed` (retry scheduled) | `exhausted` (attempts exhausted)."
        responseStatus:
          type:
            - integer
            - "null"
          description: HTTP status returned by the destination (null when no response).
          example: 200
        attempts:
          type: integer
          description: Number of attempts made so far.
        error:
          type:
            - string
            - "null"
          description: Last error message (null on success).
        requestHeaders:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Headers sent (signature and credentials redacted).
        requestBody:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: JSON body sent to the destination.
        responseHeaders:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Response headers (sensitive headers redacted).
        responseBody:
          type:
            - string
            - "null"
          description: Response body (text).
        deliveredAt:
          type:
            - string
            - "null"
          format: date-time
          description: When the delivery was confirmed (2xx); null if not yet delivered.
        lastAttemptAt:
          type:
            - string
            - "null"
          format: date-time
          description: Last attempt (ISO 8601).
        nextRetryAt:
          type:
            - string
            - "null"
          format: date-time
          description: Next scheduled retry (null when none).
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
      required:
        - id
        - eventId
        - eventType
        - status
        - responseStatus
        - attempts
        - error
        - requestHeaders
        - requestBody
        - responseHeaders
        - responseBody
        - deliveredAt
        - lastAttemptAt
        - nextRetryAt
        - createdAt
      description: "Webhook delivery: an attempt to send an event to an endpoint, with request/response capture for inspection. Signature and credential headers are redacted before persisting."
    WebhookEndpointCreateRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: HTTPS destination URL for deliveries (validated against internal addresses — SSRF).
          example: https://example.com/webhooks/kobana
        description:
          type:
            - string
            - "null"
          maxLength: 300
          description: Free-form endpoint description.
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
          description: Subscribed event types. Empty list = all events.
          example:
            - charge.paid
            - charge.overdue
        authType:
          type: string
          enum:
            - none
            - basic
            - bearer
            - header
          description: Request authentication against your endpoint (`none` | `basic` | `bearer` | `header`), in addition to the HMAC signature (always sent).
        authConfig:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: 'Credentials for `authType`: `basic` → `{"username","password"}`; `bearer` → `{"token"}`; `header` → `{"key","value"}`. Encrypted at rest; never returned on reads.'
          example:
            token: meu-token-secreto
      required:
        - url
      description: Payload to create a webhook endpoint.
    WebhookEndpointUpdateRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: HTTPS destination URL for deliveries (validated against internal addresses — SSRF).
        description:
          type:
            - string
            - "null"
          maxLength: 300
          description: Free-form endpoint description.
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
          description: Subscribed event types. Empty list = all events.
        isActive:
          type: boolean
          description: Active endpoints receive deliveries; inactive ones are skipped by the worker.
        authType:
          type: string
          enum:
            - none
            - basic
            - bearer
            - header
          description: Request authentication against your endpoint (`none` | `basic` | `bearer` | `header`), in addition to the HMAC signature (always sent).
        authConfig:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: 'Credentials for `authType`: `basic` → `{"username","password"}`; `bearer` → `{"token"}`; `header` → `{"key","value"}`. Encrypted at rest; never returned on reads.'
          example:
            token: meu-token-secreto
      description: Fields to update (partial — send only what changes).
    WebhookEndpointCreateResponse:
      type: object
      properties:
        endpoint:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Resource identifier (UUID).
            publicId:
              type: string
              description: Stable public identifier.
            url:
              type: string
              format: uri
              description: HTTPS destination URL for deliveries (validated against internal addresses — SSRF).
            description:
              type:
                - string
                - "null"
              description: Free-form endpoint description.
            events:
              type: array
              items:
                $ref: "#/components/schemas/WebhookEventType"
              description: Subscribed event types. Empty list = all events.
            isActive:
              type: boolean
              description: Active endpoints receive deliveries; inactive ones are skipped by the worker.
            secret:
              type: string
              description: HMAC secret (`whsec_…`) used in the `X-Webhook-Signature` signature. Shown only on creation and rotation — store it safely.
              example: whsec_6f2a…
          required:
            - id
            - publicId
            - url
            - description
            - events
            - isActive
            - secret
      required:
        - endpoint
    WebhookEndpointListResponse:
      type: object
      properties:
        endpoints:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEndpoint"
      required:
        - endpoints
    WebhookEndpointShowResponse:
      type: object
      properties:
        endpoint:
          $ref: "#/components/schemas/WebhookEndpointDetail"
      required:
        - endpoint
    WebhookEndpointUpdateResponse:
      type: object
      properties:
        endpoint:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Resource identifier (UUID).
            url:
              type: string
              format: uri
              description: HTTPS destination URL for deliveries (validated against internal addresses — SSRF).
            description:
              type:
                - string
                - "null"
              description: Free-form endpoint description.
            events:
              type: array
              items:
                $ref: "#/components/schemas/WebhookEventType"
              description: Subscribed event types. Empty list = all events.
            isActive:
              type: boolean
              description: Active endpoints receive deliveries; inactive ones are skipped by the worker.
          required:
            - id
            - url
            - description
            - events
            - isActive
      required:
        - endpoint
    WebhookEndpointRotateSecretResponse:
      type: object
      properties:
        secret:
          type: string
          description: HMAC secret (`whsec_…`) used in the `X-Webhook-Signature` signature. Shown only on creation and rotation — store it safely.
          example: whsec_6f2a…
      required:
        - secret
    WebhookDeliveryListResponse:
      type: object
      properties:
        endpoint:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Resource identifier (UUID).
            url:
              type: string
              format: uri
              description: HTTPS destination URL for deliveries (validated against internal addresses — SSRF).
          required:
            - id
            - url
          description: Endpoint that owns the deliveries.
        deliveries:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDelivery"
        meta:
          type: object
          properties:
            page:
              type: integer
              description: Current page.
            perPage:
              type: integer
              description: Items per page applied.
            total:
              type: integer
              description: Total records matching the filter.
            totalPages:
              type: integer
              description: Total pages.
          required:
            - page
            - perPage
            - total
            - totalPages
          description: List pagination metadata.
      required:
        - endpoint
        - deliveries
        - meta
    WebhookDeliveryRetryResponse:
      type: object
      properties:
        deliveryId:
          type: string
          format: uuid
          description: Delivery identifier (UUID).
        status:
          type: string
          enum:
            - queued
          description: Always `queued` — the delivery was re-queued.
      required:
        - deliveryId
        - status
    WebhookEndpointTestResponse:
      type: object
      properties:
        eventId:
          type: string
          format: uuid
          description: Created `webhook.test` event (UUID).
        deliveryId:
          type: string
          format: uuid
          description: Delivery identifier (UUID).
        status:
          type: string
          enum:
            - queued
          description: Always `queued` — the delivery was queued.
      required:
        - eventId
        - deliveryId
        - status
    AuditLogActor:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        name:
          type:
            - string
            - "null"
          description: User name.
        email:
          type: string
          format: email
          description: User email.
      required:
        - id
        - name
        - email
      description: User data when `actorType` = `user` (null otherwise).
    AuditLog:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        action:
          type: string
          description: Recorded action (e.g. `webhook_endpoint.created`, `dispute.resolved`).
          example: webhook_endpoint.created
        entityType:
          type: string
          description: Affected entity type (e.g. `WebhookEndpoint`).
          example: WebhookEndpoint
        entityId:
          type:
            - string
            - "null"
          description: Affected entity ID (null when not applicable).
        actorType:
          type: string
          enum:
            - user
            - system
            - job
          description: "Who acted: `user` (human), `system` or `job`."
        actorId:
          type:
            - string
            - "null"
          description: User ID, job name or system name.
        actor:
          allOf:
            - $ref: "#/components/schemas/AuditLogActor"
            - type:
                - object
                - "null"
        before:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Partial state before the change.
        after:
          type:
            - object
            - "null"
          additionalProperties: {}
          description: Partial state after the change.
        reason:
          type:
            - string
            - "null"
          description: Provided justification, when any.
        ip:
          type:
            - string
            - "null"
          description: Request source IP.
        userAgent:
          type:
            - string
            - "null"
          description: Request User-Agent.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
      required:
        - id
        - action
        - entityType
        - entityId
        - actorType
        - actorId
        - actor
        - before
        - after
        - reason
        - ip
        - userAgent
        - createdAt
      description: "Immutable (append-only) audit trail record: who did what, on which entity, with the before/after state. Writes are system-only; the API exposes read access only."
    AuditLogListResponse:
      type: object
      properties:
        logs:
          type: array
          items:
            $ref: "#/components/schemas/AuditLog"
        pagination:
          type: object
          properties:
            page:
              type: integer
              description: Current page.
            perPage:
              type: integer
              description: Items per page applied.
            total:
              type: integer
              description: Total records matching the filter.
            totalPages:
              type: integer
              description: Total pages.
          required:
            - page
            - perPage
            - total
            - totalPages
          description: List pagination metadata.
      required:
        - logs
        - pagination
    RecoveryMetrics:
      type: object
      properties:
        period:
          type: object
          properties:
            since:
              type: string
              description: Period start (YYYY-MM-DD).
              example: 2026-01-01
            months:
              type: integer
              description: Months considered.
              example: 6
          required:
            - since
            - months
          description: Period considered.
        totals:
          type: object
          properties:
            recoveredAmount:
              type: number
              description: Total amount recovered in the period.
              example: 15230.5
            recoveredCount:
              type: integer
              description: Number of recovered charges.
              example: 42
            avgDaysOverdue:
              type:
                - integer
                - "null"
              description: Average overdue days at payment time.
              example: 12
            avgStepsToRecover:
              type:
                - number
                - "null"
              description: Average rule steps executed until payment.
              example: 2.4
            recoveryRate:
              type:
                - number
                - "null"
              description: Recovered ÷ (recovered + overdue today); null when there is no basis.
              example: 0.63
            overdueAmountNow:
              type: number
              description: Overdue portfolio amount today.
              example: 8940
          required:
            - recoveredAmount
            - recoveredCount
            - avgDaysOverdue
            - avgStepsToRecover
            - recoveryRate
            - overdueAmountNow
          description: Period totals.
        byMonth:
          type: array
          items:
            type: object
            properties:
              month:
                type: string
                description: Month (YYYY-MM).
                example: 2026-03
              amount:
                type: number
                description: Amount recovered in the month.
              count:
                type: integer
                description: Charges recovered in the month.
            required:
              - month
              - amount
              - count
          description: Monthly recovery series.
        byMethod:
          type: array
          items:
            type: object
            properties:
              method:
                type: string
                enum:
                  - rule
                  - agreement
                  - overdue_no_rule
                description: "Method: `rule` (in a collection rule) | `agreement` (was negotiated) | `overdue_no_rule` (overdue with no rule)."
              amount:
                type: number
                description: Amount recovered in the group.
              count:
                type: integer
                description: Number of charges in the group.
            required:
              - method
              - amount
              - count
          description: Attribution by recovery method.
        byChannel:
          type: array
          items:
            type: object
            properties:
              channel:
                type: string
                description: Channel (e.g. `email`, `sms`, `whatsapp`).
                example: email
              amount:
                type: number
                description: Amount recovered in the group.
              count:
                type: integer
                description: Number of charges in the group.
            required:
              - channel
              - amount
              - count
          description: Attribution by the channel of the last step sent before payment.
      required:
        - period
        - totals
        - byMonth
        - byMethod
        - byChannel
      description: "Recovery metrics: what the collection engine recovered in the period — totals, monthly series, attribution by method and channel, and the recovery rate (recovered ÷ (recovered + overdue portfolio today))."
    EmailLayoutListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier.
        name:
          type: string
          description: Layout name.
          example: Layout institucional
        htmlBody:
          type: string
          description: Full layout HTML; must contain the `{{content}}` placeholder.
        isDefault:
          type: boolean
          description: Organization default layout (only one; setting a new default unsets the previous one).
        isActive:
          type: boolean
          description: Layout available for use.
        companiesCount:
          type: integer
          description: Number of companies using this layout.
      required:
        - id
        - publicId
        - name
        - htmlBody
        - isDefault
        - isActive
        - companiesCount
      description: "Email layout: HTML that wraps the content of the messages sent by the collection rules. Must contain the `{{content}}` placeholder, replaced with the notification body at send time."
    EmailLayout:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource identifier (UUID).
        publicId:
          type: string
          description: Stable public identifier.
        organizationId:
          type: string
          format: uuid
          description: Organization that owns the layout.
        name:
          type: string
          description: Layout name.
        htmlBody:
          type: string
          description: Full layout HTML; must contain the `{{content}}` placeholder.
        isDefault:
          type: boolean
          description: Organization default layout (only one; setting a new default unsets the previous one).
        isActive:
          type: boolean
          description: Layout available for use.
        metadata:
          type: object
          additionalProperties: {}
          description: System-written metadata.
        createdAt:
          type: string
          format: date-time
          description: Created at (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Updated at (ISO 8601).
        deletedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Deleted at (soft delete; null while active).
      required:
        - id
        - publicId
        - organizationId
        - name
        - htmlBody
        - isDefault
        - isActive
        - metadata
        - createdAt
        - updatedAt
        - deletedAt
      description: "Email layout: HTML that wraps the content of the messages sent by the collection rules. Must contain the `{{content}}` placeholder, replaced with the notification body at send time."
    EmailLayoutCreateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 80
          description: Layout name.
          example: Layout institucional
        htmlBody:
          type: string
          minLength: 20
          description: Full layout HTML; must contain the `{{content}}` placeholder.
          example: <html><body><header>ACME</header>{{content}}</body></html>
        isDefault:
          type: boolean
          description: Organization default layout (only one; setting a new default unsets the previous one).
      required:
        - name
        - htmlBody
      description: Payload to create an email layout.
    EmailLayoutListResponse:
      type: object
      properties:
        layouts:
          type: array
          items:
            $ref: "#/components/schemas/EmailLayoutListItem"
        builtinLayout:
          type: string
          description: Built-in reference layout (used when the organization has no default layout).
      required:
        - layouts
        - builtinLayout
    EmailLayoutCreateResponse:
      type: object
      properties:
        layout:
          $ref: "#/components/schemas/EmailLayout"
      required:
        - layout
    NotificationPreference:
      type: object
      properties:
        type:
          type: string
          enum:
            - reminder
            - overdue
            - negotiation
            - negativation_warning
            - protest_warning
            - payment_confirmation
          description: "Message type: `reminder` (pre-due reminder) | `overdue` (post-due collection) | `negotiation` (negotiation proposal) | `negativation_warning` (credit-bureau listing warning) | `protest_warning` (protest warning) | `payment_confirmation` (payment confirmation)."
          example: reminder
        label:
          type: string
          description: Human-readable type label (pt-BR).
          example: Lembrete pré-vencimento
        emailEnabled:
          type: boolean
          description: Email channel enabled for the type.
        smsEnabled:
          type: boolean
          description: SMS channel enabled for the type.
        whatsappEnabled:
          type: boolean
          description: WhatsApp channel enabled for the type.
      required:
        - type
        - label
        - emailEnabled
        - smsEnabled
        - whatsappEnabled
      description: "Notification preference: enables/disables channels (email, SMS, WhatsApp) per rule message type. Without a saved record, all channels are enabled."
    NotificationPreferenceListResponse:
      type: object
      properties:
        preferences:
          type: array
          items:
            $ref: "#/components/schemas/NotificationPreference"
      required:
        - preferences
    NotificationPreferenceUpdateRequest:
      type: object
      properties:
        preferences:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - reminder
                  - overdue
                  - negotiation
                  - negativation_warning
                  - protest_warning
                  - payment_confirmation
                description: "Message type: `reminder` (pre-due reminder) | `overdue` (post-due collection) | `negotiation` (negotiation proposal) | `negativation_warning` (credit-bureau listing warning) | `protest_warning` (protest warning) | `payment_confirmation` (payment confirmation)."
                example: reminder
              emailEnabled:
                type: boolean
                description: Email channel enabled for the type.
              smsEnabled:
                type: boolean
                description: SMS channel enabled for the type.
              whatsappEnabled:
                type: boolean
                description: WhatsApp channel enabled for the type.
            required:
              - type
              - emailEnabled
              - smsEnabled
              - whatsappEnabled
          minItems: 1
      required:
        - preferences
      description: Preferences to save (at least 1 type).
    NotificationPreferenceUpdateResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Always `true` on success.
          example: true
      required:
        - ok
  parameters: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "API key in the `Authorization: Bearer <token>` header. Create and manage keys in the dashboard (Settings → Security), with optional scopes and expiration. A key without scopes has full business access; account administration (members, roles, keys) is never available via API."
paths:
  /api/v1/people:
    get:
      tags:
        - Customers
      summary: List customers
      description: Lists the organization’s customers with pagination and filters.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            description: "Sort field. Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field. Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - schema:
            type: string
            description: Search by name, document or email.
          required: false
          description: Search by name, document or email.
          name: search
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by classification (UUID).
          required: false
          description: Filter by classification (UUID).
          name: classification_id
          in: query
        - schema:
            type: string
            enum:
              - active
              - deleted
            description: Filter by record status (`active` | `deleted`).
          required: false
          description: Filter by record status (`active` | `deleted`).
          name: status
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated customer list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-people
    post:
      tags:
        - Customers
      summary: Create customer
      description: Creates a customer in the portfolio. `externalId` and `documentNumber` drive deduplication in imports and integrations.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PersonCreateRequest"
      responses:
        "201":
          description: Customer created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-people
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/people/{id}:
    get:
      tags:
        - Customers
      summary: Get customer
      description: Returns a customer by ID.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Customer found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-people-id
    put:
      tags:
        - Customers
      summary: Update customer
      description: Updates a customer’s data (partial).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PersonUpdateRequest"
      responses:
        "200":
          description: Customer updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-people-id
    delete:
      tags:
        - Customers
      summary: Delete customer
      description: Soft-deletes a customer. Charges and history remain for the audit trail.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Customer deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-people-id
  /api/v1/people/{id}/statement-pdf:
    get:
      tags:
        - Customers
      summary: Debtor statement (PDF)
      description: "Generates the debtor statement as a PDF: all of the person’s charges (document, due date, status, original and current amount) with totals for open, overdue and already paid. Scoped to the organization. Responds with `application/pdf` as a binary attachment."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Debtor statement PDF (binary `application/pdf` attachment).
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-people-id-statement-pdf
  /api/v1/charges:
    get:
      tags:
        - Charges
      summary: List charges
      description: Lists the organization’s charges with pagination and filters. Past-due pending charges are promoted to `overdue` on read.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            description: "Sort field. Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field. Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - schema:
            type: string
            description: Search by document number, description, `externalId`, customer name or document.
          required: false
          description: Search by document number, description, `externalId`, customer name or document.
          name: search
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by a customer’s charges (UUID).
          required: false
          description: Filter by a customer’s charges (UUID).
          name: person_id
          in: query
        - schema:
            type: string
            description: Filter by status. Accepts a single value or a comma-separated list (`pending`, `paid`, `overdue`, `cancelled`, `negotiated`, `protested`, `negatived`, `written_off`).
            example: pending,overdue
          required: false
          description: Filter by status. Accepts a single value or a comma-separated list (`pending`, `paid`, `overdue`, `cancelled`, `negotiated`, `protested`, `negatived`, `written_off`).
          name: status
          in: query
        - schema:
            type: string
            description: Due date from (inclusive, `YYYY-MM-DD` or ISO datetime).
            example: 2026-01-01
          required: false
          description: Due date from (inclusive, `YYYY-MM-DD` or ISO datetime).
          name: due_date_from
          in: query
        - schema:
            type: string
            description: Due date to (inclusive, `YYYY-MM-DD` or ISO datetime).
            example: 2026-12-31
          required: false
          description: Due date to (inclusive, `YYYY-MM-DD` or ISO datetime).
          name: due_date_to
          in: query
        - schema:
            type: string
            description: Relations to include in the response (`person`).
            example: person
          required: false
          description: Relations to include in the response (`person`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated charge list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChargeListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-charges
    post:
      tags:
        - Charges
      summary: Create charge
      description: Creates a charge for a customer. Without `collectionRuleId`, the organization’s default collection rule is applied. `currentAmount` = original + interest + fine − discount; an already past-due charge starts as `overdue`.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChargeCreateRequest"
      responses:
        "201":
          description: Charge created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Charge"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-charges
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/charges/{id}:
    get:
      tags:
        - Charges
      summary: Get charge
      description: Returns a charge by ID. Use `include=engine` to receive engine telemetry (rule enrollment and step executions).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: string
            description: Relations to include in the response (`person`, `engine` — rule telemetry).
            example: person,engine
          required: false
          description: Relations to include in the response (`person`, `engine` — rule telemetry).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Charge found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Charge"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-charges-id
    put:
      tags:
        - Charges
      summary: Update charge
      description: Updates a charge’s data (partial).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChargeUpdateRequest"
      responses:
        "200":
          description: Charge updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Charge"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-charges-id
    delete:
      tags:
        - Charges
      summary: Delete charge
      description: Soft-deletes a charge along with related tasks and offers. A charge with associated notifications, interactions, negativations or protests cannot be deleted (409).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Charge deleted (returns a confirmation message).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChargeDeleteResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-charges-id
  /api/v1/charges/{id}/settlement-pdf:
    get:
      tags:
        - Charges
      summary: Settlement letter (PDF)
      description: Generates the charge’s settlement letter as a PDF (legal document), scoped to the organization. Allowed only when the charge is paid (status `paid`); otherwise returns 409 (`CHARGE_NOT_SETTLED`). Responds with `application/pdf` as a binary attachment.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Settlement letter PDF (binary `application/pdf` attachment).
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Charge is not settled — the letter can only be generated for `paid` status (code `CHARGE_NOT_SETTLED`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-charges-id-settlement-pdf
  /api/v1/charges/{id}/notify:
    post:
      tags:
        - Charges
      summary: Notify charge
      description: Creates a manual notification for the charge and queues it for processing. Updates `lastNotificationAt` and, when `collectionRuleStepId` is provided, the charge’s `currentStep`.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChargeNotifyRequest"
      responses:
        "201":
          description: Notification created and queued (`queued` status).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChargeNotifyResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-charges-id-notify
  /api/v1/agreements:
    get:
      tags:
        - Agreements
      summary: List agreements
      description: Lists the organization’s agreements with pagination and filters.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            description: "Sort field. Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field. Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - schema:
            type: string
            enum:
              - proposed
              - accepted
              - active
              - completed
              - cancelled
              - defaulted
            description: Filter by agreement status.
          required: false
          description: Filter by agreement status.
          name: status
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by a customer’s agreements (UUID).
          required: false
          description: Filter by a customer’s agreements (UUID).
          name: person_id
          in: query
        - schema:
            type: string
            description: Relations to include in the response (`person`, `installments`, `negotiationOffer`).
            example: person,installments
          required: false
          description: Relations to include in the response (`person`, `installments`, `negotiationOffer`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated agreement list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgreementListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-agreements
    post:
      tags:
        - Agreements
      summary: Create agreement
      description: Creates an agreement with `proposed` status. `finalTotal` = `originalTotal` − `discountAmount` (must be greater than zero) and `installmentValue` = `finalTotal` / `numberOfInstallments`.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementCreateRequest"
      responses:
        "201":
          description: Agreement created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agreement"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-agreements
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/agreements/{id}:
    get:
      tags:
        - Agreements
      summary: Get agreement
      description: Returns an agreement by ID (always includes summarized customer data).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: string
            description: Relations to include in the response (`installments`, `negotiationOffer`).
            example: installments,negotiationOffer
          required: false
          description: Relations to include in the response (`installments`, `negotiationOffer`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Agreement found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agreement"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-agreements-id
    put:
      tags:
        - Agreements
      summary: Update agreement
      description: Updates an agreement (partial). Allowed only while status is `proposed` or `accepted` (409 otherwise).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementUpdateRequest"
      responses:
        "200":
          description: Agreement updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agreement"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-agreements-id
    delete:
      tags:
        - Agreements
      summary: Delete agreement
      description: Soft-deletes an agreement, marking it `cancelled`. `completed` agreements cannot be deleted (409).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Agreement deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-agreements-id
  /api/v1/agreements/{id}/accept:
    post:
      tags:
        - Agreements
      summary: Accept agreement
      description: "Accepts a `proposed` agreement (409 for other statuses): records `acceptedAt`/`acceptedIp` and creates the installments with monthly due dates starting at `firstDueDate`."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementAcceptRequest"
      responses:
        "200":
          description: Agreement accepted (returns the agreement with the created installments).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agreement"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-agreements-id-accept
  /api/v1/agreements/{id}/cancel:
    post:
      tags:
        - Agreements
      summary: Cancel agreement
      description: Cancels an agreement, recording `cancelledAt` and the reason, and cancels pending/overdue installments. `completed` or already-cancelled agreements return 409.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementCancelRequest"
      responses:
        "200":
          description: Agreement cancelled (returns the agreement with its installments).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agreement"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-agreements-id-cancel
  /api/v1/agreements/{id}/pdf:
    get:
      tags:
        - Agreements
      summary: Agreement term (PDF)
      description: Generates the agreement term as a PDF (legal document) with creditor, debtor, totals and installments, scoped to the organization. Responds with `application/pdf` as a binary attachment.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Agreement term PDF (binary `application/pdf` attachment).
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-agreements-id-pdf
  /api/v1/agreements/{id}/installments:
    get:
      tags:
        - Agreements
      summary: List agreement installments
      description: Lists an agreement’s installments (ordered by number) with an aggregated summary.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Agreement installments with summary.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgreementInstallmentListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-agreements-id-installments
    put:
      tags:
        - Agreements
      summary: Update agreement installment
      description: Updates an installment (payment/status). Allowed only for `accepted` or `active` agreements; cancelled installments cannot be changed (409). The first payment activates the agreement; once all installments are paid, the agreement is completed.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgreementInstallmentUpdateRequest"
      responses:
        "200":
          description: Installment updated (returns the installment and the updated agreement).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgreementInstallmentUpdateResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-agreements-id-installments
  /api/v1/disputes:
    get:
      tags:
        - Disputes
      summary: List disputes
      description: Lists the organization’s disputes, ordered by opening date (newest first). Custom sorting is not supported.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            enum:
              - open
              - under_review
              - resolved_valid
              - resolved_invalid
              - canceled
            description: Filter by status (`open` | `under_review` | `resolved_valid` | `resolved_invalid` | `canceled`).
          required: false
          description: Filter by status (`open` | `under_review` | `resolved_valid` | `resolved_invalid` | `canceled`).
          name: status
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by charge (UUID).
          required: false
          description: Filter by charge (UUID).
          name: charge_id
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by customer (UUID).
          required: false
          description: Filter by customer (UUID).
          name: person_id
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated dispute list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DisputeListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-disputes
    post:
      tags:
        - Disputes
      summary: Open dispute
      description: Opens a dispute against a charge and immediately pauses the collection rule. If the charge already has an open or under-review dispute, the existing one is returned (no duplicates). Supports `Idempotency-Key`.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DisputeCreateRequest"
      responses:
        "201":
          description: Dispute opened (or the charge’s existing open dispute).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DisputeResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-disputes
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/disputes/{id}:
    get:
      tags:
        - Disputes
      summary: Get dispute
      description: Returns a dispute by ID, with the full charge, customer and assignee.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Dispute found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DisputeDetailResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-disputes-id
    patch:
      tags:
        - Disputes
      summary: Run dispute action
      description: "Runs a workflow action on the dispute: `start_review`, `resolve` or `cancel`. Invalid transitions (e.g., `start_review` when the status is not `open`) return 409."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DisputeActionRequest"
      responses:
        "200":
          description: Dispute updated by the action.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DisputeResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: patch-disputes-id
  /api/v1/tasks:
    get:
      tags:
        - Tasks
      summary: List tasks
      description: Lists the organization’s tasks with pagination and filters. Sortable via `sort_by` (`title` | `priority` | `status` | `dueAt` | `createdAt` | `updatedAt`).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            description: "Sort field. Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field. Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - schema:
            type: string
            enum:
              - pending
              - in_progress
              - completed
              - cancelled
            description: Filter by status (`pending` | `in_progress` | `completed` | `cancelled`).
          required: false
          description: Filter by status (`pending` | `in_progress` | `completed` | `cancelled`).
          name: status
          in: query
        - schema:
            type: string
            enum:
              - low
              - medium
              - high
              - urgent
            description: Filter by priority (`low` | `medium` | `high` | `urgent`).
          required: false
          description: Filter by priority (`low` | `medium` | `high` | `urgent`).
          name: priority
          in: query
        - schema:
            type: string
            enum:
              - call
              - email
              - visit
              - review
              - follow_up
            description: Filter by type (`call` | `email` | `visit` | `review` | `follow_up`).
          required: false
          description: Filter by type (`call` | `email` | `visit` | `review` | `follow_up`).
          name: task_type
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by assignee (UUID).
          required: false
          description: Filter by assignee (UUID).
          name: assigned_to_id
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by customer (UUID).
          required: false
          description: Filter by customer (UUID).
          name: person_id
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by charge (UUID).
          required: false
          description: Filter by charge (UUID).
          name: charge_id
          in: query
        - schema:
            type: string
            description: Relations to include, comma-separated (`person`, `assignedTo`, `charge`).
            example: person,assignedTo,charge
          required: false
          description: Relations to include, comma-separated (`person`, `assignedTo`, `charge`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated task list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-tasks
    post:
      tags:
        - Tasks
      summary: Create task
      description: Creates a task, optionally linked to a customer, a charge and an assignee (all within the organization). Supports `Idempotency-Key`.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TaskCreateRequest"
      responses:
        "201":
          description: Task created (includes customer, assignee and charge summaries).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-tasks
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/tasks/{id}:
    get:
      tags:
        - Tasks
      summary: Get task
      description: Returns a task by ID, with customer, assignee and charge summaries.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Task found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-tasks-id
    put:
      tags:
        - Tasks
      summary: Update task
      description: Updates a task’s data (partial).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TaskUpdateRequest"
      responses:
        "200":
          description: Task updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-tasks-id
    delete:
      tags:
        - Tasks
      summary: Delete task
      description: "Soft-deletes a task: the status becomes `cancelled` (the record remains)."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Task cancelled.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-tasks-id
  /api/v1/tasks/{id}/complete:
    post:
      tags:
        - Tasks
      summary: Complete task
      description: Marks the task as completed and fills `completedAt`. Returns 409 if the task is already completed or cancelled.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Task completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-tasks-id-complete
  /api/v1/interactions:
    get:
      tags:
        - Interactions
      summary: List interactions
      description: Lists the organization’s interactions with pagination and filters. Sortable via `sort_by` (`contactedAt` | `interactionType` | `createdAt` | `updatedAt`; default `contactedAt` desc).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            description: "Sort field. Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field. Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - schema:
            type: string
            enum:
              - call
              - email
              - whatsapp
              - meeting
              - note
            description: Filter by type (`call` | `email` | `whatsapp` | `meeting` | `note`).
          required: false
          description: Filter by type (`call` | `email` | `whatsapp` | `meeting` | `note`).
          name: interaction_type
          in: query
        - schema:
            type: string
            enum:
              - inbound
              - outbound
            description: Filter by direction (`inbound` | `outbound`).
          required: false
          description: Filter by direction (`inbound` | `outbound`).
          name: direction
          in: query
        - schema:
            type: string
            enum:
              - promise_to_pay
              - negotiation
              - dispute
              - no_contact
              - callback_requested
              - payment_confirmed
            description: Filter by outcome (`promise_to_pay` | `negotiation` | `dispute` | `no_contact` | `callback_requested` | `payment_confirmed`).
          required: false
          description: Filter by outcome (`promise_to_pay` | `negotiation` | `dispute` | `no_contact` | `callback_requested` | `payment_confirmed`).
          name: outcome
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by customer (UUID).
          required: false
          description: Filter by customer (UUID).
          name: person_id
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by charge (UUID).
          required: false
          description: Filter by charge (UUID).
          name: charge_id
          in: query
        - schema:
            type: string
            description: Relations to include, comma-separated (`person`, `user`, `charge`).
            example: person,user,charge
          required: false
          description: Relations to include, comma-separated (`person`, `user`, `charge`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated interaction list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InteractionListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-interactions
    post:
      tags:
        - Interactions
      summary: Log interaction
      description: Logs an interaction with a customer, optionally linked to a charge. Supports `Idempotency-Key`.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InteractionCreateRequest"
      responses:
        "201":
          description: Interaction logged (includes customer, user and charge summaries).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Interaction"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-interactions
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/interactions/{id}:
    get:
      tags:
        - Interactions
      summary: Get interaction
      description: Returns an interaction by ID, with customer, user and charge summaries.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Interaction found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Interaction"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-interactions-id
    put:
      tags:
        - Interactions
      summary: Update interaction
      description: Updates an interaction’s editable fields (partial).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InteractionUpdateRequest"
      responses:
        "200":
          description: Interaction updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Interaction"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-interactions-id
    delete:
      tags:
        - Interactions
      summary: Delete interaction
      description: Soft-deletes an interaction; the record remains for the audit trail.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Interaction deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-interactions-id
  /api/v1/notifications:
    get:
      tags:
        - Notifications
      summary: List notifications
      description: Lists the organization’s notifications with pagination and filters. Sortable via `sort_by` (`createdAt` | `updatedAt` | `sentAt` | `deliveredAt` | `channel` | `status`).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            description: "Sort field. Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field. Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - schema:
            type: string
            description: Filter by channel; accepts a single value or a comma-separated list (`email` | `sms` | `whatsapp` | `voice` | `manual`).
            example: email,whatsapp
          required: false
          description: Filter by channel; accepts a single value or a comma-separated list (`email` | `sms` | `whatsapp` | `voice` | `manual`).
          name: channel
          in: query
        - schema:
            type: string
            description: Filter by status; accepts a single value or a comma-separated list (`pending` | `queued` | `sent` | `delivered` | `read` | `failed` | `bounced`).
            example: failed,bounced
          required: false
          description: Filter by status; accepts a single value or a comma-separated list (`pending` | `queued` | `sent` | `delivered` | `read` | `failed` | `bounced`).
          name: status
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by customer (UUID).
          required: false
          description: Filter by customer (UUID).
          name: person_id
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by charge (UUID).
          required: false
          description: Filter by charge (UUID).
          name: charge_id
          in: query
        - schema:
            type: string
            description: Relations to include, comma-separated (`person`, `charge`, `step`; `template` is an alias for `step`).
            example: person,charge,step
          required: false
          description: Relations to include, comma-separated (`person`, `charge`, `step`; `template` is an alias for `step`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated notification list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-notifications
    post:
      tags:
        - Notifications
      summary: Create notification
      description: Creates a manual notification for a customer, optionally linked to a charge and a rule step. The recipient is validated according to the channel.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationCreateRequest"
      responses:
        "201":
          description: Notification created with `pending` status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Notification"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-notifications
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/notifications/{id}:
    get:
      tags:
        - Notifications
      summary: Get notification
      description: Returns a notification by ID; use `include` to attach relations.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: string
            description: Relations to include, comma-separated (`person`, `charge`, `step`; `template` is an alias for `step`).
            example: person,charge,step
          required: false
          description: Relations to include, comma-separated (`person`, `charge`, `step`; `template` is an alias for `step`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Notification found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Notification"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-notifications-id
    put:
      tags:
        - Notifications
      summary: Update notification
      description: Updates a notification’s status, delivery timestamps and metadata (partial). Useful for integrations confirming send/delivery.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationUpdateRequest"
      responses:
        "200":
          description: Notification updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Notification"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-notifications-id
    delete:
      tags:
        - Notifications
      summary: Delete notification
      description: PERMANENTLY deletes a notification (hard delete — the model has no soft delete).
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Notification deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-notifications-id
  /api/v1/notifications/{id}/resend:
    post:
      tags:
        - Notifications
      summary: Resend notification
      description: Creates a NEW `pending` notification copied from the original (the new record’s `metadata` references the original via `resendOf`). Only allowed when the original is `failed` or `bounced`; otherwise returns 400. Supports `Idempotency-Key`.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      responses:
        "201":
          description: New notification created from the original.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Notification"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-notifications-id-resend
  /api/v1/collection-rules:
    get:
      tags:
        - Collection rules
      summary: List collection rules
      description: Lists the organization’s collection rules, ordered by priority. `_count.charges` carries the number of active charges on the rule.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by associated classification (UUID).
          required: false
          description: Filter by associated classification (UUID).
          name: classification_id
          in: query
        - schema:
            type: string
            enum:
              - "true"
              - "false"
            description: Filter by default rule (`true` | `false`).
          required: false
          description: Filter by default rule (`true` | `false`).
          name: is_default
          in: query
        - schema:
            type: string
            enum:
              - "true"
              - "false"
            description: "Filter by activation: `true` = active, `false` = inactive."
          required: false
          description: "Filter by activation: `true` = active, `false` = inactive."
          name: activated_at
          in: query
        - schema:
            type: string
            description: "Comma-separated relations to embed. Supported: `steps`."
            example: steps
          required: false
          description: "Comma-separated relations to embed. Supported: `steps`."
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated collection rule list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionRuleListResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-collection-rules
    post:
      tags:
        - Collection rules
      summary: Create collection rule
      description: Creates a collection rule, optionally with steps. Setting `isDefault` unsets the previous default rule.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionRuleCreateRequest"
      responses:
        "201":
          description: Collection rule created (with classification and steps).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionRule"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-collection-rules
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/collection-rules/{id}:
    get:
      tags:
        - Collection rules
      summary: Get collection rule
      description: Returns a collection rule by ID. Use `include=steps` to embed the steps.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: string
            description: "Comma-separated relations to embed. Supported: `steps`."
            example: steps
          required: false
          description: "Comma-separated relations to embed. Supported: `steps`."
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Collection rule found (`data` envelope).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionRuleShowResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-collection-rules-id
    put:
      tags:
        - Collection rules
      summary: Update collection rule
      description: Updates the rule data (partial). The `steps` array, when sent, upserts and removes missing steps.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionRuleUpdateRequest"
      responses:
        "200":
          description: Collection rule updated (`data` envelope).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionRuleShowResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-collection-rules-id
    delete:
      tags:
        - Collection rules
      summary: Delete collection rule
      description: Soft-deletes the rule and its steps. Fails with 409 if any charge uses the rule.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Collection rule deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-collection-rules-id
  /api/v1/collection-rules/{id}/steps:
    get:
      tags:
        - Collection rules
      summary: List rule steps
      description: Lists the rule steps ordered by `position`, with the message template embedded.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Rule steps (`data` envelope, not paginated).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionRuleStepListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-collection-rules-id-steps
    post:
      tags:
        - Collection rules
      summary: Create step
      description: Creates a step on the rule. Without `position` it goes last; with `position`, following steps shift down.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionRuleStepCreateRequest"
      responses:
        "201":
          description: Step created (with message template).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionRuleStep"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-collection-rules-id-steps
  /api/v1/collection-rules/{id}/steps/{stepId}:
    put:
      tags:
        - Collection rules
      summary: Update step
      description: Updates a step (partial). Changing `position` automatically reorders the other steps.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: string
            format: uuid
            description: Step identifier (UUID).
          required: true
          description: Step identifier (UUID).
          name: stepId
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionRuleStepUpdateRequest"
      responses:
        "200":
          description: Step updated (with message template).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionRuleStep"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-collection-rules-id-steps-stepid
    delete:
      tags:
        - Collection rules
      summary: Delete step
      description: Soft-deletes a step and reorders the remaining ones. Fails with 409 if the step has associated notifications.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: string
            format: uuid
            description: Step identifier (UUID).
          required: true
          description: Step identifier (UUID).
          name: stepId
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Step deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-collection-rules-id-steps-stepid
  /api/v1/templates:
    get:
      tags:
        - Message templates
      summary: List templates
      description: Lists the organization’s message templates with pagination, search and filters.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            description: Search by name, subject or body.
          required: false
          description: Search by name, subject or body.
          name: search
          in: query
        - schema:
            type: string
            enum:
              - email
              - sms
              - whatsapp
              - voice
              - manual
            description: Filter by channel.
          required: false
          description: Filter by channel.
          name: channel
          in: query
        - schema:
            type: string
            enum:
              - reminder
              - overdue
              - negotiation
              - negativation_warning
              - protest_warning
              - payment_confirmation
            description: Filter by category.
          required: false
          description: Filter by category.
          name: category
          in: query
        - schema:
            type: string
            enum:
              - friendly
              - neutral
              - firm
              - urgent
            description: Filter by tone.
          required: false
          description: Filter by tone.
          name: tone
          in: query
        - schema:
            type: string
            enum:
              - "true"
              - "false"
            description: "Filter by activation: `true` = active, `false` = inactive."
          required: false
          description: "Filter by activation: `true` = active, `false` = inactive."
          name: is_active
          in: query
        - schema:
            type: string
            enum:
              - name
              - channel
              - category
              - createdAt
              - updatedAt
            description: "Sort field. Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field. Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated template list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageTemplateListResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-templates
    post:
      tags:
        - Message templates
      summary: Create template
      description: Creates a message template. Fails with 409 if a template with the same `name` or `externalId` already exists.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessageTemplateCreateRequest"
      responses:
        "201":
          description: Template created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageTemplate"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-templates
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/templates/{id}:
    get:
      tags:
        - Message templates
      summary: Get template
      description: Returns a template by ID.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Template found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageTemplate"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-templates-id
    put:
      tags:
        - Message templates
      summary: Update template
      description: Updates a template (partial). Fails with 409 if the new `name` or `externalId` is already taken.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessageTemplateUpdateRequest"
      responses:
        "200":
          description: Template updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageTemplate"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-templates-id
    delete:
      tags:
        - Message templates
      summary: Delete template
      description: Soft-deletes a template. Fails with 409 if it is in use by rule steps.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Template deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-templates-id
  /api/v1/templates/{id}/duplicate:
    post:
      tags:
        - Message templates
      summary: Duplicate template
      description: Creates a copy of the template with the given name. The copy starts inactive (`activatedAt` null) and without `externalId`.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessageTemplateDuplicateRequest"
      responses:
        "201":
          description: Template duplicated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageTemplate"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-templates-id-duplicate
  /api/v1/classifications:
    get:
      tags:
        - Classifications
      summary: List classifications
      description: Lists the organization’s classifications, ordered by `priority` and `name` by default. Use `include=_count` for counters.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            enum:
              - "true"
              - "false"
            description: Filter by default classification (`true` | `false`).
          required: false
          description: Filter by default classification (`true` | `false`).
          name: is_default
          in: query
        - schema:
            type: string
            enum:
              - "true"
              - "false"
            description: Filter by automatic assignment (`true` | `false`).
          required: false
          description: Filter by automatic assignment (`true` | `false`).
          name: auto_assign
          in: query
        - schema:
            type: string
            enum:
              - "true"
              - "false"
              - "null"
            description: "Filter by activation: `true` = active, `false` or `null` = inactive."
          required: false
          description: "Filter by activation: `true` = active, `false` or `null` = inactive."
          name: activated_at
          in: query
        - schema:
            type: string
            description: "Relations to embed. Supported: `_count` (customers and rules)."
            example: _count
          required: false
          description: "Relations to embed. Supported: `_count` (customers and rules)."
          name: include
          in: query
        - schema:
            type: string
            enum:
              - name
              - code
              - priority
              - createdAt
              - updatedAt
            description: Sort field (`name` | `code` | `priority` | `createdAt` | `updatedAt`).
          required: false
          description: Sort field (`name` | `code` | `priority` | `createdAt` | `updatedAt`).
          name: sort
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: Sort direction (`asc` | `desc`).
          required: false
          description: Sort direction (`asc` | `desc`).
          name: order
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated classification list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClassificationListResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-classifications
    post:
      tags:
        - Classifications
      summary: Create classification
      description: Creates a classification. Setting `isDefault` unsets the previous default; a duplicate `code` fails with 409.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClassificationCreateRequest"
      responses:
        "201":
          description: Classification created (with counters).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Classification"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-classifications
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/classifications/{id}:
    get:
      tags:
        - Classifications
      summary: Get classification
      description: Returns a classification by ID. Use `include=_count` for counters.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: string
            description: "Relations to embed. Supported: `_count` (customers and rules)."
            example: _count
          required: false
          description: "Relations to embed. Supported: `_count` (customers and rules)."
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Classification found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Classification"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-classifications-id
    put:
      tags:
        - Classifications
      summary: Update classification
      description: Updates a classification (partial). A duplicate `code` fails with 409.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClassificationUpdateRequest"
      responses:
        "200":
          description: Classification updated (with counters).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Classification"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-classifications-id
    delete:
      tags:
        - Classifications
      summary: Delete classification
      description: Soft-deletes a classification. Fails with 409 if there are associated customers or rules. The `code` stays reserved.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Classification deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-classifications-id
  /api/v1/negotiation-campaigns:
    get:
      tags:
        - Negotiation campaigns
      summary: List campaigns
      description: Lists the organization’s negotiation campaigns (active and ended), newest first. Not paginated.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Organization campaigns (`campaigns` envelope).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NegotiationCampaignListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-negotiation-campaigns
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
    post:
      tags:
        - Negotiation campaigns
      summary: Create campaign
      description: Creates and activates a discount campaign. The debtor portal starts offering it to charges within the configured overdue range.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NegotiationCampaignCreateRequest"
      responses:
        "201":
          description: Campaign created and activated (`campaign` envelope).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NegotiationCampaignCreateResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-negotiation-campaigns
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/negotiation-campaigns/{id}:
    delete:
      tags:
        - Negotiation campaigns
      summary: End campaign
      description: Ends the campaign (deactivates; `activatedAt` becomes null). The record is kept and the portal stops offering it.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Campaign ended.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-negotiation-campaigns-id
  /api/v1/negativations:
    get:
      tags:
        - Credit Bureau Reports
      summary: List bureau reports
      description: Lists the organization’s bureau reports with pagination and filters. Use `include=person,charge` to embed customer and charge summaries.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            enum:
              - createdAt
              - updatedAt
              - amount
              - registeredAt
            description: "Sort field (`createdAt` | `updatedAt` | `amount` | `registeredAt`). Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field (`createdAt` | `updatedAt` | `amount` | `registeredAt`). Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - schema:
            type: string
            enum:
              - pending
              - active
              - removed
              - failed
            description: Filter by status (`pending` | `active` | `removed` | `failed`).
          required: false
          description: Filter by status (`pending` | `active` | `removed` | `failed`).
          name: status
          in: query
        - schema:
            type: string
            enum:
              - serasa
              - spc
              - boa_vista
            description: Filter by credit bureau (`serasa` | `spc` | `boa_vista`).
          required: false
          description: Filter by credit bureau (`serasa` | `spc` | `boa_vista`).
          name: bureau
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by customer (UUID).
          required: false
          description: Filter by customer (UUID).
          name: person_id
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by charge (UUID).
          required: false
          description: Filter by charge (UUID).
          name: charge_id
          in: query
        - schema:
            type: string
            description: Comma-separated relations to embed (`person`, `charge`).
            example: person,charge
          required: false
          description: Comma-separated relations to embed (`person`, `charge`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated bureau report list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NegativationListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-negativations
    post:
      tags:
        - Credit Bureau Reports
      summary: Create bureau report
      description: Creates a bureau report for a charge. The record starts as `pending` and is ONLY submitted to the bureau after human review and approval (legal workflow; `negativation.review_required` event). Returns 409 if a `pending`/`active` report already exists for the same charge and bureau.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NegativationCreateRequest"
      responses:
        "201":
          description: Bureau report created (awaiting human review).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Negativation"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-negativations
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/negativations/{id}:
    get:
      tags:
        - Credit Bureau Reports
      summary: Get bureau report
      description: Returns a bureau report by ID, with customer and charge summaries.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Bureau report found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Negativation"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-negativations-id
    put:
      tags:
        - Credit Bureau Reports
      summary: Update bureau report
      description: "Updates a bureau report (partial). This is the approval step of the legal workflow: it requires the review (`approve`) permission and is where status moves from `pending` to `active` after human review."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NegativationUpdateRequest"
      responses:
        "200":
          description: Bureau report updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Negativation"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-negativations-id
    delete:
      tags:
        - Credit Bureau Reports
      summary: Delete bureau report
      description: "Logical removal: marks the report as `removed` and sets `removedAt`. The record remains for the audit trail."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Bureau report removed.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-negativations-id
  /api/v1/negativations/{id}/remove:
    post:
      tags:
        - Credit Bureau Reports
      summary: Request bureau report removal
      description: Requests removal of a report from the bureau. Only allowed for `active` records; status becomes `removed` and the reason (if sent) is stored in `removalReason`.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NegativationRemoveRequest"
      responses:
        "200":
          description: Removal recorded; report updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Negativation"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-negativations-id-remove
  /api/v1/protests:
    get:
      tags:
        - Notary Protests
      summary: List protests
      description: Lists the organization’s protests with pagination and filters. Use `include=person,charge` to embed customer and charge summaries.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            enum:
              - createdAt
              - updatedAt
              - amount
              - protestDate
              - sentAt
            description: "Sort field (`createdAt` | `updatedAt` | `amount` | `protestDate` | `sentAt`). Legacy alias: `sortField`."
            example: createdAt
          required: false
          description: "Sort field (`createdAt` | `updatedAt` | `amount` | `protestDate` | `sentAt`). Legacy alias: `sortField`."
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          required: false
          description: "Sort direction (`asc` | `desc`). Legacy alias: `sortDirection`."
          name: sort_order
          in: query
        - schema:
            type: string
            enum:
              - pending
              - sent
              - intimated
              - protested
              - paid
              - cancelled
            description: Filter by status (`pending` | `sent` | `intimated` | `protested` | `paid` | `cancelled`).
          required: false
          description: Filter by status (`pending` | `sent` | `intimated` | `protested` | `paid` | `cancelled`).
          name: status
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by customer (UUID).
          required: false
          description: Filter by customer (UUID).
          name: person_id
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by charge (UUID).
          required: false
          description: Filter by charge (UUID).
          name: charge_id
          in: query
        - schema:
            type: string
            description: Comma-separated relations to embed (`person`, `charge`).
            example: person,charge
          required: false
          description: Comma-separated relations to embed (`person`, `charge`).
          name: include
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated protest list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProtestListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-protests
    post:
      tags:
        - Notary Protests
      summary: Create protest
      description: Creates a protest for a charge. The record starts as `pending` and is ONLY sent to the notary after human review and approval (legal workflow; `protest.review_required` event). Returns 409 if an active protest (`pending`/`sent`/`intimated`/`protested`) already exists for the same charge.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProtestCreateRequest"
      responses:
        "201":
          description: Protest created (awaiting human review).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Protest"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-protests
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/protests/{id}:
    get:
      tags:
        - Notary Protests
      summary: Get protest
      description: Returns a protest by ID, with customer and charge summaries.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Protest found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Protest"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-protests-id
    put:
      tags:
        - Notary Protests
      summary: Update protest
      description: "Updates a protest (partial). This is the approval step of the legal workflow: it requires the review (`approve`) permission and is where status advances from `pending` to `sent`/`intimated`/`protested` after human review."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProtestUpdateRequest"
      responses:
        "200":
          description: Protest updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Protest"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-protests-id
    delete:
      tags:
        - Notary Protests
      summary: Delete protest
      description: "Logical removal: marks the protest as `cancelled` and sets `cancellationDate`. The record remains for the audit trail."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Protest cancelled.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-protests-id
  /api/v1/protests/{id}/cancel:
    post:
      tags:
        - Notary Protests
      summary: Request protest cancellation
      description: Requests cancellation of a protest. Not allowed for protests already `cancelled` or `paid`; status becomes `cancelled` and the reason (if sent) is stored in `responseData.cancellationReason`.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProtestCancelRequest"
      responses:
        "200":
          description: Cancellation recorded; protest updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Protest"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-protests-id-cancel
  /api/v1/imports:
    get:
      tags:
        - Imports
      summary: List imports
      description: History of the organization’s 50 most recent imports (no pagination). File content and per-row errors are omitted; use GET /imports/{id} for details.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of the most recent imports.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-imports
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
    post:
      tags:
        - Imports
      summary: Create import
      description: "Uploads a CSV file of customers or charges and queues asynchronous processing. The body is JSON with the raw CSV text in the `content` field (max 2 MB). Invalid rows do not abort the batch: they are recorded in `errors` (`[{ line, error }]`) while the rest is processed. Track progress via GET /imports/{id}. Responds 202."
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportCreateRequest"
      responses:
        "202":
          description: Import accepted and queued for processing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportCreatedResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413":
          description: File larger than 2 MB — split the file into smaller parts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-imports
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/imports/{id}:
    get:
      tags:
        - Imports
      summary: Get import
      description: "Returns an import’s status with progress counters and per-row rejection errors (`errors: [{ line, error }]`; line 1 is the header, data starts at line 2)."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Import found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportShowResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-imports-id
  /api/v1/exports/people:
    get:
      tags:
        - Exports
      summary: Export customers (synchronous CSV)
      description: "Generates and returns the customers CSV inline (`text/csv; charset=utf-8` with BOM, `Content-Disposition: attachment`). Columns: nome, documento, tipo_documento, email, telefone, classificacao, external_id, tags, criado_em. Capped at 10k rows; beyond that use the asynchronous export (POST /exports/jobs)."
      security:
        - bearerAuth: []
      responses:
        "200":
          description: "CSV file (`text/csv; charset=utf-8` with BOM so Excel renders accents correctly; `Content-Disposition: attachment`)."
          content:
            text/csv:
              schema:
                type: string
                description: CSV file content.
                example: |-
                  nome,documento,email
                  Maria da Silva,12345678901,maria@example.com
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-exports-people
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
  /api/v1/exports/charges:
    get:
      tags:
        - Exports
      summary: Export charges (synchronous CSV)
      description: "Generates and returns the charges CSV inline (`text/csv; charset=utf-8` with BOM, `Content-Disposition: attachment`), with optional status and due-date filters. Columns: cliente, documento_cliente, numero_documento, descricao, valor_original, valor_atual, vencimento, dias_atraso, status, origem, external_id. Capped at 10k rows; beyond that use the asynchronous export (POST /exports/jobs)."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            description: Filter charges by status (e.g. `pending`, `overdue`, `paid`).
            example: overdue
          required: false
          description: Filter charges by status (e.g. `pending`, `overdue`, `paid`).
          name: status
          in: query
        - schema:
            type: string
            format: date
            description: Due date from (ISO date `YYYY-MM-DD`).
            example: 2026-01-01
          required: false
          description: Due date from (ISO date `YYYY-MM-DD`).
          name: from
          in: query
        - schema:
            type: string
            format: date
            description: Due date until (ISO date `YYYY-MM-DD`).
            example: 2026-06-30
          required: false
          description: Due date until (ISO date `YYYY-MM-DD`).
          name: to
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: "CSV file (`text/csv; charset=utf-8` with BOM so Excel renders accents correctly; `Content-Disposition: attachment`)."
          content:
            text/csv:
              schema:
                type: string
                description: CSV file content.
                example: |-
                  nome,documento,email
                  Maria da Silva,12345678901,maria@example.com
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-exports-charges
  /api/v1/exports/jobs:
    get:
      tags:
        - Exports
      summary: List asynchronous exports
      description: History of the organization’s 50 most recent asynchronous exports (no pagination). Use this route to track job status; the CSV itself is not included in the listing.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of the most recent exports.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportJobListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-exports-jobs
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
    post:
      tags:
        - Exports
      summary: Create asynchronous export
      description: Schedules CSV generation on a worker, without the 10k-row cap of the synchronous mode and without blocking the request. Track status via GET /exports/jobs and download the file via GET /exports/jobs/{id}/download before `expiresAt`. Responds 202.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExportJobCreateRequest"
      responses:
        "202":
          description: Export accepted and queued for processing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportJobCreatedResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-exports-jobs
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/exports/jobs/{id}/download:
    get:
      tags:
        - Exports
      summary: Download export CSV
      description: Serves the generated CSV of an asynchronous export (`text/csv; charset=utf-8` with BOM). Only available once the job is `completed` and before `expiresAt`.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: "CSV file (`text/csv; charset=utf-8` with BOM so Excel renders accents correctly; `Content-Disposition: attachment`)."
          content:
            text/csv:
              schema:
                type: string
                description: CSV file content.
                example: |-
                  nome,documento,email
                  Maria da Silva,12345678901,maria@example.com
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Export not finished yet (`NOT_READY` code; the `status` field reports the current state).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "410":
          description: Export expired — create a new one (`EXPIRED` code).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-exports-jobs-id-download
  /api/v1/webhook-endpoints:
    get:
      tags:
        - Webhooks
      summary: List webhook endpoints
      description: Lists the organization’s webhook endpoints with delivery counters by status. `secret` and `authConfig` never appear in the listing.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Endpoint list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpointListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-webhook-endpoints
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
    post:
      tags:
        - Webhooks
      summary: Create webhook endpoint
      description: Creates a webhook endpoint. The URL requires HTTPS and is validated against internal addresses (SSRF). The `secret` is returned only in this response — store it safely.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookEndpointCreateRequest"
      responses:
        "201":
          description: Endpoint created (includes `secret` — shown only once).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpointCreateResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-webhook-endpoints
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/webhook-endpoints/{id}:
    get:
      tags:
        - Webhooks
      summary: Get webhook endpoint
      description: Returns the endpoint with its latest 20 deliveries. The `secret` is never returned.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Endpoint with recent deliveries.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpointShowResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-webhook-endpoints-id
    patch:
      tags:
        - Webhooks
      summary: Update webhook endpoint
      description: Updates the endpoint (partial). The URL, when sent, is re-validated (HTTPS + SSRF); `authConfig` is encrypted and never returned.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookEndpointUpdateRequest"
      responses:
        "200":
          description: Endpoint updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpointUpdateResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: patch-webhook-endpoints-id
    delete:
      tags:
        - Webhooks
      summary: Delete webhook endpoint
      description: Soft-deletes the endpoint; pending deliveries stop being processed.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "204":
          description: Endpoint deleted.
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: delete-webhook-endpoints-id
  /api/v1/webhook-endpoints/{id}/rotate-secret:
    post:
      tags:
        - Webhooks
      summary: Rotate secret
      description: Generates a new HMAC secret; the previous one stops validating immediately. The new secret is returned only in this response — store it safely.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: New secret (shown only once).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpointRotateSecretResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-webhook-endpoints-id-rotate-secret
  /api/v1/webhook-endpoints/{id}/test:
    post:
      tags:
        - Webhooks
      summary: Send test event
      description: Delivers a REAL `webhook.test` event to the endpoint through the same pipeline as business events (queue, HMAC signature, request/response capture, retry) — validate your consumer end to end without waiting for a real event. Delivered only to the target endpoint, regardless of the subscribed event list. Fails with 409 if the endpoint is inactive.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      responses:
        "202":
          description: Test event queued for delivery.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpointTestResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-webhook-endpoints-id-test
  /api/v1/webhook-endpoints/{id}/deliveries:
    get:
      tags:
        - Webhooks
      summary: List endpoint deliveries
      description: Lists the endpoint’s deliveries (paginated, newest first) with the request/response capture for inspection and debugging.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            enum:
              - pending
              - success
              - failed
              - exhausted
            description: Filter by delivery status.
          required: false
          description: Filter by delivery status.
          name: status
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated delivery list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeliveryListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-webhook-endpoints-id-deliveries
  /api/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry:
    post:
      tags:
        - Webhooks
      summary: Retry delivery
      description: Re-queues a delivery for an immediate retry (status resets to `pending`). Fails with 409 if the endpoint is inactive or deleted.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            format: uuid
            description: Resource identifier (UUID).
          required: true
          description: Resource identifier (UUID).
          name: id
          in: path
        - schema:
            type: string
            format: uuid
            description: Delivery identifier (UUID).
          required: true
          description: Delivery identifier (UUID).
          name: deliveryId
          in: path
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Delivery re-queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeliveryRetryResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Conflict with the current resource state (or reused idempotency key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-webhook-endpoints-id-deliveries-deliveryid-retry
  /api/v1/audit-logs:
    get:
      tags:
        - Audit trail
      summary: Query audit trail
      description: Lists the organization’s audit trail records (newest first), with filters by action, entity, actor and period.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            description: Page number (starts at 1).
            example: 1
          required: false
          description: Page number (starts at 1).
          name: page
          in: query
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            description: "Items per page (max 100). Legacy alias: `limit`."
            example: 20
          required: false
          description: "Items per page (max 100). Legacy alias: `limit`."
          name: per_page
          in: query
        - schema:
            type: string
            description: Filter by action (partial match, `contains`).
          required: false
          description: Filter by action (partial match, `contains`).
          name: action
          in: query
        - schema:
            type: string
            description: Filter by entity type.
          required: false
          description: Filter by entity type.
          name: entity_type
          in: query
        - schema:
            type: string
            format: uuid
            description: Filter by entity (UUID).
          required: false
          description: Filter by entity (UUID).
          name: entity_id
          in: query
        - schema:
            type: string
            enum:
              - user
              - system
              - job
            description: Filter by actor type (`user` | `system` | `job`).
          required: false
          description: Filter by actor type (`user` | `system` | `job`).
          name: actor_type
          in: query
        - schema:
            type: string
            description: Filter by actor (user ID, job name or system name).
          required: false
          description: Filter by actor (user ID, job name or system name).
          name: actor_id
          in: query
        - schema:
            type: string
            format: date-time
            description: Period start (ISO 8601, inclusive).
          required: false
          description: Period start (ISO 8601, inclusive).
          name: from
          in: query
        - schema:
            type: string
            format: date-time
            description: Period end (ISO 8601, inclusive).
          required: false
          description: Period end (ISO 8601, inclusive).
          name: to
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Paginated list of audit records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditLogListResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-audit-logs
  /api/v1/metrics/recovery:
    get:
      tags:
        - Metrics
      summary: Recovery metrics
      description: "Returns the period’s recovery metrics (default: last 6 months, counted from the first day of the starting month)."
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 24
            description: Window in months (1–24; default 6).
            example: 6
          required: false
          description: Window in months (1–24; default 6).
          name: months
          in: query
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
      responses:
        "200":
          description: Computed metrics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecoveryMetrics"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-metrics-recovery
  /api/v1/email-layouts:
    get:
      tags:
        - Email layouts
      summary: List email layouts
      description: Lists the organization’s email layouts (default first) and the built-in reference layout.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Layout list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailLayoutListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-email-layouts
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
    post:
      tags:
        - Email layouts
      summary: Create email layout
      description: "Creates an email layout. The `htmlBody` must contain the `{{content}}` placeholder (otherwise, 400 `MISSING_CONTENT_PLACEHOLDER`). `isDefault: true` unsets the previous default."
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailLayoutCreateRequest"
      responses:
        "201":
          description: Layout created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailLayoutCreateResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: post-email-layouts
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
  /api/v1/notification-preferences:
    get:
      tags:
        - Notification preferences
      summary: Get notification preferences
      description: Returns the effective gate per message type — types without a saved record appear with all channels enabled.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Effective preferences per type.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationPreferenceListResponse"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: get-notification-preferences
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
    put:
      tags:
        - Notification preferences
      summary: Update notification preferences
      description: "Upserts the submitted preferences (partial: only the included types are changed)."
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationPreferenceUpdateRequest"
      responses:
        "200":
          description: Preferences saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationPreferenceUpdateResponse"
        "400":
          description: Invalid request (validation error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing, invalid, expired or revoked API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The key lacks the scope required by this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Resource not found or outside your organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Wait and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error. Retry; if it persists, contact support.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      operationId: put-notification-preferences
      parameters:
        - name: User-Agent
          in: header
          required: true
          description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick <kmitnick@kobana.com.br>`. Used for support and audit.
          schema:
            type: string
            example: Kevin Mitnick <kmitnick@kobana.com.br>
          example: Kevin Mitnick <kmitnick@kobana.com.br>
        - name: X-Idempotency-Key
          in: header
          required: false
          description: "Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result (`X-Idempotent-Replay: true` header)."
          schema:
            type: string
            format: uuid
webhooks: {}