Préparation de la paie

Vérifiez les heures avant que quelqu'un ne soit payé.

La paie est le workflow financier qui tolère le moins d'erreur. Une mauvaise facture se corrige la semaine suivante. Un mauvais chèque de paie, c'est une personne qui ne peut pas payer son loyer, et c'est le moyen le plus rapide pour un patron de perdre son équipe. Tout dans cette compétence est construit autour de cette asymétrie : la machine assemble et vérifie, le patron décide.

Étape 1 — Corrigez la période avant toute chose

Confirmez les dates de début et fin de la période de paie, la date de paie, et qui figure dans cette exécution. Se tromper de période crée un doublon ou saute une semaine de paie pour quelqu'un, et c'est une erreur étonnamment facile quand une période chevauche une fin de mois.

Confirmez aussi la liste : nouvelles embauches qui ont commencé en milieu de période, quelqu'un de licencié, quelqu'un en congé. Voir reference/timesheet_intake.md.

Étape 2 — Récupérez les feuilles de temps

Avec Gusto connecté, demandez d'abord à Gusto lui-même ce qui se met en travers : appelez son vérificateur de blocages de paie (list_payroll_blockers) avant de construire quoi que ce soit. Si des blocages reviennent, traduisez chacun en anglais clair — ce que cela signifie, qui le corrige, et où. Par exemple : « check payments unsupported » signifie que cette entreprise paie par chèque papier, ce que l'intégration ne peut pas préparer, donc le patron exécute cette partie directement dans Gusto ; « bank account not connected via Plaid » signifie que le patron connecte la banque dans les paramètres de Gusto ; « hourly employees unsupported » peut être bloqué au niveau du compte même quand cette exécution est salariée uniquement. Les blocages sont un signal d'orientation, pas un échec — l'exécution est quand même construite et validée ici, et le livrable devient la feuille d'exécution avec la liste de blocages qui l'accompagne.

Puis récupérez les entrées de la période, chacune depuis son propre outil. Heures : list_time_records pour la période de paie ; lisez d'abord son champ source. native renvoie les équipes avec horodatage d'arrivée, de départ et pauses ; third_party renvoie les feuilles de temps du partenaire de suivi du temps de l'entreprise, et get_time_sheet donne les éléments par jour pour n'importe lequel d'entre eux (il refuse les ids de quart natifs) ; none signifie que Gusto n'a pas d'heures pour cette entreprise, donc le chemin de feuille de calcul ci-dessous les fournit. Congés : list_time_off_requests pour la période avec status: approved — chaque jour approuvé est payé comme congés payés ou maladie, jamais comme travaillé, et une demande en attente est un signal, pas un jour payé. Soldes : get_time_off_balances, c'est ce que la vérification « PTO au-delà du solde disponible » à l'étape 4 lit. Tarifs et classifications : la liste de Gusto de list_employees avec les compensations de chaque personne. Les tarifs viennent de Gusto, jamais d'une feuille de temps. Les formes d'appels pour celles-ci sont dans ../../shared/connector-call-shapes.md.

Un pointage manquant que le patron peut remplir. Quand l'étape 4 signale un quart sans horodatage de départ et que le patron donne les heures réelles, record_time les écrit — uniquement les heures que le patron a déclarées, affichées d'abord, et comme une update du quart existant plutôt qu'une deuxième entrée. Les paramètres qui refusent s'ils sont manquants (fuseau horaire, travail sur le propre suivi de Gusto, quel id compte comme le quart) et le piège de relecture (les heures confirmées d'un entrepreneur reviennent avec des heures d'horloge vides ; ne pas réécrire) sont dans la ligne record_time de ../../shared/connector-call-shapes.md. Lisez cette ligne avant l'appel. C'est la seule façon dont la compétence change jamais un pointage ; une heure supposée n'est jamais écrite.

Puis prouvez que la source renvoie ses données avant que quoi que ce soit soit préparer. Récupérez la liste (list_employees) et les calendriers (list_pay_schedules). Une entreprise qui rapporte un nombre d'employés tandis que l'une ou l'autre liste revient vide, ou un appel de blocages qui plante au lieu de répondre, est une source de paie connectée mais qui ne livre pas. Arrêtez le chemin de préparation, dites-le en une ligne (« Gusto est connecté mais n'a renvoyé aucun employé ni calendrier de paie, donc je ne peux pas préparer une exécution en fonction de cela »), et proposez le chemin de feuille de calcul ci-dessous. Ne construisez jamais une exécution à partir d'une liste vide, et ne traitez jamais un badge de connexion verte comme preuve que les données sont là.

Avec QuickBooks Payroll connecté, récupérez les mêmes champs de là. Deux échecs différents se ressemblent ici, et le patron les entend différemment. Une source vide (les listes de Gusto reviennent sans lignes sur une entreprise qui rapporte un nombre d'employés) est une lacune de données : dites-le et utilisez la feuille d'exécution. Une source qui se contredit est un défaut d'outil : qbo_payroll_get_company_payroll_readiness répondant has_employees: false et run_payroll_ready: false tandis que qbo_payroll_get_employees sur la même entreprise renvoie un total_count de 50 ne peuvent pas être tous deux vrais. C'est indépendant de la quantité de données que l'entreprise a. Quand cela arrive, utilisez la liste d'employés pour la liste (c'est l'appel qui a renvoyé les lignes), ne préparez pas une exécution tandis que la disponibilité dit pas prête, et dites les deux nombres au patron en une ligne afin que la contradiction soit enregistrée plutôt que cachée derrière « pas prête ». Puis prenez le chemin de feuille de calcul ci-dessous avec cette liste : une feuille d'exécution validée que le patron saisit dans QuickBooks Payroll est le résultat, identique à une source vide. C'est une source de première classe, pas un repli. Elle porte la liste complète d'employés avec le type de paie, le tarif et la fréquence, le statut d'emploi, et les soldes de politique de congés ; le calendrier de paie et sa fréquence ; et la dernière exécution complétée avec la paie brute, les heures et les lignes fiscales par employé. Là où les heures venaient d'une feuille de temps, l'enregistrement le dit, ce que les vérifications d'anomalies à l'étape 4 nécessitent.

Deux mises en garde spécifiques à cette source. Les employés ont un statut d'emploi distinct d'un signal actif, donc quelqu'un marqué actif peut toujours ne pas être sur la paie ou être en congé payé ; lisez les deux avant de mettre quelqu'un dans l'exécution. Et un employé peut tenir une douzaine de tarifs ou plus, la plupart assis à zéro heure, donc totalisez à partir du tarif qui a réellement des heures contre lui plutôt que le premier tarif listé.

Sans l'un ou l'autre, prenez une feuille de calcul ou un CSV téléchargé. C'est un chemin entièrement supporté — une feuille d'exécution validée que le patron saisit dans son fournisseur de paie est un résultat complet. De nombreuses petites équipes fonctionnent encore sur une feuille de temps papier photographiée à la fin de la semaine, et c'est aussi bien.

Normalisez en une ligne par personne par jour : date, entrée, sortie, pause, heures régulières, heures supplémentaires, congés payés, et le travail ou la classe si l'entreprise suit le travail aux travaux.

Étape 3 — Totalisez les heures

Calculez les heures régulières, supplémentaires, doubles, congés payés, jours fériés, et le temps non payé par personne, puis par équipe, puis pour l'exécution.

Les règles de surtemps varient selon l'État et selon la façon dont l'entreprise classe les gens, et les obtenir mal paie quelqu'un moins. Utilisez la règle déclarée du patron, et quand il n'y en a pas, utilisez le défaut de surtemps hebdomadaire simple et dites quelle règle vous avez appliquée. reference/anomaly_rules.md couvre les bords de calcul — changements de tarif en milieu de semaine, journées multi-travaux, et quarts traversant minuit.

Ne remplissez jamais un pointage manquant avec une heure supposée. Un quart avec un horodatage d'arrivée et aucun horodatage de départ a des heures inconnues, et les heures inconnues, c'est ce qui est rapporté.

Étape 4 — Signalez toute anomalie

C'est le cœur de la compétence. Exécutez la vérification complète dans reference/anomaly_rules.md et surfacez tout ce qu'elle trouve, chacun avec le nom de la personne, la date, et ce qui semble exactement mal :

• Pointages manquants et quarts sans horodatage de départ
• Surtemps au-dessus du modèle normal de cette personne, avec les deux nombres
• Zéro heure pour quelqu'un qui travaille normalement
• Heures bien au-delà de ce que le calendrier appelait
• Changements de tarif depuis la dernière exécution
• Entrées en doublon ou qui se chevauchent
• Congés payés pris au-delà du solde disponible
• Quelqu'un payé la dernière période qui manque de celle-ci
• Une nouvelle personne apparaissant sans registre d'embauche

Les signaux vont au patron. Ils ne sont jamais corrigés silencieusement. Un pointage manqué a une réponse réelle que seul l'employé et le patron connaissent, et une supposition plausible au milieu de cela devient un mauvais chèque de paie qui a l'air correct sur le rapport.

Étape 5 — Montrez l'exécution avant de l'approuver

Présentez la feuille d'exécution : personne par personne, heures par type, paie brute, et tous les signaux attachés à la personne à laquelle ils appartiennent. Puis les totaux — total heures, total brut, taxes patronales et contributions si disponibles, total en espèces nécessaires, et la date de paie.

Comparez à la période précédente et expliquez tout déplacement supérieur à 10 %. Une paie qui a augmenté de 4 000 USD a une raison, et le patron devrait l'entendre de cette compétence plutôt que de la trouver dans le solde bancaire.

Si des données de trésorerie sont disponibles, dites si l'exécution s'effectue. Si ce n'est pas disponible, dites-le simplement au lieu de l'impliquer c'est bien.

Étape 6 — Résolvez les signaux, un par un

Guidez le patron à travers chaque signal. Pour chacun : ce qui a été trouvé, ce que cela signifierait si cela restait comme ça, et ce qu'il veut faire. Enregistrez la réponse et appliquez-la.

Ne groupez pas les signaux dans une seule question « c'est bon ? ». Chacun est la paie d'une personne.

Étape 7 — La porte d'approbation

Rien n'est préparer jusqu'à ce que le patron approuve explicitement l'exécution.

Dites clairement avant de demander : nombre de personnes, total heures, total brut, total en espèces quittant le compte, la date de paie, et le nombre de signaux qu'ils ont choisi de laisser ouvert.

Puis demandez. Un patron qui veut contourner cette porte devrait être dit, une fois et sans faire de sermon, que cela reste parce qu'une mauvaise exécution n'est pas quelque chose qu'il peut annuler après que le virement direct arrive.

Avec Gusto connecté, préparez l'exécution : trouvez le bulletin de paie non traité avec list_payrolls filtré sur processing_statuses: unprocessed et un end_date quelques semaines devant (son filtre de date est sur la période de paie, et un appel simple peut manquer une période qui n'a pas encore pris fin), prenez celui avec la date de chèque la plus proche, lisez-le avec get_payroll, puis écrivez les heures approuvées, les congés payés, et toutes les lignes de bonus avec update_payroll. Deux formes sont importantes et les deux sont dans ../../shared/connector-call-shapes.md : les valeurs remplacent plutôt que d'ajouter, donc « donne à Maria cinq heures de plus » signifie envoyer son nouveau total, montré au patron comme « 40 → 45 » d'abord ; et un bulletin de paie dont la liste n'est pas encore matérialisée prend un appel update_payroll vide pour la peupler avant le véritable. Laissez run_payroll tranquille — c'est le bouton du patron, dans Gusto. Avec QuickBooks Payroll connecté, le connecteur maintient les lectures (liste, tarifs, calendriers, disponibilité, dernière exécution) et aucune écriture de préparation d'exécution, donc le résultat là est la feuille d'exécution validée que le patron saisit ; c'est ce que le connecteur maintient aujourd'hui, pas un chemin moindre. Le patron la soumet dans l'un ou l'autre système. Sans l'un ou l'autre, produisez la feuille d'exécution validée pour saisie manuelle. Si les blocages de Gusto de l'étape 2 empêchent la préparation via la connexion, la feuille d'exécution validée plus la liste de blocages en anglais clair est le résultat — dites-le sans traiter cela comme un échec.

Étape 8 — Synchronisez avec les livres

Après que l'exécution soit soumise, publiez l'entrée de journal dans le grand livre : salaires bruts, taxes patronales, et tout travail alloué aux travaux. Testez la capacité, pas le logo : un grand livre connecté dont le connecteur n'a aucun chemin d'écriture de journal ne peut pas accepter la publication, donc dites-le en une ligne et donnez l'entrée équilibrée au patron ou au comptable pour saisir — un résultat complet, pas un échec. Confirmez que les montants correspondent à ce qui a réellement couru, pas ce qui a été proposé — ceux-ci diffèrent quand le patron a édité quelque chose à la dernière étape.

Ce qu'il faut ne pas faire

• Ne devinez jamais un pointage, un tarif, ou une classification. Les heures inconnues sont nommées avec la personne et la date.
• Ne corrigez pas une anomalie silencieusement, même une évidente. Le patron peut savoir quelque chose que vous ne savez pas.
• Ne soumettez pas la paie. Préparez-la ; le patron la soumet. run_payroll n'est jamais appelé par cette compétence. Cela s'applique à QuickBooks Payroll exactement comme à Gusto — un système de paie connecté n'est pas une permission pour exécuter la paie.
• N'envoyez pas un delta à update_payroll. Ses valeurs remplacent. Calculez le nouveau total à partir de get_payroll, montrez les deux nombres, envoyez le total.
• N'écrivez pas un pointage que le patron n'a pas déclaré. record_time ne porte que les heures que le patron a données, et uniquement après qu'il ait vu l'entrée.
• Ne lisez pas un tarif de paie sans vérifier les heures contre lui. Dans QuickBooks Payroll, une personne peut avoir de nombreux tarifs avec zéro heure sur la plupart d'entre eux.
• N'enfouissez pas les signaux dans un résumé. Attachez chacun à la personne qu'il affecte.
• Ne groupez pas la révision des signaux. Une décision par personne par problème.
• Ne traitez pas un connecteur manquant comme un blocage. Une feuille de calcul rentrée, une feuille d'exécution validée sortie, est un chemin conçu.
• Ne sautez pas la comparaison de la période précédente. Un mouvement important sans explication est l'avertissement le plus utile disponible.
• Ne préparez pas une exécution à partir d'une source de paie qui rapporte les employés mais n'en renvoie aucun. Un badge connecté n'est pas des données. Dites que la source ne livre pas, et utilisez le chemin de feuille de calcul.
• Ne reproduisez pas le numéro de sécurité sociale d'un employé, la date de naissance, l'adresse personnelle, ou le numéro de compte ou de carte d'une personne dans la feuille d'exécution, le chat, ou toute page rendue. Les charges Gusto et QuickBooks Payroll les portent ; lisez au-delà d'elles (../../shared/personal-data.md).

Sortie

Livrez la feuille d'exécution validée selon la préférence de sortie stockée du patron — ne choisissez jamais par défaut un fichier markdown. Vérifiez le bloc ## Business context pour sa Output preference (règle du guide de style partagé, ../../shared/artifact-style.md) :

• Artefact visuel (le défaut) : rendez la feuille d'exécution en tant que page HTML dans le style maison — nombre d'employés, total brut, et espèces quittant le compte comme tuiles de statistiques, chaque personne une ligne avec les heures et la paie en tabular-nums, et un badge sur chaque signal attaché à la personne à laquelle il appartient. Les blocages, quand Gusto les rapporte, obtiennent leur propre panneau en anglais clair.
• Préférence docx / md / notion / canva : livrez le même contenu sous cette forme — un fichier DOCX ou markdown, une page Notion créée via le connecteur (destination nommée, jamais écrasante), ou un Canva Doc créé via le connecteur Canva (un nouveau design à chaque exécution, nommé avec la date ; les tableaux deviennent des listes) ; basculez sur l'artefact visuel si Notion ou Canva n'est pas connecté — et dites pourquoi.
• Mieux pour la compétence : utilisez l'artefact visuel — cette sortie est une feuille que le patron approuve personne par personne.

Après l'exécution

L'exécution est préparer, les signaux sont résolus, et l'entrée de livres est publiée. Si la trésorerie était le souci au départ, l'étape naturelle suivante est « puis-je effectuer la paie » — /plan-payroll exécute la prévision et la chasse aux factures devant la prochaine exécution. Aussi à proximité : « cash forecast » (cash-flow-snapshot) pour voir ce que cette exécution fait aux 30 prochains jours, et « taxes » (/tax-prep) quand les estimations trimestrielles ou 1099 approchent. Offrez au maximum trois, et sautez toute offre que le patron a déjà refusée cette session.

Fichiers de référence

• reference/timesheet_intake.md — extraction Gusto, téléchargement de feuille de calcul, configuration de liste et de période
• reference/anomaly_rules.md — chaque vérification, son seuil, et comment elle est formulée
• reference/run_sheet_format.md — le layout de la feuille d'exécution et le bloc de totaux
• reference/books_sync.md — structure d'entrée de journal et allocation de coût de travail
• reference/gotchas.md — les erreurs qui réduisent le paiement d'une personne ou double-paient une période

Utilisation d'un outil qui n'est pas listé

Les connecteurs nommés dans cette compétence sont les chemins testés, pas un mur. Si le patron veut que ce flux utilise un outil qui n'est pas connecté ou listé, offrez build-connector — il vérifie d'abord le répertoire de connecteurs et se connecte via Zapier autrement, ne construisant jamais manuellement contre une API brute. Une fois que la connexion existe, l'outil rejoint cette compétence comme tout autre connecteur optionnel, selon les mêmes portes d'approbation.