Docs de l'API 3.1Docs de l'API 4.0 SimpleDocs de l'API 4.0

Add/Update Facture

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 based on the notification options set on the customer record.

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.

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

Le même point de terminaison est utilisé pour ajouter ou mettre à jour a Facture. Si a Facture existe déjà avec le {external_id} , le Facture sera mis à jour sinon il sera inséré.
Demande
Champ
Type
Description
external_id
String
Le numéro de facture unique du système/base de données source. Si nous détectons un enregistrement avec le même external_id, il sera mis à jour, sinon il sera ajouté.
invoice_number
String
Le numéro unique attribué par le système source et affiché au client sur le Facture.
totals
Les montants totaux sur le Facture. Validés par rapport à la somme des éléments de ligne trouvés dans lines.
customer
Une référence au dossier du client. Omettez ce champ pour recevoir un lien vers le Facture.
invoice_term_name
String
Le nom du terme de facturation pour le Facture. Par défaut, il est défini sur le terme de facturation du client s'il existe, à moins que null ne soit passé en paramètre.
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 du Facture. Si elle est définie dans le futur, la demande ne sera pas envoyée avant cette date. Par défaut, elle est définie à aujourd'hui si elle est laissée vide. 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
Le URL où envoyer les données lorsque des actions spécifiques sont effectuées sur le Facture. Des notifications seront envoyées en cas d'échec d'un envoi de texto/courriel, si un client clique sur un lien, ou s'il effectue un paiement.
attachments
String [ ]
Une liste d'URL de pièces jointes.
options
Options à définir sur le Facture.
Sample Request (Simple)
			
{
  "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": {
    "tippingEnabled": false
  },
  "webhook_url": "https://yourcompany.com/webhook"
}
Sample Request (Advanced)
			
{
  "external_id": "439772921",
  "invoice_number": "12345",
  "description": "",
  "customer_memo": "Thank you for your business!",
  "internal_memo": "",
  "invoice_date": "2022-12-01",
  "invoice_term_name": null,
  "expire_at": "2023-01-01",
  "totals": {
    "tax": 2.85,
    "total": 30
  },
  "customer": {
    "external_id": "39772634",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "lines": [
    {
      "description": "",
      "product": {
        "external_id": "62331255",
        "name": "Mens Large T-shirt",
        "unit_price": 15
      },
      "unit_price": 15,
      "qty": 2,
      "total": 30
    }
  ],
  "payments": [
    {
      "external_id": "72345322",
      "payment_type": "payment_card",
      "payment_sub_type": "amex",
      "display_name": "AMEX ****** 3422",
      "amount": 20,
      "gateway_transaction_id": 1234,
      "paid_on": "2021-03-15T16:32:11Z",
      "active": true
    }
  ],
  "options": {
    "tippingEnabled": false
  },
  "webhook_url": "https://yourcompany.com/webhook",
  "attachments": [
    "https://url.to.your/attachment"
  ]
}
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 auto generated id assigned to the record.
errors
String [ ]
A list of errors. Will only be returned if success is false.
link
String
Le lien vers le Facture. Retourné seulement si un customer n'est pas passé en paramètre.
Sample Response (Successful)
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "link": "https//site.url/KA39T1A45JL"
}
Sample Response (Failed)
			
{
  "success": false,
  "errors": [
    "invalid field2",
    "missing field_name"
  ]
}