# Axonaut API v2 — Documentation de référence

**Base URL** : `https://axonaut.com/api/v2`
**Doc officielle** : https://axonaut.com/api/v2/doc
**Authentification** : Header `userApiKey` avec la clé API du compte

---

## Contexte Localiztoi

On n'édite **pas de facture Amazon via Axonaut**. L'intégration sert à :
1. **Destocker** les produits vendus (mise à jour quantité stock)
2. **Créer une observation/note** sur le produit ou la société avec les numéros IMEI

### Flux prévu
1. Commande Amazon traitée (IMEI scannés + FOTA OK)
2. → `PATCH /products/{id}/stock` pour diminuer la quantité
3. → `POST /events` (nature=6 Note) avec les IMEI dans le champ `content`

---

## Authentification

Toutes les requêtes nécessitent le header :
```
userApiKey: <votre_clé_api>
```

La clé est stockée dans notre table `api_keys` (provider: `axonaut`, label: `api_key`).

---

## Endpoints pertinents

### 1. Produits

#### GET /products
Récupérer tous les produits.

| Paramètre      | Type    | Emplacement | Description                    |
|-----------------|---------|-------------|--------------------------------|
| `page`          | integer | header      | Pagination                     |
| `internal_id`   | string  | query       | Filtre par ID interne          |
| `product_code`  | string  | query       | Filtre par code produit (SKU)  |
| `name`          | string  | query       | Filtre par nom                 |
| `with_disabled` | boolean | query       | Inclure les produits désactivés|

**Réponse** : Array de produits
```json
[
  {
    "id": 123,
    "internal_id": "LOC-001",
    "product_code": "FMC130",
    "name": "Teltonika FMC130",
    "description": "Boîtier GPS Teltonika FMC130",
    "price": 45.00,
    "tax_rate": 20.0,
    "type": 707,
    "disabled": false
  }
]
```

**Types de produit** :
- `601` = Matière première
- `701` = Produit fini
- `706` = Service
- `707` = Marchandise ← **notre cas**

#### GET /products/{productId}
Récupérer un produit spécifique par son ID Axonaut.

#### POST /products
Créer un produit.

```json
{
  "name": "Teltonika FMC130",
  "product_code": "FMC130",
  "price": 45.00,
  "tax_rate": 20.0,
  "type": 707
}
```

#### PATCH /products/{productId}
Mettre à jour un produit.

---

### 2. Stock

#### GET /products/{productId}/stock
Récupérer le stock actuel d'un produit.

**Réponse** :
```json
{
  "product_id": 123,
  "quantity": 50,
  "reserved": 5
}
```
- `quantity` : stock total disponible
- `reserved` : quantité réservée (devis en cours, etc.)

#### PATCH /products/{productId}/stock ⭐ ENDPOINT CLÉ
Mettre à jour le stock d'un produit (destockage).

**Body** :
```json
{
  "quantity": 45
}
```

> **IMPORTANT** : C'est une valeur absolue, pas un delta. Pour destocker, il faut :
> 1. `GET /products/{id}/stock` → récupérer `quantity` actuelle
> 2. Calculer `nouvelle_quantité = quantity - nb_articles_vendus`
> 3. `PATCH /products/{id}/stock` avec `{ "quantity": nouvelle_quantité }`

**Champs disponibles** :
- `quantity` (number) : nouveau stock total
- `reserved` (number) : nouveau stock réservé

> **Limitation** : Pas de champ commentaire/raison pour le mouvement de stock.
> C'est pour ça qu'on crée une observation/note séparée avec les IMEI.

---

### 3. Événements / Notes (Observations)

#### POST /events ⭐ ENDPOINT CLÉ
Créer un événement (note, appel, email, etc.) attaché à une société.

**Body** :
```json
{
  "company_id": 33,
  "title": "Destockage Amazon - Commande #AMZ-12345",
  "content": "Destockage de 3x FMC130.\n\nIMEI :\n- 352656100123456\n- 352656100123457\n- 352656100123458",
  "nature": 6,
  "date": "2024-01-15T10:30:00+01:00",
  "is_done": true
}
```

**Codes nature** :
| Code | Type        |
|------|-------------|
| 1    | Rendez-vous |
| 2    | Email       |
| 3    | Appel       |
| 4    | Courrier    |
| 5    | SMS         |
| **6**| **Note** ← notre cas |

**Champs complets** :
| Champ            | Type    | Description                                       |
|------------------|---------|---------------------------------------------------|
| `company_id`     | integer | ID de la société Axonaut (requis sauf si employee) |
| `employee_email` | string  | Email du contact (alternatif à company_id)         |
| `title`          | string  | Titre de l'événement                               |
| `content`        | string  | Contenu texte libre — **on y met les IMEI**        |
| `nature`         | integer | Type d'événement (1-6)                             |
| `date`           | string  | Date RFC3339                                       |
| `duration`       | integer | Durée en minutes                                   |
| `is_done`        | boolean | Marquer comme terminé                              |
| `opportunity_id` | integer | Lier à une opportunité                             |
| `users`          | array   | Liste d'utilisateurs associés                      |
| `attachments`    | object  | `invoices_ids`, `quotations_ids`, `documents_ids`  |

#### GET /events
Lister les événements avec filtrage par date.

| Paramètre        | Type   | Description              |
|-------------------|--------|--------------------------|
| `date[inf]`       | string | Date minimum             |
| `date[sup]`       | string | Date maximum             |
| `date[eq]`        | string | Date exacte              |
| `orders[date]`    | string | Tri par date             |

#### GET /companies/{companyId}/events
Lister les événements d'une société spécifique.

---

### 4. Sociétés

#### GET /companies
Lister les sociétés.

| Paramètre        | Type    | Description                          |
|-------------------|---------|--------------------------------------|
| `search`          | string  | Recherche par nom                    |
| `type`            | string  | `customer`, `prospect`, `supplier`, `all` |
| `is_customer`     | boolean | Filtre clients                       |
| `is_supplier`     | boolean | Filtre fournisseurs                  |
| `siret`           | string  | Filtre par SIRET                     |
| `address_city`    | string  | Filtre par ville                     |
| `sort`            | string  | `id`, `name`, `address_city`         |

#### GET /companies/{companyId}
Récupérer une société par ID.

#### POST /companies
Créer une société.

```json
{
  "name": "Amazon EU SARL",
  "is_customer": true,
  "currency": "EUR"
}
```

> Pour les B2C : ajouter `"isB2C": true` + données employé

#### PATCH /companies/{companyId}
Mettre à jour une société.

#### DELETE /companies/{companyId}
Supprimer une société. Réponse : `202 Accepted`.

---

### 5. Factures (référence, pas utilisé pour Amazon)

#### GET /invoices
Lister les factures.

| Paramètre              | Type    | Description               |
|--------------------------|---------|---------------------------|
| `number`                 | string  | Numéro de facture         |
| `date_before` / `after`  | string  | Filtre par date           |
| `is_paid`                | boolean | Filtre payé/non payé      |

#### POST /invoices
Créer une facture.

```json
{
  "company_id": 33,
  "date": "2024-01-15T00:00:00+01:00",
  "title": "Facture FMC130",
  "products": [
    {
      "product_id": 123,
      "quantity": 3,
      "price": 45.00
    }
  ]
}
```

> `company_id` OU `employee_email` requis.
> Types d'acompte : `1` = premier, `2` = acompte, `3` = solde

#### GET /invoices/{invoiceId}
Récupérer une facture.

---

### 6. Bons de livraison

#### GET /delivery-forms
Lister les bons de livraison.

#### POST /delivery-forms
Créer un bon de livraison à partir d'une facture.

```json
{
  "invoice_id": 456
}
```

#### GET /delivery-forms/{id}/download
Télécharger le PDF. Ajouter `?alt=media` pour le binaire brut.

---

### 7. Paiements

#### GET /payments
Lister les paiements de factures.

#### POST /payments
Créer un paiement.

**Codes nature** :
| Code | Mode           |
|------|----------------|
| 1    | Prélèvement    |
| 2    | Virement       |
| 3    | Chèque         |
| 4    | Carte bancaire |
| 5    | Espèces        |
| 6    | Autre          |

---

## Endpoints secondaires (non prioritaires)

| Endpoint                  | Méthode | Description                    |
|---------------------------|---------|--------------------------------|
| `/employees`              | GET/POST| Contacts/employés              |
| `/quotations`             | GET/POST| Devis                          |
| `/contracts`              | GET/POST| Commandes/contrats récurrents  |
| `/expenses`               | GET/POST| Dépenses                       |
| `/opportunities`          | CRUD    | Pipeline commercial            |
| `/tasks`                  | CRUD    | Tâches                         |
| `/projects`               | CRUD    | Projets                        |
| `/tickets`                | CRUD    | Support/tickets                |
| `/suppliers`              | CRUD    | Fournisseurs                   |
| `/supplier-contracts`     | GET/POST| Commandes fournisseur          |
| `/supplier-deliveries`    | GET/POST| Livraisons fournisseur         |
| `/bank-accounts`          | GET     | Comptes bancaires              |
| `/bank-transactions`      | GET     | Transactions bancaires         |
| `/tax-rates`              | GET     | Taux de TVA                    |
| `/accounting-codes`       | GET/POST| Codes comptables               |
| `/diverse-operations`     | GET     | Opérations diverses            |
| `/workforces`             | GET     | Effectifs                      |
| `/payslips`               | GET     | Bulletins de paie              |
| `/me`                     | GET     | Infos compte connecté          |
| `/customfields`           | GET     | Champs personnalisés           |
| `/users`                  | GET     | Utilisateurs du compte         |
| `/themes`                 | GET     | Thèmes                         |
| `/languages`              | GET     | Langues                        |

---

## Format des dates

- **RFC3339** pour la plupart des endpoints : `2024-01-15T10:30:00+01:00`
- **DD/MM/YYYY** pour certains filtres spécifiques (credits-history)

---

## Implémentation prévue dans Localiztoi

### Étape 1 : Mapping produits Axonaut ↔ SKU
- Rechercher les produits Axonaut via `GET /products?product_code=FMC130`
- Stocker le `product_id` Axonaut dans notre table `sku_mappings`

### Étape 2 : Destockage automatique
Quand une commande est finalisée (tous les IMEI scannés + FOTA OK) :
```
1. Pour chaque SKU de la commande :
   a. GET /products/{axonaut_id}/stock → récupérer quantité actuelle
   b. PATCH /products/{axonaut_id}/stock → { quantity: actuelle - nb_vendus }

2. POST /events (nature=6) sur la société "Amazon" :
   - title: "Destockage - Commande Amazon #XXX"
   - content: Liste des IMEI par produit
```

### Étape 3 : Vérification
- `GET /products/{id}/stock` pour confirmer le nouveau niveau de stock
- Log du mouvement dans notre base (traçabilité)