Gerenciar complementos

Complementos seguem o fluxo de gerenciamento de produtos: consulte o estado atual, envie apenas as alterações e use updated_at para proteger uma edição revisada. A listagem existente continua retornando categorias, complementos, pivôs e pdv_codes no formato legado.

Rotas e autenticação

Use um access token OAuth com o escopo da operação. products:write não concede escrita em complementos; chaves e instalações existentes não recebem a nova permissão automaticamente. Para consultar antes de editar, solicite ambos os escopos de complementos.

Uma sessão assinada de restaurante também é aceita e usa exclusivamente o restaurante autorizado. Tokens de garçom não são aceitos. Integrações com vários restaurantes devem enviar ?restaurant_id= em todas as operações; um restaurante fora da autorização recebe 403. Uma sessão de restaurante rejeita esse parâmetro quando ele diverge do restaurante assinado.

Campos editáveis

Preços aceitam até 9999999999999.99. Campos omitidos permanecem intactos. null só limpa os campos que explicitamente o aceitam. Campos desconhecidos e objetos fiscais nulos são rejeitados. Um objeto vazio, inclusive apenas fiscal_info: {}, não constitui uma atualização.

Complementos podem pertencer a vários grupos. Estas rotas editam o complemento compartilhado: a alteração afeta suas aparições nos grupos que o utilizam. Não alteram categorias, pivôs, ordenação, marca, imagens, integrações, estoque ou vínculos fiscais internos. A criação e a gestão de categorias usam os métodos descritos ao final deste guia. Exclusão não é exposta. O preço de iFood e a disponibilidade de autosserviço não são editados por estes campos.

Consultar e editar

GET /v1/complements/42?restaurant_id=85
Authorization: Bearer <access_token>

A resposta é um objeto com id, restaurant_id, name, description, price, delivery_price, available, available_in_delivery, limit, show_on_report, fiscal, fiscal_info, created_at e updated_at. Preços saem como strings com duas casas decimais; delivery_price pode ser null. fiscal e fiscal_info contêm os mesmos atributos públicos. Custos, credenciais e fiscal_group_id não são expostos.

PUT /v1/complements/42?restaurant_id=85
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "price": 0,
  "delivery_price": null,
  "fiscal_info": { "ncm": "04061010", "cest": null },
  "expected_updated_at": "2026-09-09T12:00:00.000Z"
}

Substitua a data pelo updated_at consultado. A resposta 200 é o snapshot atualizado. Uma versão desatualizada ou disputa concorrente retorna 409 complement_update_conflict. Consulte novamente, revise os valores e só então reenvie; não repita cegamente a edição com uma nova versão.

Edição em lote e disponibilidade

PUT /v1/complements/bulk?restaurant_id=85
Authorization: Bearer <access_token>
Content-Type: application/json

[
  { "id": 42, "price": 0 },
  { "id": 43, "available_in_delivery": false }
]

O corpo é um array com 1–100 IDs distintos, inteiros positivos até 2147483647. Cada item aceita os campos da edição individual e sua própria expected_updated_at. Toda a operação ocorre numa transação serializável: qualquer falha desfaz o lote inteiro. A resposta contém os snapshots na ordem da requisição, sem sucesso parcial.

Para alterar apenas disponibilidade, envie available e/ou available_in_delivery no PATCH. Ele também aceita expected_updated_at; ao menos um canal é obrigatório. As outras regras de elegibilidade do menu, como agenda e disponibilidade dos grupos, continuam valendo.

Erros e compatibilidade

Os erros seguem { statusCode, message, key }:

GET /v1/complements, as rotas de produtos e o formato agrupado de GET /v1/menu mantêm seus contratos. A atualização não invalida caches de outras aplicações; superfícies com cache próprio podem refletir o cadastro após sua expiração.

Criar complementos e gerenciar categorias

Todas as rotas aceitam restaurant_id pela mesma regra de autorização das demais consultas. Liste as marcas para selecionar brand_id.

Crie um complemento com name, brand_id e price. Campos opcionais: description, delivery_price (null herda o salão), available, available_in_delivery, limit, show_on_report e category_ids (até 100 IDs distintos). Preço zero é válido. O retorno 201 contém o mesmo snapshot da consulta individual. Campos fiscais podem ser ajustados pelo método de edição existente.

Crie uma categoria com name e brand_id. Configure question, available, available_in_delivery, limit, minimum, optional, single_choice e uma regra de preço: additional, more_expensive_only ou use_average. Mínimo não pode exceder o limite; escolha única exige limite 1. Somente uma regra de preço pode estar ativa.

complement_ids contém até 100 IDs distintos da mesma marca e restaurante. Um complemento pode pertencer a várias categorias. Na atualização, enviar esse array substitui somente os vínculos da categoria editada; [] remove seus vínculos e omitir mantém os atuais. Isso nunca exclui o complemento nem remove vínculos de outras categorias. A listagem inclui categorias vazias e retorna seus IDs de complementos.

A edição é parcial e aceita expected_updated_at do snapshot. A marca de uma categoria existente é imutável para preservar os vínculos com produtos. Versões divergentes e conflitos de transação retornam 409. Referências inválidas, excluídas ou de outro restaurante/marca retornam 400 sem revelar o proprietário. Criações retornam 201; consulta e edição retornam 200. Exclusão não é exposta.