Documentation API revendeur — Comink

v1 — base URL : https://comink.be/api/v1

Authentification

Toutes les requêtes portent votre clé API dans l'en-tête Authorization :

Authorization: Bearer rk_votre_clé_api

Une clé invalide ou désactivée renvoie 401.

GET /products — votre catalogue

Renvoie les produits que vous avez activés dans le portail, prix avec votre marge déjà appliquée, et toutes les contraintes à respecter dans votre interface :

  • min_width_cm / max_width_cm / min_height_cm / max_height_cm — dimensions autorisées (produits sur mesure)
  • standard_sizes — formats fixes avec leur prix (produits à formats standard)
  • finitions — groupes d'options (required: true = choix obligatoire) avec suppléments fixed (€), percent (%) ou per_m2 (€/m²)
  • sides_finitions — options par côté (haut/bas/gauche/droite) avec incompatibilities : paires d'options qui ne peuvent pas être combinées sur un même côté
  • delai_options — délais de production avec majoration en %
  • vat_rate — taux de TVA (prix renvoyés hors TVA)
curl https://comink.be/api/v1/products \
  -H "Authorization: Bearer rk_votre_clé_api"

POST /price — calcul de prix et validation

Envoyez la configuration choisie par votre client : l'API valide les contraintes (dimensions, options obligatoires, incompatibilités) et renvoie le prix avec votre marge. En cas de configuration invalide, la réponse est 422 avec la liste des erreurs.

curl -X POST https://comink.be/api/v1/price \
  -H "Authorization: Bearer rk_votre_clé_api" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "uuid-du-produit",
    "width_cm": 200,
    "height_cm": 100,
    "quantity": 2,
    "finitions": { "group_id": "option_id" },
    "sides": { "top": ["option_id"] },
    "delai_id": "delai_id"
  }'

Réponse :

{
  "valid": true,
  "errors": [],
  "unit_price": 84.50,
  "total_price": 169.00,
  "base_price": 60.00,
  "finitions_price": 12.50,
  "sides_price": 8.00,
  "delai_surcharge": 4.00,
  "surface_m2": 2.00,
  "vat_rate": 21
}

Exemple d'erreur (422) :

{
  "valid": false,
  "errors": [
    "Largeur hors limites : 50–300 cm",
    "Options incompatibles sur le côté \"top\" : \"Œillets\" et \"Fourreau\""
  ]
}

POST /files puis POST /orders — commander

1. Uploadez chaque visuel (PDF d'une page conseillé) :POST /files avec{ file_name, content_type } renvoieupload_url (PUT du binaire, valable 1h) etfile_url à référencer dans la commande.

2. Créez la commande : chaque ligne est validée techniquement puis facturée à votre prix d'achat (sans votre marge). Le colis part au nom de votre société (coordonnées d'expédition du portail — obligatoires) vers l'adresse de votre client final.

curl -X POST https://comink.be/api/v1/orders \
  -H "Authorization: Bearer rk_votre_clé_api" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [{ "product_id": "uuid", "width_cm": 200, "height_cm": 100,
                "quantity": 2, "delai_id": "...",
                "file_url": "https://... (obtenu via /files)",
                "reference": "Votre réf ligne" }],
    "delivery_address": { "name": "Client Final SPRL", "line1": "Rue X 1",
                          "postal_code": "4000", "city": "Liège" },
    "customer_reference": "Votre n° de commande interne"
  }'

Réponse (201) :

{
  "order_number": "CMD-202608-00152",
  "status": "pending_wire",
  "totals": { "subtotal_htva": 48.16, "vat": 10.11, "total_tvac": 58.27 },
  "payment": { "method": "virement", "iban": "BE..", "bic": "..",
               "communication": "CMD-202608-00152",
               "note": "La production démarre à réception du paiement." }
}

Suivi : GET /orders renvoie vos commandes avec statut, paiement et numéro de suivi. Astuce prix d'achat : POST /price avec"margin": false renvoie votre coût au lieu du prix de revente.

POST /quotes — devis pour vos clients

Créez un devis à vos prix (marge incluse) pour un de vos clients. Chaque ligne est validée techniquement (dimensions, finitions obligatoires, incompatibilités) — un devis invalide est refusé en 422 avec les erreurs par ligne. Le devis est numéroté et conservé : GET /quotes pour la liste,GET /quotes/:id pour le détail,DELETE /quotes/:id pour supprimer un brouillon.

curl -X POST https://comink.be/api/v1/quotes \
  -H "Authorization: Bearer rk_votre_clé_api" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "Boulangerie Dupont", "email": "info@dupont.be" },
    "lines": [
      { "product_id": "uuid", "width_cm": 200, "height_cm": 100,
        "quantity": 2, "finitions": {}, "delai_id": "..." }
    ],
    "notes": "Livraison souhaitée avant le 15",
    "valid_days": 30
  }'

Réponse (201) :

{
  "quote_number": "RQ-202608-0001",
  "customer": { "name": "Boulangerie Dupont", ... },
  "lines": [{ "product_name": "...", "quantity": 2,
              "unit_price_htva": 84.50, "total_htva": 169.00, "vat_rate": 21 }],
  "totals": { "subtotal_htva": 169.00, "vat": 35.49, "total_tvac": 204.49 },
  "valid_until": "2026-09-30", "status": "draft"
}

GET / PUT /reseller/settings — paramètres d'expédition

Vos commandes sont expédiées à votre nom (marque blanche). Configurez vos coordonnées d'expéditeur dans le portail ou via l'API. Le GET renvoie aussi les coordonnées de facturation que Comink a pour vous.

curl -X PUT https://comink.be/api/v1/reseller/settings \
  -H "Authorization: Bearer rk_votre_clé_api" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": {
      "name": "Votre société",
      "street": "Rue Exemple 1",
      "zip": "4000", "city": "Liège", "country": "BE",
      "phone": "+32...", "email": "contact@votresociete.be"
    }
  }'

À la commande (prochaine version), vous transmettrez l'adresse de livraison de votre client final dans delivery_address — le colis partira avec vos coordonnées d'expéditeur.

Webhook — soyez prévenu des changements de statut

Configurez une URL (https) via PUT /reseller/settings avec{ "sender": {...}, "webhook_url": "https://votre-site.be/webhooks/comink" } : Comink y enverra un POST à chaque changement de statut de vos commandes (production, prête, expédiée avec numéro de suivi, livrée).

POST https://votre-site.be/webhooks/comink
X-Comink-Event: order.status_changed | order.tracking_added
X-Comink-Signature: <HMAC-SHA256 du corps, clé = votre api_key>

{
  "event": "order.tracking_added",
  "order_number": "CMD-202609-00012",
  "status": "shipped",
  "payment_status": "paid",
  "tracking_number": "323212345678",
  "customer_reference": "votre réf interne",
  "timestamp": "2026-09-02T14:00:00.000Z"
}

Vérifiez la signature : HMAC-SHA256 du corps brut avec votre clé API comme secret, comparée àX-Comink-Signature. Timeout 6 s — répondez 200 rapidement et traitez en asynchrone.

Bonnes pratiques

  • Appelez POST /price à chaque changement de configuration côté client : c'est la source de vérité pour le prix ET la validité.
  • Affichez les bornes de dimensions dans votre formulaire, mais ne vous fiez pas qu'à votre validation front : l'API refuse toute configuration invalide.
  • Mettez le catalogue en cache maximum 1 heure — les prix et marges peuvent changer.
  • Ne mettez jamais votre clé API dans du code front-end : appelez l'API depuis votre serveur.

La commande via API (POST /orders, avec fichier d'impression et paiement) arrive dans une prochaine version — contactez Comink pour être prévenu.