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/v4/site/{site_id}/Facture/addUpdate

Le même point de terminaison est utilisé pour ajouter ou mettre à jour a Facture. Si le {_id} est fourni, le Facture sera mis à jour sinon il sera inséré.

Demande

Champ

Type

Requis

Description

_id

String

The id of the invoice. This field is auto generated by the system and is not required when creating a new invoice, but it is required when updating an existing invoice.

Facture_number

String

Le numéro unique attribué par le système source et affiché au client sur le Facture.

totals

The total amounts on the Facture. Validated against the sum of the line items found in `lines`.

customer

Une référence au dossier du client. Omettez ce champ pour recevoir un lien vers le Facture.

invoice_term_name

String

The invoice term name for the Facture. Defaults to the customer invoice term if it exists, unless `null` is passed in.

lines

A list of line items on the Facture. Required if `description` is not passed in.

description

String

A short description of the products/services on the Facture. Required if `lines` are not passed in.

Facture_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.

options

Options à définir sur le Facture.

attachment_refs

Une liste de pièces jointes.

bill_to_customer

The customer to bill, if different than the customer.

bill_to

Optional overrides for the Bill To section of the invoice. If bill_to_customer is provided, this object will be merged with the customer's information and can be used to override specific fields. If bill_to_customer is not provided, the fields in this object will be used as the Bill To information on the invoice.

sold_to

Optional overrides for the Sold To / Customer section of the invoice.

Sample Request (Simple)

			
				{
  "_id": "61f32dc2f62bdc6a48945067",
  "Facture_number": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 45.99
  },
  "customer": {
    "_id": "61f32dc2f62bdc6a48951255",
    "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)

			
				{
  "_id": "61f32dc2f62bdc6a48945067",
  "Facture_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": {
    "taxes": 2.85,
    "total": 30
  },
  "customer": {
    "_id": "61f32dc2f62bdc6a48951255",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "lines": [
    {
      "description": "",
      "product": {
        "_id": "62166eda3a8c0517866b9b46",
        "name": "Mens Large T-shirt",
        "unit_price": 15
      },
      "unit_price": 15,
      "qty": 2,
      "total": 30
    }
  ],
  "payments": [
    {
      "_id": "62166eda3a8c0517866b9r23",
      "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

The link to the Facture. Only returned if a `customer` is not passed in.

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"
  ]
}