Colaboraciones de Marketplace

API de artículos para socios de Marketplace

Si eres socio de Marketplace, tus anuncios estarán disponibles en Facebook Marketplace en ciertos países.

Para subir, actualizar o eliminar tus productos en Facebook Marketplace usarás la interfaz de API Graph.

HTTP
POST /v20.0/{product-catalog-id}/items_batch HTTP/1.1

Si quieres aprender a usar la API Graph, consulta nuestra guía de uso de la API Graph.

Al publicar en este perímetro, se creará un producto.

Parámetros

Parámetro	Descripción
item_type	Establecido como “PRODUCT_ITEM”.
requests	El método y los campos de cada producto de una variedad de productos.

En el parámetro “requests”, definirás el método y los datos de tu solicitud.

Campo	Descripción
method	La acción que deseas realizar para un producto concreto. Las opciones son crear, actualizar o eliminar: CREATE UPDATE DELETE
data	La información sobre el producto que se va a crear, actualizar o eliminar.

Ejemplo de parámetro “requests”

[
    {
        "method": "CREATE",
        "data": {
            "id": "UniqueProductID",
            "title": "Title",
            "description": "This is the description",
            "price": "100 USD",
            "image_link": "https:\/\/www.facebook.com",
            "brand": "Monster",
            "availability": "in stock",
            "condition": "new",
            "link": "https:\/\/www.facebook.com",
            "return_details": {"return_days": "30", "return_type": "SELLER_PAID_RETURN"},
            "partner_product_checkout_uri": "https:\/\/www.facebook.com",
            "partner_product_location": "San Fransisco, CA",
            "partner_product_expiration_time": "1923181264",
            "partner_delivery_method": ["shipping"],
            "partner_shipping_type": "fixed",
            "partner_shipping_cost": "14.95",
            "partner_shipping_speed": "3:5",
            "partner_attribute_data": {"color": "blue"},
            "partner_seller_id": "MySellerId1",
            "partner_item_country": "US"
        }
    },
    .... {next product}
]

Límite de frecuencia de la API

Para prevenir que se produzcan restricciones, sigue estas recomendaciones:

No excedas las 30 llamadas por minuto. Superar esta cifra dará lugar a una restricción.
Lote de artículos en una llamada a la API, hasta 300.

Campos de producto

Parámetro	Tipo	Obligatorio u opcional	Descripción
`id`	Cadena (límite de caracteres: 100)	Obligatorio	Identificador del contenido específico del artículo. Utiliza el SKU del artículo si puedes. Cada identificador de contenido debe aparecer solo una vez en el catálogo. Si existen varias instancias del mismo identificador, se ignoran todas. Si hay artículos disponibles en varios países, debe reutilizar el mismo identificador en todos los catálogos. Asegúrate de actualizar el precio según la divisa del país (véase el campo de precios).
`title`	Cadena (límite de caracteres: 200)	Obligatorio	Título del producto que aparece en la publicación de Marketplace. Este texto aparecerá en Marketplace. No incluyas etiquetas HTML.
`description`	Cadena (límite de caracteres: 9999)	Obligatorio	Descripción del producto. Aunque el límite de este campo está establecido en 9999 caracteres, solo se mostrarán los primeros 256 en la publicación de Facebook Marketplace. Este texto aparecerá en Marketplace. No incluyas etiquetas HTML. Por ejemplo: Cómoda camiseta azul real en algodón orgánico para mujer. Manga corta y corte holgado. Perfecta para los calurosos días de verano.
`condition`	Enumeración {new, refurbished, used, used_like_new, used_good, used_fair, cpo, open_box_new}	Obligatorio	Estado del producto.
`partner_listing_type`	Enum {fixed_price, auction, vehicle, rental, real_estate}	Opcional	Determina el tipo de publicación. Si no se selecciona nada, se establecerá de forma predeterminada en “fixed_price”. Si se establece en “auction”, “vehicle”, “rental” o “real_estate”, ofrecerá la experiencia de tipo de anuncio de socio especificado para los compradores en Marketplace.
`partner_product_condition`	Enumeración {acceptable, brand_new, certified_pre_owned, certified_refurbished, damaged, digital_good, excellent_refurbished, for_parts_or_not_working, good, good_refurbished, graded, like_new, new, new_other, new_other_see_details, new_with_box, new_with_defects, new_with_tags, open_box, others, pre_owned, remanufactured, retread, seller_refurbished, ungraded, used, very_good, very_good_refurbished, new_open_box, open_box_used, new_factory_sealed, unknown}	Opcional	Estado del producto. Este campo opcional invalidará el campo “condition”. Utilízalo si quieres dar más detalles sobre el estado del producto.
`brand`	Cadena	Obligatorio	Marca del producto. Si no tiene, configúralo como “N/A”.
`price`	Cadena (límite de caracteres: 9999)	Obligatorio	El formato del precio debe ser un número seguido de un espacio y el código de divisa ISO 4217 de tres letras. Por ejemplo, 10,99 EUR Si el tipo de anuncio es “auction”, este será el precio de puja del producto. El formato del precio debe ser un número seguido de un espacio y el código de divisa ISO 4217 de tres letras.
`availability`	Enumeración {in stock, out of stock}	Obligatorio	Disponibilidad del producto.
`link`	Cadena	Obligatorio	Enlace con la URL de la web móvil de la página de detalles del producto.
`partner_product_checkout_uri`	Cadena	Opcional	Enlace con la URL de finalización de compra al que enviaríamos al usuario cuando toque el botón “Comprar” de la publicación. Añadiremos el campo “clic_id” al parámetro. Si falta, añadiremos de forma predeterminada la URL desde el campo “link”.
`partner_product_html_desc_uri`	Cadena	Opcional	Enlace con la URL al sitio web con la descripción completa del producto. Se usa si la descripción del producto contiene más caracteres de los que caben en el campo de texto “description”. Marketplace proporcionará opcionalmente un enlace a la descripción completa.
`image_link`	Cadena	Obligatorio	URL de la imagen principal de tu artículo. Las imágenes deben estar en formato JPEG o PNG, tener unas dimensiones de al menos 500 × 500 píxeles y ocupar un máximo de 8 MB. Consulta las especificaciones de las imágenes del producto.
`partner_seller_id`	Cadena (límite de caracteres: 100)	Obligatorio	Identificador único del vendedor. Debe coincidir con el campo “partner_seller_id” de la información del vendedor. Ejemplo: “partner_seller_id”: “great_seller _inc”.
`partner_item_country`	Enumeración {AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK}	Obligatorio	Este es el país en el que el producto está disponible y, si procede, al que puede enviarse. El país del catálogo y “partner_item_country” tienen que coincidir. Artículos que admiten los envíos transfronterizos; se requiere crear un artículo en cada catálogo de país donde se admitan los envíos y el socio tenga la intención de distribuir.
`fb_product_category`	Cadena	Opcional	Categoría de producto de Facebook del artículo. La categoría de producto de Facebook más específica posible de esta lista: hoja de cálculo (.csv) o texto sin formato (.txt).
`status`	Enumeración {active, archived}	Opcional	Estado actual del producto.
`sale_price`	Cadena	Opcional	El formato del precio debe ser un número seguido de un espacio y el código de divisa ISO 4217 de tres letras. Por ejemplo, 10,99 EUR. Es el mismo formato que el campo “price”. Utilízalos de forma conjunta para mostrar descuentos.
`sale_price_effective_date`	Cadena	Opcional	Fecha y hora de inicio y fin de la oferta, separadas por una barra inclinada. Las fechas de inicio y finalización deben seguir este formato: AAAA-MM-DD. Añade una “T” después de cada una e incluye la hora. Escribe la hora en un formato de 24 horas (de 0:00 a 23:59). Por ejemplo: 2014-11-01T12:00-0300/2014-12-01T00:00-0300.
`additional_image_link`	Cadena (límite de caracteres: 2000)	Opcional	URL de un máximo de 20 imágenes adicionales del artículo, separadas por comas (,), punto y coma (;), espacio ( ) o barra vertical (\|). Sigue las mismas indicaciones de la imagen que las del campo “image_link”.
`return_details`	Objeto json anulable (por ejemplo, mapa) { “return_days”: 30, “return_type”: enum } Enumeración: FINAL_SALE NO_RETURNS_WITH_EXCEPTION NO_RETURNS SELLER_PAID_RETURN BUYER_PAID_RETURN. O bien, si las devoluciones no están disponibles: “return_details”: null	Opcional	return_days indica el número de días en los que el comprador tiene que iniciar la devolución del producto. return_days debería ser -1 para NO_RETURNS y FINAL_SALE. return_type hace referencia al tipo de devolución admitida para el producto. Las opciones disponibles son: FINAL_SALE, NO_RETURNS_WITH_EXCEPTION, NO_RETURNS, SELLER_PAID_RETURN, BUYER_PAID_RETURN Si este campo se deja vacío, los detalles de la devolución no se mostrarán.
`partner_attribute_data`	Objeto json nulo { “color”: “blue” } Claves disponibles: aspect_ratio, band_material, bike_type, brand, break_type, cable_length, capacity, case_size, certification, character, circulated_uncirculated, closure, color, compatible_bike_type, compatible_brand, compatible_model, compatible_operating_system, compatible_product, connectivity, credit_included, denomination, department, display_technology, dress_length, exterior_color, exterior_material, fabric_type, features, film_format, fit, focal_length, focus_type, form_factor, format, frame_color, game_name, game, gauge, golf_club_type, handedness, inseam, internet_connectivity, item_height, item_length, item_weight, item_width, items_included, main_stone, manufacturer_part_number, manufacturer, material, maximum_aperture, maximum_magnification, maximum_resolution, memory_cards_supported, metal_purity, metal, model, mount, mpn, network, number_of_items, occasion, outer_shell_material, package_quantity, part_type, pattern, performance_activity, platform, processor, publication_name, quantity, rack_type, rim_diameter, rim_width, ring_size, screen_size, section_width, series, set_includes, set, size_type, size, skirt_length, sleeve_length, sport_activity, sport, storage_capacity, style, type, unit_quantity, unit_type, upper_material, us_shoe_size, vintage, voltage, volume, waist_size, wheel_diameter, year	Opcional	Una lista de valores clave de atributos que se mostrarán en la sección de detalles del producto. Los valores tienen formato de cadena. Claves aplicables a alquileres/inmuebles: property_type (obligatorio), sale_type, bed_bath, area_size, pet_friendly, ac_type, heating_type, laundry_type, parking_type, parkingSpace, furnishing_type, garden_type, tenure_type, listed_by, property_tax_and_condo_fee, construction_status, lease_duration, energy_rating_eu, co2_emission_rating Claves aplicables a vehículos: vehicle_type, year, make, model, number_of_owners, trim, body_style, exterior_color, interior_color, transmission, fuel_type, mileage, money_still_owed, motorcycle_type, engine_size
`partner_product_creation_time`	Marca de tiempo UNIX en segundos UTC (número)	Opcional	Marca de tiempo UNIX del momento de creación o actualización del producto. Ejemplo: “partner_product_creation_time”: 1713917255.
`partner_product_location`	Cadena	Opcional	La cadena que se muestra hace referencia a la ubicación del artículo. Ejemplo: “París, Francia”. No hay restricciones sobre lo específica o amplia que puede ser esta cadena.
`partner_product_expiration_time`	Marca de tiempo UNIX en segundos UTC (número)	Opcional	Momento en el que la publicación se suprimirá de Marketplace. Debe ser un momento futuro.
`partner_delivery_method`	Matriz de enumeraciones de cadenas {shipping, in_person}	Opcional	Recoge el modo en el que se puede entregar el producto a un comprador. Si un producto se puede enviar y recoger en persona, incluye ambos métodos. Ejemplo: [“shipping”,“in_person”]. Valor predeterminado: [“shipping”]
`partner_item_latitude`	Flotante	Opcional	Latitud del artículo. Obligatorio si el método de entrega incluye “in_person”.
`partner_item_longitude`	Flotante	Opcional	Longitud del artículo. Obligatorio si el método de entrega incluye “in_person”.
`partner_shipping_type`	Enumeración {free, fixed, dynamic}	Opcional	Estrategia de precios de envío para el artículo. Si el envío es gratuito, usa “free”. Si el envío es un precio fijo, independientemente de la ubicación, usa “fixed” y establece el coste en el campo “partner_shipping_cost”. Si el precio de envío varía según la ubicación del comprador, las variantes, etc., selecciona “dynamic”. Si es dinámico, no mostraremos el coste del envío, sino que indicaremos que se puede consultar en la finalización de compra. Valor predeterminado: “dynamic”
`partner_shipping_cost`	Flotante	Opcional	Obligatorio si el campo “partner_shipping_type” está configurado como “fixed”. Ejemplo “14,95”.
`partner_shipping_speed`	Cadena “MIN_DELIVERY_SPEED_IN_DAYS:MAX_DELIVERY_SPEED_IN_DAYS”	Opcional	Días hábiles mínimos y máximos esperados para enviar el artículo. Por ejemplo: “3:5”.
`partner_auction_bid_close_time`	Marca de tiempo UNIX en segundos UTC (número)	Opcional	Campo obligatorio si partner_listing_type es “auction”. Aquí es cuando se cierra la puja por el producto. Por ejemplo: “partner_auction_bid_close_time”: 1713917255.
`partner_auction_bid_count`	Número	Opcional	Aplicable solo si partner_listing_type es “auction”. Este es el número actual de pujas realizadas para el producto.
`additional_fields`	Objeto JSON nulo Forma libre (sin enumeración o claves establecidas) { “revised_title”: “Premium Blue T-Shirt” }	Opcional	Un campo JSON de forma libre para que los socios envíen campos adicionales.

Comprobar estado de subida

Tras enviar una solicitud para crear, actualizar o eliminar, recibirás un identificador. Puedes comprobar el resultado del envío con otra solicitud.

El campo “data -> status” se establecerá como “finished” una vez completado y se mostrarán los errores y advertencias.

HTTP
GET /v20.0/{product-catalog-id}/check_batch_request_status?handle={tu identificador}

Ejemplo de devolución

{
  "data": [
    {
      "handle": "Acy3FUJwzE10XnWrYr4ttrjOAfs-h6BUg-Wtg6sWGeV7qZZaErX15XPfqT_KWeyC6T4-nTbng9r1BJuScb6hgO1B",
      "status": "finished",
      "errors_total_count": 0,
      "errors": [
      ],
      "warnings": [
        {
          "line": 1,
          "id": "YourItemID",
          "message": "These attributes are invalid and need to be updated in the feed file: The product_tags information under  is invalid. Review for more details"
        }
      ],
      "ids_of_invalid_requests": [
      ]
    }
  ],
  "__www_request_id__": "Az3ghYsDh-101IH2t6DXKuP"
}

Ver y administrar productos

Para ver o administrar los productos subidos en Commerce Manager. Cualquier problema con los productos se mostrará en Commerce Manager y puede resolverse en la propia herramienta.