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.
`category`	string	non	Catégorie de TVA EN 16931, pour la facturation électronique. `Standard` par défaut. Voir Champs de facturation électronique.
`exemptionReason`	string	non	Motif d'exonération de TVA affiché sur la facture électronique. Voir Champs de facturation électronique.
`taxableBase`	decimal	non	Montant net sur lequel la taxe a été calculée, pour la facturation électronique. Voir Champs de facturation électronique.

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

Champs de facturation électronique

Si vous utilisez la facturation électronique, chaque taxe peut aussi porter trois champs optionnels qui contrôlent la façon dont elle est rapportée dans la ventilation de TVA de la facture électronique générée. Ils n'ont aucun effet sur la façon dont la taxe est calculée ou facturée lors du paiement, et leur omission est entièrement rétrocompatible : la taxe utilise la catégorie Standard par défaut et sa base taxable est dérivée de la commande.

category - la catégorie de TVA EN 16931 (BT-118). Une des valeurs Standard (la valeur par défaut), ZeroRated, Exempt, ReverseCharge, IntraCommunity, Export, OutOfScope, CanaryIslands, CeutaMelilla.
exemptionReason - texte libre justifiant l'exonération, affiché sur la facture électronique pour toute catégorie autre que Standard - par exemple, l'article de loi qui s'applique. S'il est omis, Snipcart émet une valeur par défaut standard.
taxableBase - le montant net sur lequel la taxe a été calculée, dans la devise du panier.

{
  "taxes": [
    {
      "name": "Tax1",
      "amount": 10.00,
      "rate": 0.05,
      "numberForInvoice": "TAX-001",
      "category": "Standard",
      "taxableBase": 200.00
    },
    {
      "name": "Reverse charge",
      "amount": 0,
      "rate": 0,
      "category": "ReverseCharge",
      "exemptionReason": "VAT reverse charge under Article 196 of the VAT Directive",
      "taxableBase": 100.00
    }
  ]
}