API PA - Mise à jour du statut

Principe

Pour mettre à jour le statut d'un PA, veuillez utiliser l'API suivante, notamment dans le cadre d'une post-action.

Cette API permet de :

garantir la traçabilité de l'action ;
vérifier la faisabilité du changement de statut ;
déclencher l'événement permettant de mettre effectivement à jour le statut sur le PA.

Ne modifiez jamais directement les tables _paachat ou _pavente.

La mise à jour doit obligatoirement passer par l'API update_status.

API

def update_status(
    usession,
    entity,
    newstatusid: int,
    tfqn=None,
    vrsid=None,
    pa_entity_id=None,
    remote=True,
    pa_tstamp=None,
    motifid=0
) -> tuple[int, str, int]:

Paramètres

Paramètre	Description
`usession`	Session avec une connexion BDD ouverte.
`entity`	Entité concernée : `“achat”` ou `“vente”`.
`newstatusid`	Nouveau statut principal. Exemple : `204` → `212`.
`tfqn`	Nom de la table contenant l'entité. À utiliser avec `vrsid`.
`vrsid`	Identifiant auto-incrémenté de l'entité dans la table `tfqn`. À utiliser avec `tfqn`.
`pa_entity_id`	Identifiant auto-incrémenté de l'entité dans la table `paachat` ou `pavente`. Alternative au couple `tfqn` + `vrsid`.
`remote`	Indique si le statut provient du PA. Pour une mise à jour locale, toujours utiliser `False`.
`pa_tstamp`	Timestamp du PA. Ne pas renseigner : la date courante sera utilisée automatiquement.
`motifid`	Statut secondaire / motif. Exemple : `21001`, `21002`, etc.

Identification de l'entité

L'entité à mettre à jour peut être identifiée de deux façons.

Avec ''tfqn'' + ''vrsid''

Utiliser :

tfqn = nom_de_la_table
vrsid = identifiant_auto_increment

Avec ''pa_entity_id''

Il est également possible de fournir directement l'identifiant auto-incrémenté de l'entité dans :

paachat pour un achat ;
pavente pour une vente.

Il faut utiliser soit le couple tfqn + vrsid, soit pa_entity_id.

Paramètre ''remote''

Pour une mise à jour effectuée localement, utilisez toujours :

remote=False

La valeur remote=True est réservée aux statuts reçus du PA.

Paramètre ''pa_tstamp''

Ne renseignez pas le paramètre pa_tstamp.

L'API utilisera automatiquement la date et l'heure courantes.

Exemple

Refus d'un achat avec le motif 21002

Dans cet exemple, l'achat passe au statut principal 210 avec le motif 21002.

import common
import pa_common
 
vses = common.dbses()
 
retcode, reterror, retlogid = pa_common.update_status(
    vses,
    "achat",
    210,
    tfqn="ez_facture_fournisseur",
    vrsid=345,
    remote=False,
    motifid=21002
)
 
vses.db.disconnect()

Retour de l'API

L'API retourne un tuple de trois valeurs :

(retcode, reterror, retlogid)

Valeur	Description
`retcode`	Code retour de l'opération.
`reterror`	Message d'erreur ou `“ok”` si l'opération a réussi.
`retlogid`	Identifiant de l'enregistrement de traçabilité (log).

Exemple de succès

0, "ok", 15487

Dans cet exemple :

0 indique que l'opération a réussi ;
“ok” indique qu'aucune erreur n'a été rencontrée ;
15487 est l'identifiant du log de traçabilité.

Exemple d'erreur

-5, "mise a jour de statut impossible pour ce statut : deja en cours de synchronisation", 0

Dans cet exemple, la mise à jour n'a pas été effectuée car le PA est déjà en cours de synchronisation.

En cas d'erreur, il convient de vérifier retcode et reterror. Le retlogid peut être égal à 0 lorsqu'aucune opération de traçabilité n'a été enregistrée.

Récapitulatif

Élément	Valeur / règle
API	`pa_common.update_status()`
Entité	`“achat”` ou `“vente”`
Statut principal	`newstatusid`
Motif / statut secondaire	`motifid`
Identification	`tfqn` + `vrsid` ou `pa_entity_id`
Mise à jour locale	`remote=False`
`pa_tstamp`	Ne pas renseigner
Modification directe des tables	Interdite
Retour	`retcode`, `reterror`, `retlogid`