API : notifications

Les notifications sont des enregistrements rattachés à une commande — des commentaires que vous souhaitez conserver au dossier, ou des messages envoyés par courriel au client (factures, numéros de suivi, mises à jour d'expédition, et ainsi de suite). Utilisez-les pour suivre les modifications apportées à une commande ou pour déclencher des courriels destinés au client.

Les requêtes sont authentifiées avec votre clé API secrète, transmise comme nom d'utilisateur en authentification HTTP Basic avec un mot de passe vide. Avec curl : -u {API_KEY}:. Voir Authentification pour plus de détails. Chaque notification appartient à une commande, identifiée par son token GUID.

L'URL de base est toujours https://app.snipcart.com/api.

Table des matières

GET /orders/{token}/notifications

Retourne la liste des notifications appartenant à la commande, les plus récentes en premier.

URL de la ressource

GET https://app.snipcart.com/api/orders/{token}/notifications

En-têtes

Nom Obligatoire? Description
Accept Oui Doit être application/json. L'API ne retourne que du JSON.

Paramètres de chemin

Nom Obligatoire? Type Description
token Oui guid Le jeton de la commande. Doit être un GUID valide.

Paramètres de requête

Nom Obligatoire? Type Description
offset Non integer Le nombre d'éléments à ignorer. La valeur par défaut est 0.
limit Non integer Le nombre maximal d'éléments à retourner. La valeur par défaut est 20.

Exemple de requête 

curl "https://app.snipcart.com/api/orders/{token}/notifications?offset=0&limit=10" \
  -H "Accept: application/json" \
  -u {API_KEY}:

Exemple de réponse 

{
  "totalItems": 3,
  "offset": 0,
  "limit": 10,
  "sort": [],
  "items": [
    {
      "id": "0c3ac0bb-a94a-45c5-a4d8-a7934a7f180a",
      "creationDate": "2017-07-09T14:59:57.987Z",
      "type": "Comment",
      "deliveryMethod": "None",
      "message": "Customer called to confirm shipping address."
    },
    {
      "id": "8a52d2c5-acbe-478d-8e96-06fbd6755efe",
      "creationDate": "2017-07-09T14:38:39.227Z",
      "type": "Comment",
      "deliveryMethod": "Email",
      "body": "Email HTML body will appear here...",
      "message": "Thanks for your order!",
      "subject": "Information regarding your order SNIP4962 on Snipcart.",
      "sentOn": "2017-07-09T14:38:39.947Z"
    },
    {
      "id": "e013a0d8-dbc2-45dc-85e5-900c0ce55da7",
      "creationDate": "2017-06-07T19:09:29Z",
      "type": "Invoice",
      "deliveryMethod": "Email",
      "body": "Invoice HTML will appear here...",
      "subject": "Order SNIP4962 on Snipcart",
      "sentOn": "2017-06-07T19:09:31.933Z"
    }
  ]
}

⚠️ Important : Les champs sont omis de la réponse lorsqu'ils n'ont aucune valeur. Une notification privée (par exemple un Comment dont le deliveryMethod vaut None) ne comprendra pas subject, body ni sentOn. Seuls creationDate et type sont toujours présents.

POST /orders/{token}/notifications

Crée une nouvelle notification sur la commande. Selon le type et le deliveryMethod, la notification peut être envoyée par courriel au client ou rester privée pour un usage interne. La notification créée est retournée.

URL de la ressource

POST https://app.snipcart.com/api/orders/{token}/notifications

En-têtes

Nom Obligatoire? Description
Accept Oui Doit être application/json.
Content-Type Oui Doit être application/json. Le corps de la requête est en JSON.

Paramètres de chemin

Nom Obligatoire? Type Description
token Oui guid Le jeton de la commande. Doit être un GUID valide.

Paramètres du corps

Nom Obligatoire? Type Description
type Oui enum Le type de notification. L'une des valeurs suivantes : Other, Invoice, Comment, TrackingNumber, OrderCancelled, Refund, OrderShipped, OrderReceived, OrderPaymentExpired, OrderStatusChanged, RecoveryCampaign, DigitalDownload, Logs, SubscriptionV3PaymentFailed, SubscriptionV3Cancelled, WithdrawalConfirmation, WithdrawalAccepted, WithdrawalDeclined. Utilisez Comment pour joindre une note libre (envoyée par courriel au besoin). Consultez le tableau d'envoi ci-dessous pour savoir quels types produisent un courriel.
deliveryMethod Non enum Mode d'envoi de la notification. L'une des valeurs suivantes : None (privée, aucun courriel), Email (envoyée au client), Bcc (utilisée avec Invoice pour mettre le marchand en copie conforme invisible). La valeur par défaut est None lorsqu'elle est omise.
message Non string Le message libre de la notification. Le plus pertinent pour Comment.
subject Non string L'objet du courriel. Pour les types qui produisent un courriel, il est normalement généré à partir d'un modèle, mais vous pouvez fournir le vôtre.
body Non string Le corps de la notification. Pour les types qui produisent un courriel, le HTML rendu est rempli automatiquement à l'envoi.
refundId Non guid Lie la notification à un remboursement existant sur la commande (utilisé avec le type Refund).

Types de notification et envoi par courriel

Le deliveryMethod ne déclenche un courriel réel que pour les types ci-dessous. Les autres types sont journalisés sur la commande, mais ne sont jamais envoyés par courriel même si le deliveryMethod vaut Email — le service d'envoi les associe à une opération sans effet.

type Envoyé par courriel si deliveryMethod vaut Email?
Comment Oui
Invoice Oui (prend aussi en charge Bcc)
Refund Oui
TrackingNumber Oui
OrderShipped Oui
OrderReceived Oui
OrderPaymentExpired Oui
DigitalDownload Oui
SubscriptionV3PaymentFailed Oui
SubscriptionV3Cancelled Oui
WithdrawalConfirmation Oui
WithdrawalDeclined Oui
Other Non (journalisé seulement)
OrderCancelled Non (journalisé seulement)
OrderStatusChanged Non (journalisé seulement)
RecoveryCampaign Non (journalisé seulement)
Logs Non (journalisé seulement)
WithdrawalAccepted Non (journalisé seulement)

⚠️ Important : Si l'envoi du courriel échoue, la notification est tout de même enregistrée sur la commande, mais son deliveryMethod est réinitialisé à None et sentOn reste vide. Vérifiez la réponse pour confirmer que le message a bel et bien été envoyé.

Exemple de requête 

curl https://app.snipcart.com/api/orders/{token}/notifications \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u {API_KEY}: \
  -d '{"type": "Comment", "deliveryMethod": "Email", "message": "Thanks for your order!"}'

Exemple de réponse 

{
  "id": "bff8418c-1ed2-4ba1-8b40-2a8bbf7dfadc",
  "creationDate": "2017-07-09T15:04:27.097Z",
  "type": "Comment",
  "deliveryMethod": "Email",
  "body": "The rendered email HTML will appear here...",
  "message": "Thanks for your order!",
  "subject": "Information regarding your order SNIP4962 on Snipcart.",
  "sentOn": "2017-07-09T15:04:27.490Z"
}