Menu de la documentation : Commandes de boutique

Commandes de boutique

Guides

Le connecteur d’une boutique envoie chaque commande et chaque remboursement tels que la boutique les détient. Tallio les convertit en document, l’émet via le prestataire du marchand et en suit l’état : la boutique ne construit jamais de document elle-même.

Sur cette page

Envoyer une commande
Statuts
Action requise
Remboursements
Demandes de facture
Factures grecques et registre de TVA
Corriger ou annuler
Numérotation française
Événements
Offres et utilisation
Effacement
Motifs

Remarque

Les commandes de boutique s’appellent avec la clé restreinte propre à la boutique (rk_…), qu’elle obtient quand son propriétaire la connecte à Tallio. Connecter une boutique explique les clés et ce qu’elles peuvent appeler.

Envoyer une commande #

Quand une commande est passée ou payée, envoyez-la avec POST /store_orders : le marchand (mer_…) et la commande telle que la plateforme la détient (lignes, taxes, livraison, frais, coupons, passerelle de paiement, acheteur). Tallio convertit une commande payée en reçu ou en facture et l’émet via la connexion du marchand dans le mode de la clé ; une clé de test sans connexion de test émet via la sandbox de Tallio. Une commande impayée est conservée et ignorée avec order_not_paid : relancez-la une fois payée.

Envoyer une commande payée

curl "$TALLIO_API_URL/v1/store_orders" \
  -H "Authorization: Bearer $TALLIO_STORE_KEY" \
  -H "Tallio-Store-Url: https://shop.example" \
  -H "Idempotency-Key: store:shop.example:order:1042" \
  -H "Content-Type: application/json" \
  -d @order.json

order.json

{
  "merchant": "mer_02y9O8rh7F50tGi0QcWRrx",
  "order": {
    "platform": "woocommerce",
    "platform_version": "11.2.1",
    "external_id": "1042",
    "number": "1042",
    "created_at": "2026-10-11T09:30:00.000Z",
    "paid_at": "2026-10-11T09:31:00.000Z",
    "cancelled": false,
    "refunded_total": "0",
    "test": false,
    "currency": "EUR",
    "prices_include_tax": true,
    "tax_rounding": "line",
    "total": "12.40",
    "lines": [
      {
        "external_id": "17",
        "name": "Espresso beans, 1 kg",
        "quantity": "1",
        "total": "10.00",
        "taxes": [
          {
            "rate_id": "1",
            "rate_percent": "24",
            "amount": "2.40"
          }
        ],
        "gift_card": false
      }
    ],
    "shipping_lines": [],
    "fee_lines": [],
    "coupons": [],
    "payment_gateways": [
      {
        "id": "cod",
        "title": "Cash on delivery"
      }
    ]
  }
}

Une commande de boutique par commande. Tallio en garde une par marchand, mode, plateforme et id de commande. Envoyer une commande qu’il détient déjà renvoie cette commande de boutique avec 200 sans la convertir à nouveau : un renvoi après une réponse perdue est donc sans risque. Utilisez aussi une clé d’idempotence par commande.
Tallio convertit, jamais la boutique. Les taxes, les arrondis, les moyens de paiement et l’acheteur sont lus dans la commande avec les paramètres de boutique du marchand. Une commande que Tallio ne peut pas convertir exactement est ignorée avec un motif, jamais émise au hasard.
Relisez-la. GET /store_orders/{id} renvoie le statut, le motif et son document, avec le numéro et, en Grèce, le MARK une fois émis. GET /store_orders liste les commandes de boutique du mode de la clé, les plus récentes d’abord.

Statuts #

pending : reçue, pas encore convertie, ou en attente d’envoi.
skipped : elle ne correspond à aucun document ; reason dit pourquoi.
sent : son document a été créé et est en route vers le prestataire.
issued : le document a été émis.
failed : le document a été rejeté, a échoué ou a été annulé, ou Tallio n’a pas pu le créer ; reason dit pourquoi.

Chaque commande de boutique ignorée ou en échec porte une reason lisible par une machine et une phrase detail pour le marchand (le tableau ci-dessous). warnings liste ce qu’il est utile de savoir sur un document émis : un centime d’arrondi, une ligne gratuite omise, le moyen de paiement par défaut de la boutique utilisé.

Action requise #

Une commande de boutique ignorée ou en échec qui attend le marchand a action_needed: true, et GET /store_orders?status=action_needed les liste, avec les commandes dont le remboursement attend. Les commandes ignorées qui ne demandent rien (une commande de test, rien à facturer, une vente française à déclarer) restent hors de la liste.

Nouvel essai. Quand retryable vaut true, la cause était extérieure à la commande (aucun prestataire connecté, un moyen de paiement à choisir, la limite de l’offre) et elle est maintenant corrigée : appelez POST /store_orders/{id}/retry avec la commande telle que la plateforme la détient maintenant. Un document en échec est renvoyé tel quel. Un nouvel essai ne crée jamais de second document.
Marquer comme traitée. Quand le marchand a émis le document à la main, POST /store_orders/{id}/mark_handled retire la commande de la liste ; son motif reste. Envoyez le motif que le marchand a vu : s’il a changé entre-temps, la réponse est 409 invalid_state, afin qu’un résultat plus récent ne soit jamais masqué sans avoir été lu.

Remboursements #

Envoyez chaque remboursement avec POST /store_orders/{id}/refunds. Tallio crédite exactement ce qui a été remboursé par un avoir lié au document de la commande : toute la vente, ses lignes, ou un montant sur une vente à taux unique. Un remboursement envoyé avant l’émission du document de la commande l’attend. Un remboursement que Tallio ne peut pas convertir est ignoré avec un motif et attend le marchand, qui émet l’avoir à la main et le marque comme traité avec POST /store_orders/{id}/refunds/{refundId}/mark_handled. Le champ refunds de la commande les liste, chacun avec son avoir.

Demandes de facture #

Un acheteur qui veut une facture donne son numéro de TVA (en France, son SIREN, son SIRET ou son numéro de TVA) et sa raison sociale. Saisis au paiement, ils voyagent dans invoice_request de la commande. Demandés après le paiement, sur la page de confirmation de commande ou dans le compte de l’acheteur, ils sont enregistrés avec PUT /store_orders/{id}/invoice_request. La commande peut être désignée par platform:external_id avant que la boutique ne l’ait envoyée, et lit alors la demande à son arrivée. Une fois le document de la commande créé, une demande ne change plus rien (409 already_issued) : le marchand réémet alors le document (l’appel de correction ci-dessous).

Factures grecques et registre de TVA #

Avant l’émission d’une facture grecque, Tallio recherche le numéro de l’acheteur dans le registre de TVA. Un numéro non enregistré fait ignorer la commande avec buyer_vat_not_registered. Quand le nom enregistré diffère de celui de la commande, ou que le registre ne le communique pas, ou que les paramètres de la boutique demandent de confirmer chaque facture, la commande attend avec invoice_awaiting_confirmation :

POST /store_orders/{id}/invoice_review renvoie l’acheteur tel que la facture le nomme à côté de la réponse du registre. Il ne change rien ; montrez les deux au marchand.
Quand registry.confirmable vaut true, POST /store_orders/{id}/confirm_invoice avec la commande telle qu’elle est maintenant et registry_hash émet la facture avec le nom et l’adresse enregistrés. Si le registre a changé entre-temps, la commande attend à nouveau une nouvelle vérification.

Corriger ou annuler #

Quand le marchand modifie une commande émise, ou que les coordonnées de l’acheteur changent, POST /store_orders/{id}/correct remplace le document par un document établi à partir de la commande telle qu’elle est maintenant. En Grèce, l’original est annulé dans myDATA, ou crédité en totalité s’il ne peut pas être annulé ; en France, il est crédité en totalité et une nouvelle facture est émise. POST /store_orders/{id}/cancel annule un document grec pour une vente qui n’a pas eu lieu ; une facture française n’est jamais annulée, seulement corrigée. Les champs correctable et cancellable de la commande de boutique indiquent ce que Tallio permet maintenant ; ne proposez que ces actions.

L’application Shopify et l’extension WooCommerce de Tallio appellent cette action « Réémettre » : le document n’est pas modifié, un nouveau document avec son propre numéro est émis à la date du jour, et l’ancien reste enregistré, annulé ou crédité. Présentez-la ainsi aux marchands et demandez-leur de modifier d’abord la commande dans la boutique.

Numérotation française #

Les factures et avoirs français des commandes de boutique sont numérotés par Tallio, en une série continue pour les factures et une pour les avoirs, par mode et par année, à partir des préfixes des paramètres de boutique du marchand (PATCH /merchants/{id}/store_settings). Un numéro attribué à un enregistrement qui ne donne finalement aucun document est conservé comme trou et listé dans voided_numbers, pour que la série puisse être justifiée.

Événements #

Tallio envoie store_order.updated quand le statut, le motif, l’indicateur « traitée », le document ou les remboursements d’une commande de boutique changent. Connecter une boutique crée ses endpoints de webhook, un par clé, limités à son marchand. Traitez l’événement comme un signal : vérifiez sa signature, puis relisez la commande de boutique. Une boutique dont l’hébergeur bloque les requêtes entrantes liste plutôt ses commandes de boutique récentes à intervalles réguliers.

Offres et utilisation #

Une équipe de boutique émet en live sans carte bancaire avec l’offre Free, jusqu’à 50 documents par mois, ou avec une offre boutique payante choisie par un propriétaire dans le tableau de bord. GET /store_usage renvoie l’offre, les documents live comptés sur la période et le plafond, pour que la boutique puisse prévenir le marchand à partir de 80 % du plafond. Au-delà du plafond, Tallio émet encore 10 % de plus ; à cette limite, les nouvelles commandes sont ignorées avec plan_cap_reached, que le marchand relance une fois l’offre changée ou la période suivante commencée. Les avoirs, les corrections et les documents en mode test ne sont jamais comptés.

Effacement #

Quand un acheteur demande l’effacement de ses données, POST /erasures avec store_orders (ses ids ord_…) supprime les données personnelles de l’acheteur que Tallio détient sur chaque commande : dans ses documents, dans les avoirs et corrections de ses remboursements, dans la demande de facture de l’acheteur et dans les requêtes journalisées à son sujet. Le prestataire reste l’archive des documents émis.

Motifs #

Chaque reason qu’une commande de boutique ou un remboursement peut porter, avec le detail que Tallio envoie et ce que fait le marchand. Seules les commandes font l’objet d’un nouvel essai : un remboursement qui attend le marchand est crédité à la main et marqué comme traité.

Motifs des commandes de boutique et des remboursements
Motif	Détail	Ce que fait le marchand
`non_eur_currency`	The store's currency is not the euro. No document was issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`test_order`	A test order is not a sale, so no document is needed. Nothing to do.	Rien ; hors de la liste « Action requise »
`non_greek_vat`	The sale is taxed outside Greece. No document was issued. Issue it by hand at your provider, or check the order's tax settings.	Émettre à la main, puis « Marquer comme traité »
`gift_card_line`	The order sells a gift card. A multi-purpose gift card is usually not taxed until it is spent; a single-purpose one is. Ask your accountant, and No document was issued. Issue it by hand at your provider if one is due.	Émettre à la main, puis « Marquer comme traité »
`gift_card_payment`	The order was paid with a gift card. No document was issued. Issue it by hand at your provider, with the payment method your accountant uses for gift cards.	Émettre à la main, puis « Marquer comme traité »
`unmapped_vat_rate`	A line has a VAT rate that is not a Greek rate. Check the product's tax settings. No document was issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`zero_rated_line`	A line carries no VAT and its exemption reason is not known. No document was issued. Issue it by hand at your provider, with the exemption that applies.	Émettre à la main, puis « Marquer comme traité »
`multiple_tax_rates_on_line`	A line carries more than one VAT rate. No document was issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`missing_tax_lines`	A line has no tax information. Check the product's tax settings. No document was issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`totals_mismatch`	The order's lines do not add up to its total. No document was issued. Issue it by hand at your provider, checking the amounts first.	Émettre à la main, puis « Marquer comme traité »
`rounding_out_of_bounds`	The order's rounding differs by more than a cent per line. No document was issued. Issue it by hand at your provider, checking the amounts first.	Émettre à la main, puis « Marquer comme traité »
`no_lines`	The order has nothing to invoice (no paid lines). Nothing to do unless you expected a document.	Rien ; hors de la liste « Action requise »
`too_many_lines`	The order has more lines than one document can hold. No document was issued. Issue it by hand at your provider, split into several documents.	Émettre à la main, puis « Marquer comme traité »
`invalid_quantity`	A line's quantity cannot go on a document. No document was issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`amount_out_of_range`	The order's amounts are beyond what a document can hold. No document was issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`empty_description`	A line has no title, SKU or product to describe it. Name the product. No document was issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`foreign_b2b_manual`	The buyer gave a VAT number from another EU country. No document was issued: issue the intra-EU invoice by hand at your provider (1.2 for goods, 2.2 for services).	Émettre à la main, puis « Marquer comme traité »
`sale_to_report`	A sale to a consumer: it is reported, not invoiced. Report it through your e-invoicing platform.	Rien ; hors de la liste « Action requise »
`foreign_b2b_to_report`	A sale to a business outside France: invoice it by hand and report it through your e-invoicing platform.	Émettre à la main, puis « Marquer comme traité »
`overseas_manual`	A sale to a French business in an overseas territory: issue the invoice by hand at your e-invoicing platform.	Émettre à la main, puis « Marquer comme traité »
`franchise_with_tax`	Your store charged VAT on this order, but your business is under the VAT franchise (no VAT number). Correct the taxes in your store and issue the invoice by hand.	Émettre à la main, puis « Marquer comme traité »
`fr_invoice_request_unusable`	The buyer asked for an invoice, but the details can't be used: no valid SIREN or French VAT number, or no company name. Check them with the buyer, who can send them again from the order status page, then press Retry; or issue the invoice by hand at your e-invoicing platform.	Corriger la cause, puis réessayer
`negative_fee_line`	The order has a negative fee (a discount added by a plugin), which no document line can carry. Give such discounts as coupons. No document was issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`payment_method_unknown`	The order's payment gateway does not say how it was paid (for example, it was marked as paid by hand), so no document was issued. In Settings, choose a method under Payment method, then press Retry. Otherwise issue the document by hand at your provider.	Corriger la cause, puis réessayer
`unsupported_original_type`	The original document is of a kind that is not credited automatically. Issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`original_customer_missing`	The original invoice has no customer to credit. Issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`invalid_original_mark`	The original document's MARK could not be read. Issue the credit by hand at your provider, against the original.	Émettre à la main, puis « Marquer comme traité »
`amount_only_adjustment`	The refund is only an amount adjustment, with no lines. Issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`order_adjustment_unsupported`	The refund includes an order adjustment that is not credited automatically. Issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`nothing_refunded`	The refund returned no money for any line. Nothing to do unless you expected a credit.	Rien ; hors de la liste « Action requise »
`exceeds_original`	The refunds of this order do not match its document (more than it, or a VAT rate it does not have). No document was issued: check the refunds, then issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`classification_ambiguous`	The original document's lines could not be matched to the refund. Issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`refund_below_lines`	Less money was refunded than the lines are worth (a restocking fee?). Issue the credit by hand at your provider for the amount refunded.	Émettre à la main, puis « Marquer comme traité »
`refund_above_lines`	More money was refunded than the lines are worth. Issue the credit by hand at your provider for the amount refunded.	Émettre à la main, puis « Marquer comme traité »
`refund_without_money`	The refund returned no money (a restock only?). Nothing to do unless you expected a credit.	Rien ; hors de la liste « Action requise »
`refund_pending`	The refund was not settled when it arrived, so no credit was issued. Once your store shows it settled, issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`refund_not_mappable`	The refund could not be matched to the sale's document, so no credit note was issued. Issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`amount_only_refund`	The refund is an amount with no items, and the sale has more than one VAT rate, so its VAT cannot be told. Refund by item in your store instead, or issue the credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`order_cancelled`	The order was cancelled before its document was made, so none was issued. Issue one by hand at your provider only if the sale went ahead.	Émettre à la main, puis « Marquer comme traité »
`fr_numbering_pending`	This invoice is held. Tallio issues it automatically with its French invoice number. There is nothing to do, and do not issue it by hand.	Rien ; hors de la liste « Action requise »
`snapshot_outdated`	The order reached Tallio from an earlier version of the store connector, in a form Tallio no longer reads. No document was issued. Issue it by hand at your provider.	Corriger la cause, puis réessayer
`order_not_paid`	The order was no longer marked paid when its document was due, so none was issued. Once it is paid, press Retry, or issue the document by hand at your provider.	Corriger la cause, puis réessayer
`merchant_tax_id_missing`	Your Tallio account has no ΑΦΜ (VAT number), and a document needs one, so none was issued. Contact Tallio support to add it, then press Retry, or issue the document by hand at your provider.	Corriger la cause, puis réessayer
`merchant_legal_id_missing`	Your business in Tallio has no SIREN, and an invoice needs one, so none was issued. Contact Tallio support to add it, then press Retry, or issue the invoice by hand at your e-invoicing platform.	Corriger la cause, puis réessayer
`merchant_regime_unsupported`	The app held this order under an earlier setup, so no document was issued. Press Retry to issue it, or issue it by hand at your provider.	Corriger la cause, puis réessayer
`fr_settings_missing`	Choose what your invoices cover (goods, services or both) in the French invoices section of Settings, then press Retry.	Corriger la cause, puis réessayer
`number_taken`	This invoice number is already used for your business in Tallio. Change the invoice number prefix in the French invoices section of Settings, then press Retry.	Corriger la cause, puis réessayer
`credit_number_taken`	This credit note number is already used for your business in Tallio. Change the credit note prefix in the French invoices section of Settings, and give credit notes you issue by hand a prefix of their own so they never meet Tallio's numbers. Then press Retry, or issue this credit note by hand.	Corriger la cause, puis réessayer
`provider_not_connected`	No e-invoicing provider was connected, or the provider refused its credentials, so no document was issued. Connect it again in Settings, then press Retry, or issue the document by hand at your provider.	Corriger la cause, puis réessayer
`refunded_before_issue`	The order was refunded before its document was made, so none was issued. Issue the sale and its credit by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`tallio_refused`	Tallio refused the document, so none was issued. If the cause was outside this order (for example in Settings), fix it and press Retry; otherwise issue it by hand at your provider.	Corriger la cause, puis réessayer
`plan_cap_reached`	Your plan reached this period's document limit, so no document was issued. Choose a larger plan, or wait for the next period, then press Retry. The document is dated the day you press it. You can also issue it by hand at your provider if the order shows no document in Tallio.	Corriger la cause, puis réessayer
`original_not_issued`	The refunded sale has no document issued by this app, so no credit note was made. Once the sale's document is issued, press Retry. Otherwise issue the credit by hand at your provider.	Rien ; crédité dès que le document de la commande est émis
`original_cancelled`	The sale's document was cancelled in Tallio, so no credit note was made. Credit the refund by hand at your provider if needed.	Émettre à la main, puis « Marquer comme traité »
`original_not_creditable`	Tallio would not credit the sale's document: it is credited already, or it was not issued through Tallio. Check the sale's documents at your provider, and issue the credit there by hand if none exists.	Émettre à la main, puis « Marquer comme traité »
`original_refused`	The buyer refused the sale's invoice (status 210, Refusée) or the platform rejected it (213, Rejetée), so no credit note (avoir) is issued for it. Cancel the invoice in your accounts, and if the sale goes ahead, issue a new invoice at your e-invoicing platform.	Émettre à la main, puis « Marquer comme traité »
`refund_expired`	The refunded sale has had no document for too long, or will never have one, so Tallio no longer keeps this refund to credit it. If the sale's document is issued, credit the refund by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`partial_refund`	The app did not credit this refund. Credit it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`credit_exceeds_balance`	The refund is more than what is left to credit on the sale's document, so no credit note was issued. Check the earlier credit notes at your provider.	Émettre à la main, puis « Marquer comme traité »
`buyer_vat_not_registered`	The VAT registry has no active registration for the buyer's VAT number (ΑΦΜ), so no invoice was issued. Check the number with the buyer. Once it is registered, or the buyer sends a corrected one, press Retry. Otherwise issue a retail receipt by hand at your provider.	Corriger la cause, puis réessayer
`invoice_awaiting_confirmation`	The buyer's VAT number (ΑΦΜ) is registered, and the invoice waits for you: the registry's name differs from the buyer's, the registry shares no name, or your settings ask to confirm every invoice. Open Review to compare them and issue the invoice with the registered details, or issue it by hand at your provider.	Vérifier et confirmer
`job_failed`	The document could not be confirmed after several attempts, and Tallio may already hold it. Press Retry: Tallio recognises a document it already holds and returns it rather than issuing it twice. Issue it by hand at your provider only if the order shows no document in Tallio; if this keeps happening, contact us.	Corriger la cause, puis réessayer
`document_rejected`	Your provider or the tax administration rejected the document Tallio sent, so it was not issued. Details shows their answer. Correct the document at your provider, or issue it by hand there.	Émettre à la main, puis « Marquer comme traité »
`document_retries_exhausted`	The provider refused this document after several attempts, so it was not issued. Issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`document_cancelled`	The document was cancelled in Tallio, so this order or refund has no document. If the sale stands, issue a new one at your provider.	Rien ; l’annulation l’a marqué comme traité
`document_invalid`	Tallio did not send this document: it cannot be sent as it is, and Details shows why. Sending the same document again gets the same answer, so issue it by hand at your provider.	Émettre à la main, puis « Marquer comme traité »
`document_failed`	Tallio could not issue this document through your provider. Details shows the provider's answer. Check your provider connection in Settings, then press Retry, or issue the document by hand at your provider.	Corriger la cause, puis réessayer