# Amazon SP-API — Documentation de référence

## Authentification LWA (Login with Amazon)

OAuth2 standard. 3 credentials nécessaires :
- `client_id` (LWA Client ID) — depuis Seller Central > Developer
- `client_secret` (LWA Client Secret) — expire tous les 180 jours
- `refresh_token` — obtenu après auto-autorisation de l'app privée

### Obtenir un access_token

```http
POST https://api.amazon.com/auth/o2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=Atzr|...
&client_id=amzn1.application-oa2-client.xxx
&client_secret=xxx
```

Réponse :
```json
{
  "access_token": "Atza|...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

L'access_token expire après **1 heure**.

## Endpoints

**Base URL Europe :** `https://sellingpartnerapi-eu.amazon.com`
**URL LWA (globale) :** `https://api.amazon.com/auth/o2/token`

## Marketplace IDs

| Pays | MarketplaceId |
|------|--------------|
| **France** | **`A13V1IB3VIYZZH`** |
| Allemagne | `A1PA6795UKMFR9` |
| Italie | `APJ6JRA9NG5V4` |
| Espagne | `A1RKKUPIHCS9HS` |
| Belgique | `AMEN7PMS3EDWL` |

## Orders API

### GET /orders/v0/orders

Récupère la liste des commandes.

**Paramètres obligatoires :**
- `MarketplaceIds` — ex: `A13V1IB3VIYZZH`
- `CreatedAfter` OU `LastUpdatedAfter` — date ISO 8601

**Paramètres optionnels :**
- `OrderStatuses` — `Unshipped`, `PartiallyShipped`, `Shipped`, `Pending`, `Canceled`...
- `FulfillmentChannels` — `MFN` (expédié par le vendeur) ou `AFN` (FBA)
- `MaxResultsPerPage` — défaut 100
- `NextToken` — pagination

**Réponse :** `response.payload.Orders` (tableau)

### GET /orders/v0/orders/{orderId}/orderItems

Récupère les articles d'une commande.

**Réponse :** `response.payload.OrderItems` (tableau)

## Structure des données

### Order
```json
{
  "AmazonOrderId": "123-4567890-1234567",
  "PurchaseDate": "2026-02-18T14:30:00Z",
  "LastUpdateDate": "2026-02-18T15:00:00Z",
  "OrderStatus": "Unshipped",
  "FulfillmentChannel": "MFN",
  "SalesChannel": "Amazon.fr",
  "OrderTotal": { "CurrencyCode": "EUR", "Amount": "129.99" },
  "NumberOfItemsShipped": 0,
  "NumberOfItemsUnshipped": 2,
  "MarketplaceId": "A13V1IB3VIYZZH",
  "EarliestShipDate": "2026-02-19T00:00:00Z",
  "LatestShipDate": "2026-02-21T23:59:59Z"
}
```

### OrderItem
```json
{
  "ASIN": "B09XXXXXXXXX",
  "SellerSKU": "FMC920-FR-01",
  "OrderItemId": "12345678901234",
  "Title": "Traceur GPS FMC920",
  "QuantityOrdered": 2,
  "QuantityShipped": 0,
  "ItemPrice": { "CurrencyCode": "EUR", "Amount": "99.99" }
}
```

## Rate Limits

| Endpoint | Rate | Burst |
|----------|------|-------|
| `getOrders` | 1 req / 60 sec | 20 |
| `getOrder` | 1 req / 2 sec | 30 |
| `getOrderItems` | 1 req / 2 sec | 30 |

HTTP 429 en cas de throttling. Header `x-amzn-RateLimit-Limit`.

## SDK Node.js recommandé

Package `amazon-sp-api` (le plus simple, gestion auto du throttling + tokens) :

```bash
pnpm add amazon-sp-api
```

```typescript
import { SellingPartner } from 'amazon-sp-api'

const spClient = new SellingPartner({
  region: 'eu',
  refresh_token: '<REFRESH_TOKEN>',
  credentials: {
    SELLING_PARTNER_APP_CLIENT_ID: '<CLIENT_ID>',
    SELLING_PARTNER_APP_CLIENT_SECRET: '<CLIENT_SECRET>'
  },
  options: {
    auto_request_throttled: true
  }
})

const orders = await spClient.callAPI({
  operation: 'getOrders',
  endpoint: 'orders',
  query: {
    MarketplaceIds: ['A13V1IB3VIYZZH'],
    CreatedAfter: '2026-02-01T00:00:00Z',
    OrderStatuses: ['Unshipped', 'PartiallyShipped']
  }
})

const items = await spClient.callAPI({
  operation: 'getOrderItems',
  endpoint: 'orders',
  path: { orderId: '123-4567890-1234567' }
})
```

## Statuts de commande pertinents

- `Unshipped` — payée, rien expédié → **à traiter**
- `PartiallyShipped` — partiellement expédié
- `Shipped` — tout expédié
- `Canceled` — annulée

## Stockage des credentials (notre app)

Dans la table `api_keys`, même pattern qu'Axonaut :
- `provider=amazon`, `label=client_id`
- `provider=amazon`, `label=client_secret`
- `provider=amazon`, `label=refresh_token`

## Adresse de livraison

`GET /orders/v0/orders/{orderId}/address` — nécessite un **Restricted Data Token (RDT)** pour accéder aux PII (données personnelles).
L'adresse est nécessaire pour générer les étiquettes Colissimo.

## Notes vendeur / commentaires internes

**IMPORTANT : L'API SP-API ne permet PAS d'ajouter des notes vendeur ou commentaires internes sur une commande.**

### Ce qui n'existe PAS
- Aucun endpoint pour créer/modifier des notes sur une commande
- Aucun champ `seller_note`, `internal_note` ou `comment` dans l'API Orders v0 ou v2026-01-01
- Aucun feed POST_ORDER_ACKNOWLEDGEMENT_DATA avec support de notes personnalisées
- Les opérations disponibles se limitent à : `updateShipmentStatus`, `updateVerificationStatus`, `confirmShipment`

### Alternatives recommandées

1. **Stockage en base de données locale** (recommandé pour notre projet)
   - Créer une table `order_notes` liée à `orders` via `amazon_order_id`
   - Permet de stocker commentaires, IMEI scannés, statuts de traitement internes
   - Indépendant d'Amazon — aucune synchronisation possible

2. **Seller Central web interface** (manuel)
   - Seller Central propose une interface web pour ajouter des notes sur les commandes MFN
   - Ces notes ne sont PAS accessibles via l'API SP-API (lecture ni écriture)
   - Utilisation manuelle uniquement

3. **Champ BuyerCustomizedInfo** (lecture seule)
   - Contient des informations de personnalisation **côté acheteur** (texte gravure, etc.)
   - Nécessite un Restricted Data Token (RDT)
   - Lecture seule — ne peut pas être modifié par le vendeur

### Conclusion

Pour tracker les IMEI scannés, les statuts de préparation ou toute donnée interne liée à une commande Amazon, il est nécessaire de gérer ces informations dans notre propre base de données. Amazon SP-API ne fournit aucun mécanisme pour stocker des métadonnées vendeur personnalisées.