> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Créer et gérer des commandes

> Créez une commande depuis votre propre site, redirigez le client vers le paiement, et gérez le paiement, l'annulation et les remboursements.

Une commande (facture) contient les produits, le client et le prix. Le client paie sur la page hébergée `checkout_url`, où il choisit l'un des moyens de paiement acceptés par votre boutique.

Les commandes créées via l'API suivent les mêmes règles que votre vitrine : les prix proviennent de votre catalogue, le stock est réservé, les coupons et les règles produit s'appliquent, et les contrôles antifraude sont exécutés.

## Créer une commande

```bash cURL theme={"system"}
curl -X POST https://app.papelship.com/api/v1/invoices \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id" \
  -H "Idempotency-Key: 6f1c8a52-4f0e-4b8e-9a7c-2d1b3e5f7a90" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "buyer@example.com",
    "items": [
      { "product_id": "a1B2c3D4e5F6", "quantity": 1 },
      { "product_id": "Zx9Yw8Vu7Ts6", "variant_id": 881 }
    ],
    "coupon_code": "SUMMER10",
    "customer_ip": "203.0.113.10",
    "metadata": { "order_ref": "WEB-1042" }
  }'
```

```javascript Node.js theme={"system"}
const res = await fetch("https://app.papelship.com/api/v1/invoices", {
  method: "POST",
  headers: {
    "x-api-key": process.env.PAPELSHIP_API_KEY,
    "x-store-hash": process.env.PAPELSHIP_STORE_ID,
    "Idempotency-Key": order.id,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_email: order.email,
    items: [{ product_id: "a1B2c3D4e5F6", quantity: 1 }],
    customer_ip: order.ip,
    metadata: { order_ref: order.id },
  }),
});
const { invoice } = await res.json();
// Redirigez le client vers invoice.checkout_url
```

```python Python theme={"system"}
import os, requests

res = requests.post(
    "https://app.papelship.com/api/v1/invoices",
    headers={
        "x-api-key": os.environ["PAPELSHIP_API_KEY"],
        "x-store-hash": os.environ["PAPELSHIP_STORE_ID"],
        "Idempotency-Key": order_id,
    },
    json={
        "customer_email": "buyer@example.com",
        "items": [{"product_id": "a1B2c3D4e5F6", "quantity": 1}],
        "metadata": {"order_ref": order_id},
    },
)
invoice = res.json()["invoice"]
```

```json Réponse (201) theme={"system"}
{
  "success": true,
  "invoice": {
    "id": "c35ffd-19a1b2c3d4e-8c7a20",
    "object": "invoice",
    "status": "pending",
    "currency": "USD",
    "total_cents": 3499,
    "customer_email": "buyer@example.com",
    "source": "api",
    "metadata": { "order_ref": "WEB-1042" },
    "checkout_url": "https://app.papelship.com/invoice/c35ffd-19a1b2c3d4e-8c7a20",
    "expires_at": "2026-10-04T15:00:00.000Z",
    "items": [ ... ]
  }
}
```

Redirigez le client vers `checkout_url`. Les commandes impayées expirent au bout de 3 heures.

> [accordion] Champs que vous pouvez envoyer
>
> | Champ | Remarques |
> | :- | :- |
> | `customer_email` | Obligatoire. Reçoit l'e-mail de facture et la livraison. |
> | `items` | Obligatoire. De 1 à 50 lignes avec `product_id` (hash ID), `quantity`, et `variant_id` pour les produits avec variantes. |
> | `coupon_code` | Appliqué s'il est valide pour ces produits. |
> | `customer_ip` | L'adresse IP de l'acheteur. Active vos règles antifraude, VPN et liste de blocage pour cette commande. |
> | `expected_total_cents` | Vérification facultative. L'appel échoue avec `TOTAL_MISMATCH` si le prix a changé. |
> | `shipping_address`, `shipping_rate_id` | Produits physiques. Voir ci-dessous. |
> | `custom_fields` | Réponses à vos champs de paiement personnalisés. |
> | `affiliate_code` | Crédite un partenaire de votre programme d'affiliation. |
> | `send_email` | `false` pour ne pas envoyer l'e-mail de facture (`true` par défaut). |
> | `metadata` | Jusqu'à 20 paires clé/valeur de votre choix, sous forme de chaînes. |

> [accordion] Erreurs à la création
>
> | Code | Statut | Signification |
> | :- | :- | :- |
> | `PRODUCT_NOT_FOUND` | `404` | Un `product_id` ne fait pas partie de votre boutique. |
> | `OUT_OF_STOCK` | `409` | Stock insuffisant. `details.products` liste les produits manquants. |
> | `TOTAL_MISMATCH` | `409` | `expected_total_cents` ne correspond pas. `details.expected_total_cents` contient le total réel. |
> | `CURRENCY_MISMATCH` | `422` | Les produits ont des devises différentes, ou `currency` ne correspond pas. |
> | `INVALID_VARIANT` | `422` | `variant_id` manquant ou incorrect. |
> | `ADDRESS_INVALID` | `422` | Adresse de livraison incomplète. `details.fields` indique les champs concernés. |
> | `CUSTOMER_BLOCKED` | `403` | L'adresse e-mail ou l'adresse IP figure dans votre liste de blocage. |
> | `FRAUD_BLOCKED` | `403` | Vos règles antifraude ont rejeté la commande. |
> | `STORE_SUSPENDED` | `403` | La boutique ne peut pas accepter de commandes pour le moment. |

## Produits physiques

Pour les produits à expédier, ajoutez l'adresse. Obtenez d'abord les options avec `POST /shipping/quote`, ou omettez `shipping_rate_id` pour utiliser le tarif le moins cher.

```json theme={"system"}
{
  "customer_email": "buyer@example.com",
  "items": [{ "product_id": "Tsh1rtM3d1um", "variant_id": 2041, "quantity": 2 }],
  "shipping_address": {
    "full_name": "Alex Morgan",
    "phone": "+44 20 7946 0958",
    "country_code": "GB",
    "city": "London",
    "line1": "221B Baker Street",
    "postal_code": "NW1 6XE"
  },
  "shipping_rate_id": 12
}
```

Les frais de livraison sont ajoutés à `total_cents` et indiqués dans `shipping_cents`. Sans adresse, le client la saisit sur la page de paiement avant de payer. Après le paiement, expédiez la commande avec [`POST /orders/{invoiceId}/shipments`](https://developers.papelship.com/fr/user-api/fulfillment).

## Statuts de commande

| Statut | Signification |
| :- | :- |
| `pending` | En attente du paiement du client. |
| `payment_pending`, `payment_processing` | Le client a choisi un moyen de paiement ; le paiement est en cours. |
| `partial_payment` | Une partie du montant est arrivée (crypto). |
| `manual_review_pending` | Un paiement manuel attend votre vérification. |
| `completed` | Payée et livrée. |
| `cancelled` | Annulée avant le paiement. |
| `expired` | Non payée dans les délais. |

Écoutez le webhook `order.completed` plutôt que d'interroger l'API en boucle. Consultez [Webhooks](https://developers.papelship.com/fr/user-api/webhooks.md).

## Après la création de la commande

| Action | Point de terminaison | Quand |
| :- | :- | :- |
| Marquer comme payée | `POST /invoices/{id}/complete` | Vous avez reçu l'argent en dehors de PapelShip (virement bancaire, espèces). Livre les produits. |
| Annuler | `POST /invoices/{id}/cancel` | La commande est impayée. Libère le stock réservé. |
| Enregistrer un remboursement | `POST /invoices/{id}/refund` | Vous avez remboursé le client. Envoyez `amount_cents` pour un remboursement partiel. |
| Voir ce qui a été livré | `GET /invoices/{id}/deliveries` | Clés de licence, fichiers et notes envoyés au client. |
| Mettre à jour | `PATCH /invoices/{id}` | Modifier `metadata` ou `delivery_email`. |

> [!TIP]
>
> Utilisez l'identifiant de votre propre commande comme `Idempotency-Key` pour les appels de création, de finalisation et de remboursement. Ainsi, les nouvelles tentatives ne créent jamais de seconde commande ni de second remboursement.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.