NUHO API

API interne — commandes, clients, KOL, produits. Auth : X-Api-Key header ou ?api_key=

Lecture (GET)

GET /api/orders

Commandes completes avec adresses, line items, TVA, fulfillments, refunds, paiement.

Parametres de requete

Param	Description
`days`	Fenetre en jours (defaut 90)
`from` / `to`	Date range (ISO ou YYYY-MM-DD)
`updated_since`	Delta sync — modifiees apres cette date
`status`	paid, pending, refunded, authorized
`fulfillment`	fulfilled, unfulfilled, partial
`email`	Email client
`customer`	Recherche nom/email
`city`	Ville
`zip`	Code postal exact
`country`	Code pays (CH, FR, DE...)
`province`	Canton/province
`kol`	Code KOL exact
`has_kol`	true/false
`tag`	Tag commande
`sku`	SKU exact
`product`	Nom du produit
`discount_code`	Code promo
`gateway`	Moyen de paiement
`has_tracking`	true/false
`has_refund`	true
`cancelled`	true/false
`min_total` / `max_total`	Montant
`order_number_min` / `order_number_max`	Plage de numeros
`sort` / `order`	Tri (created_at, total_price... + asc/desc)
`page` / `per_page`	Pagination (max 250)

Champs de reponse (par commande)

Champ	Type	Description
`id`	number	ID Shopify
`name`	string	#1042
`order_number`	number	1042
`email`	string	Email du client
`phone`	string	Telephone
`created_at`	ISO date	Date de creation
`updated_at`	ISO date	Derniere modification
`processed_at`	ISO date	Date de paiement
`closed_at`	ISO date	Date de cloture
`cancelled_at`	ISO date	Date d'annulation (null si non annulee)
`cancel_reason`	string	Raison d'annulation
`financial_status`	string	paid, pending, refunded, partially_refunded
`fulfillment_status`	string	fulfilled, unfulfilled, partial, null
`currency`	string	CHF
`subtotal_price`	number	Sous-total (sans shipping/taxes)
`total_price`	number	Total TTC
`total_tax`	number	TVA totale (0 actuellement)
`total_discounts`	number	Total des remises
`total_shipping`	number	Frais de port
`taxes_included`	bool	Prix TTC (true)
`tax_exempt`	bool	Client exonere
`tax_lines[]`	array	Lignes TVA : title, rate (0.026), price
`customer`	object	id, email, first_name, last_name, phone, tags, tax_exempt, locale, accepts_marketing, orders_count, total_spent
`billing_address`	object	first_name, last_name, company, address1, address2, city, province, province_code, zip, country, country_code, phone, lat, lng
`shipping_address`	object	Meme structure que billing_address
`line_items[]`	array	id, product_id, variant_id, title, variant_title, sku, vendor, quantity, price, total_discount, grams, requires_shipping, taxable, tax_lines[], discount_allocations[]
`shipping_lines[]`	array	title, price, code, source, carrier_identifier, tax_lines[]
`fulfillments[]`	array	id, status, created_at, tracking_number, tracking_numbers[], tracking_url, tracking_urls[], tracking_company, shipment_status, line_items[]
`refunds[]`	array	id, created_at, note, restock, refund_line_items[] (line_item_id, quantity, subtotal, total_tax), transactions[] (amount, currency, kind, gateway, status)
`payment_gateway_names[]`	array	Ex: ["shopify_payments"], ["manual"]
`processing_method`	string	direct, manual, offsite
`discount_codes[]`	array	code, amount, type (percentage/fixed_amount)
`discount_applications[]`	array	type (automatic/discount_code), title, value, value_type, target_type
`note`	string	Note de commande
`note_attributes[]`	array	Attributs (dont kol_ref)
`tags`	string	Tags de la commande
`source_name`	string	web, pos, shopify_draft_order
`kol_ref`	string	Code KOL attribue (null si aucun)
`total_weight`	number	Poids total en grammes

Pagination : count, total, page, per_page, total_pages

GET /api/customers

Clients avec adresses, tags, depenses, marketing, KOL.

Parametres de requete

Param	Description
`tag`	Tag (kol, therapeute-20...)
`email`	Email
`name`	Nom
`company`	Entreprise
`city`	Ville
`zip`	Code postal
`country`	Code pays
`province`	Canton
`search`	Recherche globale
`locale`	Langue (fr, de, en...)
`kol_only`	true
`tax_exempt`	true
`accepts_marketing`	true
`has_phone`	true
`has_address`	true
`min_spent` / `max_spent`	Depense
`min_orders`	Nb commandes min
`created_since` / `created_before`	Date range
`sort` / `order`	Tri + direction
`page` / `per_page`	Pagination

Champs de reponse (par client)

Champ	Type	Description
`id`	string	ID Shopify
`email`	string	Email
`first_name` / `last_name`	string	Nom
`phone`	string	Telephone
`locale`	string	Langue
`tags`	string	Tags (virgule separee)
`created_at` / `updated_at`	ISO date	Dates
`verified_email`	bool	Email verifie
`tax_exempt`	bool	Exonere TVA
`tax_exemptions[]`	array	Types d'exemptions
`email_marketing`	string	SUBSCRIBED / NOT_SUBSCRIBED
`sms_marketing`	string	SUBSCRIBED / NOT_SUBSCRIBED
`note`	string	Note client
`orders_count`	number	Nombre de commandes
`total_spent`	number	Total depense (CHF)
`currency`	string	CHF
`vat_number`	string	Numero de TVA (B2B)
`default_address`	object	first_name, last_name, company, address1, address2, city, province, province_code, zip, country, country_code, phone
`addresses[]`	array	Toutes les adresses (meme structure)
`kol_code`	string	Code referral KOL
`kol_pct`	number	Commission %
`kol_total_sold`	number	Ventes generees (CHF)
`kol_orders_count`	number	Commandes attribuees
`kol_commission_due`	number	Commission due (CHF)
`kol_last_updated`	string	Derniere MAJ des stats
`kol_iban`	string	IBAN pour paiement commission
`kol_iban_name`	string	Nom beneficiaire IBAN

GET /api/kols

Programme ambassadeur : KOLs, commissions, ventes, IBAN.

Champs de reponse

count, active, total_revenue, total_orders, total_commission + tableau kols[] (memes champs KOL que /api/customers).

GET /api/stats

Resume global. Param: days (defaut 90).

Champs de reponse

Champ	Description
`orders.total`	Nombre de commandes
`orders.today` / `week` / `month`	Commandes jour/semaine/mois
`orders.revenue_today` / `week` / `month` / `total`	CA en CHF
`customers.total`	Nombre de clients
`customers.new_this_week`	Nouveaux cette semaine
`customers.tags`	Comptage par tag
`kol.count` / `active`	KOL total/actifs
`kol.total_revenue` / `total_commission`	CA et commissions KOL
`generated_at`	Timestamp de generation

GET /api/products

Catalogue produits. Param: status (active/draft/archived).

Champs de reponse (par produit)

Champ	Description
`id`	ID produit
`title`	Nom
`handle`	Slug URL
`status`	active, draft, archived
`product_type`	Type (Supplement)
`vendor`	Marque (NUHO)
`tags`	Tags produit
`variants[]`	id, title, sku, barcode, price, compare_at_price, weight, weight_unit, inventory_item_id, inventory_quantity, requires_shipping, taxable
`image`	src, alt

Ecriture (POST)

POST /api/customer-create

Creer un client.

Body JSON

Champ	Requis	Description
`email`	oui	Email du client
`first_name`	non	Prenom
`last_name`	non	Nom
`phone`	non	Telephone
`tags`	non	Tags (array de strings)
`note`	non	Note interne
`address`	non	{address1, city, zip, country_code, company, phone}
`metafields`	non	[{namespace, key, type, value}]

Reponse

{"customer_id": "123", "email": "...", "name": "...", "tags": [...]}

POST /api/customer-update

Modifier un client. Tags proteges et metafields kol.* bloques.

Body JSON

Champ	Requis	Description
`customer_id`	oui	ID Shopify du client
`vat_number`	non	Numero de TVA
`tags_add`	non	Tags a ajouter (array)
`tags_remove`	non	Tags a supprimer (array)
`note`	non	Note client
`metafields`	non	[{namespace, key, type, value}] — namespace "billing" uniquement

Reponse

{"customer_id": "123", "updated": {"metafields": [...], "tags_added": [...]}, "rejected": [...]}

POST /api/order-update

Modifier une commande.

Body JSON

Champ	Requis	Description
`order_id`	oui	ID de la commande
`note`	non	Note de commande
`tags`	non	Remplace tous les tags (string)
`tags_add`	non	Ajouter des tags (array)
`tags_remove`	non	Supprimer des tags (array)
`email`	non	Changer l'email
`shipping_address`	non	{first_name, last_name, address1, city, zip, country_code, phone}
`metafields`	non	[{namespace, key, type, value}]

Reponse

{"order_id": "123", "updated": {"order_updated": ["note","tags"], "tags_added": [...]}}

POST /api/order-fulfill

Expedier une commande avec tracking. Shopify envoie l'email de confirmation au client.

Body JSON

Champ	Requis	Description
`order_id`	oui	ID de la commande
`tracking_number`	non	Numero de suivi
`tracking_company`	non	Transporteur (La Poste, DPD...)
`tracking_url`	non	URL de suivi
`notify_customer`	non	Envoyer email au client (defaut: true)
`message`	non	Message dans la notification

Reponse

{"order_id": "123", "fulfillment": {"id": "...", "status": "success", "tracking_number": "...", "tracking_company": "...", "created_at": "..."}}

POST /api/order-mark-paid

Marquer une commande pending comme payee (virement bancaire recu).

Body JSON

Champ	Requis	Description
`order_id`	oui	ID de la commande

Reponse

{"order_id": "123", "name": "#1042", "status": "paid", "amount": 72.90, "currency": "CHF", "transaction_id": "..."}

Si deja payee : {"status": "already_paid"}

POST /api/order-refund

Rembourser une commande (total ou partiel).

Body JSON

Champ	Requis	Description
`order_id`	oui	ID de la commande
`amount`	non	Montant partiel (CHF). Si absent = remboursement total
`line_items`	non	[{line_item_id, quantity}] — rembourser des articles specifiques
`note`	non	Raison du remboursement
`notify`	non	Notifier le client (defaut: true)
`restock`	non	Remettre en stock (defaut: false)
`restock_shipping`	non	Rembourser aussi les frais de port

Reponse

{"order_id": "123", "refund_id": "...", "total_refunded": 13.40, "currency": "CHF", "line_items_refunded": [...]}

POST /api/order-cancel

Annuler une commande.

Body JSON

Champ	Requis	Description
`order_id`	oui	ID de la commande
`reason`	non	customer, fraud, inventory, declined, other
`email`	non	Notifier le client (defaut: true)
`refund`	non	Rembourser en meme temps (defaut: false)
`restock`	non	Remettre en stock (defaut: true)

Reponse

{"order_id": "123", "name": "#1042", "status": "cancelled", "cancelled_at": "...", "financial_status": "refunded"}

POST /api/kol-create restreint

Creer un KOL ambassadeur.

Body JSON

Champ	Requis	Description
`email`	oui	Email du KOL
`code`	oui	Slug referral (1-40 chars, a-z 0-9 _ -)
`commission_pct`	oui	Commission en % (ex: 10)
`first_name`	non	Prenom (requis si nouveau client)
`last_name`	non	Nom
`iban`	non	IBAN pour paiement commission
`iban_name`	non	Nom du beneficiaire

Reponse

{"customer_id": "123", "email": "...", "name": "...", "kol_code": "CARLOS", "kol_pct": 10, "kol_link": "https://nuho.ch/?ref=CARLOS"}

POST /api/product-update restreint

Modifier un produit (prix, description, stock).

Body JSON

Champ	Requis	Description
`product_id`	oui	ID du produit
`title`	non	Nouveau titre
`body_html`	non	Description HTML
`tags`	non	Tags (remplace tous)
`status`	non	active, draft, archived
`variants[]`	non	id (requis), price, compare_at_price, sku, weight, barcode, inventory_quantity_adjust (+/-N)

Reponse

{"product_id": "123", "updated": {"product": {"id": "...", "title": "...", "variants": [...]}, "inventory_adjusted": [...]}}

NUHO API

NUHO API

★ Gestion des KOL

Créer un KOL directement (statut Active, pas de pending)

Lecture (GET)

GET /api/orders

GET /api/customers

GET /api/kols

GET /api/stats

GET /api/products

Ecriture (POST)

POST /api/customer-create

POST /api/customer-update

POST /api/order-update

POST /api/order-fulfill

POST /api/order-mark-paid

POST /api/order-refund

POST /api/order-cancel

POST /api/kol-create restreint

POST /api/product-update restreint