Webhooks : taxes

Snipcart dispose d'un système de gestion des taxes intégré dans le tableau de bord du marchand. Si vous avez besoin d'un contrôle total sur la façon dont les taxes sont calculées, le webhook de taxes vous permet de retourner par programmation les taxes applicables à chaque panier.

Pendant le paiement, Snipcart envoie le panier en cours à votre point de terminaison, et votre application est responsable de retourner les taxes à appliquer. Configurez votre point de terminaison dans votre tableau de bord sous Configurations de la boutique → Taxes → Fournisseurs → Webhooks.

Requête

Snipcart fait une requête HTTP POST avec un corps JSON. L'enveloppe de premier niveau est la même que pour tous les webhooks de Snipcart :

Field	Type	Notes
eventName	string	Toujours taxes.calculate.
mode	string	Live ou Test.
createdOn	datetime	Le moment où la requête a été émise.
content	object	Le panier en cours - voir ci-dessous.

Le contenu

Contrairement aux webhooks d'événements de commande et de livraison - qui envoient tous deux un objet de forme Order - le webhook de taxes envoie le panier en cours. À noter au sujet de ce payload : les dates qu'il contient (creationDate, modificationDate, addedOn des articles, …) sont des horodatages Unix, et non des chaînes ISO, et paymentMethod est sérialisé comme un nombre. Champs les plus utilisés :

Field	Type	Notes
token	string	Identifiant du panier.
email	string	Courriel du client.
currency	string	Code de devise ISO.
lang	string	Langue du panier.
status	string	Généralement InProgress pendant le paiement.
shipToBillingAddress	boolean	Si la livraison utilise l'adresse de facturation.
billingAddress	object	name, company, address1, address2, city, province, country, postalCode, phone.
shippingAddress	object	Même structure que billingAddress.
shippingInformation	object	fees et method de l'option de livraison choisie.
items	object[]	Les articles du panier. Chacun porte quantity, unitPrice, totalPrice, totalPriceWithoutTaxes et taxable.
discounts	object[]	Les rabais appliqués.
customFields	object[]	Les champs personnalisés du panier.
metadata	object	Métadonnées du marchand.
itemsTotal	number	Total des articles.
totalWeight	number	Poids total du panier.
total	number	Total du panier.
taxesTotal	number	Somme des taxes déjà appliquées.

Exemple

{
  "eventName": "taxes.calculate",
  "mode": "Test",
  "createdOn": "2017-05-01T19:05:18.1321539Z",
  "content": {
    "ipAddress": "127.0.0.1",
    "lang": "en",
    "token": "5af47604-61ef-454b-92c9-37f64684e5e5",
    "email": "geeks@snipcart.com",
    "mode": "Test",
    "status": "InProgress",
    "shipToBillingAddress": true,
    "billingAddress": {
      "name": "Geeks at Snipcart",
      "company": "Snipcart",
      "address1": "226 rue St-Joseph E",
      "address2": "",
      "city": "Québec",
      "country": "CA",
      "postalCode": "G1K3A9",
      "province": "QC",
      "phone": ""
    },
    "shippingAddress": {
      "name": "Geeks at Snipcart",
      "company": "Snipcart",
      "address1": "226 rue St-Joseph E",
      "address2": "",
      "city": "Québec",
      "country": "CA",
      "postalCode": "G1K3A9",
      "province": "QC",
      "phone": ""
    },
    "completionDate": null,
    "invoiceNumber": "",
    "shippingInformation": {
      "fees": 10,
      "method": "Shipping"
    },
    "paymentMethod": 0,
    "metadata": {},
    "items": [
      {
        "uniqueId": "abb5bd38-ae77-4feb-8d05-c674e302f986",
        "token": "",
        "id": "1",
        "name": "An item",
        "price": 300,
        "description": "Item description",
        "url": "/",
        "image": "http://placehold.it/50/50",
        "quantity": 1,
        "minQuantity": null,
        "maxQuantity": null,
        "stackable": true,
        "shippable": true,
        "taxable": true,
        "taxes": [],
        "customFields": [],
        "duplicatable": false,
        "metadata": null,
        "unitPrice": 300,
        "totalPrice": 300,
        "totalPriceWithoutTaxes": 300,
        "addedOn": 1493665299,
        "initialData": "",
        "modificationDate": 1493665299
      }
    ],
    "discounts": [],
    "customFields": [],
    "refunds": [],
    "taxes": [],
    "currency": "usd",
    "totalWeight": 3000,
    "total": 310,
    "discountsTotal": 0,
    "itemsTotal": 300,
    "taxesTotal": 0,
    "taxProvider": null,
    "modificationDate": 1493665318,
    "creationDate": 1493665299
  }
}

Réponse

Répondez avec un code d'état 2XX et un corps JSON contenant un tableau taxes. Le Content-Type doit être application/json.

Field	Type	Requis	Notes
name	string	oui	Nom de la taxe, affiché au client et sur la facture.
amount	decimal	oui	Le montant de la taxe, dans la devise du panier (arrondi à 2 décimales). Pas en cents.
rate	decimal	non	Le taux de taxe, sous forme de fraction (0.05) ou de pourcentage (5) - les deux sont interprétés comme 5 %.
numberForInvoice	string	non	Numéro de taxe ou d'enregistrement affiché sur la facture.
includedInPrice	boolean	non	Voir Taxes incluses dans le prix.
appliesOnShipping	boolean	non	Voir Taxes sur la livraison.

{
  "taxes": [
    {
      "name": "Tax1",
      "amount": 10.00,
      "rate": 0.05,
      "numberForInvoice": "TAX-001"
    },
    {
      "name": "Tax2",
      "amount": 20.00,
      "rate": 0.10,
      "numberForInvoice": "TAX-002"
    }
  ]
}

Taxes incluses dans le prix

Si vos taxes sont déjà incluses dans vos prix, définissez includedInPrice à true. Le client voit toujours les taxes dans le sommaire de la commande, mais elles ne seront pas ajoutées au total du panier.

{
  "taxes": [
    {
      "name": "Tax1",
      "amount": 10.00,
      "rate": 0.05,
      "numberForInvoice": "TAX-001",
      "includedInPrice": true
    },
    {
      "name": "Tax2",
      "amount": 20.00,
      "rate": 0.10,
      "numberForInvoice": "TAX-002",
      "includedInPrice": true
    }
  ]
}

Taxes sur la livraison

Lorsqu'une taxe est incluse dans le prix, vous pouvez aussi indiquer si elle s'applique aux frais de livraison avec appliesOnShipping.

{
  "taxes": [
    {
      "name": "Tax1",
      "amount": 10.00,
      "rate": 0.05,
      "numberForInvoice": "TAX-001",
      "includedInPrice": true,
      "appliesOnShipping": true
    },
    {
      "name": "Tax2",
      "amount": 20.00,
      "rate": 0.10,
      "numberForInvoice": "TAX-002",
      "includedInPrice": true,
      "appliesOnShipping": false
    }
  ]
}