Commit 87cf3bda authored by Karamel's avatar Karamel
Browse files

Add some help texts in the fiscal access.

parent 93122177
......@@ -508,3 +508,39 @@ $app->POST('/fiscal/import',
fiscalTPL($ptApp, $response, 'imported.php', $apiResult);
return $response;
});
$app->GET('/fiscal/help/tickets',
function ($request, $response, $args) {
$ptApp = $this->get('settings')['ptApp'];
$response = fiscalLogin($this, $ptApp, $request, $response);
if ($ptApp->getCurrentUser() == null) {
fiscalTpl($ptApp, $response, 'login.php');
} else {
fiscalTpl($ptApp, $response, 'help_tickets.php');
}
return $response;
});
$app->GET('/fiscal/help/archives',
function ($request, $response, $args) {
$ptApp = $this->get('settings')['ptApp'];
$response = fiscalLogin($this, $ptApp, $request, $response);
if ($ptApp->getCurrentUser() == null) {
fiscalTpl($ptApp, $response, 'login.php');
} else {
return fiscalTpl($ptApp, $response, 'help_archives.php');
}
return $response;
});
$app->GET('/fiscal/help/issues',
function ($request, $response, $args) {
$ptApp = $this->get('settings')['ptApp'];
$response = fiscalLogin($this, $ptApp, $request, $response);
if ($ptApp->getCurrentUser() == null) {
fiscalTpl($ptApp, $response, 'login.php');
} else {
return fiscalTpl($ptApp, $response, 'help_issues.php');
}
return $response;
});
<?php
function render($ptApp, $data) {
$ret = '<h1>Génération et lecture des archives</h1>';
$ret .= "<p>Les archives sont des export des tickets fiscaux d'une date à une autre, signées avec le protocole OpenPGP. L'archive signée doit d'abord être déchiffrée avant de pouvoir être lue. Ce déchiffrage assure la conformité avec le fichier d'origine.</p>";
$ret .= "<p>Les archives servent à conserver les tickets fiscaux en dehors de Pastèque, de manière autonome. Ces données devant être conservée pendant 6 ans, y compris en cas de clôture du compte Pastèque. Il revient aux utilisateurs de conserver une copie des archives, voir plusieurs pour assurer leur pérénité en cas de perte ou corruption du support.</p>";
$ret .= "<h2>Génération d'une archive</h2>";
$ret .= "<p>Sur la page d'accueil, indiquez une date de début et de fin que couvrira l'archive. Cette période ne peut être supérieure à un an. La demande est enregistrée et placée en attente. La génération d'archives pouvant être une opération lourde, celle-ci n'est pas effectuée immédiatement. Celles-ci peuvent être générées pendant la nuit par exemple. Consultez votre codestaire Pastèque pour plus d'informations sur les délais de génération des archives.</p>";
$ret .= "<p>Une fois l'archive générée, la demande est effacée et l'archive elle-même devient disponible sur la page d'accueil. Chaque archive est numérotée et signée.</p>";
$ret .= "<h2>Lecture d'une archive</h2>";
$ret .= "<p>Après avoir téléchargé l'archive, vous obtenez un fichier archive-pasteque-#.gpg, avec # le numéro de l'archive. Ce fichier doit d'abort être déchiffré avant de pouvoir être ouvert. Le déchiffrement se fait à l'aide de la clé publique que vous a fourni le codestataire Pastèque ainsi qu'un logiciel OpenPGP, tel que <a href=\"https://www.gnupg.org\" target=\"_blank\">GnuPG</a>. Le exemples de commandes se basent sur ce logiciel.</p>";
$ret .= "<h3>Importer la clé publique</h3>";
$ret .= "<p>L'import de la clé publique dans le trousseau OpenPGP n'est à effectuer qu'une fois. La clé sera ensuite disponible pour toutes les archives. L'import s'effectue avec la commande <code>gpg --import &lt;clé_publique.pgp&gt;</code>.</p>";
$ret .= "<p>Une fois importée, la clé publique est disponible pour le déchiffrement. Elle figure dans la liste des clés obtenue avec la commande <code>gpg --list-keys</code>.</p>";
$ret .= "<h3>Déchiffrer l'archive</h3>";
$ret .= "<p>Pour déchiffrer une archive, utilisez la commande <code>gpg --output archive_pasteque_#.zip --decrypt archive_pasteque_#.gpg</code> avec # le numéro de l'archive pour correspondre au nom du fichier. Vous obtiendrez ainsi le fichier zip correspondant à l'archive déchiffrée. Conservez le fichier <code>.gpg</code> d'origine pour pouvoir réitérer l'opération et ainsi garantir que le fichier résultant est bien conforme à l'archive originale. En effet c'est le déchiffrement avec la clé publique du prestataire qui assure la conformité du fichier avec l'archive originale.</p>";
$ret .= "<p>Pour vérifier que l'archive est bien signée avec la clé du prestataire, utilisez la commande <code>gpg --verify archive_pasteque_#.gpg</code> et contrôlez les informations de signature.</p>";
$ret .= "<h3>Contenu d'une archive</h3>";
$ret .= "<p>L'archive zip contient plusieurs fichiers, chacun contenant des informations au format JSON. Le fichier <code>archive.txt</code> contient les informations relatives à l'archive elle-même :</p>";
$ret .= "<dl>";
$ret .= "<dt>account</dt><dd>Le nom du compte Pastèque auquel cette archive correspond. Il correspond à l'identifiant pour se connecter aux différents clients Pastèque.</dd>";
$ret .= "<dt>dateStart</dt><dd>Le début de la période que couvre cette archive. Les archives ne sont pas nécessairement dans l'ordre chronologique.</dd>";
$ret .= "<dt>dateStop</dt><dd>La fin de la période que couvre cette archive.</dd>";
$ret .= "<dt>number</dt><dd>Le numéro de l'archive. Il commence à 1 et s'incrémente de 1 pour chaque archive générée. Ce numéro permet de s'assurer qu'il ne manque pas une archive dans la série.</dd>";
$ret .= "<dt>generated</dt><dd>La date de génération de l'archive. Elle correspond à la date de la génération effective et non de la date de demande de création de l'archive.</dd>";
$ret .= "<dt>purged</dt><dd>Indique si cette archive est le résultat d'une purge des données ou non, si c'est le cas (true), les données de tickets présents dans cette archive ont été supprimés. Les tickets Z sont toujours conservés.</dd>";
$ret .= "</dl>";
$ret .= "<p>Les autres fichiers de l'archive contiennent les tickets fiscaux. Ils sont només de la façon suivante : XXX-YYY-Z.txt, avec XXX le type de tickets (tickets de vente, tickets Z), YYY le numéro de séquence (l'identifiant de caisse) et Z le numéro de la série. Lorsque la séquence contient beaucoup de tickets, celle-ci est divisée en plusieurs fichiers comme pour la pagination. Chacun de ces fichiers contient les tickets fiscaux au format JSON, comme présent dans l'interface fiscale.</p>";
return $ret;
}
<?php
function render($ptApp, $data) {
$ret = '<h1>Problèmes connus</h1>';
$ret .= "<p>Les tickets fiscaux étant immuables, les correctifs apportés à l'API ne peuvent pas être rétro-actifs. Certaines incohérences peuvent alors apparaître sur certains tickets. Cette page regroupe les problèmes connus sur les précédentes versions ainsi que leur impact sur les enregistrements. Le champ <em>version</em> des tickets fiscaux permet d'identifier la version de l'API au moment de l'enregistrement pour vérifier si une incohérence peut être expliquée par des bugs.</p>";
$ret .= "<h2>Versions 8.2 et précédentes</h2>";
$ret .= "<h3>Calcul des <em>custBalance</em></h3>";
$ret .= "<p>Le champ <em>custBalance</em> des tickets Z ne prend en compte que les montants positifs pour les tickets Z enregistrés avec le client Desktop. La balance client elle-même n'est par contre pas affectée et est calculée correctement ticket par ticket.</p>";
$ret .= "<p>Un script est disponible pour lister et corriger les enregistrements usuels en recalculant les balances du ticket Z à partir des tickets de la session.</p>";
$ret .= "<h2>Versions 8.1 et précédentes</h2>";
$ret .= "<h3>Chiffre d'affaire perpetuel</h3>";
$ret .= "<p>Le champ <em>csPerpetual</em> n'est pas présent dans les tickets Z. Lors de la mise à jour de l'API, le total perpetuel a été recalculé pour chaque caisse pour les sessions suivantes et a été recalculé pour les enregistrements usuels passés.</p>";
return $ret;
}
<?php
function render($ptApp, $data) {
$ret = '<h1>Description des tickets</h1>';
$ret .= '<h2>Tickets usuels et tickets fiscaux</h2>';
$ret .= "<p>Chaque ticket génère deux enregistrements. Le premier dit usuel est fortement structuré et peut évoluer au fil des ajouts de fonctionnalités ou des correctifs. Les enregistrements usuels sont utilisés par les interfaces de gestion pour effectuer des calculs. Le second dit fiscal est un instantanné au moment de l'enregistrement. Ceux-ci sont faiblement structurés et ne peuvent être modifiés en aucun cas. Ces enregistrements sont signés et leur intégrité peut être contrôlée. Les enregistrements présents sur cette interface sont les enregistrement fiscaux.</p>";
$ret .= '<h2>Séquences</h2>';
$ret .= "<p>Chaque caisse génère 2 séquences de tickets, et éventuellement deux séquences d'erreurs. Une séquence regroupe les tickets de ventes, l'autre les tickets Z. En cas d'erreur à l'enregistrement, un tickets d'erreur est inscrit dans la séquence d'erreur correspondante.</p>";
$ret .= "<p>Les champs en emphase correspondent à l'identification, le chiffre d'affaire et la TVA.</p>";
$ret .= "<p>Le contrôle de signature atteste de l'intégrité du contenu du ticket ainsi que son chaînage avec le ticket précédent.</p>";
$ret .= "<p>Chaque séquence dispose d'un enregistrement particulier qui porte toujours le numéro 0 et contient EOS (End Of Sequence). Cet enregistrement permet de contrôler l'exhaustivité de la séquence. Sa signature est chaînée au dernier ticket de la séquence.</p>";
$ret .= '<h2>Description des tickets de vente</h2>';
$ret .= "<h3>Champs généraux</h3>";
$ret .= '<dl>';
$ret .= '<dt><em>sequence</em></dt><dd>Indique le numéro de séquence de la session de caisse pendant laquelle le ticket a été enregistré.</dd>';
$ret .= "<dt><em>number</em></dt><dd>Le numéro du ticket. Celui-ci est lié à la caisse et n'est jamais remis à zéro.</dd>";
$ret .= "<dt><em>date</em></dt><dd>La date et l'heure de la vente.</dd>";
$ret .= "<dt>custCount</dt><dd>Le nombre de convives reseigné (optionnel).</dd>";
$ret .= "<dt><em>price</em></dt><dd>Le prix de vente hors taxes du ticket avant remise.</dd>";
$ret .= "<dt><em>taxedPrice</em></dt><dd>Le prix de vente TTC du ticket avant remise.</dd>";
$ret .= "<dt><em>discountRate</em></dt><dd>Le taux de remise appliqué au ticket.</dd>";
$ret .= "<dt><em>finalPrice</em></dt><dd>Le prix de vente host taxes du ticket.</dd>";
$ret .= "<dt><em>finalTaxedPrice</em></dt><dd>Le prix de vente TTC du ticket.</dd>";
$ret .= "<dt>custBalance</dt><dd>La variation du solde du compte client.</dd>";
$ret .= "<dt><em>cashRegister</em></dt><dd>La caisse sur laquelle la vente a été enregistrée.</dd>";
$ret .= "<dt>user</dt><dd>Le nom du compte avec lequel la vente a été enregistrée.</dd>";
$ret .= "<dt>version</dt><dd>La version de l'API au moment de l'enregistrement.</dd>";
$ret .= '</dl>';
$ret .= '<h3>Lignes du ticket</h3>';
$ret .= "<p>Les informations ligne à ligne sont regroupées dans le champ <em>lines</em>.</p>";
$ret .= '<dl>';
$ret .= "<dt>dispOrder</dt><dd>Le numéro de la ligne.</dd>";
$ret .= "<dt>productLabel</dt><dd>La désignation du produit</dd>";
$ret .= "<dt><em>unitPrice</em></dt><dd>Le prix unitaire hors taxes. Il n'est pas renseigné lorsque le montant TTC est utilisé pour les calculs de somme pour éviter les erreurs d'arrondis.</dd>";
$ret .= "<dt><em>taxedUnitPrice</em></dt><dd>Le prix unitaire TTC. Il n'est pas renseigné lorsque le montant hors taxes est utilisé pour les calculs de somme.</dd>";
$ret .= "<dt><em>quantity</em></dt><dd>La quantité.</dd>";
$ret .= "<dt><em>price</em><dt><dd>Le montant hors taxes de la ligne avant remise. Il n'est pas renseigné lorsque le montant TTC est utilisé pour les calculs de somme.</dd>";
$ret .= "<dt><em>taxedPrice</em><dt><dd>Le montant TTC de la ligne avant remise. Il n'est pas reseigné lorsque le montant hors taxes est utilisé pour les calculs de somme.</dd>";
$ret .= "<dt><em>taxRate</em><dt><dd>Le taux de TVA appliqué au moment de la vente.</dd>";
$ret .= "<dt><em>discountRate</em></dt><dd>Le taux de remise appliqué à la ligne.</dd>";
$ret .= "<dt><em>finalPrice</em><dt><dd>Le montant hors taxes de la ligne. Il n'est pas renseigné lorsque le montant TTC est utilisé pour le calcul de la somme.</dd>";
$ret .= "<dt><em>finalTaxedPrice</em><dt><dd>Le montant TTC de la ligne. Il n'est pas renseigné lorsque le montant hors taxes est utilisé pour le calcul de la somme.</dd>";
$ret .= '</dl>';
$ret .= '<h3>TVA</h3>';
$ret .= "<p>Les informations relative au montant de TVA total du ticket sont regroupées dans le champ <em>taxes</em>. Chaque taux de TVA dispose de son total.</p>";
$ret .= '<dl>';
$ret .= "<dt><em>base</em></dt><dd>Le montant hors taxes du ticket correspondant à ce taux de TVA.</dd>";
$ret .= "<dt><em>taxRate</em></dt><dd>Le taux de TVA.</dd>";
$ret .= "<dt><em>amount</em></dt><dd>Le montant de TVA associé à ce taux.</dd>";
$ret .= '</dl>';
$ret .= '<h3>Encaissements</h3>';
$ret .= "<p>Les informations relative aux encaissements du ticket sont regroupées dans le champ <em>payments</em>. Chaque encaissement dispose de ses propres informations. Il en va de même pour les éventuels rendus, avec des quantités négatives.</p>";
$ret .= "<p>Un ticket ne peut être enregistré que lorsque le montant des encaissements est égal ou supérieur au montant du ticket. Un ticket ne peut être enregistré avec un paiement partiel.</p>";
$ret .= '<dl>';
$ret .= "<dt>dispOrder</dt><dd>Le numéro du paiement</dd>";
$ret .= "<dt><em>amount</em></dt><dd>Le montant converti en devise principale encaissé ou rendu, lorsque négatif.</dd>";
$ret .= "<dt>currencyAmount</dt><dd>Le montant en devise encaissé ou rendu.</dd>";
$ret .= "<dt><em>paymentMode</em></dt><dd>La référence et désignation du mode de paiement utilisé.</dd>";
$ret .= "<dt>currency</dt><dd>La référence et désignation de la devise utilisée.</dd>";
$ret .= "<dt>type</dt><dd>Équivaut à la référence du mode de paiement (champ de compatibilité).</dd>";
$ret .= '</dl>';
$ret .= '<h3>Informations client</h3>';
$ret .= "<p>Lorsqu'un compte client est affecté au ticket, les informations du client sont listées dans le champ <em>customer</em>. Les champs reprennent les informations de la fiche client au moment de la vente.</p>";
$ret .= '<h3>Zone tarifaire</h3>';
$ret .= "<p>Lorsqu'une zone tarifaire, qui permet d'indiquer des tarifs alternatifs, est utilisée, elle est indiquée à titre informatif dans le champ <em>tariffArea</em>. Les prix effectifs sont indiqués dans les lignes du ticket.</p>";
$ret .= '<h3>Profil de remise</h3>';
$ret .= "<p>Lorsqu'un profil de remise, qui permet d'associer automatiquement un taux de réduction au ticket, est utilisé, il est indiqué à titre informatif dans le champ <em>discountProfile</em>. Le taux de remise indiqué dans les informations générales correspond au taux appliqué.</p>";
$ret .= '<dl>';
$ret .= "<dt>label</dt><dd>Le nom du profil de remise.</dd>";
$ret .= "<dt>rate</dt><dd>Le taux normalement associé à ce profil. Le taux de remise effectif est indiqué dans le champ <em>discountRate</em> du ticket.</dd>";
$ret .= '</dl>';
$ret .= '<h2>Tickets Z</h2>';
$ret .= "<p>Les tickets Z sont générés à chaque clôture de caisse. Ils comportent les données récapitulatives de la session ainsi que les données cumulatives. Ces cumuls sont remis à zéro lorsque la période est clôturée au lieu d'effectuer une clôture simple à la fin de la session de caisse. Le choix du type de clôture est manuel et laissé à la charge de l'utilisateur.</p>";
$ret .= '<h3>Informations générales</h3>';
$ret .= '<dl>';
$ret .= "<dt><em>sequence</em></dt><dd>Le numéro de séquence de la session. Il commence à 1 est est incrémenté à chaque session.</dd>";
$ret .= "<dt><em>continuous</em></dt><dd>Contrôle de continuité des sessions de caisse. Lorsqu'il est a false, cette session de caisse ne suit pas directement la précédente. Par exemple suite à un changement de matériel ou une réinstallation.</dd>";
$ret .= "<dt><em>openDate</em></dt><dd>La date et l'heure d'ouverture de la session.</dd>";
$ret .= "<dt><em>closeDate</em></dt><dd>La date et l'heure de clôture de la session.</dd>";
$ret .= "<dt>openCash</dt><dd>Le montant déclaratif du fond de caisse à l'ouverture.</dd>";
$ret .= "<dt>closeCash</dt><dd>Le montant déclaratif du fond de caisse à la clôture.</dd>";
$ret .= "<dt>expectedCash</dt><dd>Le montant attendu du fond de caisse à la clôture (fond à l'ouverture plus encaissements).</dd>";
$ret .= "<dt>ticketCount</dt><dd>Le nombre de tickets enregistrés durant la session.</dd>";
$ret .= "<dt>custCount</dt><dd>Le total du nombre de convives sur la session (optionel).</dd>";
$ret .= "<dt><em>cs</em></dt><dd>Le montant de chiffre d'affaire hors taxes réalisé pendant cette session.</dd>";
$ret .= "<dt><em>csPeriod</em></dt><dd>Le montant de chiffre d'affaire hors taxes réalisé sur la période.</dd>";
$ret .= "<dt><em>csFYear</em><dt><dd>Le montant de chiffre d'affaire hors taxes réalisé sur l'année fiscale.</dd>";
$ret .= "<dt><em>csPerpetual</em><dt><dd>Le montant de chiffre d'affaire hors taxes réalisé sur cette caisse. Ce montant n'est jamais remis à zéro.</dd>";
$ret .= "<dt>cashRegister</dt><dd>L'identification de la caisse.</dd>";
$ret .= "<dt>version</dt><dd>La version de l'API au moment de l'enregistrement.</dd>";
$ret .= '</dl>';
$ret .= '<h3>Encaissements</h3>';
$ret .= "<p>Les informations relative aux encaissements de la session sont regroupées dans le champ <em>payments</em>. Chaque mode d'encaissement dispose de ses propres informations.</p>";
$ret .= '<dl>';
$ret .= "<dt><em>amount</em></dt><dd>Le montant converti en devise principale.</dd>";
$ret .= "<dt>currencyAmount</dt><dd>Le montant en devise.</dd>";
$ret .= "<dt><em>paymentMode</em></dt><dd>La référence et désignation du mode de paiement utilisé.</dd>";
$ret .= "<dt>currency</dt><dd>La référence et désignation de la devise utilisée.</dd>";
$ret .= '</dl>';
$ret .= '<h3>TVA</h3>';
$ret .= "<p>Les informations relative aux montants de TVA collectés durant la session sont regroupées dans le champ <em>taxes</em>. Chaque taux de TVA dispose de son total.</p>";
$ret .= '<dl>';
$ret .= "<dt><em>base</em></dt><dd>Le montant hors taxes correspondant à ce taux de TVA.</dd>";
$ret .= "<dt><em>taxRate</em></dt><dd>Le taux de TVA.</dd>";
$ret .= "<dt><em>amount</em></dt><dd>Le montant de TVA associé à ce taux.</dd>";
$ret .= "<dt><em>basePeriod, baseFYear, amountPeriod, amountFYear</em></dt><dd>Les cumuls sur la période mensuelle (Period) et annuelle (FYear).</dd>";
$ret .= '</dl>';
$ret .= '<h3>Ventes par catégories</h3>';
$ret .= "<p>Les montants hors taxes réalisés par catégorie sont regroupés dans le champ <em>catSales</em>. Ces montants sont indicatifs et peuvent présenter quelques centimes d'écart par rapport au total de la session en raison de calculs intérmédiaires.</p>";
$ret .= '<dl>';
$ret .= "<dt>reference</dt><dd>L'identifiant de la catégorie.</dd>";
$ret .= "<dt>label</dt><dd>L'intitulé de la catégorie.</dd>";
$ret .= "<dt>amount</dt><dd>Le montant approximatif hors taxe associé à la catégorie.</dd>";
$ret .= '</dl>';
$ret .= '<h3>Ventes par catégories et TVA</h3>';
$ret .= "<p>Les montants de TVA regroupés par catégories sont regroupés dans le champ <em>catTaxes</em>. Ces montants sont indicatifs et peuvent présenter quelques centimes d'écart par rapport au total de la session en raison de calculs intérmédiaires.</p>";
$ret .= "<dt>reference</dt><dd>L'identifiant de la catégorie.</dd>";
$ret .= "<dt>label</dt><dd>L'intitulé de la catégorie.</dd>";
$ret .= "<dt>base</dt><dd>Le montant approximatif hors taxe associé à la catégorie et au taux de TVA.</dd>";
$ret .= "<dd>amount</dt><dd>Le montant approximatif de TVA associé.</dd>";
$ret .= "<dt>tax</dt><dd>Le nom de la taxe.</dd>";
$ret .= "<dt>taxRate</td><dd>Le taux de TVA.</dd>";
$ret .= '<h3>Balances client</h3>';
$ret .= "<p>Les variation de compte client sont regroupées dans le champ <em>custBalances</em>. Chaque client dispose de sa propre entrée.</p>";
$ret .= "<dt>balance</dt><dd>La montant de la variation du solde du compte client sur la session.</dd>";
$ret .= "<dt>customer</dt><dd>Les informations d'identification du compte client.</dd>";
return $ret;
}
......@@ -86,5 +86,11 @@ function render($ptApp, $data) {
$ret .= '<p><form method="POST" action="import" enctype="multipart/form-data">';
$ret .= '<input type="file" name="file" required="true" /> <input type="submit" value="Envoyer" /></form></p>';
}
$ret .= '<h2>Aide</h2>';
$ret .= '<ul>';
$ret .= '<li><a href="./help/tickets" target="_blank">Description des champs des tickets</a></li>';
$ret .= '<li><a href="./help/archives" target="_blank">Archives</a></li>';
$ret .= '<li><a href="./help/issues" target="_blank">Problèmes connus</a></li>';
$ret .= '</ul>';
return $ret;
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment