Add/Update Customer

Utilisez ceci lorsqu'un client est créé ou modifié dans votre système.


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 est notifié

Chaque client est sous un seul contrôle des notifications, déterminé à partir du site et du client. Il n'est jamais enregistré et ne peut pas être défini directement.

  • Contrôle par contact : chaque adresse courriel et chaque numéro de téléphone des contacts du client porte son propre doNotContact indicateur, et cet indicateur est la seule chose qui arrête les messages automatiques envoyés à cette adresse ou à ce numéro. C'est le mode de contrôle des clients créés dans l'application, de tous les clients d'un site QuickBooks qui n'associe pas les modes de paiement aux notifications, et des intégrations sur l'API v4.
  • Contrôle par client : les notificationOptions du client (un choix pour chacun : courriel, message texte et WhatsApp) s'appliquent à chaque adresse de chaque contact. Un choix manquant signifie que le client est avisé. C'est le mode de contrôle de tous les clients d'un site QuickBooks qui associe les modes de paiement aux notifications, et des clients dont l'intégration a défini ces options dans une version antérieure à 4.0.

Sur l'API v4 :

  • Une écriture de client ou d'abonnement qui contient notificationOptions est refusée avec une erreur 400 et le message « notification_options is not accepted on API v4. Set do_not_contact on the contact emails and phone_numbers instead. »
  • Lors de l'écriture d'une facture, notificationOptions est obsolète et sera refusé dans une prochaine version. Il est toujours appliqué, exactement comme sur la version 3.1 : il devient les destinataires de la facture, send.to et la réponse réussit avec une entrée warnings . S'il est envoyé avec send.to il est refusé avec une erreur 400. Passez dès maintenant à send.to .
  • Une écriture de client sur un site non connecté à QuickBooks fait passer ce client au contrôle par contact. Ses options de notification sont copiées une seule fois sur doNotContact pour chaque adresse, puis supprimées, et les doNotContact valeurs de la requête sont appliquées ensuite.
  • Sur un site QuickBooks avec mapPaymentMethodsToNotifications activé, les modes de paiement QuickBooks déterminent les notifications de chaque client; une écriture de client qui contient doNotContact est donc refusée avec une erreur 400 qui nomme ce paramètre. Omettez l'indicateur, ou demandez au marchand de désactiver le paramètre.
  • onHold: false lors de l'écriture d'une facture ne libère pas une facture retenue parce qu'elle ne joint personne. Ajoutez-lui un destinataire pour permettre l'envoi.
  • La lecture d'un client ne renvoie jamais notificationOptions .

Point de terminaison

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

Demande
Champ
Type
Description
_id
String
L'identifiant que nous attribuons à ce client. Omettez-le lors de la création d'un client et envoyez-le lors de la mise à jour d'un client.
externalId
String
Votre propre identifiant pour ce client, provenant de votre logiciel. Envoyez à nouveau le même externalId pour mettre à jour ce client au lieu d'en ajouter un nouveau. Nous faisons la correspondance sur cette valeur, mais nous n'empêchons pas les doublons; gardez-la donc unique au sein du site.
displayName
String
Le nom qui sera affiché pour le client.
accountName
String
Le nom de l'entreprise ou du ménage du client, par exemple ABC Company. C'est le nom affiché pour un client ayant plus d'un contact, et pour un client ayant un seul contact uniquement lorsqu'aucun prénom ni nom de famille n'est envoyé.
primaryContact
Les informations de contact principales des clients. Requis si aucun contacts n'est fourni.
contacts
Une liste de contacts clients. Requis si primaryContact n'est pas passé en paramètre.
parentCustomer
Le client parent, le cas échéant. Une simple chaîne _id est également acceptée.
billToParentFlag
Boolean
Définissez à true pour envoyer les factures de ce client au client parent aux fins de paiement. S'applique uniquement lorsque parentCustomer est défini.
notes
String
Notes internes pour le client. Visible seulement par le commerçant.
attachmentRefs
Une liste de pièces jointes.
deleted
Boolean
Que le dossier du client ait été supprimé et n'est plus actif.
Default = false
			
{
  "externalId": "39772634",
  "displayName": "ABC Plumbing",
  "primaryContact": {
    "firstName": "John",
    "lastName": "Doe",
    "mobilePhone": "333-444-5555",
    "email": "johndoe@abc.com",
    "billingAddress": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 123",
      "city": "Naples",
      "stateCode": "FL",
      "zipCode": "34102"
    }
  }
}


		
Réponse
Champ
Type
Description
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 moment précis en format ISO 8601, avec un fuseau horaire. 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"
}


		

Voir aussi