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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.fincome.co/ressources/mapping-dintegration-et-api/mapping-dintegration-netsuite.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.