Quelques règles s'appliquent à tous les points de terminaison. Lisez-les une fois et les tableaux de champs seront plus clairs.
_id est l'identifiant de Hyfin pour l'enregistrement, et chaque création le retourne. Enregistrez-le et renvoyez-le chaque fois que vous mettez à jour cet enregistrement.
externalId est votre propre identifiant pour l'enregistrement, par exemple votre numéro de facture ou de client. Hyfin le retourne lorsque vous lisez l'enregistrement. Un envoi sans _id avec un externalId déjà utilisé met à jour cet enregistrement au lieu d'en créer un nouveau.
Les webhooks de paiement désignent les factures uniquement par _id; une intégration qui néglige de l'enregistrer ne peut donc pas associer un paiement à sa facture.
Chaque montant en 4.0 est un nombre entier de cents, dans les requêtes comme dans les réponses. Envoyez 4599 pour 45,99 $. Les webhooks de paiement utilisent aussi les cents pour les sites sur la version de webhook 4.0, la valeur par défaut des nouveaux sites.
Un champ Date est un jour du calendrier sans heure, écrit YYYY-MM-DD, par exemple 2026-10-23. Une heure ou un fuseau horaire envoyé avec lui est ignoré, et non converti, de sorte que la date reste telle qu'écrite. Les réponses de Facture retournent invoiceDate et dueDate sous forme d'horodatage à minuit UTC à cette date, par exemple 2026-10-23T00:00:00.000Z.
Un champ Timestamp est un moment précis en format ISO 8601, avec millisecondes et fuseau horaire : YYYY-MM-DDTHH:mm:ss.SSSZ, par exemple 2026-10-23T15:04:05.123Z. Les réponses retournent les horodatages en UTC. Le paramètre de requête updated_after accepte uniquement ce format exact.
Votre logiciel gère les clients, les contacts, les articles, les factures et les abonnements. Envoyez-les à Hyfin lorsqu'ils sont créés ou modifiés. Hyfin gère les paiements : il les reçoit, puis vous en informe par le webhook de paiement. Pour enregistrer un paiement reçu en dehors de Hyfin, comme un chèque, utilisez Add/Update Payment.
Le webhook de paiement envoie un appel chaque fois qu'un paiement atteint un nouveau status; un même paiement peut donc arriver plus d'une fois, par exemple comme captured, puis comme settled. Associez-le selon le _id du paiement et mettez à jour le paiement existant plutôt que d'en ajouter un nouveau.
Un client est le compte que vous facturez. Un contact est une personne chez ce client qui reçoit les textos et les courriels. Un client peut avoir plusieurs contacts : envoyez-les dans primaryContact et contacts, ou avec Add/Update Contact.