Skip to main content
Puedes enriquecer cualquier transacción con un memo, una categoría y/o un archivo adjunto (p. ej., recibos, facturas, órdenes de compra). Las anotaciones se pueden agregar en el momento de la transacción original o actualizar después usando la mutación updateTransactionMetadata. Para cuentas con integraciones ERP habilitadas y una conexión activa a QuickBooks Online, también puedes gestionar metadatos de transacciones ERP: categoría contable, proveedor, cliente, estado facturable y un memo específico de ERP. Los metadatos ERP son independientes de las anotaciones. Las anotaciones son compatibles con:
  • Depósitos (depositCashBalance)
  • Compras de tarjeta de regalo (purchaseGiftCard)
  • Transferencias de la billetera (createTransfer, transferInternalBalance)
  • Creación de tarjeta virtual (createVirtualCard)
    • Se excluye attachment
Los metadatos ERP son compatibles con:
  • Transacciones existentes (updateTransactionMetadata.input.erpTransactionMetadata)
  • Actualizaciones masivas de transacciones (bulkUpdateErpTransactionMetadata)
  • Lecturas de transacciones (Transaction.erpMetadata, erpTransactionMetadata, erpTransactionMetadataList)

Cómo funciona

  1. Opcional: Si quieres adjuntar un archivo, súbelo primero mediante el endpoint REST de carga. Recibirás un attachmentId.
  2. Pasa memo, transactionCategory y/o attachmentId en el input de tu mutación, ya sea en el momento de la transacción o después mediante updateTransactionMetadata.
  3. Para metadatos ERP, primero consulta los ítems de referencia importados de QuickBooks Online, o pasa nombres que deban resolverse o crearse en QuickBooks Online.
  4. Actualiza los metadatos ERP en una transacción con updateTransactionMetadata.input.erpTransactionMetadata, o actualiza hasta 100 transacciones con bulkUpdateErpTransactionMetadata.
  5. Lee las anotaciones en getTransactions, getUserPurchases o en la respuesta de la mutación. Lee los detalles ERP en Transaction.erpMetadata, erpTransactionMetadata o erpTransactionMetadataList. El campo attachmentUrl devuelve una URL firmada de corta duración para el acceso al archivo.

Paso 1: Cargar un archivo adjunto (opcional)

Este es un endpoint REST, no una mutación de GraphQL

Endpoint

POST /api/v1/file-upload/transaction-memo-attachment

Autenticación

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>

Solicitud

Envía el archivo como multipart/form-data con el nombre de campo file. Tipos aceptados: application/pdf, image/png
⚠️ JPEG no es aceptado para adjuntos de transacciones.

Solicitud de ejemplo

Respuesta

Copia el attachmentId: lo pasarás en el input de tu mutación en el siguiente paso.
El attachmentId está limitado al alcance de tu cuenta. El sistema verifica que el archivo exista en el almacenamiento de tu cuenta cuando envías la mutación. Un ID de una cuenta diferente será rechazado.

Errores de carga


Paso 2: Anotar la transacción

Puedes proporcionar anotaciones en el momento de la transacción original o actualizarlas después.

Opción A — En el momento de la transacción

Las siguientes mutaciones aceptan memo, transactionCategory y attachmentId como campos opcionales en su input:
  • depositCashBalanceDepositCashBalanceInput
  • purchaseGiftCardPurchaseGiftCardInput
  • createTransferCreateTransferInput
  • transferInternalBalanceTransferInternalBalanceInput

Campos de anotación

Ejemplo — Comprar tarjeta de regalo con anotación


Opción B — Después de la transacción (updateTransactionMetadata)

Usa esta mutación para agregar o actualizar anotaciones en cualquier transacción existente.
Semántica de actualización parcial: Solo se actualizan los campos que incluyes. Los campos omitidos quedan sin cambios. Pasa null para borrar un campo.

Mutación

UpdateTransactionMetadataInput

Alcances requeridos

LIST_PAYMENT y LIST_PURCHASES. Si incluyes erpTransactionMetadata, la solicitud también requiere MANAGE_ERP_TRANSACTION_METADATA.

Ejemplo — Agregar un memo y categoría

Ejemplo — Adjuntar un archivo a una transacción existente

Ejemplo — Borrar un memo

Respuesta de ejemplo

Errores


Paso 3: Gestionar metadatos ERP

Los metadatos ERP se usan para categorizar transacciones antes de exportarlas al proveedor contable conectado. El proveedor actualmente disponible es QuickBooks Online. Los campos de metadatos ERP son independientes de las anotaciones:
  • El memo de anotación está limitado a 255 caracteres.
  • El erpTransactionMetadata.memo de ERP está limitado a 4000 caracteres.
  • transactionCategory de anotación es una etiqueta de categoría de Fluz.
  • categoryReferenceItemId de ERP apunta a un ítem del plan de cuentas de QuickBooks Online.

UpdateErpTransactionMetadataInput

Omite erpTransactionMetadata de la solicitud cuando no quieras actualizar metadatos ERP.

Ejemplo: Actualizar anotaciones y metadatos ERP juntos


Paso 4: Encontrar ítems de referencia ERP

Usa estas queries para encontrar ítems de referencia importados de QuickBooks Online antes de configurar categoryReferenceItemId, vendorReferenceItemId o customerReferenceItemId.

Campos de ítem de referencia

Filtros de ítems de referencia

Ejemplo: Buscar plan de cuentas

Ejemplo: Buscar proveedores y clientes


Paso 5: Leer metadatos ERP

Los metadatos ERP se pueden leer desde el objeto de transacción o mediante queries dedicadas de metadatos ERP.

Leer metadatos ERP en getTransactions

erpMetadata es null cuando la cuenta no tiene una conexión ERP activa o la transacción no tiene metadatos ERP.

Leer los metadatos ERP de una transacción

Esta query devuelve null, no un error, cuando no hay metadatos ERP para la transacción o la cuenta no tiene una conexión ERP activa.

Listar registros de metadatos ERP

Filtros de la lista de metadatos ERP


Estado de sincronización ERP


Actualización masiva de metadatos ERP

Usa bulkUpdateErpTransactionMetadata para actualizar metadatos ERP para hasta 100 transacciones en una sola solicitud. Cada elemento usa los mismos campos de UpdateErpTransactionMetadataInput. Los campos omitidos quedan sin cambios; los campos de referencia anulables, memo y isBillable pueden pasarse como null para borrarlos.

Mutación

Variables

Respuesta de ejemplo

Las fallas de validación ERP por elemento se devuelven en failed; otros elementos válidos aún pueden tener éxito.

Lectura de anotaciones

Las anotaciones se devuelven en lo siguiente:
⚠️ attachmentUrl es una URL firmada. Expira poco después de generarse. No la almacenes: vuelve a obtener la transacción cuando necesites mostrar o acceder al archivo.

Errores comunes


Notas y límites

  • recordId es el ID de registro de la transacción devuelto por las queries de transacciones.
  • Las actualizaciones de anotaciones son parciales: los campos omitidos permanecen sin cambios y null los borra.
  • Las actualizaciones de metadatos ERP también son parciales: los campos omitidos permanecen sin cambios, y los campos anulables admitidos se pueden borrar con null.
  • En updateTransactionMetadata, erpTransactionMetadata: null no hace nada; no borra.
  • En updateTransactionMetadata, erpTransactionMetadata: {} es inválido. Omite el campo en su lugar.
  • Si se proporcionan tanto un ID de referencia ERP como un nombre para el mismo campo, prevalece el ID de referencia.
  • categoryName crea o selecciona una cuenta de QuickBooks Online con tipo de cuenta Expense.
  • vendorName crea o selecciona un proveedor de QuickBooks Online.
  • customerName crea o selecciona un cliente de QuickBooks Online.
  • La paginación de GraphQL usa OffsetInput, limit es 20 por defecto y está limitado por el tope de paginación del API.