Produits

Alimentez votre catalogue de services et exposez vos inventaires en toute sécurité dans vos frontends.

Vue d’ensemble

L’objet Producto contient les éléments de votre liste de prix (SKU, nom, prix de base et unité de mesure). L’API des produits de Cord est suffisamment sûre pour que vous puissiez la consommer non seulement depuis vos serveurs internes, mais aussi directement depuis le navigateur de vos clients.

Créer un produit

Utilisez votre clé API secrète (sk_) pour alimenter le catalogue en masse. Idéal pour des intégrations nocturnes ou des webhooks provenant de systèmes de gestion des stocks.

Requête :

curl -X POST "https://cordhq.app/api/v1/productos" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{
       "sku": "LIC-PRO-24",
       "nombre": "Professional Annual License",
       "unidad": "license",
       "precio": 12000,
       "activo": true
     }'

Réponse réussie :

{
  "data": {
    "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2"
  }
}

Champs facultatifs de taxe et de facturation

Champ	Ce que c’est	Validation
`tax_rate`	La taxe que le produit suggère lorsqu’il est ajouté à un devis ou à une facture, sous forme de fraction (`0.08` = 8 %). Sans elle, la ligne utilise votre taux par défaut.	Doit être un taux de votre catalogue de taxes (ou `0`) ; sinon, `400`.
`clave_sat`	Clé de produit ou de service du SAT (c_ClaveProdServ) pour le CFDI au Mexique.	8 chiffres (`81111500`) ; sinon, `400`.
`clave_unidad_sat`	Clé d’unité du SAT (c_ClaveUnidad). Sans elle, elle est déduite de `unidad` lors du timbrage (`hora` → `HUR`).	1 à 3 lettres ou chiffres (`E48`), enregistrée en majuscules ; sinon, `400`.

Dans la liste, ils sont renvoyés sous les noms taxRate, claveSat et claveUnidadSat (null s’ils n’ont pas été attribués).

Lister les produits et sécurité des données

L’API de liste (GET /api/v1/productos) dispose d’un mécanisme de masquage dynamique (Dynamic Masking) fondé sur le niveau de confiance de la clé API avec laquelle vous vous authentifiez.

Si vous utilisez une clé secrète (sk_) : Cord considère que vous êtes un système interne de confiance et vous renvoie l’objet complet, y compris les coûts cachés et les marges bénéficiaires (costo).

Si vous utilisez une clé publiable (pk_) : Les clés publiables sont exposées dans le navigateur (par exemple, pour afficher une liste de prix sur un site web public en React). Cord prend en compte ce risque et retire automatiquement le champ costo de tous les résultats en mémoire avant de sérialiser le JSON. Ainsi, vos marges ne fuient jamais vers le frontend public.

curl -X GET "https://cordhq.app/api/v1/productos?limit=50" \
     -H "Authorization: Bearer pk_live_yX..."

Avec sk_live_..., le même produit inclut costo :

{ "data": [ { "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2", "sku": "LIC-PRO-24", "nombre": "Professional Annual License", "unidad": "license", "precio": 12000, "costo": 4000, "activo": true, "taxRate": null, "claveSat": "43231500", "claveUnidadSat": null } ] }

Avec pk_live_..., costo n’apparaît tout simplement pas dans l’objet (il ne vaut ni null ni 0 — la clé n’existe pas) :

{ "data": [ { "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2", "sku": "LIC-PRO-24", "nombre": "Professional Annual License", "unidad": "license", "precio": 12000, "activo": true, "taxRate": null, "claveSat": "43231500", "claveUnidadSat": null } ] }

Remarque : une clé publiable ne peut être utilisée que sur quatre routes : GET /api/v1/productos, POST /api/v1/cotizaciones, GET /api/v1/elements/config et POST /api/v1/elements/ai-draft. Toute autre route (créer des produits, lire des clients, le recouvrement) répond 403 insufficient_scope. Elle exige aussi un en-tête Origin ou Referer qui correspond aux domaines autorisés de votre organisation, configurés dans Paramètres › Générateur de devis intégrable. Une clé pk_live_ sans domaines configurés répond 403 origin_allowlist_required ; une clé pk_test_ fonctionne depuis n’importe quelle origine.