API pública v1 de Pinturas Popular

API HTTP de solo lectura con el catálogo de productos, la carta de colores, las tiendas y los contenidos del sitio (noticias, tips, tendencias y preguntas frecuentes). Todas las respuestas son JSON. La especificación completa está en OpenAPI 3.1 (/openapi.json).

Autenticación

Cada petición necesita una API key. Envíala en la cabecera x-api-key o como token Authorization: Bearer. Sin una key válida la API responde 401. 

curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/products?limit=5" -H "x-api-key: $API_KEY"
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/products?limit=5" -H "Authorization: Bearer $API_KEY"

¿Necesitas una key? Escríbenos desde el formulario de contacto y cuéntanos qué integración quieres construir.

Formato de respuesta

Las colecciones devuelven { "data": [...], "meta": { "total", "limit", "offset" } } y los detalles { "data": { ... } }. Pagina con limit y offset. Los archivos (imágenes, fichas técnicas) se descargan desde /api/assets/{id}.

Límites de uso

Cada IP puede hacer 60 peticiones cada 60 segundos. Todas las respuestas incluyen las cabeceras RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset y RateLimit-Policy. Si superas el límite recibirás un 429 con Retry-After en segundos.

Errores

Los errores comparten un formato JSON con un código estable, un mensaje y una pista para resolverlo. 

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or missing API key",
    "hint": "Send your key in the \"x-api-key\" header or as \"Authorization: Bearer <key>\". Request a key through /contacto.",
    "docs": "/docs/api"
  },
  "statusCode": 401,
  "statusMessage": "Invalid or missing API key"
}
HTTPerror.codeSignificado
400invalid_parametersAlgún parámetro no es válido. `data.issues` indica cuál.
401invalid_api_keyFalta la API key o no es correcta.
404not_foundEl recurso no existe o no está publicado.
429rate_limitedSuperaste el límite. Espera los segundos de `Retry-After`.
500internal_errorError inesperado del servidor. Reintenta más tarde.

Versiones y retirada de endpoints

La versión mayor va en la ruta (/api/v1). Dentro de v1 solo hay cambios compatibles: pueden aparecer endpoints, parámetros opcionales y campos nuevos, así que tu integración debe ignorar los campos que no conozca. Quitar o renombrar campos, parámetros o endpoints exige una versión nueva (/api/v2).

Antes de retirar algo lo marcaremos como obsoleto en el documento OpenAPI y sus respuestas llevarán las cabeceras Deprecation (RFC 9745) y Sunset (RFC 8594) con la fecha de retirada, con al menos 180 días de antelación. Hoy no hay nada obsoleto.

Endpoints

GET /api/v1/products

operationId: listProducts · List products

Paginated list of published products. Use it to search the catalogue by name or SKU, or to filter by business unit, category, finish and usage (interior, exterior). Sorted like the website catalogue.

ParámetroTipoDescripción
unidadstringBusiness unit slug, e.g. arquitectonico, industrial, madera.
categoriastringProduct category slug.
finishstring[]Finish filter (case-insensitive contains). Repeat the parameter to match any of several finishes.
is_ready_mixstringOnly ready-mix products. The filter is applied only when the value is exactly `true`; any other value is ignored.
is_color_matcherstringOnly products available in the color matcher. The filter is applied only when the value is exactly `true`; any other value is ignored.
has_color_basestringOnly products with a tintable color base. The filter is applied only when the value is exactly `true`; any other value is ignored.
is_third_partystringOnly third-party brand products. The filter is applied only when the value is exactly `true`; any other value is ignored.
interiorstringOnly products suitable for interiors. The filter is applied only when the value is exactly `true`; any other value is ignored.
exteriorstringOnly products suitable for exteriors. The filter is applied only when the value is exactly `true`; any other value is ignored.
slugstringExact product slug.
searchstringCase-insensitive "contains" search over product name and SKU.
limitintegerMaximum number of rows to return. Defaults to 12 when missing, empty or not a number.
offsetintegerNumber of rows to skip for pagination. Defaults to 0.
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/products" \
  -H "x-api-key: $API_KEY"

GET /api/v1/products/{slug}

operationId: getProductBySlug · Get a product

Full detail of one published product: technical data, pack sizes, compatible colors, attributes, technical and safety sheets. Returns 404 when the slug does not exist or is unpublished.

ParámetroTipoDescripción
slug*stringURL slug of the product (lowercase letters, digits and hyphens).
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/products/ejemplo-de-slug" \
  -H "x-api-key: $API_KEY"

GET /api/v1/colors

operationId: listColors · List colors

Paginated color chart. Filter by family, undertone, category, base or line, or search by name or code.

ParámetroTipoDescripción
color_family_idstringColor family id (see listColorFamilies).
undertonestring[]Undertone filter. Repeat the parameter to match any of several values.
is_best_sellerstringOnly best-selling colors. The filter is applied only when the value is exactly `true`; any other value is ignored.
category_idstringColor category id.
base_idstringColor base id.
color_line_idstringColor line id (see listColorLines).
searchstringCase-insensitive "contains" search over color name and code.
sort_bystringSort order: `code`, `family`, or name when omitted or any other value.
limitintegerMaximum number of rows to return. Defaults to 30 when missing, empty or not a number.
offsetintegerNumber of rows to skip for pagination. Defaults to 0.
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/colors" \
  -H "x-api-key: $API_KEY"

GET /api/v1/color-families

operationId: listColorFamilies · List color families

All color families with their swatch. Not paginated. Use the ids to filter listColors.

curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/color-families" \
  -H "x-api-key: $API_KEY"

GET /api/v1/color-lines

operationId: listColorLines · List color lines

All color lines, optionally restricted to one color category. Not paginated.

ParámetroTipoDescripción
category_idstringColor category id (matches the line base category).
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/color-lines" \
  -H "x-api-key: $API_KEY"

GET /api/v1/stores

operationId: listStores · List or find nearby stores

Points of sale. Standard mode filters by region, services and category. Nearby mode starts when both `lat` and `lng` are sent: rows are ordered by distance and include `distance_km`. Not paginated.

ParámetroTipoDescripción
regionstringRegion name (contains).
has_redimixstringOnly stores with Redimix service. The filter is applied only when the value is exactly `true`; any other value is ignored.
has_color_matcherstringOnly stores with a color matcher. The filter is applied only when the value is exactly `true`; any other value is ignored.
has_rostolinstringOnly stores selling Rostolin. The filter is applied only when the value is exactly `true`; any other value is ignored.
categorystringStore category id.
searchstringCase-insensitive "contains" search over store name and address.
latnumberLatitude in decimal degrees. Send together with lng to enable nearby mode.
lngnumberLongitude in decimal degrees. Send together with lat to enable nearby mode.
radiusKmnumberNearby mode only: maximum distance in km.
limitintegerNearby mode only: maximum number of stores.
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/stores" \
  -H "x-api-key: $API_KEY"

GET /api/v1/noticias

operationId: listNoticias · List news

Paginated company news, newest first.

ParámetroTipoDescripción
categoriastringSlug of the news category to filter by.
featuredstringOnly featured news. The filter is applied only when the value is exactly `true`; any other value is ignored.
announcementstringOnly announcements. The filter is applied only when the value is exactly `true`; any other value is ignored.
searchstringCase-insensitive "contains" search over title and excerpt.
limitintegerMaximum number of rows to return. Defaults to 12 when missing, empty or not a number.
offsetintegerNumber of rows to skip for pagination. Defaults to 0.
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/noticias" \
  -H "x-api-key: $API_KEY"

GET /api/v1/noticias/{slug}

operationId: getNoticiaBySlug · Get a news article

Full news article with HTML content. Returns 404 when not found or unpublished.

ParámetroTipoDescripción
slug*stringURL slug of the news article (lowercase letters, digits and hyphens).
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/noticias/ejemplo-de-slug" \
  -H "x-api-key: $API_KEY"

GET /api/v1/tips

operationId: listTips · List painting tips

Paginated how-to guides about preparing surfaces and painting, newest first.

ParámetroTipoDescripción
categoriastringSlug of the tip category to filter by.
featuredstringOnly featured tips. The filter is applied only when the value is exactly `true`; any other value is ignored.
searchstringCase-insensitive "contains" search over title and excerpt.
limitintegerMaximum number of rows to return. Defaults to 12 when missing, empty or not a number.
offsetintegerNumber of rows to skip for pagination. Defaults to 0.
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/tips" \
  -H "x-api-key: $API_KEY"

GET /api/v1/tips/{slug}

operationId: getTipBySlug · Get a tip

Full tip with HTML content. Returns 404 when not found or unpublished.

ParámetroTipoDescripción
slug*stringURL slug of the tip (lowercase letters, digits and hyphens).
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/tips/ejemplo-de-slug" \
  -H "x-api-key: $API_KEY"

GET /api/v1/tendencias

operationId: listTendencias · List color trends

Paginated color and decoration trends, newest first. Each row includes its gallery and color palette.

ParámetroTipoDescripción
categoriastringSlug of the trend category to filter by.
featuredstringOnly featured trends. The filter is applied only when the value is exactly `true`; any other value is ignored.
searchstringCase-insensitive "contains" search over title and excerpt.
limitintegerMaximum number of rows to return. Defaults to 6 when missing, empty or not a number.
offsetintegerNumber of rows to skip for pagination. Defaults to 0.
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/tendencias" \
  -H "x-api-key: $API_KEY"

GET /api/v1/tendencias/{slug}

operationId: getTendenciaBySlug · Get a color trend

Full trend with content, gallery and palette. Returns 404 when not found or unpublished.

ParámetroTipoDescripción
slug*stringURL slug of the trend (lowercase letters, digits and hyphens).
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/tendencias/ejemplo-de-slug" \
  -H "x-api-key: $API_KEY"

GET /api/v1/faq

operationId: listFaq · List frequently asked questions

Paginated FAQ entries ordered as on the website. Use it to answer customer questions about products and purchases.

ParámetroTipoDescripción
categoriastringSlug of the FAQ category to filter by.
searchstringCase-insensitive "contains" search over question and answer.
limitintegerMaximum number of rows to return. Defaults to 12 when missing, empty or not a number.
offsetintegerNumber of rows to skip for pagination. Defaults to 0.
curl -s "https://pinturas-popular-staging.zunamicorp.com/api/v1/faq" \
  -H "x-api-key: $API_KEY"