Como funciona

A API de Catálogo organiza seu cardápio em três níveis: catálogo, categoria e item. Os itens têm complementos e podem ter preço e disponibilidade diferentes por canal de venda (contexto).Este guia mostra quando chamar cada endpoint. Para exemplos hands-on, veja Introdução. Para a referência completa, veja Endpoints.

Fluxo de integração

Toda integração segue seis passos:

Autentique — Obtenha um accessToken. Veja Autenticação.
Liste catálogos — GET /catalogs. Toda loja já tem pelo menos um.
Crie categorias — POST /categories agrupa itens (lanches, bebidas, sobremesas).
Crie itens — PUT /items envia item, produtos, grupos de opção e opções em uma chamada.
Atualize preço e status — PATCH /items/price e PATCH /items/status para mudanças pontuais.
Acompanhe operações em lote — GET /batch/{batchId} para patches assíncronos.

Arquitetura completa do catálogo mostrando merchants, catálogos, categorias, itens e modificadores

Exemplo de estrutura de produto mostrando item e seus componentes

Ciclo de vida do item

Todo item tem dois estados:

AVAILABLE — Clientes podem comprar.
UNAVAILABLE — Item pausado. Não aparece no app até retornar para AVAILABLE.

Use PATCH /items/status para alterne estados sem reenviar o item completo.

Escolha o endpoint certo

A mudança que você quer fazer determina o endpoint:

Mudança	Endpoint	Notas
Criar ou reescrever um item completo	`PUT /items`	Envia item, produtos, grupos e opções em uma chamada. Idempotente.
Alterar preço	`PATCH /items/price`	Muda apenas preço de itens. Suporta lote.
Alterar preço de complementos	`PATCH /options/price`	Muda apenas preço de opções (complementos). Suporta lote.
Pausar ou reativar um item	`PATCH /items/status`	Muda apenas `status`. Suporta lote.
Pausar uma opção de complemento	`PATCH /options/status`	Afeta uma única opção.
Pausar todas as opções de um grupo	`PATCH /optionGroups/status`	Afeta o grupo inteiro.
Ajustar estoque	`POST /inventory`	Define a quantidade máxima vendível.

Lembre-se: PUT /items substitui o item completo — campos omitidos são removidos. Use PATCH para mudanças pontuais.

Idempotência

PUT /items é idempotente: chamar duas vezes com o mesmo payload não cria duplicatas. A segunda chamada sobrescreve a primeira, simplificando retries em falhas transitórias.

Exemplos de payload

Criar um item simples

PUT /catalog/v2.0/merchants/{merchantId}/items

{
  "item": {
    "id": "burger-001",
    "type": "DEFAULT",
    "categoryId": "appetizers",
    "status": "AVAILABLE",
    "price": {"value": 25.00}
  },
  "products": [
    {
      "id": "burger-prod-001",
      "name": "X-Burger"
    }
  ],
  "optionGroups": [],
  "options": []
}

Adicionar complementos

Use o mesmo PUT /items com optionGroups e options preenchidos:

{
  "item": { /* ... */ },
  "products": [ /* ... */ ],
  "optionGroups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Escolha uma bebida",
      "min": 0,
      "max": 1,
      "optionIds": ["550e8400-e29b-41d4-a716-446655440020", "550e8400-e29b-41d4-a716-446655440021"]
    }
  ],
  "options": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "productId": "550e8400-e29b-41d4-a716-446655440002",
      "price": {"value": 8.00}
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "productId": "550e8400-e29b-41d4-a716-446655440003",
      "price": {"value": 12.00}
    }
  ]
}

Atualizar preços em lote

PATCH /catalog/v2.0/merchants/{merchantId}/items/price

{
  "prices": [
    {"productId": "burger-prod-001", "price": 26.50},
    {"productId": "burger-prod-002", "price": 28.00}
  ]
}

A resposta retorna um batchId. Acompanhe com GET /batch/{batchId}:

GET /catalog/v2.0/merchants/{merchantId}/batch/{batchId}

{
  "batchId": "batch-123",
  "status": "COMPLETED",
  "successCount": 95,
  "failureCount": 5
}

Patches em lote rodam de forma assíncrona. Consulte GET /batch/{batchId} até o status ser COMPLETED antes de assumir que as mudanças estão aplicadas.

Multi-canal com contextos

Ofereça o mesmo item em canais diferentes (Entrega, Cardápio Digital, Consumo no Local) com preços e status distintos. Use contextModifiers em vez de duplicar itens:

{
  "item": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "price": {"value": 25.00},
    "status": "AVAILABLE",
    "contextModifiers": [
      {
        "catalogContext": "WHITELABEL",
        "price": {"value": 28.00},
        "status": "UNAVAILABLE"
      }
    ]
  }
}