Referencia de la API

Todos los endpoints de la API de PerfumesDupes, sus parámetros y ejemplos de respuesta. La spec OpenAPI completa está disponible en /v1/openapi.json.

Autenticación

Todos los endpoints /v1/ requieren autenticación con el header X-API-Key. Los endpoints marcados como Premium requieren un plan de pago.

curl https://api.perfumesdupes.com/v1/search?note=vanilla \
  -H "X-API-Key: sk_live_your_key_here"

Obtener API Key Swagger UI ↗

Endpoints

GET/v1/searchBuscar perfumes
GET/v1/perfume/:idDetalle de perfume
GET/v1/perfume/:id/clonesClones y alternativasPremium
GET/v1/similar/:idPerfumes similaresPremium
GET/v1/brand/:slug/perfumesCatálogo de marcaPremium
GET/public/rankings/by-note/:noteTop 10 por nota

GET/v1/search

Busca perfumes por nota olfativa, marca, género o categoría. Devuelve una lista paginada.

Parámetros

Nombre	Tipo	Descripción
`note`	string	Nota olfativa (ej: vanilla, rose, oud)
`brand`	string	Nombre de la marca (ej: Chanel, Dior)
`gender`	string	Género: male \| female \| unisex
`limit`	number	Máximo de resultados (default: 20, max: 100)
`offset`	number	Paginación (default: 0)

Respuesta de ejemplo

{
  "results": [
    {
      "id": "clxyz123",
      "name": "Vanilla Diorama",
      "slug": "vanilla-diorama",
      "brand": { "name": "Dior", "slug": "dior" },
      "year": 2023,
      "gender": "unisex",
      "accords": ["vanilla", "woody", "sweet"],
      "cloneCount": 14
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 142,
    "hasMore": true
  },
  "filters": { "note": "vanilla" }
}

Ejemplo con curl

curl "https://api.perfumesdupes.com/v1/search" \
  -H "X-API-Key: sk_live_your_key_here"

GET/v1/perfume/:id

Devuelve el perfil completo de un perfume: notas, acordes, rendimiento y precio. El array de clones está disponible en el endpoint /v1/perfume/:id/clones (plan de pago).

Parámetros

Nombre	Tipo	Descripción
`id`*	string	ID o slug del perfume

Respuesta de ejemplo

{
  "id": "clxyz123",
  "name": "Baccarat Rouge 540",
  "slug": "baccarat-rouge-540",
  "brand": { "name": "MFK", "slug": "mfk" },
  "year": 2015,
  "gender": "unisex",
  "concentration": "extrait",
  "notes": {
    "top": ["safran", "jazmín"],
    "heart": ["amberwood", "ambroxan"],
    "base": ["cedro", "almizcle"]
  },
  "accords": ["amberwood", "floral", "amberish"],
  "sillage": "strong",
  "longevity": "very long",
  "priceRange": "luxury",
  "cloneCount": 42
}

Ejemplo con curl

curl "https://api.perfumesdupes.com/v1/perfume/PERFUME_ID" \
  -H "X-API-Key: sk_live_your_key_here"

GET/v1/perfume/:id/clonesPremium

Devuelve todos los clones, alternativas e inspiraciones de un perfume, ordenados por similarity score.

Parámetros

Nombre	Tipo	Descripción
`id`*	string	ID o slug del perfume original

Respuesta de ejemplo

{
  "perfume": { "id": "clxyz123", "name": "Baccarat Rouge 540" },
  "equivalences": [
    {
      "targetName": "Lattafa Bade'e Al Oud Amethyst",
      "targetBrand": "Lattafa",
      "targetSlug": "badee-al-oud-amethyst",
      "similarityScore": 0.94,
      "confidence": "HIGH",
      "type": "CLONE",
      "priceRange": "budget"
    }
  ],
  "total": 42
}

Ejemplo con curl

curl "https://api.perfumesdupes.com/v1/perfume/PERFUME_ID/clones" \
  -H "X-API-Key: sk_live_your_key_here"

GET/v1/similar/:idPremium

Devuelve los perfumes más similares basado en notas, acordes y relaciones de equivalencia.

Parámetros

Nombre	Tipo	Descripción
`id`*	string	ID o slug del perfume de referencia
`limit`	number	Número de resultados (default: 10)

Respuesta de ejemplo

{
  "results": [
    {
      "id": "clabc456",
      "name": "Amyris Homme",
      "brand": { "name": "Maison Margiela" },
      "similarityScore": 0.87,
      "accords": ["amberwood", "floral"]
    }
  ]
}

Ejemplo con curl

curl "https://api.perfumesdupes.com/v1/similar/PERFUME_ID" \
  -H "X-API-Key: sk_live_your_key_here"

GET/v1/brand/:slug/perfumesPremium

Lista todos los perfumes de una marca con paginación.

Parámetros

Nombre	Tipo	Descripción
`slug`*	string	Slug de la marca (ej: chanel, dior, mfk)
`limit`	number	Máximo de resultados (default: 20)
`offset`	number	Paginación (default: 0)

Respuesta de ejemplo

{
  "brand": { "name": "Chanel", "slug": "chanel" },
  "results": [
    {
      "id": "cldef789",
      "name": "N°5",
      "slug": "n5",
      "year": 1921,
      "gender": "female",
      "cloneCount": 87
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 38 }
}

Ejemplo con curl

curl "https://api.perfumesdupes.com/v1/brand/chanel/perfumes" \
  -H "X-API-Key: sk_live_your_key_here"

GET/public/rankings/by-note/:note

Devuelve los 10 perfumes más clonados que contienen la nota indicada. Sin autenticación. Caché 1 hora.

Parámetros

Nombre	Tipo	Descripción
`note`*	string	Nota olfativa (ej: vanilla, rose, oud, bergamot)

Respuesta de ejemplo

{
  "note": "vanilla",
  "results": [
    {
      "rank": 1,
      "id": "clxyz123",
      "name": "Baccarat Rouge 540",
      "brand": "MFK",
      "cloneCount": 42
    }
  ],
  "cachedAt": "2025-01-15T10:00:00Z"
}

Ejemplo con curl

curl "https://api.perfumesdupes.com/public/rankings/by-note/vanilla"

Códigos de error

Código	Significado	Solución
`401 Unauthorized`	API key ausente o inválida	Incluye un X-API-Key válido en el header
`403 Forbidden`	Plan no tiene acceso al endpoint	Actualiza a un plan superior en /pricing
`404 Not Found`	Perfume o recurso no encontrado	Verifica el ID o slug del recurso
`429 Too Many Requests`	Rate limit alcanzado	Espera el tiempo indicado en Retry-After o actualiza el plan
`500 Internal Server Error`	Error inesperado en el servidor	Reintenta en unos segundos; contacta soporte si persiste

Rate limits por plan

Plan	Requests/día	Endpoints
Free	250/mes	/v1/search, /v1/perfume/:id
Developer	1.000/mes	Todos los /v1/
Pro	10.000/mes	Todos los /v1/ + Premium
Business	100.000/mes	Todos los /v1/ + Premium
Enterprise	Sin límite	Todos + acceso negociado

¿Listo para empezar?

Obtén tu API key y empieza a consultar datos de perfumes en minutos.

Empezar gratis Swagger UI interactivo ↗← Volver a Developers