> ## Documentation Index > Fetch the complete documentation index at: https://docs.cardapioweb.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar item > Cria um novo item no cardápio. O nome deve ser único no estabelecimento. Para associar grupos de complementos, é necessário que eles tenham sido criados previamente. Em seguida, o ID de cada grupo deve ser enviado no array `option_groups`, utilizando o campo `option_group_id`. ## OpenAPI ````yaml /reference/api-catalogo.json post /api/partner/v1/catalog/items openapi: 3.1.0 info: title: API Catálogo version: '1.0' description: >- A API de catálogo é responsável por fornecer e gerenciar o catálogo completo do estabelecimento incluindo categorias, itens, grupos de complementos e opções. ## Autenticação Todas as requisições devem incluir obrigatoriamente os seguintes headers: - `X-API-KEY`: token do estabelecimento - `X-PARTNER-KEY`: token da integradora A ausência de qualquer um desses headers resultará na rejeição da requisição. ## Rate Limits Para o endpoint `GET /api/partner/v1/catalog`, o limite é de **5 requisições por minuto**. Para os demais endpoints do módulo de Catálogo, o limite é de **100 requisições por minuto**. contact: email: integracao@cardapioweb.com url: https://cardapioweb.com name: Cardápio Web servers: - url: https://integracao.sandbox.cardapioweb.com description: Sandbox - description: Produção url: https://integracao.cardapioweb.com security: - partnerKey: [] apiKey: [] tags: - name: Catálogo Completo description: Consulta do catálogo completo do estabelecimento. - name: Categorias description: Gerenciamento de categorias do cardápio. - name: Itens description: Gerenciamento de itens (produtos) do cardápio. - name: Grupos de Complementos description: Gerenciamento de grupos de complementos (option groups) do cardápio. - name: Opções description: Gerenciamento de opções (subitens/complementos individuais) do cardápio. - name: Imagens description: Upload e remoção de imagens de categorias, itens e opções. paths: /api/partner/v1/catalog/items: post: tags: - Itens summary: Criar item description: >- Cria um novo item no cardápio. O nome deve ser único no estabelecimento. Para associar grupos de complementos, é necessário que eles tenham sido criados previamente. Em seguida, o ID de cada grupo deve ser enviado no array `option_groups`, utilizando o campo `option_group_id`. operationId: createItem requestBody: $ref: '#/components/requestBodies/CreateItem' responses: '201': description: Item criado com sucesso. content: application/json: schema: $ref: '#/components/schemas/Item' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' components: requestBodies: CreateItem: required: true content: application/json: schema: type: object required: - name - category_id - price properties: name: type: string description: Nome do item. Deve ser único no estabelecimento. minLength: 1 maxLength: 500 description: type: - string - 'null' description: >- Descrição do item. Suporta formatação: negrito (\*texto\*), itálico (\_texto\_) ou riscado (\~texto\~). maxLength: 5000 category_id: type: integer description: ID da categoria à qual o item pertence. highlighted: type: boolean description: Define se o item aparece em destaque. external_code: type: - string - 'null' description: Código externo do item. maxLength: 50 price: type: number description: Preço base do item. Deve ter no máximo 2 casas decimais. minimum: 0 cost_price: type: number description: Preço de custo do item. Deve ter no máximo 2 casas decimais. minimum: 0 status: type: string enum: - ACTIVE - INACTIVE - MISSING description: |- Status do item. - `ACTIVE`: item ativo e visível. - `INACTIVE`: item oculto. - `MISSING`: item em falta. default: ACTIVE index: type: - integer - 'null' description: Índice de exibição do item dentro da categoria. minimum: 0 unit_type: type: string enum: - UN - KG - L default: UN description: |- Unidade de medida do item. - `UN`: unidade (padrão). - `KG`: quilograma. - `L`: litro. badge: type: - string - 'null' enum: - best_seller - new_item - recommended - limited_edition description: |- Badge de destaque do item. - `best_seller`: mais vendido. - `new_item`: novidade. - `recommended`: recomendado. - `limited_edition`: edição limitada. hide_observation_field: type: boolean description: Define se o campo de observações deve ser escondido. adults_only: type: boolean description: Define se o item é apenas para maiores de 18 anos. promotional_price: type: - number - 'null' description: >- Preço promocional. Obrigatório quando `promotional_price_active` é `true`. Deve ser menor que `price` e ter no máximo 2 casas decimais. minimum: 0 promotional_price_active: type: boolean description: Ativa ou desativa o preço promocional. promotional_price_schedules: type: - array - 'null' description: >- Define os dias e horários em que o preço promocional é aplicado. items: $ref: '#/components/schemas/PromotionalPriceSchedule' option_groups: type: array description: Grupos de complementos a associar ao item. items: type: object maxProperties: 20 required: - option_group_id properties: option_group_id: type: integer description: ID do grupo de complementos a associar. index: type: - integer - 'null' description: >- Índice de exibição do grupo de complemento dentro do item. minimum: 0 example: name: Margherita description: A clássica pizza italiana category_id: 658 price: 30 cost_price: 12.5 status: ACTIVE unit_type: UN highlighted: false adults_only: false hide_observation_field: false promotional_price_active: false option_groups: - option_group_id: 1039 index: 1 - option_group_id: 1040 index: 2 schemas: Item: type: object title: Item description: Produto do cardápio que pode ser item regular ou combo. properties: id: type: integer description: Identificador único do item. name: type: string description: Nome do item. description: type: - string - 'null' description: >- Descrição do item. Suporta formatação: negrito (\*texto\*), itálico (\_texto\_) ou riscado (\~texto\~). image: $ref: '#/components/schemas/Image' description: Imagem principal do item. highlighted: type: boolean description: Indica se o item deve aparecer em destaque no site. external_code: type: - string - 'null' description: Código externo do item. price: type: number description: >- Preço base do item. Deve ser um número positivo com no máximo 2 casas decimais. minimum: 0 cost_price: type: number description: >- Preço de custo do item. Deve ser um número positivo com no máximo 2 casas decimais. minimum: 0 stock: type: number description: Quantidade disponível em estoque. minimum: 0 active_stock_control: type: boolean description: Indica se o controle de estoque está ativo. index: type: - integer - 'null' description: Índice de exibição do item dentro da categoria. available_for: type: array description: |- Locais onde o item está disponível. - `delivery`: cardápio digital de delivery e retirada. - `internal_table`: pedido de mesa pelo portal. - `table`: pedido de mesa pelo cardápio digital. - `service_desk`: cardápio digital de balcão e portal. - `view_only`: cardápio digital de visualização. items: type: string enum: - delivery - table - service_desk - view_only - internal_table hide_observation_field: type: boolean description: Indica se o campo de observações deve ser escondido. adults_only: type: boolean description: Indica se o item é apenas para maiores de 18 anos. promotional_price_active: type: boolean description: Indica se o preço promocional está ativo. promotional_price: type: - number - 'null' description: >- Preço promocional do item. Deve ser menor que `price` quando ativo. É obrigatório se `promotional_price_active` for `true`. minimum: 0 promotional_price_schedules: type: - array - 'null' description: >- Horários em que o preço promocional é aplicado. Se `promotional_price_active` for `true`, define os dias e horários da promoção. items: $ref: '#/components/schemas/PromotionalPriceSchedule' status: type: string enum: - ACTIVE - INACTIVE - MISSING description: |- Status do item. - `ACTIVE`: item ativo e visível. - `INACTIVE`: item oculto. - `MISSING`: item em falta. unit_type: type: string enum: - UN - KG - L default: UN description: |- Unidade de medida do item. - `UN`: unidade (padrão). - `KG`: quilograma. - `L`: litro. badge: type: - string - 'null' enum: - best_seller - new_item - recommended - limited_edition description: |- Badge de destaque do item. - `best_seller`: mais vendido. - `new_item`: novidade. - `recommended`: recomendado. - `limited_edition`: edição limitada. kind: type: string enum: - regular_item - combo description: |- Tipo do item. - `regular_item`: item normal. - `combo`: combo. allowed_times: type: array description: >- Horários de disponibilidade do item. Array vazio significa sempre disponível. items: $ref: '#/components/schemas/AllowedTimes' extra_images: type: array description: Imagens extras do item. items: $ref: '#/components/schemas/Image' option_groups: type: array description: >- Grupos de complementos associados ao item. Disponível quando `kind` é `regular_item`. items: $ref: '#/components/schemas/OptionGroupInItem' combo_steps: type: array description: Etapas do combo. Disponível quando `kind` é `combo`. items: $ref: '#/components/schemas/ComboStep' PromotionalPriceSchedule: title: PromotionalPriceSchedule type: object description: >- Dia da semana e intervalo de horário para aplicação de preço promocional. required: - day properties: day: type: string enum: - sunday - monday - tuesday - wednesday - thursday - friday - saturday description: Dia da semana. start: type: - string - 'null' description: >- Horário de início `(HH:MM)` da promoção no fuso horário do estabelecimento. Se omitido juntamente com `end`, a promoção será válida durante todo o dia. É obrigatório caso `end` seja informado. example: '18:00' end: type: - string - 'null' description: >- Horário de fim `(HH:MM)` da promoção no fuso horário do estabelecimento. Se omitido juntamente com `start`, a promoção será válida durante todo o dia. É obrigatório caso `start` seja informado. Deve ser maior que o `start`. example: '23:00' Image: title: Image type: - object - 'null' description: Imagem associada a um recurso (categoria, item ou opção). properties: image_url: type: string format: uri description: URL da imagem versão padrão. thumbnail_url: type: string format: uri description: URL da imagem versão reduzida (thumbnail). AllowedTimes: title: AllowedTimes type: object description: Intervalo de horário de disponibilidade para um dia da semana. properties: weekday: type: string enum: - sunday - monday - tuesday - wednesday - thursday - friday - saturday description: Dia da semana. start_at: type: string example: '18:00' description: Horário de início `(HH:MM)` no fuso horário do estabelecimento. end_at: type: string example: '23:00' description: Horário de fim `(HH:MM)` no fuso horário do estabelecimento. OptionGroupInItem: type: object title: Grupo de complementos (no item) description: Grupo de complementos associado a um item. properties: id: type: integer description: Identificador único do grupo de complementos. name: type: string description: Nome do grupo de complementos. status: type: string enum: - ACTIVE - INACTIVE - MISSING description: |- Status do grupo de complementos. - `ACTIVE`: grupo ativo e visível. - `INACTIVE`: grupo oculto. - `MISSING`: grupo em falta. choice_type: type: string enum: - SINGLE - MULTIPLE - SUMMABLE description: >- Regra de escolha das opções no grupo. - `SINGLE`: apenas uma opção pode ser escolhida. - `MULTIPLE`: mais de uma opção pode ser escolhida, sem repetição. - `SUMMABLE`: mais de uma opção pode ser escolhida, com repetição permitida. price_calculation_type: type: string enum: - SUM - MEAN - MAX - MIN description: |- Regra de cálculo do preço quando múltiplas opções são selecionadas. - `SUM`: soma dos preços das opções selecionadas. - `MEAN`: média dos preços das opções selecionadas. - `MAX`: preço da opção mais cara entre as selecionadas. - `MIN`: preço da opção mais barata entre as selecionadas. minimum_quantity: type: integer description: Quantidade mínima de opções. minimum: 0 maximum_quantity: type: integer description: Quantidade máxima de opções. minimum: 1 index: type: - integer - 'null' description: Índice de exibição do grupo dentro do item. options: type: array description: Lista das opções do grupo. items: $ref: '#/components/schemas/OptionInGroup' ComboStep: title: ComboStep type: object description: Etapa de seleção de um combo. properties: id: type: integer description: Identificador único da etapa. name: type: string description: Nome da etapa. price: type: number description: Preço base da etapa, independente do item escolhido. minimum: 0 remove_add_on_prices: type: boolean description: >- Se `true`, preços de complementos escolhidos são ignorados no cálculo. index: type: - integer - 'null' description: Índice de exibição da etapa dentro do combo. combo_step_items: type: array description: Itens disponíveis nesta etapa. items: $ref: '#/components/schemas/ComboStepItem' Error: title: Error type: object description: Resposta de erro padrão da API. properties: code: type: integer description: Código interno de identificação do erro. message: type: string description: Mensagem de resumo do erro. details: type: string description: Detalhes adicionais do erro (quando disponível). errors: type: object description: Erros de validação por campo (quando disponível). additionalProperties: type: array items: type: string required: - code - message Unauthorized: type: object title: Unauthorized description: >- Resposta de erro de autenticação. Retornado quando os headers `X-API-KEY` ou `X-PARTNER-KEY` estão ausentes ou são inválidos. examples: - code: 4010 message: Token inválido. properties: code: type: integer description: Código interno de identificação do erro. message: type: string description: Mensagem de resumo do erro. required: - code - message OptionInGroup: type: object title: Opção (no grupo de complemento) description: Opção dentro de um grupo de complementos. properties: id: type: integer description: Identificador único da opção (subitem). name: type: string description: Nome da opção. description: type: - 'null' - string description: Descrição da opção. external_code: type: - 'null' - string description: Código externo da opção. status: type: string enum: - ACTIVE - INACTIVE - MISSING description: |- Status da opção. - `ACTIVE`: opção ativa e visível. - `INACTIVE`: opção oculta. - `MISSING`: opção em falta. image: $ref: '#/components/schemas/Image' description: Imagem da opção. cost_price: type: number description: Preço de custo da opção. minimum: 0 active_stock_control: type: boolean description: Indica se o controle de estoque está ativo. stock: type: - number - 'null' description: Quantidade disponível em estoque. index: type: - integer - 'null' description: Índice de exibição da opção dentro do grupo. max_quantity: type: - integer - 'null' description: >- Quantidade máxima desta opção que pode ser selecionada dentro do grupo de complementos. Relevante quando `choice_type` do grupo é `SUMMABLE`. price: type: number description: >- Preço da opção dentro deste grupo. Deve ser um número positivo com no máximo 2 casas decimais. Uma mesma opção pode ter preços diferentes em grupos diferentes. minimum: 0 badge: x-stoplight: id: l0rqsi0rwrrzs description: |- Badge de destaque da opção dentro do grupo. - `best_seller`: mais vendido. - `new_item`: novidade. - `recommended`: recomendado. - `limited_edition`: edição limitada. enum: - best_seller - new_item - recommended - limited_edition ComboStepItem: title: ComboStepItem type: object description: Item disponível para seleção em uma etapa de combo. properties: item_id: type: integer description: ID do item disponível nesta etapa. index: type: - integer - 'null' description: Índice de exibição do item dentro da etapa. additional_price: type: number description: >- Preço adicional cobrado pela escolha deste item, somado ao preço base da etapa. minimum: 0 responses: ValidationError: description: Erro de validação. Os dados enviados não passaram nas validações. content: application/json: schema: $ref: '#/components/schemas/Error' examples: validation_error: summary: Erro de validação com detalhes por campo value: code: 4001 message: Requisição inválida. errors: name: - não pode ficar em branco - 'é muito curto (mínimo: 1 caractere)' price: - não é um número Unauthorized: description: >- Não autorizado. O token no header `X-API-KEY` não foi enviado ou é inválido. content: application/json: schema: $ref: '#/components/schemas/Unauthorized' example: code: 4010 message: Token inválido. TooManyRequests: description: >- Muitas requisições foram feitas em um curto período. Verifique as regras de rate limit na descrição da API. content: {} securitySchemes: partnerKey: name: X-PARTNER-KEY type: apiKey in: header description: >- Token de autenticação da integradora. Para ter esse token, a integradora precisa estar previamente cadastrada em nosso sistema. Deve ser enviado no header `X-PARTNER-KEY`. apiKey: name: X-API-KEY type: apiKey in: header description: Token de autenticação da API. Deve ser enviado no header `X-API-KEY`. ````