Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Fundamentos

Referência conceitual dos objetos da Catalog API v2.0. Para tutoriais e chamadas, veja Introdução e Endpoints.

Hierarquia do catálogo

Catálogo
├── Contexto (DEFAULT, WHITELABEL, INDOOR)
│   ├── Categoria
│   │   └── Item
│   │       ├── Produtos (products)
│   │       └── Grupos de complementos (optionGroups)
│   │           └── Opções (options)

Cada nível tem seu próprio status. Preço e status podem variar por contexto via contextModifiers.

Diagrama da hierarquia do catálogo mostrando a estrutura de Merchant através de Catálogos, Categorias, Itens e Complementos

Contextos

Um catálogo serve múltiplos canais de venda. Cada canal é um contexto:

Contexto	Canal
`DEFAULT`	Entrega
`WHITELABEL`	Cardápio Digital
`INDOOR`	Consumo no Local

O mesmo item pode ter preço, status e código POS diferentes por contexto. Use contextModifiers para customizar valores por contexto em vez de duplicar o item. Diagrama mostrando como um único catálogo serve múltiplos contextos

Diagrama mostrando como um único catálogo serve múltiplos contextos

Categorias

Categorias agrupam itens no cardápio. O campo template define o tipo:

DEFAULT — Itens comuns (lanches, bebidas, sobremesas).
PIZZA — Itens de pizza, com grupos de complementos obrigatórios (SIZE, CRUST, EDGE, TOPPING). Uma loja aceita no máximo uma categoria PIZZA. Veja Pizza.

Outros tipos de item, como combos, use o tipo DEFAULT no item e a estrutura de complementos (optionGroups) para modelar a complexidade necessária. Veja Combos. Exemplo de uma categoria com itens e como aparecem nos contextos de Entrega e Cardápio Digital

Itens

Item é o produto vendido ao cliente final (X-Burger, Refrigerante, Pizza Calabresa).

Tipos de item

`type`	Uso	Grupos obrigatórios
`DEFAULT`	Item simples	Nenhum
`PIZZA`	Pizza	`SIZE`, `CRUST`, `EDGE`, `TOPPING`
`COMBO_V2`	Combo com até 3 níveis de customização	Nenhum

Campos principais

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador que você gera. Use-o para referenciar o item em atualizações.
`type`	enum	Sim	`DEFAULT`, `PIZZA` ou `COMBO_V2`.
`categoryId`	string	Sim	ID da categoria.
`status`	enum	Sim	`AVAILABLE` (visível) ou `UNAVAILABLE` (pausado).
`price`	object	Sim	Objeto com `value` (número) e `originalValue` (opcional).
`externalCode`	string	Sim	Seu código POS. Único por merchant.

`id` — Identificador do item

O id é um identificador que você gera e deve seguir o padrão UUID v4. Ele identifica unicamente o item no seu sistema.Se você enviar um id que não esteja no formato UUID v4, a API retornará um erro 404.Exemplos de UUIDs v4 válidos:

550e8400-e29b-41d4-a716-446655440000
123e4567-e89b-12d3-a456-426614174000

`externalCode` — Código POS customizado

O externalCode é seu identificador customizado para integração com PDV. Diferentemente do id, não precisa seguir o padrão UUID — é uma string arbitrária que você controla. Deve ser único dentro do merchant.Exemplos válidos:

BURGER_001, COKE_001, COLDRINK_GROUP
xburger-default, frappuccino-grande

Se você enviar um item com externalCode já existente, a API reutiliza o item em vez de criar outro. Você pode usar o externalCode como identificador principal do seu POS/PDV em vez do id — eles são interoperáveis para fins de sincronização. Item com exemplo de campo de código externo

Item com exemplo de campo de código externo

Preço

{
  "value": 25.00,
  "originalValue": 30.00
}

value — Preço cobrado.
originalValue — Preço original, usado para exibir desconto. Opcional.

Complementos

Complementos são escolhas que o cliente faz ao comprar um item (bebida, tamanho, molho). Organize complementos em grupos (optionGroups) que contêm opções (options).

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

Exemplo de grupo de complementos mostrando grupos de add-on e opções

Tipos de grupo

Todo grupo precisa de um optionGroupType:

Tipo	Uso	Exemplo
`OFFER_UNIT`	Venda adicional (cross-sell)	Bebida no combo
`SPECIFICATION`	Especificação de preparo	Ponto da carne
`INGREDIENTS`	Alteração de ingredientes	Com ou sem cebola
`CUTLERY`	Utensílios	Garfo, faca, guardanapo

Pizzas usam os tipos especiais SIZE, CRUST, EDGE e TOPPING. Veja Pizza.

Obrigatoriedade (`min` e `max`)

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`

Exemplo mostrando requisitos de grupos de add-on obrigatórios

Exemplo mostrando requisitos de grupos de add-on opcionais

`contextModifiers`

Use contextModifiers para sobrescrever campos de um item ou opção em contextos específicos, sem duplicar o objeto:

{
  "item": {
    "id": "item-burger",
    "price": {"value": 25.00},
    "status": "AVAILABLE",
    "contextModifiers": [
      {
        "catalogContext": "WHITELABEL",
        "price": {"value": 28.00},
        "status": "UNAVAILABLE"
      }
    ]
  }
}

Campos aceitos em contextModifiers:

catalogContext — Contexto afetado (obrigatório).
price — Preço no contexto.
status — Status no contexto.
externalCode — Código POS no contexto.

Contextos não listados herdam os valores da raiz.

Inventário

Inventário limita a quantidade vendível de um produto. Quando o estoque atinge zero, o item torna-se UNAVAILABLE automaticamente. Use inventário para produtos com quantidade limitada (ex.: bolo artesanal). Veja Gerenciar Disponibilidade. Exemplo de quantidade de produto servida