Add/Update Facture

Utilisez ceci lorsque a Facture est prêt dans votre système et que vous voulez que le client le reçoive et le paie, ou lorsqu'il change.


The following endpoint can be used to add or update a Facture within the Hyfin application. When a Facture is added to Hyfin, a payment request will be automatically generated and the customer will be notified via text message, email or both, as described under Who gets notified below.

If you choose to omit the customer info, a payment link will be provided in the API response. The payment link can be used on a self-checkout system or kiosk.

If the customer is viewing the Facture on their device and the Facture is updated, a message will display letting the customer know the Facture has been updated and the new version of the Facture will automatically be displayed on the customers device.

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 Facture. 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}/invoice/addUpdate

Demande
Champ
Type
Description
_id
String
L'identifiant que nous attribuons à cette facture. Omettez-le lors de la création d'une facture et envoyez-le lors de la mise à jour d'une facture.
externalId
String
Votre propre identifiant pour cette facture, provenant de votre logiciel. Envoyez à nouveau le même externalId pour mettre à jour cette facture au lieu d'en ajouter une nouvelle. Nous faisons la correspondance sur cette valeur, mais nous n'empêchons pas les doublons; gardez-la donc unique au sein du site.
isCredit
Boolean
Passez true pour enregistrer cet élément comme un crédit plutôt qu'une facture (voir Ajouter/Mettre à jour un crédit). Nécessite que les crédits soient activés pour le site.
Default = false
autoReverseAmount
Boolean
Avec isCredit, définissez à true lorsque les montants du crédit sont négatifs, comme votre système les stocke. Ils sont convertis en valeurs positives avant d'être enregistrés.
Default = false
invoiceNumber
String
Le numéro attribué par le système source et affiché au client sur la Facture. Deux Factures d'un même site peuvent partager un numéro, et un paiement appliqué par numéro est attribué à la première correspondance trouvée; gardez-le donc unique au sein du site.
totals
Les montants totaux de Facture. Lorsque lines est fourni, total est validé par rapport à celles-ci et doit être égal à la somme de chaque lines[].total, plus taxes, moins discounts. Une requête dont les totaux ne concordent pas est rejetée. Omettez lines et aucune vérification de ce type n'est effectuée.
customer
Une référence au dossier du client.
term
Les conditions de la facture, par leur _id Hyfin ou votre externalId. Envoyez l'un ou l'autre. Définit la date d'échéance et ajoute les escomptes de paiement anticipé et les frais de retard des conditions. Par défaut, les conditions de facturation du client, si elles existent.
lines
Une liste des articles de ligne sur le Facture. Requis si description n'est pas passé en.
description
String
Une brève description des produits/services sur le Facture. Requis si les lines ne sont pas passées en paramètre.
invoiceDate
La date de Facture. Si elle est fixée dans le futur, Facture n'est envoyé par texto ou par courriel au client qu'à cette date. Par défaut, la date du jour si elle est laissée vide. Une date sans heure. Une heure ou un fuseau horaire envoyé avec elle est ignoré, et non converti, de sorte que la date reste telle qu'écrite. Format = YYYY-MM-DD
customerMemo
String
Une note présentée au client en bas du Facture.
internalMemo
String
Un mémo ajouté au bas de la Facture. Visible uniquement par le personnel interne, jamais affiché aux clients.
payments
Une liste des paiements effectués sur le Facture.
webhookUrl
String
L'URL à laquelle envoyer une requête POST lorsque certaines actions sont effectuées sur Facture. Un webhook est envoyé lorsqu'un paiement atteint un nouvel état, et lorsqu'un message texte, un courriel ou un message WhatsApp est envoyé, livré, lu, retardé ou échoue, ou lorsque le client clique sur le lien de paiement.
options
Options à définir sur le Facture.
attachmentRefs
Une liste de pièces jointes.
send
À qui Facture est envoyé, par canal. Un canal que vous indiquez est utilisé tel quel, et une liste vide ([]) désactive ce canal. Un canal que vous omettez conserve les destinataires que Facture a déjà, ou est rempli à partir des contacts du client, selon le contrôle des notifications du client, lorsqu'il n'en a pas encore. Lors d'une création, omettez send pour laisser les contacts du client décider de chaque canal lors de l'envoi de Facture. Lors d'une mise à jour, l'omettre conserve les destinataires déjà choisis. Une lecture renvoie send.to à null tant que les destinataires n'ont pas été choisis. billTo.emails et billTo.sms demeurent le remplacement pour déterminer qui reçoit ces canaux, mais ne réactivent jamais un canal que send a désactivé.
onHold
Boolean
Indique si le premier versement impayé est mis en attente, de sorte que sa demande de paiement n'est pas envoyée tant que la mise en attente n'est pas levée. En lecture, la valeur est true lorsque ce versement est en attente et false autrement. En écriture, définissez-la à true pour mettre ce versement en attente, ou à false lors d'une mise à jour pour la lever. Omettez-la pour laisser la mise en attente telle quelle. La mise en attente se trouve sur le versement, et non sur Facture.
false lève une mise en attente que vous ou le marchand avez placée. Il ne lève pas la mise en attente qu'obtient Facture lorsqu'il ne rejoint personne et ne sera pas facturé automatiquement : send.to désactive tous les canaux, ou toutes les adresses du client sont en mode ne pas contacter et il n'y a aucun remplacement billTo. Ce Facture reste en attente et l'écriture réussit quand même, y compris lorsque vous fournissez vous-même installments ou définissez installments[].onHold à false. Donnez-lui un destinataire pour permettre l'envoi.
Une écriture qui envoie à la fois onHold et installments[].onHold sur le premier versement impayé doit leur donner la même valeur. Sinon, elle est refusée avec une erreur 400 et le message « Invalid on_hold, it conflicts with on_hold on the first unpaid installment. Send one of them, or the same value in both ». Une valeur qui n'est pas un booléen est refusée avec « Invalid on_hold, must be a boolean ».
billToCustomer
Le client qui reçoit et paie la facture, lorsqu'il ne s'agit pas de customer.
billTo
Remplacements facultatifs pour la section Facturer à de la facture. Si billToCustomer est fourni, cet objet sera fusionné avec les renseignements du client et peut servir à remplacer des champs précis. Si billToCustomer n'est pas fourni, les champs de cet objet seront utilisés comme renseignements de facturation sur la facture.
soldTo
Options facultatives pour la section Expédié à / Client de la facture.
deleted
Boolean
Ce drapeau représente si l'enregistrement est supprimé et n'est plus disponible pour être utilisé.
			
{
  "invoiceNumber": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 4599
  },
  "customer": {
    "externalId": "39772634",
    "primaryContact": {
      "firstName": "John",
      "lastName": "Doe",
      "mobilePhone": "111-222-3333",
      "email": "johndoe@abc.com"
    }
  },
  "options": {
    "tippingEnabled": false
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}


		
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.
link
String
La page de paiement destinée au client pour la Facture. Retournée à chaque ajout ou mise à jour réussi, ce qui vous permet de l'envoyer vous-même au client.
missingCustomer
Boolean
Indique si Facture fait référence à un client qui n'a pas encore été synchronisé; le client sera alors rattaché dès son arrivée.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https://site.url/KA39T1A45JL",
  "missingCustomer": false
}


		

Voir aussi