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

# Fusionar contactos duplicados

> Fusiona de 2 a 20 contactos en un sobreviviente (una persona = un contacto con muchos destinos). Los destinos se mueven al sobreviviente; un id inexistente o ajeno responde 404 y no fusiona nada (sin fusión parcial). No es idempotente: reintentar tras el éxito responde 404 (fuentes ya borradas), así que el cliente no debe reintentar a ciegas.



## OpenAPI

````yaml /openapi.es.yaml post /v1/contacts/merge
openapi: 3.1.0
info:
  title: CBPay API
  version: '2.308'
  description: >
    CBPay es una plataforma de pagos multimoneda: payouts y cobros fiat

    en toda América Latina, transferencias internas, fondeo y retiros

    on-chain, y screening KYC. Cada cuenta mantiene doce saldos virtuales

    independientes — USD (la moneda principal de las cuentas nuevas; las cuentas

    existentes mantienen USDT salvo que cambien su configuración), USDT, USDC,
    USDCE, BTC y GOLD (gramos de

    oro fino), SILVER, PLATINUM (gramos) y BOB, MXN, ARS y CLP (libro mayor
    fiat; BOB/MXN/ARS usan 2 decimales y CLP 0) —

    convertibles a demanda con swaps entre los siete assets convertibles. Los
    balances fiat (BOB/MXN/ARS/CLP) solo acumulan payins retenidos con el flag
    `fiat_hold_local` y débitos directos en misma moneda; no son intercambiables
    por swap.

    Los payouts y las comisiones de servicios pueden pagarse desde cualquiera

    de los ocho saldos de liquidación (`PUT /v1/settlement` u override por
    payout con

    `settlement_asset`), y los payins directos en USD se acreditan en USD; el
    resto de payins puede auto-convertirse al asset que

    elijas (`default_payin_asset`).


    Todos los montos son strings decimales en la precisión de cada moneda (2

    decimales para USD/BOB/MXN/ARS, 0 para CLP, 6 decimales para
    USDT/USDC/USDCE/GOLD/SILVER/PLATINUM y 8 para BTC). Los errores siempre
    devuelven

    `{"error": "<code>", "message": "<detail>"}`.
servers:
  - url: https://api.qbank.cl/platform
    description: Live (producción, dinero real)
  - url: https://cryptobank.qbank.cl/platform
    description: Test (sandbox, dinero simulado — keys pk_test_)
security:
  - bearerAuth: []
tags:
  - name: Support
    description: Support tickets and organization queue
  - name: Comprobantes
    description: >-
      Comprobante PDF brandeado por operacion, con verificacion publica de
      autenticidad (QR firmado), receipt_url en respuestas/webhooks de estado
      final y envio automatico por email en estados finales. Un payout pendiente
      antes del debito no expone receipt_url.
  - name: Autenticación
    description: >-
      Registra e inicia sesión de los miembros de la cuenta. Las sesiones duran
      24 horas.
  - name: Cuenta
    description: Perfil, miembros y llaves de API de la cuenta que llama.
  - name: Saldos
    description: Saldos, historial de movimientos y tasas de cambio.
  - name: Payouts
    description: >-
      Dispersiones fiat que se debitan del saldo de settlement que elijas (USD
      es el saldo principal).
  - name: Payins
    description: >-
      Recargas fiat (QR, transferencias, cuentas dedicadas, cobros pull,
      tarjetas, links de checkout) que se acreditan automáticamente — en USD, o
      convertidas al settlement asset que elijas.
  - name: Checkout
    description: >-
      Links de checkout universal (`POST /v1/payins` con `method: "checkout"`) y
      los endpoints públicos de la página de pago — fiat multi-país, crypto con
      wallet efímera por link y pago directo CBPay, liquidado en el asset que
      elijas.
  - name: Tarjetas guardadas
    description: >-
      Tarjetas guardadas con el consentimiento explícito del pagador durante un
      pago 3-D Secure (COF). Listarlas, revocarlas y cobrarlas bajo demanda
      (MIT) sin pedir la tarjeta de nuevo.
  - name: Suscripciones
    description: >-
      Cobros recurrentes sobre una tarjeta guardada gestionados por el scheduler
      de la plataforma — diarios, semanales, mensuales o anuales, con
      pausa/reanudación/cancelación y dunning automático.
  - name: Transferencias
    description: >-
      Transferencias internas gratuitas entre cuentas CBPay (persona o empresa,
      cualquier combinación).
  - name: Contacts
    description: >-
      Libreta de beneficiarios por cuenta (destinos CBPay, bancarios y crypto)
      con match por teléfono y auto-guardado en cada envío.
  - name: Swaps
    description: >-
      Conversión instantánea entre los saldos USD (predeterminado), USDT, USDC,
      BTC, GOLD, SILVER y PLATINUM de la cuenta a la tasa cotizada de la cuenta.
  - name: Crypto
    description: Fondeo y retiros on-chain (TRON, Ethereum y Bitcoin).
  - name: Wallets segregadas
    description: >-
      Wallets on-chain con saldo propio (empresas ilimitadas; personas 1 por
      combinación red+activo) — crear, importar, enviar, exportar la llave
      privada y auto-forward. El saldo vive on-chain, nunca en el ledger.
  - name: Pruebas de firma
    description: >-
      Firma criptográfica de mensajes con wallets (EIP-191 ETH/EVM, TIP-191
      TRON) — crear, listar, consultar y revocar pruebas de firma con
      verificación pública.
  - name: Vínculos de wallets
    description: >-
      Vincula wallets externas (custody=client) a tu cuenta firmando un desafío
      nonce — crear desafíos, verificar firmas, listar y revocar vínculos.
  - name: QR Crypto POS
    description: >-
      Cobros QR crypto con monto para procesadores con POS físicos (cuentas
      empresa): merchants verificados, dirección exclusiva + QR por cobro,
      detección temprana del pago, conciliación por merchant y devoluciones por
      el riel de retiro crypto.
  - name: KYC / KYB
    description: >-
      Verificación de identidad: KYC para personas, KYB para empresas — tu
      propio onboarding y verificaciones de terceros para cuentas empresa.
  - name: Screening de wallets
    description: >-
      Evaluación de riesgo AML/CFT de direcciones blockchain (sanciones,
      exposición a fondos ilícitos) con comisión por scan, más protección
      automática gratuita en retiros y depósitos.
  - name: AML/CFT screening
    description: >-
      Screening AML/CFT standalone de personas y empresas contra listas de
      sanciones, PEP y medios adversos, con re-screening, monitoreo continuo e
      informe PDF descargable.
  - name: Qscore
    description: >-
      Buró de crédito API-first. Emite informes crediticios completos con score
      1-999 (bandas A-E, o SC cuando no hay datos), consulta el último score de
      un sujeto y gestiona disputas ARCO. Chile primero, con diseño agnóstico al
      país. Cada informe emitido lleva un código de verificación pública.
  - name: Analytics
  - name: Webhooks
    description: Suscripciones para recibir notificaciones de eventos firmadas.
  - name: Estado
    description: Disponibilidad del servicio.
  - name: Banking
    description: >-
      Cuentas bancarias reales: recibe, mantén y envía dinero por rieles
      bancarios internacionales.
  - name: Cards
    description: >-
      Tarjetas virtuales y físicas que gastan Just-In-Time desde cualquiera de
      los siete activos de gasto (USD, USDT, USDC, BTC, GOLD, SILVER o
      PLATINUM), con límites de gasto por tarjeta.
  - name: Seguridad (OTP)
    description: >-
      Códigos de verificación de un solo uso por SMS/WhatsApp/email que protegen
      acciones sensibles, más las preferencias de 2FA self-service. Aplican solo
      a sesiones de usuario — las API keys quedan exentas.
  - name: Passkeys
    description: >-
      Inicio de sesión sin contraseña con la biometría del dispositivo (Face ID,
      Touch ID, Windows Hello, llaves de seguridad) vía WebAuthn, apps
      autenticadoras (TOTP) con códigos de respaldo, y gestión de
      sesiones/dispositivos.
  - name: Login social
    description: >-
      Registro e inicio de sesión sin contraseña con Google, Apple, Microsoft y
      Facebook vía token exchange. El front obtiene la credencial del proveedor;
      la API la verifica y emite la sesión CBPay.
  - name: Eventos en tiempo real
    description: >-
      Stream Server-Sent Events con todo lo que pasa en la cuenta (o en toda la
      organización para administradores), replay con `Last-Event-ID`, snapshot
      inicial opcional e historial consultable de 90 días.
  - name: Contratos
    description: Contratos Marco Grupo CB prellenados para cuentas empresa verificadas.
  - name: Portal del referidor
    description: >-
      Portal de solo lectura para referidores (credencial de la cuenta payout):
      perfil, clientes referidos, comisiones devengadas e informe trilingüe
      (JSON/PDF/XLSX).
paths:
  /v1/contacts/merge:
    post:
      tags:
        - Contacts
      summary: Fusionar contactos duplicados
      description: >-
        Fusiona de 2 a 20 contactos en un sobreviviente (una persona = un
        contacto con muchos destinos). Los destinos se mueven al sobreviviente;
        un id inexistente o ajeno responde 404 y no fusiona nada (sin fusión
        parcial). No es idempotente: reintentar tras el éxito responde 404
        (fuentes ya borradas), así que el cliente no debe reintentar a ciegas.
      operationId: mergeContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contact_ids
              properties:
                contact_ids:
                  type: array
                  minItems: 2
                  maxItems: 20
                  items:
                    type: string
                    format: uuid
                  description: Contactos distintos de tu libreta a fusionar.
                surviving_contact_id:
                  type: string
                  format: uuid
                  description: >-
                    El contacto que sobrevive (debe ser uno de contact_ids; por
                    defecto el primero).
                display_name:
                  type: string
                  description: Override opcional del nombre del sobreviviente.
                alias:
                  type: string
                  description: Override opcional del alias del sobreviviente.
            example:
              contact_ids:
                - 3f8a1b2c-4d5e-6f70-8a9b-0c1d2e3f4a5b
                - 9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
              surviving_contact_id: 3f8a1b2c-4d5e-6f70-8a9b-0c1d2e3f4a5b
      responses:
        '200':
          description: Contacto fusionado con todos sus destinos.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Contact'
                  - type: object
                    properties:
                      merged_contact_ids:
                        type: array
                        items:
                          type: string
                          format: uuid
                        description: Contactos fuente borrados por la fusión.
              example:
                contact_id: 3f8a1b2c-4d5e-6f70-8a9b-0c1d2e3f4a5b
                display_name: Carlos Soto
                phone: '+56987654321'
                has_cbpay: true
                source: import
                favorite: true
                destinations:
                  - destination_id: aa11bb22-cc33-44dd-8899-aabbccddeeff
                    type: payout
                    country: CL
                    currency: CLP
                    method: bank_transfer
                  - destination_id: bb22c3d4-5e6f-7a80-9b0c-1d2e3f4a5b6c
                    type: crypto
                    chain: tron
                    address: TVJ6njG5Fyrq6XwYok3xPQx8kR7HQx6vXk
                merged_contact_ids:
                  - 9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
                created_at: '2026-07-07T12:00:00Z'
                updated_at: '2026-11-13T12:00:00Z'
        '400':
          description: invalid_payload / batch_too_large / invalid_characters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid_payload
                message: contact_ids must include at least 2 distinct contacts
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Un teléfono/email heredado pertenece a otro contacto de tu libreta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: duplicate
                message: duplicate
components:
  schemas:
    Contact:
      type: object
      properties:
        contact_id:
          type: string
          format: uuid
        display_name:
          type: string
        alias:
          type: string
        phone:
          type: string
          description: E.164.
        email:
          type: string
        has_cbpay:
          type: boolean
          description: >-
            True cuando el teléfono corresponde a una cuenta activa de tu
            operador.
        cbpay_account_id:
          type: string
          format: uuid
          description: Cuenta enlazada (presente cuando has_cbpay es true).
        source:
          type: string
          enum:
            - manual
            - import
            - transfer
            - payout
            - crypto
        favorite:
          type: boolean
        destinations:
          type: array
          description: >-
            Presente en el endpoint de detalle y en listados cuando se usa
            `expand=destinations`. Los filtros opcionales `dest_type` y
            `dest_country` solo aplican a este campo expandido.
          items:
            $ref: '#/components/schemas/ContactDestination'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
          description: Código de error legible por máquina (snake_case).
          example: insufficient_funds
        message:
          type: string
          description: Explicación legible por humanos.
    ContactDestination:
      type: object
      properties:
        destination_id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - cbpay
            - payout
            - crypto
        country:
          type: string
        currency:
          type: string
        method:
          type: string
        chain:
          type: string
        address:
          type: string
        details:
          type: object
          description: Beneficiario de payout completo en destinos payout.
        label:
          type: string
        last_used_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Credencial faltante o inválida (`unauthorized`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: invalid or missing credentials
    NotFound:
      description: Recurso no encontrado (`not_found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: resource not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        JWT de sesión (de register/login) o llave de API (`pk_...`).
        `X-API-Key: <token>` se acepta como header alternativo.

````

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