Sincronizar cuentas de una cartera

Carga y mantén las cuentas de deuda de una cartera desde tu propio sistema de origen con client.portfolios.syncAccounts. Envías un lote de filas de cuentas y un modo de fusión; QCobro empareja cada fila con una cuenta existente por su externalId y aplica el modo que elegiste.

Requisitos previos

syncAccounts está acotado a un workspace. Necesitas un Client autenticado con un workspace activo seleccionado, y el id de una cartera donde sincronizar. Crea una antes con client.portfolios.create.

Sincroniza un lote

Autentícate y selecciona un workspace

Construye un cliente, inicia sesión y elige el workspace al que pertenece la cartera.

import { Client } from "@qcobro/sdk";

const client = new Client();
await client.login({ email: "me@acme.com", password: process.env.QCOBRO_PASSWORD! });
client.useWorkspace("WO6ueex0qan9ojhf820wgiae3qi5luy08y");

Envía las filas

Pasa el portfolioId, un mode y al menos una fila. Cada fila necesita un externalId, un fullName y un outstandingBalance.

const result = await client.portfolios.syncAccounts({
  portfolioId: "f47ac10b-...",
  mode: "APPEND_ONLY",
  rows: [
    { externalId: "A-1", fullName: "Jane Doe", outstandingBalance: 1200.5 },
    { externalId: "A-2", fullName: "John Roe", outstandingBalance: 845 }
  ]
});

Lee los conteos

La llamada devuelve cuántas cuentas se crearon, actualizaron y archivaron, y el nuevo total activo de la cartera.

console.log(result); // { created: 2, updated: 0, archived: 0, total: 2 }

Elige un modo de sincronización

El mode decide qué pasa con las cuentas existentes. Las filas se emparejan con las cuentas por externalId dentro de la cartera.

Modo	Fila con un `externalId` nuevo	Fila que coincide con una cuenta existente	Cuenta existente ausente del lote
`APPEND_ONLY`	Se crea	Se deja sin cambios	Se deja sin cambios
`UPDATE_EXISTING`	Se crea	Se actualiza	Se deja sin cambios
`REPLACE`	Se crea	Se actualiza	Se archiva

APPEND_ONLY
UPDATE_EXISTING
REPLACE

Añade cuentas nuevas y nunca toca las que ya existen. Úsalo para cargas incrementales en las que los datos previos son la fuente autoritativa.

await client.portfolios.syncAccounts({ portfolioId: "f47ac10b-...", mode: "APPEND_ONLY", rows });

Añade cuentas nuevas y refresca las que ya existen: un upsert. Úsalo para feeds recurrentes que traen saldos o datos de contacto actualizados.

await client.portfolios.syncAccounts({ portfolioId: "f47ac10b-...", mode: "UPDATE_EXISTING", rows });

Haz que la cartera refleje el lote: crea, actualiza y archiva cualquier cuenta cuyo externalId no esté en rows. Úsalo cuando el lote es una instantánea completa de la cartera.

await client.portfolios.syncAccounts({ portfolioId: "f47ac10b-...", mode: "REPLACE", rows });

REPLACE archiva toda cuenta existente cuyo externalId falte en el lote, y expira las promesas de pago pendientes de esas cuentas. Envía siempre una instantánea completa con REPLACE: un lote parcial archivará las cuentas que dejaste fuera.

Da forma a las filas de cuenta

Cada entrada de rows se valida contra el esquema de cuenta compartido. Solo tres campos son obligatorios; el resto es opcional, y los campos numéricos de abajo toman 0 por defecto cuando se omiten.

string

required

Tu identificador estable de la cuenta. Las cuentas se emparejan entre sincronizaciones por este valor, así que debe ser único dentro de la cartera.

string

required

Nombre completo del titular de la cuenta.

number

required

Importe adeudado actual. Debe ser cero o mayor.

string

Teléfono de contacto usado para gestiones por voz y SMS.

string

Email de contacto. Debe ser una dirección válida cuando se aporta.

string

Idioma preferido para las gestiones (QCobro es multilingüe).

string

Nota libre sobre cuándo prefiere ser contactado el titular.

string

Tu propia etiqueta de segmentación de la cuenta.

number

default:"0"

Principal original adeudado.

number

default:"0"

Importe de la cuota según las condiciones de la cuenta.

string

Cada cuánto vencen las cuotas (por ejemplo monthly).

number

default:"0"

Número de cuotas del plazo.

number

default:"0"

Días de mora de la cuenta.

number

default:"0"

Número de cuotas impagadas.

string

Fecha del último pago, como cadena de fecha ISO.

number

Importe del último pago.

string

Notas sobre opciones de negociación o acuerdo aceptables para esta cuenta.

Lee el resultado

syncAccounts resuelve a un resumen de lo que cambió:

number

Cuentas insertadas porque su externalId era nuevo para la cartera.

number

Cuentas existentes refrescadas. Siempre 0 en APPEND_ONLY.

number

Cuentas archivadas por estar ausentes del lote. Distinto de cero solo en REPLACE.

number

Número de cuentas activas de la cartera tras la sincronización (las archivadas se excluyen).

Maneja los errores de validación

Las filas se validan en el cliente contra el esquema compartido de QCobro antes de enviar cualquier petición. Un lote vacío, un mode desconocido o un email malformado lanza un ValidationError con detalle por campo y no hace ninguna llamada de red.

import { ValidationError } from "@qcobro/sdk";

try {
  await client.portfolios.syncAccounts({
    portfolioId: "f47ac10b-...",
    mode: "APPEND_ONLY",
    rows: [] // los lotes vacíos se rechazan
  });
} catch (err) {
  if (err instanceof ValidationError) {
    console.error(err.fieldErrors); // [{ field: "rows", message: "...", code: "..." }]
  }
}

Consulta Validación y errores para la forma completa del error.

Siguientes pasos

Gestionar carteras

Crea, actualiza, archiva y lista las carteras donde sincronizas.

Validación y errores

Captura los fallos de validación del cliente y lee el detalle por campo.

Get started

Operator guides

SDK

MCP

CLI

API reference

Concepts

Sincronizar cuentas de una cartera

Requisitos previos

Sincroniza un lote

Elige un modo de sincronización

Da forma a las filas de cuenta

Lee el resultado

Maneja los errores de validación

Siguientes pasos

Gestionar carteras

Validación y errores

​Requisitos previos

​Sincroniza un lote

​Elige un modo de sincronización

​Da forma a las filas de cuenta

​Lee el resultado

​Maneja los errores de validación

​Siguientes pasos

Gestionar carteras

Validación y errores

Requisitos previos

Sincroniza un lote

Elige un modo de sincronización

Da forma a las filas de cuenta

Lee el resultado

Maneja los errores de validación

Siguientes pasos