> ## 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.

# Pedir el código

> Crea el cobro, igual que `POST checkouts`, y pide al banco del pagador que le envíe el código por SMS. Cobrix calcula el monto en bolívares; no lo envíes. Guarda el `id` de la respuesta para ejecutar el débito. Con `splits` la llave necesita además `payout_splits:write`.



## OpenAPI

````yaml /openapi/integrations-v1.json post /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:
    post:
      tags:
        - Débito inmediato
      summary: Pedir el código
      description: >-
        Crea el cobro, igual que `POST checkouts`, y pide al banco del pagador
        que le envíe el código por SMS. Cobrix calcula el monto en bolívares; no
        lo envíes. Guarda el `id` de la respuesta para ejecutar el débito. Con
        `splits` la llave necesita además `payout_splits:write`.
      operationId: createDirectDebit
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CobrixTimestamp'
        - $ref: '#/components/parameters/CobrixSignature'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectDebitRequest'
      responses:
        '201':
          description: 'Código enviado: el débito queda en `otp_sent`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitCreated'
        '400':
          $ref: '#/components/responses/DirectDebitInvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: >-
            `checkout_document_closed`: la referencia ya está pagada o anulada.
            `payer_debit_in_progress`: otro débito de este cliente está en
            `processing`. También un conflicto de idempotencia.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitApiError'
        '422':
          description: >-
            `direct_debit_unavailable`, `payer_bank_not_supported`,
            `payer_bank_rejected` (el banco del pagador no quiso enviar el
            código; trae `bankCode`), `payer_data_invalid` (los datos del
            pagador no sirven, por ejemplo un teléfono que no es celular),
            `rate_unavailable`, `invoice_total_mismatch`,
            `invoice_line_amount_mismatch` o un error de `splits`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitApiError'
        '429':
          description: >-
            `rate_limited`: demasiados códigos para este pagador o este cliente,
            otro código para el mismo pagador en curso, o más de 120 llamadas
            por minuto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitApiError'
        '500':
          $ref: '#/components/responses/DirectDebitInternalError'
        '503':
          description: >-
            `bank_unavailable`: el banco no responde; ninguna de sus rutas
            contestó. Reintenta en unos minutos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebitApiError'
components:
  parameters:
    CompanyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Empresa vinculada a la llave.
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 1
      description: Identificador estable de la operación.
    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.
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
      description: Identificador opcional para correlación de soporte.
  schemas:
    CreateDirectDebitRequest:
      type: object
      required:
        - externalDocumentId
        - customerExternalId
        - customer
        - currency
        - totalMinor
        - payer
      properties:
        externalDocumentId:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            Tu referencia del cobro. Si ya existe y sigue abierta, Cobrix la
            actualiza y abre un cobro nuevo.
        customerExternalId:
          type: string
          minLength: 1
          maxLength: 200
          description: El cliente en tu sistema.
        customer:
          $ref: '#/components/schemas/ExternalCustomerCore'
        currency:
          type: string
          enum:
            - USD
            - VES
            - EUR
          description: Moneda del cobro. El banco siempre debita bolívares.
        totalMinor:
          type: integer
          minimum: 1
          description: 'Total en unidades menores: `1500` es USD 15,00.'
        description:
          type: string
          minLength: 1
          maxLength: 500
          description: >-
            Texto del cobro cuando no envías `lines`. También es el concepto del
            débito.
        lines:
          type: array
          minItems: 1
          description: >-
            Las líneas del cobro. Cada `amountMinor` es `quantity` por
            `unitAmountMinor` y la suma da `totalMinor`.
          items:
            type: object
            required:
              - description
              - quantity
              - unitAmountMinor
              - amountMinor
            properties:
              description:
                type: string
              quantity:
                type: integer
                minimum: 1
              unitAmountMinor:
                type: integer
                minimum: 0
              amountMinor:
                type: integer
                minimum: 0
              periodStart:
                type: string
                format: date-time
              periodEnd:
                type: string
                format: date-time
              metadata:
                type: object
                additionalProperties: true
        dueDate:
          type: string
          description: Fecha ISO 8601. Por defecto, hoy.
        expiresInHours:
          type: integer
          minimum: 1
          maximum: 720
          default: 72
        splits:
          type: array
          minItems: 1
          maxItems: 20
          description: >-
            Opcional. Reparte esta venta entre varias cuentas, con el mismo
            formato y los mismos errores que en Links de cobro. La llave
            necesita además `payout_splits:write`.
          items:
            $ref: '#/components/schemas/CheckoutSplitPart'
        payer:
          $ref: '#/components/schemas/DirectDebitPayer'
      example:
        externalDocumentId: PED-1001
        customerExternalId: CLI-77
        customer:
          type: individual
          name: Ana Pérez
        currency: USD
        totalMinor: 1500
        description: Botín de cuero
        payer:
          bankCode: '0102'
          documentType: V
          documentNumber: '12345678'
          phone: '04120000000'
          holderName: Ana Pérez
    DirectDebitCreated:
      allOf:
        - $ref: '#/components/schemas/DirectDebit'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: object
              required:
                - minor
                - currency
              description: El total del cobro en su moneda.
              properties:
                minor:
                  type: integer
                currency:
                  type: string
            splits:
              type: array
              description: >-
                Solo cuando la petición trajo `splits`: cada cuenta enmascarada,
                en el mismo orden, como en Links de cobro.
              items:
                $ref: '#/components/schemas/CheckoutSplitPartResult'
      example:
        id: 6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10
        externalDocumentId: PED-1001
        status: otp_sent
        amount:
          minor: '1313475'
          currency: VES
        reference:
          minor: 1500
          currency: USD
        otp:
          sentTo: 0412***00
          expiresAt: '2026-11-10T15:02:00.000Z'
          validitySeconds: 120
        createdAt: '2026-11-10T15:00:00.000Z'
        updatedAt: '2026-11-10T15:00:00.000Z'
    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.
    ExternalCustomerCore:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - individual
            - business
        name:
          type: string
          minLength: 1
          maxLength: 200
        email:
          type:
            - string
            - 'null'
          format: email
        phone:
          type:
            - string
            - 'null'
        taxId:
          type:
            - string
            - 'null'
        customerCode:
          type:
            - string
            - 'null'
        metadata:
          type: object
          additionalProperties: true
    CheckoutSplitPart:
      type: object
      required:
        - percent
      description: >-
        Una parte del reparto: una cuenta registrada (`beneficiaryId`, o
        `"principal"` para la cuenta de cobro) o una cuenta nueva (`account`,
        `holderDocument` y `holderName`), nunca ambas.
      properties:
        percent:
          type: string
          pattern: ^[0-9]{1,3}([.][0-9]{1,4})?$
          description: Porcentaje como texto, hasta 4 decimales. Las partes suman 100.
          example: '37.5'
        beneficiaryId:
          type: string
          maxLength: 40
          description: Id de una cuenta registrada de la empresa, o `"principal"`.
        account:
          type: string
          maxLength: 40
          description: >-
            Cuenta nueva: 20 dígitos de un banco venezolano; se ignoran espacios
            y guiones.
        holderDocument:
          type: string
          maxLength: 20
          description: >-
            Documento del titular de la cuenta nueva, por ejemplo
            `J-50832606-7`.
        holderName:
          type: string
          maxLength: 100
          description: Titular de la cuenta nueva, de 3 a 100 caracteres.
        alias:
          type: string
          maxLength: 40
          description: Nombre corto para reconocer la cuenta nueva.
      example:
        account: 0102 0123 4500 0001 2345
        holderDocument: J-50832606-7
        holderName: Distribuidora Llanos, C.A.
        alias: Socio Llanos
        percent: '37.5'
    DirectDebitPayer:
      type: object
      required:
        - bankCode
        - documentType
        - documentNumber
        - phone
        - holderName
      description: >-
        Quién paga: la cuenta que el banco debita, con los datos que el banco
        tiene.
      properties:
        bankCode:
          type: string
          pattern: ^[0-9]{4}$
          description: >-
            Banco del pagador, 4 dígitos. Usa `code` de `GET
            direct-debits/banks`.
        documentType:
          type: string
          enum:
            - V
            - E
            - J
            - P
            - G
        documentNumber:
          type: string
          pattern: ^[0-9]{5,10}$
          description: De 5 a 10 dígitos, sin letra ni puntos.
        phone:
          type: string
          pattern: ^0[0-9]{10}$
          description: >-
            El celular asociado a la cuenta: 11 dígitos con el 0. Un teléfono
            que no es celular responde `422 payer_data_invalid`.
        holderName:
          type: string
          minLength: 2
          maxLength: 120
          description: Titular de la cuenta.
    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'
    CheckoutSplitPartResult:
      type: object
      required:
        - beneficiaryId
        - kind
        - bankCode
        - bankName
        - maskedAccount
        - alias
        - percent
        - created
      properties:
        beneficiaryId:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - principal
            - additional
            - api
          description: '`api`: una cuenta agregada por la API.'
        bankCode:
          type: string
          example: '0102'
        bankName:
          type: string
          example: Banco de Venezuela
        maskedAccount:
          type: string
          example: •••• 2345
          description: Nunca se devuelve el número completo ni el titular.
        alias:
          type:
            - string
            - 'null'
        percent:
          type: string
          example: '37.5'
        created:
          type: boolean
          description: >-
            `true` cuando esta petición agregó la cuenta; la misma cuenta
            enviada otra vez vuelve con `false`.
    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'
    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.
    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:
    DirectDebitInvalidRequest:
      description: >-
        `invalid_request`: el cuerpo no cumple el formato. `field` es el primer
        campo con problema y `details` trae todos. También
        `missing_idempotency_key`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DirectDebitApiError'
          example:
            error:
              code: invalid_request
              message: payer.phone must be 11 digits starting with 0.
              field: payer.phone
              details:
                - field: payer.phone
                  message: payer.phone must be 11 digits starting with 0.
    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'
    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.