> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar débitos

> Los débitos de los cobros que creó tu integración, del más nuevo al más viejo, para conciliar. Todos los filtros son opcionales. El cursor no repite ni salta débitos aunque entren nuevos mientras lees.



## OpenAPI

````yaml /openapi/integrations-v1.json get /integrations/v1/{companyId}/direct-debits
openapi: 3.1.0
info:
  title: Cobrix API de integraciones
  version: 1.0.0
  description: >-
    API firmada para sincronizar clientes, documentos de cobro, links y pagos
    verificados, para cobrar con débito inmediato, validar pagos recibidos y
    enviar vueltos. Los campos monetarios terminados en Minor usan unidades
    menores.
  license:
    name: Propietaria
    url: https://cobrix.co/terms
servers:
  - url: https://api.cobrix.co/api
    description: Producción
  - url: https://sandbox-api.cobrix.co/api
    description: Sandbox
security:
  - bearerAuth: []
tags:
  - name: Clientes
    description: Identidades externas vinculadas al source de la llave.
  - name: Documentos de cobro
    description: Documentos o cargos importados desde un sistema externo.
  - name: Débito inmediato
    description: Cobros por débito inmediato desde el formulario propio del comercio.
  - name: Validación de pagos
    description: >-
      Comprueba un pago móvil, una transferencia o un Zelle que recibió la
      empresa, desde tu servidor o con un token que usa tu web.
  - name: Vueltos
    description: Pago móvil desde la cuenta de la empresa a una persona.
  - name: Links de cobro
    description: Sesiones de checkout para documentos abiertos.
  - name: Pagos
    description: Pagos verificados y su aplicación financiera.
  - name: Dispersiones
    description: Lo que Cobrix transfirió a tus cuentas de los cobros por débito inmediato.
paths:
  /integrations/v1/{companyId}/direct-debits:
    get:
      tags:
        - Débito inmediato
      summary: Listar débitos
      description: >-
        Los débitos de los cobros que creó tu integración, del más nuevo al más
        viejo, para conciliar. Todos los filtros son opcionales. El cursor no
        repite ni salta débitos aunque entren nuevos mientras lees.
      operationId: listDirectDebits
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/CobrixTimestamp'
        - $ref: '#/components/parameters/CobrixSignature'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/DirectDebitStatus'
        - name: from
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Creados desde esta fecha y hora, incluida. ISO 8601, por ejemplo
            `2026-11-01T00:00:00Z`.
        - name: to
          in: query
          schema:
            type: string
            format: date-time
          description: Creados antes de esta fecha y hora, sin incluirla.
        - name: externalDocumentId
          in: query
          schema:
            type: string
          description: Los débitos de un cobro.
      responses:
        '200':
          description: Página de débitos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitListResponse'
        '400':
          description: >-
            `invalid_status`, `invalid_date` o `invalid_cursor`: un filtro mal
            escrito.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitApiError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/DirectDebitInternalError'
components:
  parameters:
    CompanyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Empresa vinculada a la llave.
    CobrixTimestamp:
      name: Cobrix-Timestamp
      in: header
      required: true
      schema:
        type: string
        pattern: ^[0-9]{10}$
      description: Segundos Unix dentro de una ventana de cinco minutos.
    CobrixSignature:
      name: Cobrix-Signature
      in: header
      required: true
      schema:
        type: string
        pattern: ^v1=[a-f0-9]{64}$
      description: HMAC-SHA256 de timestamp, método, ruta y cuerpo crudo.
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      description: Cursor opaco devuelto por la página anterior.
  schemas:
    DirectDebitStatus:
      type: string
      enum:
        - otp_sent
        - processing
        - succeeded
        - failed
        - expired
        - cancelled
      description: >-
        `otp_sent`: el banco envió el código, falta ejecutar. `processing`:
        enviado al banco, falta su respuesta. `succeeded`: cobrado y aplicado al
        documento. `failed`: el banco lo rechazó o falló el cobro. `expired`: el
        código venció; Cobrix lo cierra solo un minuto después. `cancelled`: lo
        cancelaste. Solo `succeeded` mueve dinero.
    DirectDebitListResponse:
      type: object
      required:
        - items
        - pagination
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DirectDebit'
        pagination:
          $ref: '#/components/schemas/Pagination'
    DirectDebitApiError:
      type: object
      required:
        - error
      description: Todos los errores HTTP de las rutas de débito inmediato.
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            field:
              type: string
              description: >-
                En `invalid_request`, el primer campo con problema, por ejemplo
                `payer.phone`. En un error de `splits`, la parte, por ejemplo
                `splits[1].holderDocument`.
            reason:
              type: string
              description: >-
                Solo en `invalid_split`: qué regla no se cumple, por ejemplo
                `sum`.
            details:
              type: array
              description: 'Solo en `invalid_request`: cada problema con su campo.'
              items:
                type: object
                required:
                  - field
                  - message
                properties:
                  field:
                    type: string
                  message:
                    type: string
            bankCode:
              type: string
              description: 'Solo en `payer_bank_rejected`: el código propio del banco.'
            requestId:
              type: string
              description: El `X-Request-Id` que enviaste, si enviaste uno.
    DirectDebit:
      type: object
      required:
        - id
        - externalDocumentId
        - status
        - amount
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: El débito. Es el `directDebitId` de `payment.failed`.
        externalDocumentId:
          type: string
          description: Tu referencia del cobro.
        status:
          $ref: '#/components/schemas/DirectDebitStatus'
        amount:
          type: object
          required:
            - minor
            - currency
          description: Lo que el banco debita, siempre en bolívares.
          properties:
            minor:
              type: string
              pattern: ^[0-9]+$
              description: 'Unidades menores, como texto: `"1313475"` es Bs 13.134,75.'
            currency:
              type: string
              example: VES
        otp:
          type: object
          required:
            - validitySeconds
          description: Solo mientras espera su código (`otp_sent`).
          properties:
            sentTo:
              type: string
              description: >-
                El teléfono enmascarado, por ejemplo `0412***00`. Solo en `POST
                direct-debits` y `POST direct-debits/{id}/otp`.
            expiresAt:
              type: string
              format: date-time
            validitySeconds:
              type: integer
              minimum: 0
              description: Segundos de vigencia que le quedan al código.
        paymentId:
          type: string
          format: uuid
          description: Solo en `succeeded`. Es el `data.paymentId` de `payment.succeeded`.
        error:
          $ref: '#/components/schemas/DirectDebitError'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      example:
        id: 6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10
        externalDocumentId: PED-1001
        status: otp_sent
        amount:
          minor: '1313475'
          currency: VES
        otp:
          expiresAt: '2026-11-10T15:02:00.000Z'
          validitySeconds: 74
        createdAt: '2026-11-10T15:00:00.000Z'
        updatedAt: '2026-11-10T15:00:00.000Z'
    Pagination:
      type: object
      required:
        - limit
        - nextCursor
        - hasMore
      properties:
        limit:
          type: integer
        nextCursor:
          type:
            - string
            - 'null'
        hasMore:
          type: boolean
    IntegrationError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            field:
              type: string
              description: El campo con problema, cuando el error trae uno.
            requestId:
              type:
                - string
                - 'null'
    DirectDebitError:
      type: object
      required:
        - code
        - message
      description: Por qué un débito `failed`, `expired` o `cancelled` no se cobró.
      properties:
        code:
          type: string
          enum:
            - payer_bank_rejected
            - payer_data_invalid
            - bank_timeout
            - duplicate_debit
            - bank_error
            - otp_expired
            - cancelled
          description: >-
            Estable para cualquier banco. `duplicate_debit`: el banco dice que
            ya tiene ese débito. `bank_error`: cualquier otro fallo, también un
            código del banco sin clasificar o un fallo de Cobrix.
        message:
          type: string
          description: En español, listo para mostrar al pagador.
        bankCode:
          type: string
          description: >-
            El código propio del banco, solo para soporte. Solo viene cuando el
            código es del banco; un fallo de Cobrix no lo trae.
  responses:
    Unauthorized:
      description: Llave o firma inválida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IntegrationError'
          example:
            error:
              code: invalid_api_key
              message: The API key is missing or invalid.
              requestId: req-1001
    Forbidden:
      description: Empresa o scope no autorizado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IntegrationError'
    RateLimited:
      description: Límite por llave y ruta excedido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IntegrationError'
          example:
            error:
              code: rate_limited
              message: Too many requests for this API key.
              requestId: req-1001
    DirectDebitInternalError:
      description: >-
        `internal_error`: falló algo de Cobrix, no del banco ni de los datos. El
        mensaje es genérico; reintenta en unos minutos. Con `X-Request-Id`, la
        respuesta lo trae como `requestId`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DirectDebitApiError'
          example:
            error:
              code: internal_error
              message: >-
                Something failed on our side. Try again in a few minutes; if it
                keeps failing, contact Cobrix support.
              requestId: req-1001
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Cobrix API key
      description: Llave cbx_live creada para el partner.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.