====== 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.

<WRAP important>
**Ne modifiez jamais directement les tables ''_paachat'' ou ''_pavente''.**

La mise à jour doit obligatoirement passer par l'API ''update_status''.
</WRAP>

===== API =====

<code python>
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]:
</code>

===== 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 :

<code>
tfqn = nom_de_la_table
vrsid = identifiant_auto_increment
</code>

==== 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.

<WRAP info>
Il faut utiliser **soit** le couple ''tfqn'' + ''vrsid'', **soit** ''pa_entity_id''.
</WRAP>

===== Paramètre ''remote'' =====

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

<code python>
remote=False
</code>

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''.

<code python>
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()
</code>

===== Retour de l'API =====

L'API retourne un tuple de trois valeurs :

<code>
(retcode, reterror, retlogid)
</code>

^ 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 ====

<code>
0, "ok", 15487
</code>

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 ====

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

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

<WRAP important>
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.
</WRAP>

===== 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'' |