Add/Update Customer

Usa esto cuando se cree un cliente o cambie en tu sistema.


The following endpoint can be used to add or update a customer within the Hyfin application. The customer mobile phone number and email address will be used to send payment requests to the customer, as described under Who gets notified below.

Quién recibe notificaciones

Cada cliente está bajo un solo control de notificaciones, determinado a partir del sitio y del cliente. Nunca se almacena y no se puede establecer directamente.

  • Control por contacto : cada dirección de correo electrónico y número de teléfono de los contactos del cliente tiene su propia doNotContact marca, y esa marca es lo único que detiene los mensajes automáticos hacia ella. Este es el control para los clientes creados en la app, para todos los clientes de un sitio de QuickBooks que no asigna métodos de pago a notificaciones, y para las integraciones en la API v4.
  • Control por cliente : las notificationOptions del cliente (una opción para cada uno: correo electrónico, mensaje de texto y WhatsApp) deciden para cada dirección de cada contacto. Si falta una opción, se notifica. Este es el control para todos los clientes de un sitio de QuickBooks que asigna métodos de pago a notificaciones, y para los clientes cuya integración definió esas opciones en una versión anterior a la 4.0.

En la API v4:

  • Una escritura de cliente o suscripción que incluya notificationOptions se rechaza con un error 400 y el mensaje "notification_options is not accepted on API v4. Set do_not_contact on the contact emails and phone_numbers instead."
  • En una escritura de Orden de compra, notificationOptions está obsoleta y se rechazará en una versión futura. Todavía se aplica, exactamente como en la 3.1: se convierte en los destinatarios de la Orden de compra send.to , y la respuesta es exitosa con una entrada de warnings . Si se envía junto con send.to se rechaza con un error 400. Cambie a send.to ahora.
  • Una escritura de cliente en un sitio que no está conectado a QuickBooks pasa a ese cliente al control por contacto. Sus opciones de notificación se copian en doNotContact en cada dirección una sola vez, luego se eliminan, y los doNotContact valores de la solicitud se aplican después de eso.
  • En un sitio de QuickBooks con mapPaymentMethodsToNotifications activado, los métodos de pago de QuickBooks deciden las notificaciones de todos los clientes, por lo que una escritura de cliente que incluya doNotContact se rechaza con un error 400 que nombra esa configuración. Omita la marca, o pida al comerciante que desactive la configuración.
  • onHold: false en una escritura de Orden de compra no libera una Orden de compra retenida porque no llega a nadie. Agregue un destinatario para que se pueda enviar.
  • La lectura del cliente nunca devuelve notificationOptions .

Punto Final

The following endpoint can be used to add or update a customer. You must replace the {base_url} and {site_id} variable with the site id that was provided when the site was created.

POST
{base_url}/api/v4/site/{site_id}/customer/addUpdate

Solicitud
Campo
Tipo
Descripción
externalId
String
Tu propio id para este cliente, desde tu software. Envía de nuevo el mismo externalId para actualizar este cliente en lugar de agregar uno nuevo. Usamos este valor para hacer la coincidencia, pero no evitamos duplicados, así que manténgalo único dentro del sitio.
firstName
String
El primer nombre del cliente. Se requiere al menos uno de firstName, lastName, accountName, email o mobilePhone.
lastName
String
El apellido del cliente. Se requiere al menos uno de firstName, lastName, accountName, email o mobilePhone.
accountName
String
El nombre de la empresa o del hogar del cliente, como ABC Company. Es el nombre que se muestra para un cliente con más de un contacto, y para un cliente con un solo contacto solo cuando no se envía nombre ni apellido. Se requiere al menos uno de firstName, lastName, accountName, email o mobilePhone.
mobilePhone
String
El número de teléfono móvil del cliente. Requerido si se notificará a este cliente por mensaje de texto. Se requiere al menos uno de firstName, lastName, accountName, email o mobilePhone.
email
String
La dirección de correo electrónico del cliente. Requerido si se notificará a este cliente por correo electrónico. Se requiere al menos uno de firstName, lastName, accountName, email o mobilePhone.
notes
String
Notas internas del cliente. Visible solo para el comerciante.
attachmentRefs
Una lista de adjuntos.
deleted
Boolean
Esta bandera representa si el registro ha sido eliminado y ya no está disponible para ser utilizado.
Sample Request
			
{
  "externalId": "39772634",
  "firstName": "John",
  "lastName": "Doe",
  "accountName": "",
  "mobilePhone": "111-222-3333",
  "email": "johndoe@abc.com",
  "notes": "World's best customer",
  "deleted": false
}


		
Respuesta
Campo
Tipo
Descripción
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if success is true.
One of added, updated
_id
String
The id we assign to the record.
updatedAt
The date the record was last updated. Un momento en el tiempo en formato ISO 8601, con zona horaria. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}


		

Ver también