362 lines
11 KiB
Markdown
362 lines
11 KiB
Markdown
# 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é)
|