204 lines
5.9 KiB
Markdown
204 lines
5.9 KiB
Markdown
# 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.
|