# Mapping d'intégration Netsuite

### Connexion à NetSuite

Suivez ces étapes pour connecter Fincome à NetSuite :

1. Assurez-vous que votre compte NetSuite est activé pour les Web Services REST et dispose du rôle/permissions approprié.
2. Obtenez les informations d'identification suivantes depuis votre compte NetSuite ou votre enregistrement d'intégration :
   * Account ID (remplacez `_` par `-` dans les URLs)
   * Client ID

> Remarque : Le connecteur implémente actuellement un flux Machine-to-Machine (client\_credentials / JWT). Les flux OAuth interactifs sont présents dans le code mais non encore implémentés. OAuth sera la méthode principale pour les WebServices NetSuite.

***

### Données synchronisées

| **Objet NetSuite**                       | **Champs clés synchronisés**                                                                                                                                         |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Clients                                  | id, entityId (nom), email                                                                                                                                            |
| Factures (transaction + lignes + devise) | invoice\_id, invoice\_number, customer\_id, date, status, invoice\_line\_item\_id, description, netamount, foreignamount, currency\_code, period\_start, period\_end |
| Devise                                   | symbol → currency\_code                                                                                                                                              |

***

### Comportement détaillé de l'intégration

* **Extraction SuiteQL**\
  Le connecteur compose des requêtes SuiteQL combinant les objets `transaction`, `transactionLine` et `currency`. Les champs sélectionnés sont codés en dur pour l’instant, mais pourraient devenir configurables à l’avenir.
* **Extraction incrémentale**

  L’intégration NetSuite supporte l’extraction incrémentale via le champ `last_modified_date`.
* **Authentification & rafraîchissement du token**
  * Les tokens d’accès expirent après une heure et sont automatiquement rafraîchis.
* **Classification des types de ligne**
  * Le connecteur NetSuite détermine si une ligne est `subscription` ou `one_off` selon le champ personnalisé `custcol_iw_item_revenue_category` et la validité des dates de période.
* **Gestion des devises**
  * Le connecteur récupère `currency.symbol` en tant que `currency_code`.
  * Si `netamount` et `foreignamount` existent tous deux, ce dernier peut être utilisé pour calculer les montants en devise d’origine ou devise de base selon les besoins.

***

### Points à savoir

* **Champs personnalisés utilisés**\
  Le connecteur utilise des champs personnalisés NetSuite (ex. `custcol_iw_rr_start_date`, `custcol_iw_rr_end_date`, `custcol_iw_item_revenue_category`). Si votre compte NetSuite utilise d’autres IDs, mettez à jour `fields_per_object`, `where_conditions` et la logique de mapping en conséquence.
* **Format des dates**\
  Le connecteur attend `JJ/MM/AAAA`. Adaptez l’OperationMap `Date` si NetSuite renvoie un format différent.
* **Pagination et offsets**\
  SuiteQL supporte `limit` et `offset`. Les synchronisations historiques volumineuses peuvent prendre du temps ; le connecteur met à jour le curseur et reprend automatiquement.
* **Portée & permissions**\
  L’intégration nécessite le scope `rest_webservices` et un compte/role avec accès lecture sur `transaction`, `transactionLine`, `currency` et les données clients.

***

### Vue d'ensemble de l'intégration

| **Élément**                  | **Détail**                                                        |
| ---------------------------- | ----------------------------------------------------------------- |
| Méthode d’intégration        | JWT client-assertion → OAuth2 token (Machine-to-Machine)          |
| Objets pris en charge        | customer, transaction (invoice), transactionLine, currency        |
| Fréquence de synchronisation | Incrémentale via curseur + rafraîchissement du token à la demande |
| Import initial               | Historique complet via SuiteQL avec pagination par offset         |
| Méthode de synchronisation   | Requêtes SuiteQL via NetSuite REST `query/v1/suiteql` endpoint    |
| Suppressions                 | Non propagées (soft-deletes à gérer séparément)                   |

### Paramètres & comportements des données

| **Paramètre**                | **Comportement**                                                                        |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| Format de date               | `%d/%m/%Y` via l’OperationMap `Date`                                                    |
| Mapping statuts facture      | `A` → open, `B` → paid, `D` → pending, autres ignorés                                   |
| Classification ligne facture | `custcol_iw_item_revenue_category` + dates de période                                   |
| Inversion des montants       | `netamount` actuellement inversé dans `IliAmount`                                       |
| Filtre                       | Factures avec `custcol_iw_item_revenue_category IS NOT NULL` et `netamount IS NOT NULL` |

### Mapping technique (NetSuite → Fincome)

#### Clients

| **NetSuite** | **Fincome**  |
| ------------ | ------------ |
| id           | original\_id |
| entityId     | name         |
| email        | email        |

#### Factures & Lignes

| **NetSuite**                    | **Fincome**                                                    |
| ------------------------------- | -------------------------------------------------------------- |
| t.id                            | original\_id (facture)                                         |
| t.number                        | invoice\_number                                                |
| t.entity                        | customer\_id                                                   |
| t.tranDate                      | date                                                           |
| t.status                        | status (via `InvoiceStatus`)                                   |
| tl.id                           | original\_id (ligne facture)                                   |
| tl.item                         | produit / référence                                            |
| tl.netamount                    | amount\_excluding\_tax\_after\_discount (inversé actuellement) |
| tl.foreignamount                | montant étranger optionnel                                     |
| tl.memo                         | description                                                    |
| tl.custcol\_iw\_rr\_start\_date | period\_start                                                  |
| tl.custcol\_iw\_rr\_end\_date   | period\_end                                                    |
| cur.symbol                      | currency\_code                                                 |

#### Avoirs

| **NetSuite**                              | **Fincome**                 |
| ----------------------------------------- | --------------------------- |
| transaction avec recordtype = credit note | original\_id (avoir)        |
| facture liée                              | invoice\_id                 |
| id ligne                                  | original\_id (ligne avoir)  |
| netamount                                 | amount (négatif)            |
| foreignamount                             | montant étranger optionnel  |
| memo                                      | description                 |
| start/end dates                           | period\_start / period\_end |
| currency.symbol                           | currency\_code              |