Commandes & logistique

Lorsque vous passez à Ultineo avec des années de ventes enregistrées dans un autre système, ces points d'accès permettent à votre outil de migration ou de synchronisation de rapatrier tout l'historique dans votre boutique — clients, commandes avec leurs lignes, paiements, expéditions, réclamations transporteur, colis refusés, remboursements, retours, mouvements de cagnotte de fidélité et demandes de support avec leurs messages — en conservant les dates d'origine, puis de relire n'importe quel enregistrement pour le vérifier.

Chaque import suit le contrat commun décrit dans Votre premier appel : une liste items, un dry_run facultatif et un rapport ligne par ligne. Chaque enregistrement est reconnu par son external_id — sa référence d'origine — si bien que le renvoyer le met à jour au lieu de créer un doublon.

Points d'accès

Importez dans cet ordre, car chaque enregistrement fait référence aux précédents : les clients, puis les commandes, puis les paiements et les expéditions, puis les remboursements, les retours, les réclamations transporteur, les colis refusés, les mouvements de cagnotte et les demandes de support. Un enregistrement qui fait référence à un autre pas encore importé est refusé, avec un reason qui nomme la référence manquante.

Ce que toutes les ressources ont en commun

• Les dates (created_at, placed_at, shipped_at…) sont des horodatages Unix en secondes. Le created_at que vous envoyez est conservé comme date d'origine de l'enregistrement et n'est jamais modifié par un import ultérieur. Si vous l'omettez, la plupart des ressources utilisent la date connue la plus proche, comme la date de la commande.
• Les liens vers d'autres enregistrements utilisent leur external_id : customer_external_id, order_external_id, shipment_external_id, etc.
• Les statuts sont contrôlés par rapport aux valeurs exactes listées ci-dessous, en minuscules. Un enregistrement retiré dans votre espace de travail conserve son statut : un import ne le rétablit jamais, et un notice le signale.
• Lire un enregistrement : GET avec ?external_id= (sa référence d'origine) ou ?id= (son identifiant dans votre boutique). Sans l'un ni l'autre, l'appel répond 400 ; un enregistrement absent de votre boutique répond 404.

Clients

Un client est un acheteur de votre boutique, avec une adresse de facturation et une adresse de livraison. Importez les clients en premier : tous les autres enregistrements de cette page y font référence.

Importer des clients

POST /v1/customer/import

Chaque adresse contient line1, line2 (jusqu'à 190 caractères), city (jusqu'à 120), postal_code (jusqu'à 30), state (jusqu'à 120) et country_iso — un code pays à deux lettres comme fr.

curl https://api.ultineo.com/v1/customer/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "C1001",
        "created_at": 1717236000,
        "first_name": "Claire",
        "last_name": "Martin",
        "email": "claire.martin@example.com",
        "email_verified": true,
        "phone": "+33 6 12 34 56 78",
        "delivery": {
          "line1": "12 rue des Lilas",
          "line2": "",
          "city": "Lyon",
          "postal_code": "69003",
          "state": "",
          "country_iso": "fr"
        }
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "customer",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "C1001", "action": "created", "id": "cust_c3e9a1074b5d28f6e0a7", "code": null, "title": null, "reason": null, "notice": ["blank billing initialized from delivery"] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire un client

GET /v1/customer/import

Sans l'un ni l'autre, l'appel répond 400 Name the customer to read: ?external_id=… or /v1/customer/cust_…. ; un client inconnu répond 404 Customer not found.

curl "https://api.ultineo.com/v1/customer/import?external_id=C1001" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "cust_c3e9a1074b5d28f6e0a7",
    "object": "customer",
    "external_id": "C1001",
    "status": "activated",
    "type": "individual",
    "first_name": "Claire",
    "last_name": "Martin",
    "name": "Claire Martin",
    "company": "",
    "email": "claire.martin@example.com",
    "email_verified": true,
    "phone": "+33 6 12 34 56 78",
    "has_password": false,
    "note": "",
    "billing": { "line1": "12 rue des Lilas", "line2": "", "city": "Lyon", "postal_code": "69003", "state": "", "country_iso": "fr" },
    "delivery": { "line1": "12 rue des Lilas", "line2": "", "city": "Lyon", "postal_code": "69003", "state": "", "country_iso": "fr" },
    "created_at": 1717236000,
    "updated_at": 1791745200
  }
}

Le mot de passe lui-même n'est jamais renvoyé ; has_password indique s'il en existe un.

Commandes

Une commande est importée avec toutes ses lignes dans un seul élément, et conserve ses dates d'origine. Les totaux sont enregistrés tels que vous les envoyez et ne sont jamais recalculés : lorsque le total ne correspond pas aux montants des articles, de la livraison et de la remise, le rapport vous le signale dans amount_check.

Importer des commandes

POST /v1/order/import

Chaque entrée de items :

Une commande est enregistrée avec toutes ses lignes ou pas du tout : une seule ligne invalide fait refuser toute la commande. Les lignes que vous omettez lors d'un import ultérieur sont conservées.

Chaque entrée acceptée du rapport ajoute :

curl https://api.ultineo.com/v1/order/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "ORD-10458",
        "customer_external_id": "C1001",
        "order_number": "10458",
        "status": "delivered",
        "currency": "EUR",
        "channel": "online",
        "articles_amount": "459.00",
        "delivery_amount": "0.00",
        "discount_amount": "15.00",
        "total_amount": "444.00",
        "discount_code": "SPRING15",
        "placed_at": 1781258400,
        "delivered_at": 1781431200,
        "items": [
          { "external_id": "ORD-10458-1", "sku": "IP13-128-MID", "name": "iPhone 13 128 GB Midnight", "grade": "very_good", "quantity": 1, "unit_price": "459.00", "line_total": "459.00" }
        ]
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "order",
    "dry_run": false,
    "data": [
      {
        "index": 0,
        "external_id": "ORD-10458",
        "action": "created",
        "id": "ordr_5e0a8c2f71d94b36e1c8",
        "code": null,
        "title": null,
        "reason": null,
        "notice": [],
        "items": { "created": 1, "updated": 0, "unchanged": 0 },
        "items_detail": [
          { "external_id": "ORD-10458-1", "action": "created", "id": "oitm_8a3f0e6c2d1b47e95c20" }
        ],
        "amount_check": null
      }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire une commande

GET /v1/order/import

Sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. ; une commande inconnue répond 404 Order not found.

curl "https://api.ultineo.com/v1/order/import?external_id=ORD-10458" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "ordr_5e0a8c2f71d94b36e1c8",
    "object": "order",
    "external_id": "ORD-10458",
    "project": "proj_5a91c7e03d2b48f6a1e9",
    "status": "activated",
    "commercial_status": "delivered",
    "reference": "10458",
    "customer": "cust_c3e9a1074b5d28f6e0a7",
    "customer_external_id": "C1001",
    "si_code": "",
    "currency": "EUR",
    "channel": "online",
    "articles_amount": "459.00",
    "delivery_amount": "0.00",
    "discount_amount": "15.00",
    "discount_code": "SPRING15",
    "total_amount": "444.00",
    "note": "",
    "placed_at": 1781258400,
    "delivered_at": 1781431200,
    "ship_before_at": 0,
    "created_at": 1781258400,
    "updated_at": 1791745200,
    "items": [
      {
        "id": "oitm_8a3f0e6c2d1b47e95c20",
        "object": "order_item",
        "external_id": "ORD-10458-1",
        "status": "activated",
        "product": "prod_a81f3c6e0b2d49e7c5f0",
        "sku": "IP13-128-MID",
        "name": "iPhone 13 128 GB Midnight",
        "grade": "very_good",
        "serial": "",
        "quantity": 1,
        "unit_price": "459.00",
        "line_total": "459.00",
        "delivery_amount": "0.00",
        "warranty_amount": "0.00",
        "currency": "EUR",
        "created_at": 1781258400,
        "updated_at": 1791745200
      }
    ]
  }
}

commercial_status est le statut commercial de la commande ; status est l'état de l'enregistrement lui-même. ship_before_at est la date limite d'expédition calculée par votre boutique ; il est en lecture seule.

Paiements

Un paiement règle une commande. Son gateway (le prestataire de paiement) et sa method (le moyen de paiement de l'acheteur) sont deux champs distincts.

Importer des paiements

POST /v1/payment/import

curl https://api.ultineo.com/v1/payment/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "PAY-77120",
        "order_external_id": "ORD-10458",
        "created_at": 1781258460,
        "status": "paid",
        "amount": "444.00",
        "fee_amount": "6.66",
        "currency": "EUR",
        "method": "card",
        "gateway": "stripe",
        "reference": "pi_3PZ0d2KJ8nA1",
        "paid_at": 1781258460
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "payment",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "PAY-77120", "action": "created", "id": "paym_2b7d9e04c1a35f8e6d91", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire un paiement

GET /v1/payment/import

Sans l'un ni l'autre, l'appel répond 400 Name the payment to read: ?external_id=… or /v1/payment/paym_…. ; un paiement inconnu répond 404 Payment not found.

curl "https://api.ultineo.com/v1/payment/import?external_id=PAY-77120" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "paym_2b7d9e04c1a35f8e6d91",
    "object": "payment",
    "external_id": "PAY-77120",
    "status": "paid",
    "order_id": "ordr_5e0a8c2f71d94b36e1c8",
    "order_external_id": "ORD-10458",
    "amount": "444.00",
    "fee_amount": "6.66",
    "refunded_amount": "0.00",
    "currency": "EUR",
    "method": "card",
    "gateway": "stripe",
    "reference": "pi_3PZ0d2KJ8nA1",
    "session_reference": "",
    "paid_at": 1781258460,
    "created_at": 1781258460,
    "updated_at": 1791745200
  }
}

Expéditions

Une expédition est un colis envoyé pour une commande, avec son transporteur et son numéro de suivi. Son statut suit ses dates : delivered dès que delivered_at est renseigné, shipped dès que shipped_at est renseigné, pending sinon.

Importer des expéditions

POST /v1/shipment/import

curl https://api.ultineo.com/v1/shipment/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "SHP-20931",
        "order_external_id": "ORD-10458",
        "carrier_name": "Colissimo",
        "tracking_number": "6A23456789012",
        "recipient_name": "Claire Martin",
        "shipped_at": 1781334000,
        "delivered_at": 1781431200
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "shipment",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "SHP-20931", "action": "created", "id": "ship_9c1e5a7f02d34b86e0a3", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire une expédition

GET /v1/shipment/import

Sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. ; un colis inconnu répond 404 Shipment not found.

curl "https://api.ultineo.com/v1/shipment/import?external_id=SHP-20931" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "ship_9c1e5a7f02d34b86e0a3",
    "object": "shipment",
    "external_id": "SHP-20931",
    "status": "delivered",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "carrier_name": "Colissimo",
    "tracking_number": "6A23456789012",
    "recipient_name": "Claire Martin",
    "note": "",
    "shipped_at": 1781334000,
    "delivered_at": 1781431200,
    "created_at": 1781334000,
    "updated_at": 1791745200
  }
}

Réclamations transporteur

Une réclamation transporteur est un litige ouvert auprès du transporteur au sujet d'un colis — perdu, endommagé, retenu en douane ou non retiré.

Importer des réclamations transporteur

POST /v1/shipment/claim

Remarque — Si votre boutique n'a jamais ouvert sa page Réclamations, l'import répond 422 et vous demande d'ouvrir cette page une fois dans votre espace de travail, puis de rejouer le lot.

curl https://api.ultineo.com/v1/shipment/claim \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "CLM-0081",
        "shipment_external_id": "SHP-20931",
        "type": "damaged",
        "status": "open",
        "reference": "COL-2026-55102",
        "opened_at": 1781517600
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "shipment_claim",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "CLM-0081", "action": "created", "id": "clai_4f8b2d6e01a93c75e2b0", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire une réclamation transporteur

GET /v1/shipment/claim

Sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. ; une réclamation inconnue répond 404 Claim not found.

curl "https://api.ultineo.com/v1/shipment/claim?external_id=CLM-0081" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "clai_4f8b2d6e01a93c75e2b0",
    "object": "shipment_claim",
    "external_id": "CLM-0081",
    "status": "open",
    "shipment": "ship_9c1e5a7f02d34b86e0a3",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "type": "damaged",
    "reference": "COL-2026-55102",
    "note": "",
    "opened_at": 1781517600,
    "settled_at": 0,
    "created_at": 1781517600,
    "updated_at": 1791745200
  }
}

Colis refusés

Un colis refusé est une expédition refusée par le destinataire, en cours de retour vers votre entrepôt.

Importer des colis refusés

POST /v1/shipment/refused

Remarque — Si votre boutique n'a jamais ouvert sa page Colis refusés, l'import répond 422 et vous demande d'ouvrir cette page une fois dans votre espace de travail, puis de rejouer le lot.

curl https://api.ultineo.com/v1/shipment/refused \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "REF-0042",
        "shipment_external_id": "SHP-20931",
        "status": "warehouse_received",
        "return_number": "RET-55871",
        "refused_at": 1781431200,
        "received_at": 1781690400
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "shipment_refused",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "REF-0042", "action": "created", "id": "refu_7a0c3e9b51d24f68a0e7", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire un colis refusé

GET /v1/shipment/refused

Sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. ; un refus inconnu répond 404 Refusal not found.

curl "https://api.ultineo.com/v1/shipment/refused?external_id=REF-0042" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "refu_7a0c3e9b51d24f68a0e7",
    "object": "shipment_refused",
    "external_id": "REF-0042",
    "status": "warehouse_received",
    "shipment": "ship_9c1e5a7f02d34b86e0a3",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "return_number": "RET-55871",
    "note": "",
    "refused_at": 1781431200,
    "received_at": 1781690400,
    "created_at": 1781431200,
    "updated_at": 1791745200
  }
}

Remboursements

Un remboursement restitue de l'argent à l'acheteur pour une commande, éventuellement sur l'un de ses paiements.

Importer des remboursements

POST /v1/refund/import

Remarque — Le champ reason de l'élément est le motif du remboursement. Ne le confondez pas avec le reason d'une entrée refusée dans le rapport d'import.

Important — Un remboursement supérieur à zéro qui n'est pas un mistake est imputé sur son paiement. Ce paiement doit être payé ou remboursé, la currency du remboursement doit être celle du paiement, et l'ensemble des remboursements d'un paiement, en cours compris, ne peut pas le dépasser. Sinon l'entrée est refusée avec 422 et un reason tel que Total refunds, including pending refunds, cannot exceed the original payment.

curl https://api.ultineo.com/v1/refund/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "RFD-3307",
        "order_external_id": "ORD-10458",
        "payment_external_id": "PAY-77120",
        "amount": "40.00",
        "currency": "EUR",
        "reason": "commercial_gesture",
        "status": "finished",
        "refunded_at": 1781604000
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "refund",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "RFD-3307", "action": "created", "id": "rfnd_0e6b4a2c93f15d78b4c1", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire un remboursement

GET /v1/refund/import

Sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. ; un remboursement inconnu répond 404 Refund not found.

curl "https://api.ultineo.com/v1/refund/import?external_id=RFD-3307" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "rfnd_0e6b4a2c93f15d78b4c1",
    "object": "refund",
    "external_id": "RFD-3307",
    "status": "finished",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "payment": "paym_2b7d9e04c1a35f8e6d91",
    "customer": "",
    "reason": "commercial_gesture",
    "amount": "40.00",
    "currency": "EUR",
    "note": "",
    "refunded_at": 1781604000,
    "created_at": 1781604000,
    "updated_at": 1791745200
  }
}

Retours

Un retour est un article qu'un client renvoie — une rétractation, un cas de garantie ou un article erroné — ainsi que la façon dont il a été traité.

Importer des retours

POST /v1/order-return/import

curl https://api.ultineo.com/v1/order-return/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "RTN-1190",
        "order_external_id": "ORD-10458",
        "customer_external_id": "C1001",
        "order_item_external_id": "ORD-10458-1",
        "type": "withdrawal",
        "resolution": "refund",
        "status": "received",
        "carrier_name": "Colissimo",
        "tracking_number": "8R00112233445",
        "received_at": 1781776800
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "order_return",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "RTN-1190", "action": "created", "id": "ortn_6d2a0f8c41e93b57d1a8", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire un retour

GET /v1/order-return/import

Sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. ; un retour inconnu répond 404 Order return not found.

curl "https://api.ultineo.com/v1/order-return/import?external_id=RTN-1190" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "ortn_6d2a0f8c41e93b57d1a8",
    "object": "order_return",
    "external_id": "RTN-1190",
    "status": "received",
    "type": "withdrawal",
    "resolution": "refund",
    "customer": "cust_c3e9a1074b5d28f6e0a7",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "order_item": "oitm_8a3f0e6c2d1b47e95c20",
    "support_request": "",
    "serial": "",
    "carrier_name": "Colissimo",
    "tracking_number": "8R00112233445",
    "label_url": "",
    "received_at": 1781776800,
    "completed_at": 0,
    "created_at": 1781776800,
    "updated_at": 1791745200
  }
}

Cagnotte client

Un mouvement de cagnotte est une ligne de la cagnotte de fidélité d'un client : des points gagnés sur un achat, un parrainage ou un avis, ou des points dépensés.

Importer des mouvements de cagnotte

POST /v1/customer-wallet/import

curl https://api.ultineo.com/v1/customer-wallet/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "WAL-55210",
        "customer_external_id": "C1001",
        "order_external_id": "ORD-10458",
        "points": "44.4",
        "reason": "purchase",
        "status": "credited",
        "earned_at": 1781431200
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "customer_wallet",
    "dry_run": false,
    "data": [
      { "index": 0, "external_id": "WAL-55210", "action": "created", "id": "cwal_3b9e1d7a05c42f86e3d2", "code": null, "title": null, "reason": null, "notice": [] }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire un mouvement de cagnotte

GET /v1/customer-wallet/import

Sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. ; un mouvement inconnu répond 404 Wallet entry not found.

curl "https://api.ultineo.com/v1/customer-wallet/import?external_id=WAL-55210" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "cwal_3b9e1d7a05c42f86e3d2",
    "object": "customer_wallet_entry",
    "external_id": "WAL-55210",
    "status": "credited",
    "customer": "cust_c3e9a1074b5d28f6e0a7",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "reason": "purchase",
    "points": "44.4000",
    "note": "",
    "earned_at": 1781431200,
    "created_at": 1781431200,
    "updated_at": 1791745200
  }
}

Demandes de support

Une demande de support est une question ou un dossier de service après-vente d'un client, importé avec son fil de messages.

Importer des demandes de support

POST /v1/support-request/import

Sujets de la catégorie order : package_not_arrived, missing_item, missing_accessory, wrong_model, cancel_order, item_problem, withdrawal, customs_invoice, voucher_refund, delivery, delivery_problem, payment, refund, claim, returned_item, account, order_general, other.

Sujets de la catégorie device : slow, no_start, blocking, photo_video, no_flash, screen_color, screen_flash, screen_pixels, battery, battery_80, no_charge, cable, no_sound_call, geolocation, screen_lock, screen_fixed, network, vibrator, black_screen, scratched, button, not_listed.

Chaque entrée de messages :

Une demande est enregistrée avec tous ses messages ou pas du tout. Les messages que vous omettez lors d'un import ultérieur sont conservés.

Chaque entrée acceptée du rapport ajoute messages (le nombre de messages created, updated et unchanged) et messages_detail (une entrée par message : son external_id, son action et son id).

curl https://api.ultineo.com/v1/support-request/import \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "SUP-4402",
        "customer_external_id": "C1001",
        "order_external_id": "ORD-10458",
        "category": "device",
        "topic": "battery",
        "status": "closed",
        "message": "The battery drains faster than expected.",
        "created_at": 1782036000,
        "answered_at": 1782046800,
        "messages": [
          { "external_id": "SUP-4402-1", "author": "shop", "text": "Thank you, a prepaid return label is on its way.", "created_at": 1782046800 }
        ]
      }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "resource": "support_request",
    "dry_run": false,
    "data": [
      {
        "index": 0,
        "external_id": "SUP-4402",
        "action": "created",
        "id": "sprq_1c7e3a9f50b24d68c1e5",
        "code": null,
        "title": null,
        "reason": null,
        "notice": [],
        "messages": { "created": 1, "updated": 0, "unchanged": 0 },
        "messages_detail": [
          { "external_id": "SUP-4402-1", "action": "created", "id": "spmg_8e2b0d4a61f37c95e2b4" }
        ]
      }
    ],
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "refused": 0,
    "total": 1
  }
}

Lire une demande de support

GET /v1/support-request/import

Sans l'un ni l'autre, l'appel répond 400 Missing required parameter: external_id. ; une demande inconnue répond 404 Support request not found.

curl "https://api.ultineo.com/v1/support-request/import?external_id=SUP-4402" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "sprq_1c7e3a9f50b24d68c1e5",
    "object": "support_request",
    "external_id": "SUP-4402",
    "project": "proj_5a91c7e03d2b48f6a1e9",
    "status": "closed",
    "category": "device",
    "topic": "battery",
    "customer": "cust_c3e9a1074b5d28f6e0a7",
    "order": "ordr_5e0a8c2f71d94b36e1c8",
    "order_item": "",
    "message": "The battery drains faster than expected.",
    "answered_at": 1782046800,
    "created_at": 1782036000,
    "updated_at": 1791745200,
    "messages": [
      {
        "id": "spmg_8e2b0d4a61f37c95e2b4",
        "object": "support_message",
        "external_id": "SUP-4402-1",
        "status": "activated",
        "author": "shop",
        "text": "Thank you, a prepaid return label is on its way.",
        "created_at": 1782046800,
        "updated_at": 1791745200
      }
    ]
  }
}

Le fil est renvoyé par ordre chronologique, y compris les messages rédigés dans votre espace de travail (leur external_id est vide).

Remarque — Ces points d'accès ne listent, ne recherchent ni ne suppriment d'enregistrements, et ne déclenchent aucune action : annuler une commande, émettre un remboursement, créer une étiquette d'expédition ou contacter un transporteur se font dans votre espace de travail.