Referință API

Documentația API pentru ingrediente cosmetice

Referință API completă pentru endpoint-urile de analiză INCI, scoring de siguranță, detectare alergeni și compatibilitate cu pielea.

Autentificare pentru API-ul cosmetic

Toate cererile către INCI API necesită o cheie API trimisă prin antetul X-API-Key. Obține cheia API gratuită din Panoul de control.

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913" \
  -H "X-API-Key: sk_live_your_api_key"

Notă privind datele

Important Disclaimer

The ingredient safety data, scores, and ratings provided by INCI API are for informational and educational purposes only. This information is compiled from public databases and scientific literature, and may contain errors, omissions, or outdated information. INCI API does not guarantee the accuracy, completeness, or reliability of any data presented.

This service does not provide medical, dermatological, or health advice. Safety scores and ratings are algorithmic assessments based on available data and should not be used as a substitute for professional medical advice, diagnosis, or treatment. Always consult a qualified healthcare professional or dermatologist before making decisions about cosmetic products, especially regarding pregnancy safety, allergies, or skin conditions.

INCI API assumes no liability for any decisions made based on the information provided.

Toate răspunsurile API includ date despre ingrediente compilate din surse publice precum EU CosIng, rapoarte CIR și literatură științifică publicată. Acuratețea nu este garantată. Scorurile de siguranță sunt estimări algoritmice bazate pe datele disponibile, nu evaluări clinice. Utilizatorii trebuie să verifice independent toate informațiile despre ingrediente. Vezi Termenii și condițiile și Acordul de licență API pentru termenii completi.

Endpoint-urile API-ului de analiză INCI

GET/v1/products/:barcodeFree+

Caută un produs cosmetic după cod de bare. Returnează informații despre produs, marca, lista INCI și imagini.

Cerere

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913" \
  -H "X-API-Key: sk_live_your_api_key"

Răspuns

json

{
  "success": true,
  "data": {
    "barcode": "3337875597913",
    "name": "La Roche-Posay Toleriane Double Repair",
    "brand": "La Roche-Posay",
    "category": ["Skincare", "Moisturizer"],
    "imageUrls": ["https://cdn.inciapi.com/..."],
    "inciList": [
      "Aqua", "Glycerin", "Dimethicone",
      "Niacinamide", "Ceramide NP"
    ],
    "vertical": "cosmetics",
    "qualityScore": 92
  }
}

GET/v1/products/:barcode/safetyStarter+

Obține analiza completă de siguranță pentru un produs. Include scor general și evaluări per ingredient.

Cerere

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913/safety" \
  -H "X-API-Key: sk_live_your_api_key"

Răspuns

json

{
  "success": true,
  "data": {
    "overallSafetyScore": 92,
    "cleanBeautyScore": 88,
    "ingredients": [
      {
        "inciName": "Aqua",
        "safetyRating": 1,
        "functions": ["Solvent"],
        "isAllergen": false,
        "isPregnancySafe": true
      },
      {
        "inciName": "Niacinamide",
        "safetyRating": 1,
        "functions": ["Antioxidant", "Brightening"],
        "isAllergen": false,
        "isPregnancySafe": true
      },
      {
        "inciName": "Phenoxyethanol",
        "safetyRating": 4,
        "functions": ["Preservative"],
        "isAllergen": false,
        "isPregnancySafe": true
      }
    ]
  }
}

GET/v1/products/:barcode/allergensStarter+

Obține avertismente despre alergeni pentru un produs. Verifică cei 80 de alergeni obligatorii UE, sensibilizatorii de contact și alergenii conservanți.

Cerere

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913/allergens" \
  -H "X-API-Key: sk_live_your_api_key"

Răspuns

json

{
  "success": true,
  "data": {
    "allergenWarnings": [
      {
        "inciName": "Linalool",
        "allergenType": "EU Fragrance Allergen",
        "severity": "moderate",
        "description": "Common fragrance allergen, mandatory labeling in EU"
      },
      {
        "inciName": "Citronellol",
        "allergenType": "EU Fragrance Allergen",
        "severity": "low",
        "description": "Fragrance component, potential sensitizer"
      }
    ],
    "totalAllergens": 2,
    "hasEuAllergens": true,
    "hasContactSensitizers": false
  }
}

GET/v1/products/:barcode/compatibility?skinType=sensitiveÎn curând+

Verifică compatibilitatea cu un tip de piele. Tipuri suportate: grasă, uscată, sensibilă, mixtă, predispusă la acnee, normală.

Cerere

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913/compatibility?skinType=sensitive" \
  -H "X-API-Key: sk_live_your_api_key"

Răspuns

json

{
  "success": true,
  "data": {
    "skinType": "sensitive",
    "compatible": true,
    "score": 95,
    "concerns": [],
    "recommendations": [
      "Product is fragrance-free",
      "Contains ceramides (skin barrier support)",
      "Contains niacinamide (anti-inflammatory)"
    ],
    "allSkinTypes": [
      { "skinType": "sensitive", "compatible": true, "score": 95 },
      { "skinType": "dry", "compatible": true, "score": 90 },
      { "skinType": "oily", "compatible": true, "score": 82 },
      { "skinType": "combination", "compatible": true, "score": 88 },
      { "skinType": "acne-prone", "compatible": true, "score": 78 },
      { "skinType": "normal", "compatible": true, "score": 96 }
    ]
  }
}

GET/v1/products/:barcode/pregnancyÎn curând+

Verifică siguranța în sarcină. Marchează retinoizii, acidul salicilic (BHA), hidrochinona și alte ingrediente nesigure în sarcină.

Cerere

bash

curl -X GET "https://api.inciapi.com/v1/products/3337875597913/pregnancy" \
  -H "X-API-Key: sk_live_your_api_key"

Răspuns

json

{
  "success": true,
  "data": {
    "pregnancySafe": true,
    "warnings": [],
    "flaggedIngredients": [],
    "safeAlternatives": [],
    "note": "No pregnancy-unsafe ingredients detected"
  }
}

POST/v1/analyzeÎn curând+

Analizează o listă INCI brută fără cod de bare. Trimite numele ingredientelor și obține o analiză completă de siguranță.

Cerere

bash

curl -X POST "https://api.inciapi.com/v1/analyze" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inci": [
      "Aqua", "Glycerin", "Niacinamide",
      "Cetearyl Alcohol", "Phenoxyethanol",
      "Retinol", "Linalool"
    ]
  }'

Răspuns

json

{
  "success": true,
  "data": {
    "overallSafetyScore": 78,
    "cleanBeautyScore": 72,
    "ingredients": [
      { "inciName": "Aqua", "safetyRating": 1, "isAllergen": false, "isPregnancySafe": true },
      { "inciName": "Glycerin", "safetyRating": 1, "isAllergen": false, "isPregnancySafe": true },
      { "inciName": "Niacinamide", "safetyRating": 1, "isAllergen": false, "isPregnancySafe": true },
      { "inciName": "Retinol", "safetyRating": 7, "isAllergen": false, "isPregnancySafe": false },
      { "inciName": "Linalool", "safetyRating": 5, "isAllergen": true, "isPregnancySafe": true }
    ],
    "allergenWarnings": [
      { "inciName": "Linalool", "allergenType": "EU Fragrance Allergen", "severity": "moderate" }
    ],
    "pregnancySafe": false,
    "pregnancyWarnings": ["Retinol: Vitamin A derivative, avoid during pregnancy"]
  }
}

GET/v1/ingredients/:inciNameFree+

Obține informații detaliate despre un anumit ingredient după numele său INCI.

Cerere

bash

curl -X GET "https://api.inciapi.com/v1/ingredients/Niacinamide" \
  -H "X-API-Key: sk_live_your_api_key"

Răspuns

json

{
  "success": true,
  "data": {
    "inciName": "Niacinamide",
    "commonName": "Vitamin B3",
    "casNumber": "98-92-0",
    "safetyRating": 1,
    "functions": ["Antioxidant", "Brightening", "Anti-inflammatory"],
    "isAllergen": false,
    "isPregnancySafe": true,
    "comedogenicity": 0,
    "suitableSkinTypes": ["oily", "dry", "sensitive", "combination", "acne-prone", "normal"],
    "euStatus": "approved",
    "description": "Well-researched skincare ingredient. Helps with hyperpigmentation, fine lines, and skin barrier function."
  }
}

GET/v1/ingredients/search?q=retinolFree+

Caută ingrediente după nume sau funcție. Returnează ingredientele care se potrivesc cu datele de siguranță.

Cerere

bash

curl -X GET "https://api.inciapi.com/v1/ingredients/search?q=retinol&limit=5" \
  -H "X-API-Key: sk_live_your_api_key"

Răspuns

json

{
  "success": true,
  "data": {
    "ingredients": [
      {
        "inciName": "Retinol",
        "safetyRating": 7,
        "functions": ["Anti-Aging", "Cell Turnover"],
        "isAllergen": false,
        "isPregnancySafe": false
      },
      {
        "inciName": "Retinyl Palmitate",
        "safetyRating": 5,
        "functions": ["Anti-Aging", "Antioxidant"],
        "isAllergen": false,
        "isPregnancySafe": false
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 5
  }
}

POST/v1/products/submitFree+

Trimite un produs cosmetic lipsă cu lista sa INCI. Produsele contribuite sunt disponibile după moderare.

Cerere

bash

curl -X POST "https://api.inciapi.com/v1/products/submit" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "1234567890123",
    "name": "My Beauty Serum",
    "brand": "Indie Beauty",
    "inciList": ["Aqua", "Hyaluronic Acid", "Niacinamide"]
  }'

Răspuns

json

{
  "success": true,
  "data": {
    "submissionId": "sub_abc123",
    "status": "pending_review",
    "message": "Product submitted successfully. Will be available after moderation."
  }
}

Limitarea cererilor API-ului cosmetic

Limitele de cereri ale API-ului de analiză a ingredientelor depind de nivelul abonamentului. Limitele sunt returnate în antetele răspunsului.

Plan	Limită	Resetare
Free	100 cereri/zi	Zilnic la miezul nopții UTC
Starter	5.000 cereri/lună	Lunar la data facturării

Antete răspuns:

http

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4831
X-RateLimit-Reset: 1711929600

Coduri de eroare INCI API

Cod	Semnificație	Acțiune
`400`	Cerere incorectă	Verifică parametrii și formatul corpului cererii
`401`	Neautorizat	Verifică cheia API în antetul X-API-Key
`403`	Interzis	Endpoint-ul necesită un plan superior
`404`	Negăsit	Produsul sau ingredientul nu se află în baza noastră
`429`	Limită de cereri depășită	Așteaptă secundele indicate în Retry-After și încearcă din nou
`500`	Eroare internă a serverului	Încearcă mai târziu, contactează suportul dacă persistă

Format răspuns eroare:

json

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Product not found for barcode: 1234567890123"
  }
}