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
- Se excluye
- Transacciones existentes (
updateTransactionMetadata.input.erpTransactionMetadata) - Actualizaciones masivas de transacciones (
bulkUpdateErpTransactionMetadata) - Lecturas de transacciones (
Transaction.erpMetadata,erpTransactionMetadata,erpTransactionMetadataList)
Cómo funciona
- Opcional: Si quieres adjuntar un archivo, súbelo primero mediante el endpoint REST de carga. Recibirás un
attachmentId. - Pasa
memo,transactionCategoryy/oattachmentIden el input de tu mutación, ya sea en el momento de la transacción o después medianteupdateTransactionMetadata. - Para metadatos ERP, primero consulta los ítems de referencia importados de QuickBooks Online, o pasa nombres que deban resolverse o crearse en QuickBooks Online.
- Actualiza los metadatos ERP en una transacción con
updateTransactionMetadata.input.erpTransactionMetadata, o actualiza hasta 100 transacciones conbulkUpdateErpTransactionMetadata. - Lee las anotaciones en
getTransactions,getUserPurchaseso en la respuesta de la mutación. Lee los detalles ERP enTransaction.erpMetadata,erpTransactionMetadataoerpTransactionMetadataList. El campoattachmentUrldevuelve 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 comomultipart/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
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 aceptanmemo, transactionCategory y attachmentId como campos opcionales en su input:
depositCashBalance→DepositCashBalanceInputpurchaseGiftCard→PurchaseGiftCardInputcreateTransfer→CreateTransferInputtransferInternalBalance→TransferInternalBalanceInput
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
memode anotación está limitado a 255 caracteres. - El
erpTransactionMetadata.memode ERP está limitado a 4000 caracteres. transactionCategoryde anotación es una etiqueta de categoría de Fluz.categoryReferenceItemIdde 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 configurarcategoryReferenceItemId, 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
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
UsabulkUpdateErpTransactionMetadata 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
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
recordIdes 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
nulllos 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: nullno 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.
categoryNamecrea o selecciona una cuenta de QuickBooks Online con tipo de cuentaExpense.vendorNamecrea o selecciona un proveedor de QuickBooks Online.customerNamecrea o selecciona un cliente de QuickBooks Online.- La paginación de GraphQL usa
OffsetInput,limites 20 por defecto y está limitado por el tope de paginación del API.