Skip to main content
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

1

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("ws_abc123");
2

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: "ptf_123",
  mode: "APPEND_ONLY",
  rows: [
    { externalId: "A-1", fullName: "Jane Doe", outstandingBalance: 1200.5 },
    { externalId: "A-2", fullName: "John Roe", outstandingBalance: 845 }
  ]
});
3

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.
ModoFila con un externalId nuevoFila que coincide con una cuenta existenteCuenta existente ausente del lote
APPEND_ONLYSe creaSe deja sin cambiosSe deja sin cambios
UPDATE_EXISTINGSe creaSe actualizaSe deja sin cambios
REPLACESe creaSe actualizaSe archiva
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: "ptf_123", mode: "APPEND_ONLY", 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.
​
externalId
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.
​
fullName
string
required
Nombre completo del titular de la cuenta.
​
outstandingBalance
number
required
Importe adeudado actual. Debe ser cero o mayor.
​
phone
string
Teléfono de contacto usado para gestiones por voz y SMS.
​
email
string
Email de contacto. Debe ser una dirección válida cuando se aporta.
​
preferredLanguage
string
Idioma preferido para las gestiones (QCobro es multilingüe).
​
bestTimeToCall
string
Nota libre sobre cuándo prefiere ser contactado el titular.
​
customerSegment
string
Tu propia etiqueta de segmentación de la cuenta.
​
principalAmount
number
default:"0"
Principal original adeudado.
​
termsAmount
number
default:"0"
Importe de la cuota según las condiciones de la cuenta.
​
termsFrequency
string
Cada cuánto vencen las cuotas (por ejemplo monthly).
​
termsLength
number
default:"0"
Número de cuotas del plazo.
​
daysPastDue
number
default:"0"
Días de mora de la cuenta.
​
missedInstallments
number
default:"0"
Número de cuotas impagadas.
​
lastPaymentDate
string
Fecha del último pago, como cadena de fecha ISO.
​
lastPaymentAmount
number
Importe del último pago.
​
negotiationOptions
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ó:
​
created
number
Cuentas insertadas porque su externalId era nuevo para la cartera.
​
updated
number
Cuentas existentes refrescadas. Siempre 0 en APPEND_ONLY.
​
archived
number
Cuentas archivadas por estar ausentes del lote. Distinto de cero solo en REPLACE.
​
total
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: "ptf_123",
    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.