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 do_not_contact 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 notification_options 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 cette version :

  • Une écriture de client avec n'importe quelle notification_options.notify_* valeur place le client sous contrôle par client, y compris un client créé dans l'application. Pour un client déjà sous contrôle par client, une option omise conserve son choix enregistré. Pour un client que cette écriture fait passer au contrôle par client, une option omise prend la valeur par défaut du site pour les nouveaux clients, et est activée si le site n'en a pas. Un champ omis, nul ou vide notification_options ne change rien. Sur un site QuickBooks qui n'associe pas les modes de paiement, les options sont ignorées et le client reste sous contrôle par contact.
  • Lors de l'écriture d'une facture, les notification_options.notify_* valeurs deviennent les destinataires de cette facture au moment de son écriture : un canal défini à false est désactivé pour la facture, et chaque autre canal est rempli à partir des contacts du client à ce moment. Un canal défini à true l'emporte sur une option de contrôle par client à false pour cette facture, mais n'atteint jamais une adresse marquée « ne pas contacter » sous contrôle par contact. Une mise à jour qui omet les valeurs conserve les destinataires déjà associés à la facture.

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/v3.1/site/{site_id}/invoice/addUpdate

Demande
Champ
Type
Description
external_id
String
Votre propre identifiant pour cette facture, provenant de votre logiciel. Envoyez à nouveau le même external_id 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.
invoice_number
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 tax, 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.
invoice_term_name
String
Le nom d'une condition de facture configurée pour le site, par exemple Net 30. Lorsqu'il est envoyé, la date d'échéance est calculée à partir de la condition et de la date de la Facture, remplaçant tout due_date que vous envoyez. Un nom ne correspondant à aucune condition est rejeté avec Invoice term "" not found. Lorsqu'il est omis pour une nouvelle Facture, la condition de facture du client est utilisée s'il en a une.
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.
invoice_date
Date
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
customer_memo
String
Une note présentée au client en bas du Facture.
internal_memo
String
Un mémo ajouté au bas de la Facture. Visible uniquement par le personnel interne, jamais affiché aux clients.
active
Boolean
Ce drapeau représente si l'enregistrement Facture est actif et disponible pour être utilisé ou non.
Default = true
payments
Une liste des paiements effectués sur le Facture.
webhook_url
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.
attachments
String [ ]
Une liste d'URL de pièces jointes.
options
Options à définir sur le Facture.
			
{
  "external_id": "439772921",
  "invoice_number": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 45.99
  },
  "customer": {
    "external_id": "39772634",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "options": {
    "tipping_enabled": false
  },
  "webhook_url": "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.
id
String
The same id as _id, kept for backwards compatibility. Not returned on 4.0 and later.
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.
missing_customer
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",
  "id": "60f720d248f143332af022e0",
  "link": "https://site.url/KA39T1A45JL",
  "missing_customer": false
}


		

Voir aussi