Gerenciar complementos

Complementos (chamados options na API) são escolhas que o cliente faz ao comprar um item: bebidas, molhos, ingredientes extras. Este guia cobre como criá-los, atualizá-los e controlar obrigatoriedade.Para a referência conceitual (tipos de grupo, campos obrigatórios), veja Fundamentos.

Estrutura

Complementos são organizados em grupos (optionGroups) com opções (options):

{
  "optionGroups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Escolha uma bebida",
      "status": "AVAILABLE",
      "optionGroupType": "OFFER_UNIT",
      "min": 0,
      "max": 1,
      "optionIds": ["opt-coke", "opt-juice"]
    }
  ],
  "options": [
    {
      "id": "opt-coke",
      "productId": "prod-coke",
      "status": "AVAILABLE",
      "price": {"value": 8.00}
    },
    {
      "id": "opt-juice",
      "productId": "prod-juice",
      "status": "AVAILABLE",
      "price": {"value": 10.00}
    }
  ]
}

O grupo aponta para as opções via optionIds. Cada opção referencia um product pelo productId.

Criar complementos

Envie o item com os grupos e opções no mesmo PUT /items:

curl --request PUT \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "item": {
      "id": "item-burger",
      "type": "DEFAULT",
      "status": "AVAILABLE",
      "price": {"value": 25.00}
    },
    "products": [
      {
        "id": "prod-burger",
        "name": "Hamburger",
        "optionGroups": [
          {"id": "550e8400-e29b-41d4-a716-446655440010", "min": 0, "max": 1},
          {"id": "og-sauces", "min": 0, "max": 2}
        ]
      },
      {"id": "prod-coke", "name": "Coca-Cola"},
      {"id": "prod-ketchup", "name": "Ketchup"},
      {"id": "prod-mayo", "name": "Maionese"}
    ],
    "optionGroups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "name": "Escolha uma bebida",
        "status": "AVAILABLE",
        "optionGroupType": "OFFER_UNIT",
        "optionIds": ["opt-coke"]
      },
      {
        "id": "og-sauces",
        "name": "Escolha molhos",
        "status": "AVAILABLE",
        "optionGroupType": "INGREDIENTS",
        "optionIds": ["opt-ketchup", "opt-mayo"]
      }
    ],
    "options": [
      {
        "id": "opt-coke",
        "productId": "prod-coke",
        "status": "AVAILABLE",
        "price": {"value": 8.00}
      },
      {
        "id": "opt-ketchup",
        "productId": "prod-ketchup",
        "status": "AVAILABLE",
        "price": {"value": 0}
      },
      {
        "id": "opt-mayo",
        "productId": "prod-mayo",
        "status": "AVAILABLE",
        "price": {"value": 0}
      }
    ]
  }'

Toda opção precisa de price, mesmo que seja 0.

Atualizar preço de uma opção

Use PATCH /options/price em vez de reenviar o item inteiro:

curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/options/price' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "optionId": "opt-coke",
    "price": {"value": 9.00}
  }'

Pausar ou reativar uma opção

Use PATCH /options/status:

curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/options/status' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "optionId": "opt-coke",
    "status": "UNAVAILABLE"
  }'

Obrigatoriedade

Use min e max no grupo para controlar quantas opções o cliente pode escolher:

Regra	`min`	`max`
Obrigatório, 1 escolha	`1`	`1`
Obrigatório, múltiplas escolhas	`2`	`3`
Opcional, 1 escolha	`0`	`1`
Opcional, múltiplas escolhas	`0`	`5`

Se um grupo obrigatório não tem nenhuma opção AVAILABLE, o item inteiro fica indisponível. Diagnostique com GET /catalogs/{catalogId}/unsellableItems.

Terceiro nível (aninhamento)

Grupos de complemento podem ser vinculados a opções para criar uma camada extra de customização (ex.: após escolher "Hamburger de salada", permitir tirar ingredientes). O terceiro nível é suportado apenas em combos — veja Combos.

Próximos passos

Criar um combo — Combos.
Modelar pizza — Pizza.
Pausar opções ou grupos — Gerenciar disponibilidade.
Alterar preços em lote — Veja PATCH /products/price em Endpoints.

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página