# BeeFood API — documentação completa ## Atualizar complementos em lote --- title: "Atualizar complementos em lote" description: "PATCH /v1/catalog/complements — atualizar complementos e cardápios em lote na API BeeFood." method: "PATCH" path: "/v1/catalog/complements" url: "https://developer.beefood.com.br/docs/catalogo/atualizar-complementos-lote" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Atualizar complementos em lote `PATCH /v1/catalog/complements` - Produção: `https://api.beefood.app/v1/catalog/complements` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/complements` Atualiza vários complementos em uma requisição. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `[]` *array* **obrigatório** — Lote com pelo menos 1 item. - `[].complementId` *integer* **obrigatório** — Identificador do complemento. Exemplo: `2587090`. - `[].type` *string* **obrigatório** — Tipo de atualização. Exemplo: `complement`. - *Valores:* `complement`, `menu` - `[].complement` *object* — Obrigatório quando type é complement; campos da atualização parcial do complemento. - `[].complement.name` *string* — Nome do complemento. - `[].complement.description` *string* — Descrição do complemento. - `[].complement.label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `[].complement.price` *number* — Preço de venda. - `[].complement.code` *string* — Código interno. - `[].complement.barcode` *string* — Código de barras. - `[].complement.unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `[].complement.featuredPrint` *boolean* — Indica se tem destaque na impressão. - `[].complement.cost` *object* — Custos do complemento. - `[].complement.cost.base` *number* — Custo base. - `[].menu` *object* — Obrigatório quando type é menu; um único cardápio. - `[].menu.merchantId` *number* **obrigatório** — Identificador do cardápio. - `[].menu.active` *boolean* — Indica se está ativo neste cardápio. - `[].menu.delivery` *boolean* — Indica se aparece no delivery. - `[].menu.deliveryPrice` *number* — Preço no delivery. - `[].menu.dineIn` *boolean* — Indica se aparece no presencial. - `[].menu.dineInPrice` *number* — Preço no presencial. - `[].menu.totem` *boolean* — Indica se aparece no totem. - `[].menu.promotionPrice` *number* — Preço promocional. - `[].menu.sortOrder` *number* — Posição de exibição. - `[].menu.featuredOrder` *number* — Posição entre destaques. - `[].menu.cashbackEnabled` *boolean* — Indica se o cashback está ativo neste cardápio. ## Exemplos de requisição ### cURL ```bash curl -X PATCH "https://api.beefood.app/v1/catalog/complements" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '[ { "complementId": 2587090, "type": "complement", "complement": { "price": 2.5 } }, { "complementId": 2587090, "type": "menu", "menu": { "merchantId": 122, "active": false } } ]' ``` ## Exemplos de resposta ### 200 OK ```json [ { "complementId": 2587090, "type": "complement", "success": true }, { "complementId": 2587090, "type": "menu", "success": false, "message": "Complement ID 2587090 is not linked to merchant ID(s) 122" } ] ``` ## Campos da resposta - `[].complementId` *integer* — Identificador do complemento. - `[].type` *string* — Tipo de atualização. Exemplo: `complement`. - *Valores:* `complement`, `menu` - `[].success` *boolean* — Indica se este item foi atualizado. - `[].message` *string* — Mensagem retornada somente quando success é false. ## Atualização em lote Cada item informa o complemento, o tipo e o objeto correspondente. As regras da atualização unitária continuam valendo. ### Regras - Envie um array não vazio; outro formato ou array vazio retorna `400`. - `complement`: envie `complement` com os campos a alterar; os omitidos preservam o valor atual. - `menu`: envie `menu` com `merchantId` e os campos a alterar; o cardápio precisa estar vinculado ao complemento. - Item com `complementId`, `type` ou payload inválido volta com `success: false`. - Falhas de negócio (complemento inexistente, vínculo) voltam no item com a mesma mensagem da rota unitária; falha inesperada retorna `Failed to update complement`. - Os itens são independentes: a falha de um não desfaz os demais. - O retorno mantém a ordem do body; confira `success` em cada item, mesmo com HTTP `200`. `message` aparece apenas nas falhas. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Body must be a non-empty array of complement updates | ## Vocabulários usados neste endpoint ## Atualização em lote de complementos · type | Valor | Significado | Uso | | --- | --- | --- | | `complement` | Dados do complemento | Objeto complement | | `menu` | Cardápio do complemento | Objeto menu | ## Catálogo · unit Valores aceitos no campo unit dos produtos do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `UN` | Unidade | /v1/catalog/products | | `KG` | Quilograma | /v1/catalog/products | | `G` | Grama | /v1/catalog/products | | `L` | Litro | /v1/catalog/products | | `ML` | Mililitro | /v1/catalog/products | | `PCT` | Pacote | /v1/catalog/products | | `CX` | Caixa | /v1/catalog/products | | `DZ` | Dúzia | /v1/catalog/products | | `FD` | Fardo | /v1/catalog/products | | `BD` | Balde | /v1/catalog/products | | `SC` | Saco | /v1/catalog/products | | `PT` | Pote | /v1/catalog/products | | `CP` | Copo | /v1/catalog/products | | `PC` | Peça | /v1/catalog/products | | `FT` | Fátia | /v1/catalog/products | | `PQ` | Porção | /v1/catalog/products | | `GF` | Garrafa | /v1/catalog/products | | `LT` | Lata | /v1/catalog/products | | `BN` | Bandeja | /v1/catalog/products | ## Atualizar grupo --- title: "Atualizar grupo" description: "PATCH /v1/catalog/groups/{groupId} — atualizar parcialmente um grupo de opções BeeFood." method: "PATCH" path: "/v1/catalog/groups/{groupId}" url: "https://developer.beefood.com.br/docs/catalogo/atualizar-grupo" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Atualizar grupo `PATCH /v1/catalog/groups/{groupId}` - Produção: `https://api.beefood.app/v1/catalog/groups/{groupId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups/{groupId}` Atualiza parcialmente um grupo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `groupId` *integer* **obrigatório** — Identificador do grupo. Exemplo: `264006`. ## Parâmetros do body - `name` *string* — Nome do grupo, até 100 caracteres. - `active` *boolean* — Indica se o grupo está ativo. - `delivery` *boolean* — Indica se o grupo aparece no delivery. - `dineIn` *boolean* — Indica se o grupo aparece no presencial. - `required` *boolean* — Indica se a escolha é obrigatória. - `pizza` *boolean* — Indica se o grupo é de pizza. - `sortOrder` *integer* — Posição de exibição, inteiro maior ou igual a 0. - `priceFormation` *string* — Formação de preço: sum, gift, highest ou proportional. - `minQuantity` *integer* — Quantidade mínima de opções, inteiro maior ou igual a 0. - `maxQuantity` *integer* — Quantidade máxima de opções, inteiro maior ou igual a 1. ## Exemplos de requisição ### cURL ```bash curl -X PATCH "https://api.beefood.app/v1/catalog/groups/{groupId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Escolha até 3 condimentos:", "maxQuantity": 3, "priceFormation": "sum" }' ``` ## Exemplos de resposta ### 200 OK ```json { "groupId": 264006, "name": "Acompanhamentos", "active": true, "delivery": true, "dineIn": true, "required": true, "pizza": false, "sortOrder": 0, "priceFormation": "gift", "minQuantity": 1, "maxQuantity": 1, "products": [ { "productId": 2585290, "name": "Combo Supreme", "image": { "original": "https://cdn.beefood.com.br/products/2585290.jpg", "thumbnail60": "https://cdn.beefood.com.br/products/2585290_60.jpg", "thumbnail120": "https://cdn.beefood.com.br/products/2585290_120.jpg", "thumbnailWeb": "https://cdn.beefood.com.br/products/2585290_web.jpg" } } ] } ``` ## Campos da resposta - `groupId` *number* — Identificador do grupo. - `name` *string* — Nome do grupo. - `active` *boolean* — Indica se o grupo está ativo. - `delivery` *boolean* — Indica se o grupo aparece no delivery. - `dineIn` *boolean* — Indica se o grupo aparece no presencial. - `required` *boolean* — Indica se a escolha é obrigatória. - `pizza` *boolean* — Indica se o grupo é de pizza. - `sortOrder` *number* — Posição de exibição. - `priceFormation` *string* — Formação de preço: sum, gift, highest ou proportional. - `minQuantity` *number* — Quantidade mínima de opções. - `maxQuantity` *number* — Quantidade máxima de opções. - `products` *array* — Produtos vinculados ao grupo. - `products[].productId` *number* — Identificador do produto. - `products[].name` *string* — Nome do produto. - `products[].image` *object* — URLs da imagem do produto. - `products[].image.original` *string* — Imagem original. - `products[].image.thumbnail60` *string* — Miniatura de 60 px. - `products[].image.thumbnail120` *string* — Miniatura de 120 px. - `products[].image.thumbnailWeb` *string* — Miniatura para web. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | At least one field is required | | 400 | Invalid group data | | 404 | Group not found | ## Atualizar produtos em lote --- title: "Atualizar produtos em lote" description: "PATCH /v1/catalog/products — atualizar produtos, cardápios, restrições e grupos em lote na API BeeFood." method: "PATCH" path: "/v1/catalog/products" url: "https://developer.beefood.com.br/docs/catalogo/atualizar-produtos-lote" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Atualizar produtos em lote `PATCH /v1/catalog/products` - Produção: `https://api.beefood.app/v1/catalog/products` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/products` Atualiza vários produtos em uma requisição. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `[]` *array* **obrigatório** — Lote com pelo menos 1 item. - `[].productId` *integer* **obrigatório** — Identificador do produto, inteiro maior ou igual a 1. Exemplo: `131822`. - `[].type` *string* **obrigatório** — Tipo de atualização. Exemplo: `product`. - *Valores:* `product`, `menu`, `restrictions`, `groups` - `[].product` *object* — Obrigatório quando type é product; campos da atualização parcial do produto. - `[].product.barcode` *string* — Código de barras. - `[].product.code` *string* — Código interno. - `[].product.name` *string* — Nome do produto. - `[].product.description` *string* — Descrição do produto. - `[].product.internalNotes` *string* — Observações internas. - `[].product.label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `[].product.unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `[].product.price` *number* — Preço padrão. - `[].product.featured` *boolean* — Indica se está em destaque. - `[].product.featuredPrint` *boolean* — Indica se tem destaque na impressão. - `[].product.serviceFeeActive` *boolean* — Indica se a taxa de serviço está ativa. - `[].product.scheduleOnly` *boolean* — Indica se a venda é apenas por agendamento. - `[].product.scaleActive` *boolean* — Indica se a balança está ativa. - `[].product.scaleShelfLifeDays` *number* — Validade em dias na balança. - `[].product.sectorId` *number* — Identificador de um setor da mesma empresa. - `[].product.cost` *object* — Custos do produto. - `[].product.cost.base` *number* — Custo base. - `[].menu` *object* — Obrigatório quando type é menu; um único cardápio. - `[].menu.merchantId` *number* **obrigatório** — Cardápio da mesma empresa. - `[].menu.active` *boolean* — Indica se está ativo nesto cardápio. - `[].menu.delivery` *boolean* — Indica se aparece no delivery. - `[].menu.deliveryPrice` *number* — Preço no delivery. - `[].menu.dineIn` *boolean* — Indica se aparece no presencial. - `[].menu.dineInPrice` *number* — Preço no presencial. - `[].menu.totem` *boolean* — Indica se aparece no totem. - `[].menu.promotionPrice` *number* — Preço promocional. - `[].menu.sortOrder` *number* — Posição de exibição. - `[].menu.featuredOrder` *number* — Posição entre destaques. - `[].menu.cashbackEnabled` *boolean* — Indica se o cashback está ativo nesto cardápio. - `[].menu.upsell` *array* — Produtos sugeridos nesto cardápio. - `[].menu.upsell[].productId` *number* — Produto sugerido no upsell. - `[].restrictions` *object | null* — Obrigatório quando type é restrictions; null limpa as restrições. - `[].restrictions.vegetarian` *boolean* — Indica se é vegetariano. - `[].restrictions.vegan` *boolean* — Indica se é vegano. - `[].restrictions.organic` *boolean* — Indica se é orgânico. - `[].restrictions.glutenFree` *boolean* — Indica se não contém glúten. - `[].restrictions.sugarFree` *boolean* — Indica se não contém açúcar. - `[].restrictions.lactoseFree` *boolean* — Indica se não contém lactose. - `[].restrictions.natural` *boolean* — Indica se é natural. - `[].restrictions.iced` *boolean* — Indica se é gelado. - `[].restrictions.serves` *number* — Número de pessoas servidas. - `[].groups` *array* — Obrigatório quando type é groups; grupos cuja ordem será alterada. - `[].groups[].groupId` *integer* **obrigatório** — Grupo vinculado ao produto, inteiro maior ou igual a 1; sem repetição no array. Exemplo: `266128`. - `[].groups[].sortOrder` *integer* **obrigatório** — Posição do grupo, inteiro maior ou igual a 0. Exemplo: `1`. ## Exemplos de requisição ### cURL ```bash curl -X PATCH "https://api.beefood.app/v1/catalog/products" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '[ { "productId": 131822, "type": "product", "product": { "price": 22.5, "featured": true } }, { "productId": 131822, "type": "menu", "menu": { "merchantId": 122, "deliveryPrice": 22.5 } }, { "productId": 131822, "type": "restrictions", "restrictions": { "vegetarian": false, "serves": 1 } }, { "productId": 131822, "type": "groups", "groups": [ { "groupId": 266128, "sortOrder": 1 } ] } ]' ``` ## Exemplos de resposta ### 200 OK ```json [ { "productId": 131822, "type": "product", "success": true }, { "productId": 131822, "type": "menu", "success": true }, { "productId": 131822, "type": "restrictions", "success": true }, { "productId": 131822, "type": "groups", "success": true } ] ``` ## Campos da resposta - `[].productId` *integer* — Identificador do produto. - `[].type` *string* — Tipo de atualização. Exemplo: `product`. - *Valores:* `product`, `menu`, `restrictions`, `groups` - `[].success` *boolean* — Indica se este item foi atualizado. - `[].message` *string* — Mensagem retornada somente quando success é false. ## Atualização em lote Cada item informa o produto, o tipo e o objeto correspondente. As regras da atualização unitária continuam valendo. ### Regras - Envie um array não vazio; outro formato ou array vazio retorna `400`. - `product`: envie `product` com os campos a alterar; os omitidos preservam o valor atual. - `menu`: envie `menu` com `merchantId` e os campos a alterar; o cardápio precisa estar vinculado ao produto. - `restrictions`: envie `restrictions` como objeto ou `null` para limpar. - `groups`: envie `groups` como array não vazio de `{ groupId, sortOrder }`; só os grupos enviados mudam. - Booleanos com `null` são ignorados em `product`, `menu` e `restrictions`. Em `menu`, `null` limpa preços, `sortOrder`, `featuredOrder` e `upsell`; `upsell: []` também limpa. - Os itens são independentes: a falha de um não desfaz os demais. - O retorno mantém a ordem do body; confira `success` em cada item, mesmo com HTTP `200`. `message` aparece apenas nas falhas. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Body deve ser um array não vazio (descrição; mensagem literal não fornecida no contrato). | ## Vocabulários usados neste endpoint ## Atualização em lote · type | Valor | Significado | Uso | | --- | --- | --- | | `product` | Dados do produto | Objeto product | | `menu` | Cardápio do produto | Objeto menu | | `restrictions` | Restrições alimentares | Objeto restrictions ou null | | `groups` | Ordem dos grupos | Array groups | ## Catálogo · unit Valores aceitos no campo unit dos produtos do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `UN` | Unidade | /v1/catalog/products | | `KG` | Quilograma | /v1/catalog/products | | `G` | Grama | /v1/catalog/products | | `L` | Litro | /v1/catalog/products | | `ML` | Mililitro | /v1/catalog/products | | `PCT` | Pacote | /v1/catalog/products | | `CX` | Caixa | /v1/catalog/products | | `DZ` | Dúzia | /v1/catalog/products | | `FD` | Fardo | /v1/catalog/products | | `BD` | Balde | /v1/catalog/products | | `SC` | Saco | /v1/catalog/products | | `PT` | Pote | /v1/catalog/products | | `CP` | Copo | /v1/catalog/products | | `PC` | Peça | /v1/catalog/products | | `FT` | Fátia | /v1/catalog/products | | `PQ` | Porção | /v1/catalog/products | | `GF` | Garrafa | /v1/catalog/products | | `LT` | Lata | /v1/catalog/products | | `BN` | Bandeja | /v1/catalog/products | ## Atualizar setores em lote --- title: "Atualizar setores em lote" description: "PATCH /v1/catalog/sectors — reordenar, ativar e desativar setores em lote na API BeeFood." method: "PATCH" path: "/v1/catalog/sectors" url: "https://developer.beefood.com.br/docs/catalogo/atualizar-setores-lote" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Atualizar setores em lote `PATCH /v1/catalog/sectors` - Produção: `https://api.beefood.app/v1/catalog/sectors` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/sectors` Atualiza vários setores em uma requisição. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `[]` *array* **obrigatório** — Lote com pelo menos 1 item. - `[].sectorId` *integer* **obrigatório** — Identificador do setor. Exemplo: `221145`. - `[].type` *string* **obrigatório** — Tipo de atualização. Exemplo: `sector`. - *Valores:* `sector`, `menu` - `[].sector` *object* — Obrigatório quando type é sector; campos da atualização parcial do setor. - `[].sector.name` *string* — Nome do setor, até 150 caracteres. Exemplo: `Sobremesas`. - `[].sector.publicName` *string* — Nome exibido no cardápio digital, até 150 caracteres. Exemplo: `Doces`. - `[].sector.delivery` *boolean* — Indica se o setor aparece no delivery. - `[].sector.dineIn` *boolean* — Indica se o setor aparece no presencial. - `[].menu` *object* — Obrigatório quando type é menu; um único cardápio. - `[].menu.merchantId` *integer* **obrigatório** — Identificador do cardápio vinculado ao setor, inteiro maior ou igual a 1. Exemplo: `122`. - `[].menu.active` *boolean* — Indica se o setor fica ativo no cardápio. - `[].menu.sortOrder` *integer* — Posição do setor no cardápio, inteiro maior ou igual a 0 ou null. Exemplo: `2`. ## Exemplos de requisição ### cURL ```bash curl -X PATCH "https://api.beefood.app/v1/catalog/sectors" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '[ { "sectorId": 221145, "type": "menu", "menu": { "merchantId": 122, "sortOrder": 1 } }, { "sectorId": 221146, "type": "menu", "menu": { "merchantId": 122, "sortOrder": 2 } }, { "sectorId": 221146, "type": "sector", "sector": { "publicName": "Promoções" } } ]' ``` ## Exemplos de resposta ### 200 OK ```json [ { "sectorId": 221145, "type": "menu", "success": true }, { "sectorId": 221146, "type": "menu", "success": false, "message": "Sector ID 221146 is not linked to merchant ID(s) 122" }, { "sectorId": 221146, "type": "sector", "success": true } ] ``` ## Campos da resposta - `[].sectorId` *integer* — Identificador do setor. - `[].type` *string* — Tipo de atualização. Exemplo: `sector`. - *Valores:* `sector`, `menu` - `[].success` *boolean* — Indica se este item foi atualizado. - `[].message` *string* — Mensagem retornada somente quando success é false. ## Atualização em lote Cada item informa o setor, o tipo e o objeto correspondente. As regras da atualização unitária continuam valendo. ### Regras - Envie um array não vazio; outro formato ou array vazio retorna `400`. - `sector`: envie `sector` com os campos a alterar; os omitidos preservam o valor atual. - Para ordenar setores, use `menu` com `sortOrder`; a ordem é definida por cardápio. - `menu`: envie `menu` com `merchantId` e os campos a alterar; o cardápio precisa estar vinculado ao setor. - Item com `sectorId`, `type` ou payload inválido volta com `success: false`. - Falhas de negócio (setor inexistente, vínculo) voltam no item com a mesma mensagem da rota unitária; falha inesperada retorna `Failed to update sector`. - Os itens são independentes: a falha de um não desfaz os demais. - O retorno mantém a ordem do body; confira `success` em cada item, mesmo com HTTP `200`. `message` aparece apenas nas falhas. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Body must be a non-empty array of sector updates | ## Vocabulários usados neste endpoint ## Atualização em lote de setores · type | Valor | Significado | Uso | | --- | --- | --- | | `sector` | Dados do setor | Objeto sector | | `menu` | Cardápio do setor | Objeto menu | ## Detalhe do complemento --- title: "Detalhe do complemento" description: "GET /v1/catalog/complements/{complementId} — detalhe de um complemento no cardápio da BeeFood." method: "GET" path: "/v1/catalog/complements/{complementId}" url: "https://developer.beefood.com.br/docs/catalogo/complemento" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Detalhe do complemento `GET /v1/catalog/complements/{complementId}` - Produção: `https://api.beefood.app/v1/catalog/complements/{complementId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/complements/{complementId}` Retorna o detalhe de um complemento. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `complementId` *integer* **obrigatório** — Identificador do complemento. Exemplo: `2587090`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/complements/{complementId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "complementId": 2515324, "storeId": 38311, "name": "Onion rings", "description": "Porção c/ 08 onion (cebola empanada)", "price": 4, "unit": "UN", "active": true, "featuredPrint": false, "cost": { "base": 0, "supply": 0, "total": 0 }, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202608181109_832.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202608181109_832.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202608181109_832.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202608181109_832.webp" }, "menus": [ { "merchantId": 39202, "name": "Restaurante Exemplo", "active": true, "delivery": true, "dineIn": true, "totem": true, "cashbackEnabled": true }, { "merchantId": 50502, "name": "Restaurante Exemplo - Sushi", "active": true, "delivery": true, "dineIn": true, "totem": true, "cashbackEnabled": true } ], "groups": [ { "optionId": 5616517, "name": "Acompanhamentos" }, { "optionId": 5616578, "name": "Acompanhamentos" } ] } ``` ## Campos da resposta - `complementId` *number* — Identificador do complemento. - `storeId` *number* — Identificador da empresa. - `name` *string* — Nome do complemento. - `description` *string* — Descrição do complemento. - `label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `price` *number* — Preço de venda. - `code` *string* — Código interno. - `barcode` *string* — Código de barras. - `unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `active` *boolean* — Indica se está ativo em pelo menos um cardápio da empresa. Somente leitura. - `featuredPrint` *boolean* — Indica se tem destaque na impressão. - `cost` *object* — Custos do complemento. - `cost.base` *number* — Custo base. - `cost.supply` *number* — Custo da ficha técnica. Somente leitura. - `cost.total` *number* — Soma do custo base com o custo da ficha técnica. Somente leitura. - `image` *object* — URLs da imagem do complemento. Somente leitura. Para enviar ou remover, use Enviar imagem e Remover imagem com resourceType = complements. - `image.original` *string* — Imagem original. - `image.thumbnail60` *string* — Miniatura de 60 px. - `image.thumbnail120` *string* — Miniatura de 120 px. - `image.thumbnailWeb` *string* — Miniatura para web. - `menus` *array* — Configurações do complemento por cardápio. - `menus[].merchantId` *number* — Identificador do cardápio. - `menus[].name` *string* — Nome do cardápio. Somente leitura. - `menus[].active` *boolean* — Indica se está ativo neste cardápio. - `menus[].delivery` *boolean* — Indica se aparece no delivery. - `menus[].deliveryPrice` *number* — Preço no delivery. - `menus[].dineIn` *boolean* — Indica se aparece no presencial. - `menus[].dineInPrice` *number* — Preço no presencial. - `menus[].totem` *boolean* — Indica se aparece no totem. - `menus[].promotionPrice` *number* — Preço promocional. - `menus[].sortOrder` *number* — Posição de exibição. - `menus[].featuredOrder` *number* — Posição entre destaques. - `menus[].cashbackEnabled` *boolean* — Indica se o cashback está ativo neste cardápio. - `groups` *array* — Grupos de opções em que o complemento aparece. Somente leitura. - `groups[].optionId` *number* — Identificador da opção no grupo. - `groups[].name` *string* — Nome do grupo. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | | 404 | Complement not found | ## Vocabulários usados neste endpoint ## Catálogo · unit Valores aceitos no campo unit dos produtos do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `UN` | Unidade | /v1/catalog/products | | `KG` | Quilograma | /v1/catalog/products | | `G` | Grama | /v1/catalog/products | | `L` | Litro | /v1/catalog/products | | `ML` | Mililitro | /v1/catalog/products | | `PCT` | Pacote | /v1/catalog/products | | `CX` | Caixa | /v1/catalog/products | | `DZ` | Dúzia | /v1/catalog/products | | `FD` | Fardo | /v1/catalog/products | | `BD` | Balde | /v1/catalog/products | | `SC` | Saco | /v1/catalog/products | | `PT` | Pote | /v1/catalog/products | | `CP` | Copo | /v1/catalog/products | | `PC` | Peça | /v1/catalog/products | | `FT` | Fátia | /v1/catalog/products | | `PQ` | Porção | /v1/catalog/products | | `GF` | Garrafa | /v1/catalog/products | | `LT` | Lata | /v1/catalog/products | | `BN` | Bandeja | /v1/catalog/products | ## Listar complementos --- title: "Listar complementos" description: "GET /v1/catalog/complements — complementos da empresa BeeFood, com filtros e paginação." method: "GET" path: "/v1/catalog/complements" url: "https://developer.beefood.com.br/docs/catalogo/complementos" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Listar complementos `GET /v1/catalog/complements` - Produção: `https://api.beefood.app/v1/catalog/complements` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/complements` Lista os complementos da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de query - `page` *integer* — Página (padrão 1). Exemplo: `1`. - `limit` *integer* — Itens por página, de 1 a 100 (padrão 20). Exemplo: `20`. - `sort` *string* — Ordem por complementId: asc ou desc (padrão desc). Exemplo: `desc`. - *Valores:* `asc`, `desc` - `active` *boolean* — Filtra complementos ativos ou inativos em algum cardápio da empresa. Exemplo: `true`. - `name` *string* — Filtra pelo nome do complemento. Exemplo: `Molho`. - `code` *string[]* — Filtra pelo código interno. Exemplo: `MN1`. - `barcode` *string[]* — Filtra pelo código de barras. Exemplo: `7891000315507`. - `label` *string[]* — Filtra pelos selos: new, recommended, bestSeller, limitedEdition, soldOut. Exemplo: `new`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/complements?page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "complementId": 2589008, "storeId": 38311, "name": "Molho Lemon Fresh", "description": "Azeite, Limão Tahiti e Sal.", "price": 3, "unit": "UN", "active": true, "featuredPrint": false, "cost": { "base": 0, "supply": 0, "total": 0 }, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202411082010_1X5.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202411082010_1X5.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202411082010_1X5.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202411082010_1X5.webp" }, "menus": [ { "merchantId": 39202, "name": "Restaurante Exemplo", "active": true, "delivery": true, "dineIn": true, "totem": true, "cashbackEnabled": true }, { "merchantId": 50502, "name": "Restaurante Exemplo - Sushi", "active": true, "delivery": true, "dineIn": true, "totem": true, "cashbackEnabled": true } ], "groups": [ { "optionId": 5673284, "name": "Deseja algum molho?" } ] }, { "complementId": 2589007, "storeId": 38311, "name": "Molho Shoyu Spicy", "description": "Shoyu, Óleo de Gergelim e Tabasco.", "price": 3, "unit": "UN", "active": true, "featuredPrint": false, "cost": { "base": 0, "supply": 0, "total": 0 }, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202411082010_R05.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202411082010_R05.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202411082010_R05.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202411082010_R05.webp" }, "menus": [ { "merchantId": 39202, "name": "Restaurante Exemplo", "active": true, "delivery": true, "dineIn": true, "totem": true, "cashbackEnabled": true }, { "merchantId": 50502, "name": "Restaurante Exemplo - Sushi", "active": true, "delivery": true, "dineIn": true, "totem": true, "cashbackEnabled": true } ], "groups": [ { "optionId": 5673281, "name": "Deseja algum molho?" } ] } ], "page": 1, "limit": 2, "total": 152, "pages": 76 } ``` ## Campos da resposta - `items[].complementId` *number* — Identificador do complemento. - `items[].storeId` *number* — Identificador da empresa. - `items[].name` *string* — Nome do complemento. - `items[].description` *string* — Descrição do complemento. - `items[].label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `items[].price` *number* — Preço de venda. - `items[].code` *string* — Código interno. - `items[].barcode` *string* — Código de barras. - `items[].unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `items[].active` *boolean* — Indica se está ativo em pelo menos um cardápio da empresa. Somente leitura. - `items[].featuredPrint` *boolean* — Indica se tem destaque na impressão. - `items[].cost` *object* — Custos do complemento. - `items[].cost.base` *number* — Custo base. - `items[].cost.supply` *number* — Custo da ficha técnica. Somente leitura. - `items[].cost.total` *number* — Soma do custo base com o custo da ficha técnica. Somente leitura. - `items[].image` *object* — URLs da imagem do complemento. Somente leitura. Para enviar ou remover, use Enviar imagem e Remover imagem com resourceType = complements. - `items[].image.original` *string* — Imagem original. - `items[].image.thumbnail60` *string* — Miniatura de 60 px. - `items[].image.thumbnail120` *string* — Miniatura de 120 px. - `items[].image.thumbnailWeb` *string* — Miniatura para web. - `items[].menus` *array* — Configurações do complemento por cardápio. - `items[].menus[].merchantId` *number* — Identificador do cardápio. - `items[].menus[].name` *string* — Nome do cardápio. Somente leitura. - `items[].menus[].active` *boolean* — Indica se está ativo neste cardápio. - `items[].menus[].delivery` *boolean* — Indica se aparece no delivery. - `items[].menus[].deliveryPrice` *number* — Preço no delivery. - `items[].menus[].dineIn` *boolean* — Indica se aparece no presencial. - `items[].menus[].dineInPrice` *number* — Preço no presencial. - `items[].menus[].totem` *boolean* — Indica se aparece no totem. - `items[].menus[].promotionPrice` *number* — Preço promocional. - `items[].menus[].sortOrder` *number* — Posição de exibição. - `items[].menus[].featuredOrder` *number* — Posição entre destaques. - `items[].menus[].cashbackEnabled` *boolean* — Indica se o cashback está ativo neste cardápio. - `items[].groups` *array* — Grupos de opções em que o complemento aparece. Somente leitura. - `items[].groups[].optionId` *number* — Identificador da opção no grupo. - `items[].groups[].name` *string* — Nome do grupo. - `page` *number* — page da paginação. - `limit` *number* — limit da paginação. - `total` *number* — total da paginação. - `pages` *number* — pages da paginação. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | ## Vocabulários usados neste endpoint ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Catálogo · unit Valores aceitos no campo unit dos produtos do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `UN` | Unidade | /v1/catalog/products | | `KG` | Quilograma | /v1/catalog/products | | `G` | Grama | /v1/catalog/products | | `L` | Litro | /v1/catalog/products | | `ML` | Mililitro | /v1/catalog/products | | `PCT` | Pacote | /v1/catalog/products | | `CX` | Caixa | /v1/catalog/products | | `DZ` | Dúzia | /v1/catalog/products | | `FD` | Fardo | /v1/catalog/products | | `BD` | Balde | /v1/catalog/products | | `SC` | Saco | /v1/catalog/products | | `PT` | Pote | /v1/catalog/products | | `CP` | Copo | /v1/catalog/products | | `PC` | Peça | /v1/catalog/products | | `FT` | Fátia | /v1/catalog/products | | `PQ` | Porção | /v1/catalog/products | | `GF` | Garrafa | /v1/catalog/products | | `LT` | Lata | /v1/catalog/products | | `BN` | Bandeja | /v1/catalog/products | ## Criar complemento --- title: "Criar complemento" description: "POST /v1/catalog/complements — criar um complemento no cardápio BeeFood." method: "POST" path: "/v1/catalog/complements" url: "https://developer.beefood.com.br/docs/catalogo/criar-complemento" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Criar complemento `POST /v1/catalog/complements` - Produção: `https://api.beefood.app/v1/catalog/complements` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/complements` Cria um complemento. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `name` *string* **obrigatório** — Nome do complemento. - `description` *string* — Descrição do complemento. - `label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `price` *number* — Preço de venda. - `code` *string* — Código interno. - `barcode` *string* — Código de barras. - `unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `featuredPrint` *boolean* — Indica se tem destaque na impressão. - `cost` *object* — Custos do complemento. - `cost.base` *number* — Custo base. ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/catalog/complements" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Molho Nola", "price": 2, "unit": "UN" }' ``` ## Exemplos de resposta ### 201 OK ```json { "complementId": 2587090, "storeId": 107, "name": "Molho Nola", "description": "Molho Nola", "label": "new", "price": 2, "code": "MN1", "barcode": "7891000315507", "unit": "UN", "active": true, "featuredPrint": false, "cost": { "base": 0, "supply": 0, "total": 0 }, "menus": [ { "merchantId": 122, "name": "BeeFood - Cardápio Digital", "active": true, "delivery": true, "deliveryPrice": 2, "dineIn": true, "dineInPrice": 2, "totem": false, "sortOrder": 1, "cashbackEnabled": false } ], "groups": [ { "optionId": 5672302, "name": "Pop Barbecue + Pop Nola Rose : Deseja acrescentar algum ingrediente?" } ] } ``` ## Campos da resposta - `complementId` *number* — Identificador do complemento. - `storeId` *number* — Identificador da empresa. - `name` *string* — Nome do complemento. - `description` *string* — Descrição do complemento. - `label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `price` *number* — Preço de venda. - `code` *string* — Código interno. - `barcode` *string* — Código de barras. - `unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `active` *boolean* — Indica se está ativo em pelo menos um cardápio da empresa. Somente leitura. - `featuredPrint` *boolean* — Indica se tem destaque na impressão. - `cost` *object* — Custos do complemento. - `cost.base` *number* — Custo base. - `cost.supply` *number* — Custo da ficha técnica. Somente leitura. - `cost.total` *number* — Soma do custo base com o custo da ficha técnica. Somente leitura. - `menus` *array* — Configurações do complemento por cardápio. - `menus[].merchantId` *number* — Identificador do cardápio. - `menus[].name` *string* — Nome do cardápio. Somente leitura. - `menus[].active` *boolean* — Indica se está ativo neste cardápio. - `menus[].delivery` *boolean* — Indica se aparece no delivery. - `menus[].deliveryPrice` *number* — Preço no delivery. - `menus[].dineIn` *boolean* — Indica se aparece no presencial. - `menus[].dineInPrice` *number* — Preço no presencial. - `menus[].totem` *boolean* — Indica se aparece no totem. - `menus[].promotionPrice` *number* — Preço promocional. - `menus[].sortOrder` *number* — Posição de exibição. - `menus[].featuredOrder` *number* — Posição entre destaques. - `menus[].cashbackEnabled` *boolean* — Indica se o cashback está ativo neste cardápio. - `groups` *array* — Grupos de opções em que o complemento aparece. Somente leitura. - `groups[].optionId` *number* — Identificador da opção no grupo. - `groups[].name` *string* — Nome do grupo. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Invalid complement data | ## Vocabulários usados neste endpoint ## Catálogo · unit Valores aceitos no campo unit dos produtos do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `UN` | Unidade | /v1/catalog/products | | `KG` | Quilograma | /v1/catalog/products | | `G` | Grama | /v1/catalog/products | | `L` | Litro | /v1/catalog/products | | `ML` | Mililitro | /v1/catalog/products | | `PCT` | Pacote | /v1/catalog/products | | `CX` | Caixa | /v1/catalog/products | | `DZ` | Dúzia | /v1/catalog/products | | `FD` | Fardo | /v1/catalog/products | | `BD` | Balde | /v1/catalog/products | | `SC` | Saco | /v1/catalog/products | | `PT` | Pote | /v1/catalog/products | | `CP` | Copo | /v1/catalog/products | | `PC` | Peça | /v1/catalog/products | | `FT` | Fátia | /v1/catalog/products | | `PQ` | Porção | /v1/catalog/products | | `GF` | Garrafa | /v1/catalog/products | | `LT` | Lata | /v1/catalog/products | | `BN` | Bandeja | /v1/catalog/products | ## Criar grupo --- title: "Criar grupo" description: "POST /v1/catalog/groups — criar um grupo de opções no cardápio BeeFood." method: "POST" path: "/v1/catalog/groups" url: "https://developer.beefood.com.br/docs/catalogo/criar-grupo" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Criar grupo `POST /v1/catalog/groups` - Produção: `https://api.beefood.app/v1/catalog/groups` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups` Cria um grupo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `name` *string* **obrigatório** — Nome do grupo, até 100 caracteres. - `active` *boolean* — Indica se o grupo está ativo (padrão true). - `delivery` *boolean* — Indica se o grupo aparece no delivery (padrão true). - `dineIn` *boolean* — Indica se o grupo aparece no presencial (padrão true). - `required` *boolean* — Indica se a escolha é obrigatória (padrão false). - `pizza` *boolean* — Indica se o grupo é de pizza (padrão false). - `sortOrder` *integer* — Posição de exibição, inteiro maior ou igual a 0 (padrão 0). - `priceFormation` *string* — Formação de preço (Default: sum): sum, gift, highest ou proportional. - `minQuantity` *integer* — Quantidade mínima de opções, inteiro maior ou igual a 0 (padrão 0). - `maxQuantity` *integer* — Quantidade máxima de opções, inteiro maior ou igual a 1 (padrão 1). ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/catalog/groups" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Escolha seus Condimentos:", "active": true, "delivery": true, "dineIn": true, "required": false, "pizza": false, "sortOrder": 0, "priceFormation": "gift", "minQuantity": 0, "maxQuantity": 2 }' ``` ## Exemplos de resposta ### 201 OK ```json { "groupId": 264010, "name": "Escolha seus Condimentos:", "active": true, "delivery": true, "dineIn": true, "required": false, "pizza": false, "sortOrder": 0, "priceFormation": "gift", "minQuantity": 0, "maxQuantity": 2, "products": [] } ``` ## Campos da resposta - `groupId` *number* — Identificador do grupo. - `name` *string* — Nome do grupo. - `active` *boolean* — Indica se o grupo está ativo. - `delivery` *boolean* — Indica se o grupo aparece no delivery. - `dineIn` *boolean* — Indica se o grupo aparece no presencial. - `required` *boolean* — Indica se a escolha é obrigatória. - `pizza` *boolean* — Indica se o grupo é de pizza. - `sortOrder` *number* — Posição de exibição. - `priceFormation` *string* — Formação de preço: sum, gift, highest ou proportional. - `minQuantity` *number* — Quantidade mínima de opções. - `maxQuantity` *number* — Quantidade máxima de opções. - `products` *array* — Produtos vinculados ao grupo. - `products[].productId` *number* — Identificador do produto. - `products[].name` *string* — Nome do produto. - `products[].image` *object* — URLs da imagem do produto. - `products[].image.original` *string* — Imagem original. - `products[].image.thumbnail60` *string* — Miniatura de 60 px. - `products[].image.thumbnail120` *string* — Miniatura de 120 px. - `products[].image.thumbnailWeb` *string* — Miniatura para web. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Invalid group data | ## Criar produto --- title: "Criar produto" description: "POST /v1/catalog/products — criar um produto BeeFood e vinculá-lo a uma ou mais filiais." method: "POST" path: "/v1/catalog/products" url: "https://developer.beefood.com.br/docs/catalogo/criar-produto" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Criar produto `POST /v1/catalog/products` - Produção: `https://api.beefood.app/v1/catalog/products` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/products` Cria um produto. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `barcode` *string* — Código de barras. - `code` *string* — Código interno. - `name` *string* **obrigatório** — Nome do produto. - `description` *string* — Descrição do produto. - `internalNotes` *string* — Observações internas. - `label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `price` *number* — Preço padrão. - `featured` *boolean* — Indica se está em destaque. - `featuredPrint` *boolean* — Indica se tem destaque na impressão. - `serviceFeeActive` *boolean* — Indica se a taxa de serviço está ativa. - `scheduleOnly` *boolean* — Indica se a venda é apenas por agendamento. - `scaleActive` *boolean* — Indica se a balança está ativa. - `scaleShelfLifeDays` *number* — Validade em dias na balança. - `sectorId` *number* — Identificador de um setor da mesma empresa. - `cost` *object* — Custos do produto. - `cost.base` *number* — Custo base. ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/catalog/products" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "4 Esferas do Dragão de Pepperoni", "description": "Mussarela e pepperoni.", "sectorId": 1997, "label": "new", "featured": false, "price": 19.99, "code": "25", "barcode": "7891000315507", "unit": "UN", "cost": { "base": 8.5 }, "featuredPrint": false, "serviceFeeActive": true, "scheduleOnly": false, "internalNotes": "Disponível por tempo indeterminado.", "scaleActive": false, "scaleShelfLifeDays": 0 }' ``` ## Exemplos de resposta ### 201 OK ```json { "productId": 131822, "storeId": 107, "barcode": "7891234567890", "code": "25", "type": "product", "name": "Pizza de Frango com Catupiry", "description": "Mussarela, frango e requeijão.", "internalNotes": "Disponível por tempo indeterminado.", "label": "new", "unit": "UN", "price": 19.99, "featured": false, "featuredPrint": false, "serviceFeeActive": true, "scheduleOnly": false, "scaleActive": false, "scaleShelfLifeDays": 0, "sectorId": 1997, "sectorName": "Pizzas", "combo": false, "cost": { "base": 0, "supply": 0, "total": 0 }, "menus": [ { "merchantId": 122, "name": "BeeFood - Cardápio Digital", "active": true, "delivery": true, "deliveryPrice": 19.99, "dineIn": true, "dineInPrice": 19.99, "totem": false, "promotionPrice": 15.99, "sortOrder": 1, "featuredOrder": 2, "cashbackEnabled": true, "upsell": [ { "productId": 2586827, "name": "7 Esferas do Dragão de Pepperoni" } ] } ], "restrictions": { "vegetarian": false, "vegan": false, "organic": false, "glutenFree": false, "sugarFree": false, "lactoseFree": false, "natural": false, "iced": false, "serves": 1 }, "groups": [ { "groupId": 5668252, "name": "Escolha seus Condimentos:", "active": true, "delivery": true, "dineIn": true, "required": true, "sortOrder": 1, "priceFormation": "gift", "minQuantity": 1, "maxQuantity": 1, "selectionMode": "single", "options": [ { "optionId": 5670994, "productId": 2586516, "name": "Sachê Ketchup", "type": "complement", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 0, "deliveryPrice": 0, "dineInPrice": 0, "sortOrder": 0, "image": { "original": "https://domain.com/opt.webp", "thumbnail60": "https://domain.com/opt-60.jpg", "thumbnail120": "https://domain.com/opt-120.jpg", "thumbnailWeb": "https://domain.com/opt.webp" } } ] } ] } ``` ## Campos da resposta - `productId` *number* — Identificador do produto. - `storeId` *number* — Identificador da empresa. - `barcode` *string* — Código de barras. - `code` *string* — Código interno. - `type` *string* — Tipo derivado do PDV: "product". Somente leitura. - *Valores:* `product`, `menu`, `restrictions`, `groups` - `name` *string* — Nome do produto. - `description` *string* — Descrição do produto. - `internalNotes` *string* — Observações internas. - `label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `price` *number* — Preço padrão. - `featured` *boolean* — Indica se está em destaque. - `featuredPrint` *boolean* — Indica se tem destaque na impressão. - `serviceFeeActive` *boolean* — Indica se a taxa de serviço está ativa. - `scheduleOnly` *boolean* — Indica se a venda é apenas por agendamento. - `scaleActive` *boolean* — Indica se a balança está ativa. - `scaleShelfLifeDays` *number* — Validade em dias na balança. - `sectorId` *number* — Identificador de um setor da mesma empresa. - `sectorName` *string* — Nome do setor. Somente leitura. - `combo` *boolean* — Indica se é combo. Somente leitura: vira true quando o produto tem ao menos um grupo vinculado e volta a false quando o último é desvinculado. - `cost` *object* — Custos do produto. - `cost.base` *number* — Custo base. - `cost.supply` *number* — Custo da composição, calculado dos insumos. Somente leitura. - `cost.total` *number* — Soma do custo base com o custo da composição. Somente leitura. - `menus` *array* — Configurações do produto por cardápio. - `menus[].merchantId` *number* — Cardápio da mesma empresa. - `menus[].name` *string* — Nome do cardápio. Somente leitura. - `menus[].active` *boolean* — Indica se está ativo nesto cardápio. - `menus[].delivery` *boolean* — Indica se aparece no delivery. - `menus[].deliveryPrice` *number* — Preço no delivery. - `menus[].dineIn` *boolean* — Indica se aparece no presencial. - `menus[].dineInPrice` *number* — Preço no presencial. - `menus[].totem` *boolean* — Indica se aparece no totem. - `menus[].promotionPrice` *number* — Preço promocional. - `menus[].sortOrder` *number* — Posição de exibição. - `menus[].featuredOrder` *number* — Posição entre destaques. - `menus[].cashbackEnabled` *boolean* — Indica se o cashback está ativo nesto cardápio. - `menus[].upsell` *array* — Produtos sugeridos nesto cardápio. - `menus[].upsell[].productId` *number* — Produto sugerido no upsell. - `menus[].upsell[].name` *string* — Nome do produto sugerido. Somente leitura. - `restrictions` *object* — Restrições e características alimentares. - `restrictions.vegetarian` *boolean* — Indica se é vegetariano. - `restrictions.vegan` *boolean* — Indica se é vegano. - `restrictions.organic` *boolean* — Indica se é orgânico. - `restrictions.glutenFree` *boolean* — Indica se não contém glúten. - `restrictions.sugarFree` *boolean* — Indica se não contém açúcar. - `restrictions.lactoseFree` *boolean* — Indica se não contém lactose. - `restrictions.natural` *boolean* — Indica se é natural. - `restrictions.iced` *boolean* — Indica se é gelado. - `restrictions.serves` *number* — Número de pessoas servidas. - `groups` *array* — Grupos já existentes vinculados ao produto, ordenados por sortOrder. - `groups[].groupId` *number* — Grupo existente da mesma empresa. - `groups[].name` *string* — Nome do grupo. Somente leitura. - `groups[].active` *boolean* — Indica se o grupo está ativo. - `groups[].delivery` *boolean* — Indica se o grupo aparece no delivery. - `groups[].dineIn` *boolean* — Indica se o grupo aparece no presencial. - `groups[].required` *boolean* — Indica se a escolha é obrigatória. - `groups[].sortOrder` *number* — Posição do grupo neste produto; menor valor aparece primeiro. Omitido quando o produto não tem ordem definida para o grupo. - `groups[].priceFormation` *string* — Regra de preço: gift, highest, proportional ou sum. - `groups[].minQuantity` *number* — Quantidade mínima de opções. - `groups[].maxQuantity` *number* — Quantidade máxima de opções. - `groups[].selectionMode` *string* — Modo de seleção do grupo. - `groups[].options` *array* — Opções do grupo. Somente leitura nesta entrega. - `groups[].options[].optionId` *number* — Campo optionId. - `groups[].options[].productId` *number* — Campo productId. - `groups[].options[].name` *string* — Campo name. - `groups[].options[].type` *string* — Campo type. - `groups[].options[].active` *boolean* — Campo active. - `groups[].options[].delivery` *boolean* — Campo delivery. - `groups[].options[].dineIn` *boolean* — Campo dineIn. - `groups[].options[].minQuantity` *number* — Campo minQuantity. - `groups[].options[].maxQuantity` *number* — Campo maxQuantity. - `groups[].options[].price` *number* — Campo price. - `groups[].options[].deliveryPrice` *number* — Campo deliveryPrice. - `groups[].options[].dineInPrice` *number* — Campo dineInPrice. - `groups[].options[].sortOrder` *number* — Campo sortOrder. - `groups[].options[].image` *object* — Campo image. - `groups[].options[].image.original` *string* — Campo original. - `groups[].options[].image.thumbnail60` *string* — Campo thumbnail60. - `groups[].options[].image.thumbnail120` *string* — Campo thumbnail120. - `groups[].options[].image.thumbnailWeb` *string* — Campo thumbnailWeb. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Invalid product data | | 400 | Referenced resource does not belong to the store | ## Vocabulários usados neste endpoint ## Atualização em lote · type | Valor | Significado | Uso | | --- | --- | --- | | `product` | Dados do produto | Objeto product | | `menu` | Cardápio do produto | Objeto menu | | `restrictions` | Restrições alimentares | Objeto restrictions ou null | | `groups` | Ordem dos grupos | Array groups | ## Catálogo · unit Valores aceitos no campo unit dos produtos do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `UN` | Unidade | /v1/catalog/products | | `KG` | Quilograma | /v1/catalog/products | | `G` | Grama | /v1/catalog/products | | `L` | Litro | /v1/catalog/products | | `ML` | Mililitro | /v1/catalog/products | | `PCT` | Pacote | /v1/catalog/products | | `CX` | Caixa | /v1/catalog/products | | `DZ` | Dúzia | /v1/catalog/products | | `FD` | Fardo | /v1/catalog/products | | `BD` | Balde | /v1/catalog/products | | `SC` | Saco | /v1/catalog/products | | `PT` | Pote | /v1/catalog/products | | `CP` | Copo | /v1/catalog/products | | `PC` | Peça | /v1/catalog/products | | `FT` | Fátia | /v1/catalog/products | | `PQ` | Porção | /v1/catalog/products | | `GF` | Garrafa | /v1/catalog/products | | `LT` | Lata | /v1/catalog/products | | `BN` | Bandeja | /v1/catalog/products | ## Criar setor --- title: "Criar setor" description: "POST /v1/catalog/sectors — criar um setor no cardápio BeeFood." method: "POST" path: "/v1/catalog/sectors" url: "https://developer.beefood.com.br/docs/catalogo/criar-setor" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Criar setor `POST /v1/catalog/sectors` - Produção: `https://api.beefood.app/v1/catalog/sectors` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/sectors` Cria um setor. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `name` *string* **obrigatório** — Nome do setor, até 150 caracteres. Exemplo: `Sobremesas`. - `publicName` *string* — Nome exibido no cardápio digital, até 150 caracteres. Exemplo: `Doces`. - `delivery` *boolean* — Indica se o setor aparece no delivery (padrão true). - `dineIn` *boolean* — Indica se o setor aparece no presencial (padrão true). ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/catalog/sectors" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Sobremesas", "publicName": "Doces", "delivery": true, "dineIn": true }' ``` ## Exemplos de resposta ### 201 OK ```json { "sectorId": 221160, "storeId": 107, "name": "Sobremesas", "publicName": "Doces", "delivery": true, "dineIn": true, "menus": [ { "merchantId": 122, "name": "Restaurante Exemplo", "active": true } ] } ``` ## Campos da resposta - `sectorId` *number* — Identificador do setor. - `storeId` *number* — Identificador da empresa. - `name` *string* — Nome do setor. - `publicName` *string* — Nome exibido no cardápio digital. - `delivery` *boolean* — Indica se o setor aparece no delivery. - `dineIn` *boolean* — Indica se o setor aparece no presencial. - `image` *object* — URLs da imagem do setor. Somente leitura. Para enviar ou remover, use Enviar imagem e Remover imagem com resourceType = sectors. - `image.original` *string* — Imagem original. - `image.thumbnail80` *string* — Miniatura de 80 px. - `image.thumbnail180` *string* — Miniatura de 180 px. - `menus` *array* — Cardápios do setor. - `menus[].merchantId` *number* — Identificador do cardápio. - `menus[].name` *string* — Nome do cardápio. - `menus[].active` *boolean* — Indica se o setor está ativo no cardápio. - `menus[].sortOrder` *number* — Posição do setor no cardápio. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Invalid sector data | ## Desvincular produto do grupo --- title: "Desvincular produto do grupo" description: "DELETE /v1/catalog/groups/{groupId}/products/{productId} — desvincular um produto de um grupo BeeFood." method: "DELETE" path: "/v1/catalog/groups/{groupId}/products/{productId}" url: "https://developer.beefood.com.br/docs/catalogo/desvincular-produto-grupo" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Desvincular produto do grupo `DELETE /v1/catalog/groups/{groupId}/products/{productId}` - Produção: `https://api.beefood.app/v1/catalog/groups/{groupId}/products/{productId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups/{groupId}/products/{productId}` Desvincula um produto de um grupo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `groupId` *integer* **obrigatório** — Identificador do grupo. Exemplo: `264006`. - `productId` *integer* **obrigatório** — Identificador do produto. Exemplo: `2585290`. ## Exemplos de requisição ### cURL ```bash curl -X DELETE "https://api.beefood.app/v1/catalog/groups/{groupId}/products/{productId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 204 OK ```json ``` ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 404 | Group not found | | 404 | Product is not linked to the group | ## Editar opções em lote --- title: "Editar opções em lote" description: "PATCH /v1/catalog/options — editar e ordenar opções de grupos BeeFood em lote." method: "PATCH" path: "/v1/catalog/options" url: "https://developer.beefood.com.br/docs/catalogo/editar-opcoes" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Editar opções em lote `PATCH /v1/catalog/options` - Produção: `https://api.beefood.app/v1/catalog/options` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/options` Edita e reordena opções em lote. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `[].optionId` *integer* **obrigatório** — Identificador da opção. Exemplo: `5689444`. - `[].active` *boolean* — Indica se a opção está ativa. - `[].delivery` *boolean* — Indica se a opção aparece no delivery. - `[].dineIn` *boolean* — Indica se a opção aparece no presencial. - `[].minQuantity` *integer* — Quantidade mínima, inteiro maior ou igual a 0. - `[].maxQuantity` *integer* — Quantidade máxima, inteiro maior ou igual a 1. - `[].price` *number* — Preço, número maior ou igual a 0 ou null. - `[].deliveryPrice` *number* — Preço no delivery, número maior ou igual a 0 ou null. - `[].dineInPrice` *number* — Preço no presencial, número maior ou igual a 0 ou null. - `[].sortOrder` *integer* — Posição da opção no grupo, inteiro maior ou igual a 0. ## Exemplos de requisição ### cURL ```bash curl -X PATCH "https://api.beefood.app/v1/catalog/options" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '[ { "optionId": 5689444, "active": true, "price": 6, "deliveryPrice": 2, "dineInPrice": null, "sortOrder": 0 }, { "optionId": 5689445, "sortOrder": 1 } ]' ``` ## Exemplos de resposta ### 200 OK ```json [ { "optionId": 5689444, "success": true }, { "optionId": 5689445, "success": false, "message": "Option ID 5689445 not found" } ] ``` ## Campos da resposta - `[].optionId` *number* — Identificador da opção. - `[].success` *boolean* — Indica se o item foi gravado. - `[].message` *string* — Motivo da falha; só vem quando o item falha. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Body must be a non-empty array of options | ## Enviar imagem --- title: "Enviar imagem" description: "PUT /v1/catalog/{resourceType}/{resourceId}/image — enviar ou substituir a imagem de um setor, produto ou complemento no cardápio BeeFood." method: "PUT" path: "/v1/catalog/{resourceType}/{resourceId}/image" url: "https://developer.beefood.com.br/docs/catalogo/enviar-imagem" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Enviar imagem `PUT /v1/catalog/{resourceType}/{resourceId}/image` - Produção: `https://api.beefood.app/v1/catalog/{resourceType}/{resourceId}/image` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/{resourceType}/{resourceId}/image` Envia ou substitui a imagem do recurso. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Observações - Formatos aceitos: PNG, JPEG, WEBP e GIF. ## Parâmetros de path - `resourceType` *enum* **obrigatório** — Tipo do recurso dono da imagem. Exemplo: `products`. - *Valores:* `sectors`, `products`, `complements` - `resourceId` *integer* **obrigatório** — ID do setor, produto ou complemento. Exemplo: `221145`. ## Parâmetros do body - `file` *string* **obrigatório** — Imagem em base64. Aceita também o formato data URL (data:image/png;base64,...). Exemplo: `"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."`. ## Exemplos de requisição ### cURL ```bash curl -X PUT "https://api.beefood.app/v1/catalog/{resourceType}/{resourceId}/image" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..." }' ``` ## Exemplos de resposta ### 200 OK ```json { "url": "https://beetech-imagens.s3-sa-east-1.amazonaws.com/38311/2f6c1d0e-7b1a-4c55-9f0e-1a2b3c4d5e6f.jpg" } ``` ## Campos da resposta - `url` *string* — URL da imagem salva. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'resourceType' must be one of: sectors, products, complements | | 400 | 'resourceId' must be a positive integer | | 400 | 'file' must be a base64 string | | 400 | 'file' must be a PNG, JPEG, WEBP or GIF image | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 404 | Product ID {id} not found | | 404 | Complement ID {id} not found | | 404 | Sector ID {id} not found | | 429 | Too many requests | ## Vocabulários usados neste endpoint ## Catálogo · resourceType Tipo do recurso dono da imagem, usado na rota de envio e remoção de imagens do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `sectors` | Setor | /v1/catalog/{resourceType}/{resourceId}/image | | `products` | Produto | /v1/catalog/{resourceType}/{resourceId}/image | | `complements` | Complemento | /v1/catalog/{resourceType}/{resourceId}/image | ## Excluir complemento --- title: "Excluir complemento" description: "DELETE /v1/catalog/complements/{complementId} — ocultar um complemento do cardápio BeeFood." method: "DELETE" path: "/v1/catalog/complements/{complementId}" url: "https://developer.beefood.com.br/docs/catalogo/excluir-complemento" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Excluir complemento `DELETE /v1/catalog/complements/{complementId}` - Produção: `https://api.beefood.app/v1/catalog/complements/{complementId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/complements/{complementId}` Oculta um complemento. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `complementId` *integer* **obrigatório** — Identificador do complemento. Exemplo: `2587090`. ## Parâmetros de query - `usuarioId` *integer* — Usuário do PDV da mesma empresa; opcional. Exemplo: `10`. ## Exemplos de requisição ### cURL ```bash curl -X DELETE "https://api.beefood.app/v1/catalog/complements/{complementId}?usuarioId=10" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 204 OK ```json ``` ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Store ID 107 does not have user ID 10 | | 404 | Complement not found | ## Excluir grupo --- title: "Excluir grupo" description: "DELETE /v1/catalog/groups/{groupId} — excluir um grupo de opções BeeFood." method: "DELETE" path: "/v1/catalog/groups/{groupId}" url: "https://developer.beefood.com.br/docs/catalogo/excluir-grupo" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Excluir grupo `DELETE /v1/catalog/groups/{groupId}` - Produção: `https://api.beefood.app/v1/catalog/groups/{groupId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups/{groupId}` Exclui um grupo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `groupId` *integer* **obrigatório** — Identificador do grupo. Exemplo: `264006`. ## Exemplos de requisição ### cURL ```bash curl -X DELETE "https://api.beefood.app/v1/catalog/groups/{groupId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 204 OK ```json ``` ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 404 | Group not found | ## Excluir produto --- title: "Excluir produto" description: "DELETE /v1/catalog/products/{productId} — ocultar um produto do cardápio BeeFood." method: "DELETE" path: "/v1/catalog/products/{productId}" url: "https://developer.beefood.com.br/docs/catalogo/excluir-produto" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Excluir produto `DELETE /v1/catalog/products/{productId}` - Produção: `https://api.beefood.app/v1/catalog/products/{productId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/products/{productId}` Oculta um produto. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `productId` *integer* **obrigatório** — Identificador do produto. Exemplo: `131822`. ## Parâmetros de query - `usuarioId` *integer* — Usuário do PDV da mesma empresa; opcional. Exemplo: `10`. ## Exemplos de requisição ### cURL ```bash curl -X DELETE "https://api.beefood.app/v1/catalog/products/{productId}?usuarioId=10" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 204 OK ```json ``` ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Store ID 107 does not have user ID 10 | | 404 | Product not found | ## Excluir setor --- title: "Excluir setor" description: "DELETE /v1/catalog/sectors/{sectorId} — excluir um setor do cardápio BeeFood." method: "DELETE" path: "/v1/catalog/sectors/{sectorId}" url: "https://developer.beefood.com.br/docs/catalogo/excluir-setor" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Excluir setor `DELETE /v1/catalog/sectors/{sectorId}` - Produção: `https://api.beefood.app/v1/catalog/sectors/{sectorId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/sectors/{sectorId}` Exclui um setor. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `sectorId` *integer* **obrigatório** — Identificador do setor. Exemplo: `221145`. ## Parâmetros de query - `usuarioId` *integer* — Usuário do PDV registrado nos produtos alterados. Exemplo: `5501`. ## Exemplos de requisição ### cURL ```bash curl -X DELETE "https://api.beefood.app/v1/catalog/sectors/{sectorId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 204 OK ```json ``` ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Invalid usuarioId | | 404 | Sector not found | ## Detalhe do grupo --- title: "Detalhe do grupo" description: "GET /v1/catalog/groups/{groupId} — detalhe de um grupo de opções da BeeFood." method: "GET" path: "/v1/catalog/groups/{groupId}" url: "https://developer.beefood.com.br/docs/catalogo/grupo" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Detalhe do grupo `GET /v1/catalog/groups/{groupId}` - Produção: `https://api.beefood.app/v1/catalog/groups/{groupId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups/{groupId}` Retorna o detalhe de um grupo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `groupId` *integer* **obrigatório** — Identificador do grupo. Exemplo: `264006`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/groups/{groupId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "groupId": 264006, "name": "Acompanhamentos", "active": true, "delivery": true, "dineIn": true, "required": true, "pizza": false, "sortOrder": 0, "priceFormation": "gift", "minQuantity": 1, "maxQuantity": 1, "products": [ { "productId": 2585290, "name": "Combo Supreme", "image": { "original": "https://cdn.beefood.com.br/products/2585290.jpg", "thumbnail60": "https://cdn.beefood.com.br/products/2585290_60.jpg", "thumbnail120": "https://cdn.beefood.com.br/products/2585290_120.jpg", "thumbnailWeb": "https://cdn.beefood.com.br/products/2585290_web.jpg" } } ] } ``` ## Campos da resposta - `groupId` *number* — Identificador do grupo. - `name` *string* — Nome do grupo. - `active` *boolean* — Indica se o grupo está ativo. - `delivery` *boolean* — Indica se o grupo aparece no delivery. - `dineIn` *boolean* — Indica se o grupo aparece no presencial. - `required` *boolean* — Indica se a escolha é obrigatória. - `pizza` *boolean* — Indica se o grupo é de pizza. - `sortOrder` *number* — Posição de exibição. - `priceFormation` *string* — Formação de preço: sum, gift, highest ou proportional. - `minQuantity` *number* — Quantidade mínima de opções. - `maxQuantity` *number* — Quantidade máxima de opções. - `products` *array* — Produtos vinculados ao grupo. - `products[].productId` *number* — Identificador do produto. - `products[].name` *string* — Nome do produto. - `products[].image` *object* — URLs da imagem do produto. - `products[].image.original` *string* — Imagem original. - `products[].image.thumbnail60` *string* — Miniatura de 60 px. - `products[].image.thumbnail120` *string* — Miniatura de 120 px. - `products[].image.thumbnailWeb` *string* — Miniatura para web. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | | 404 | Group not found | ## Listar grupos --- title: "Listar grupos" description: "GET /v1/catalog/groups — grupos de opções da empresa BeeFood, com filtros e paginação." method: "GET" path: "/v1/catalog/groups" url: "https://developer.beefood.com.br/docs/catalogo/grupos" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Listar grupos `GET /v1/catalog/groups` - Produção: `https://api.beefood.app/v1/catalog/groups` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups` Lista os grupos da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de query - `page` *integer* — Página (padrão 1). Exemplo: `1`. - `limit` *integer* — Itens por página, de 1 a 100 (padrão 20). Exemplo: `20`. - `sort` *string* — Ordem por groupId: asc ou desc (padrão desc). Exemplo: `desc`. - *Valores:* `asc`, `desc` - `name` *string* — Filtra pelo nome do grupo. Exemplo: `massa`. - `active` *boolean* — Filtra grupos ativos ou inativos. Exemplo: `true`. - `required` *boolean* — Filtra grupos obrigatórios. Exemplo: `true`. - `priceFormation` *string* — Filtra pela formação de preço: sum, gift, highest ou proportional. Exemplo: `gift`. - `productId` *integer* — Filtra grupos vinculados ao produto. Exemplo: `2585290`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/groups?page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "groupId": 264006, "name": "Acompanhamentos", "active": true, "delivery": true, "dineIn": true, "required": true, "pizza": false, "sortOrder": 0, "priceFormation": "gift", "minQuantity": 1, "maxQuantity": 1, "products": [ { "productId": 2585290, "name": "Combo Supreme", "image": { "original": "https://cdn.beefood.com.br/products/2585290.jpg", "thumbnail60": "https://cdn.beefood.com.br/products/2585290_60.jpg", "thumbnail120": "https://cdn.beefood.com.br/products/2585290_120.jpg", "thumbnailWeb": "https://cdn.beefood.com.br/products/2585290_web.jpg" } } ] } ], "page": 1, "limit": 20, "total": 1, "pages": 1 } ``` ## Campos da resposta - `items[].groupId` *number* — Identificador do grupo. - `items[].name` *string* — Nome do grupo. - `items[].active` *boolean* — Indica se o grupo está ativo. - `items[].delivery` *boolean* — Indica se o grupo aparece no delivery. - `items[].dineIn` *boolean* — Indica se o grupo aparece no presencial. - `items[].required` *boolean* — Indica se a escolha é obrigatória. - `items[].pizza` *boolean* — Indica se o grupo é de pizza. - `items[].sortOrder` *number* — Posição de exibição. - `items[].priceFormation` *string* — Formação de preço: sum, gift, highest ou proportional. - `items[].minQuantity` *number* — Quantidade mínima de opções. - `items[].maxQuantity` *number* — Quantidade máxima de opções. - `items[].products` *array* — Produtos vinculados ao grupo. - `items[].products[].productId` *number* — Identificador do produto. - `items[].products[].name` *string* — Nome do produto. - `items[].products[].image` *object* — URLs da imagem do produto. - `items[].products[].image.original` *string* — Imagem original. - `items[].products[].image.thumbnail60` *string* — Miniatura de 60 px. - `items[].products[].image.thumbnail120` *string* — Miniatura de 120 px. - `items[].products[].image.thumbnailWeb` *string* — Miniatura para web. - `page` *number* — page da paginação. - `limit` *number* — limit da paginação. - `total` *number* — total da paginação. - `pages` *number* — pages da paginação. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | | 400 | Invalid priceFormation | ## Vocabulários usados neste endpoint ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Listar opções --- title: "Listar opções" description: "GET /v1/catalog/options — opções dos grupos da empresa BeeFood, com filtros e paginação." method: "GET" path: "/v1/catalog/options" url: "https://developer.beefood.com.br/docs/catalogo/opcoes" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Listar opções `GET /v1/catalog/options` - Produção: `https://api.beefood.app/v1/catalog/options` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/options` Lista as opções da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de query - `page` *integer* — Página (padrão 1). Exemplo: `1`. - `limit` *integer* — Itens por página, de 1 a 100 (padrão 20). Exemplo: `20`. - `groupId` *integer* — Filtra as opções pertencentes a determinado grupo. Exemplo: `264428`. - `name` *string* — Filtra pelo nome da opção. Exemplo: `onion`. - `type` *string* — Filtra pelo tipo: product ou complement. Exemplo: `product`. - `active` *boolean* — Filtra opções ativas ou inativas. Exemplo: `true`. - `delivery` *boolean* — Filtra opções do delivery. Exemplo: `true`. - `dineIn` *boolean* — Filtra opções do presencial. Exemplo: `true`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/options?page=1&limit=20&groupId=264428" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "groupId": 264428, "optionId": 5689346, "productId": 2586945, "name": "Onion rings", "type": "product", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 5.5, "sortOrder": 1, "image": { "original": "https://cdn.beefood.com.br/products/2586945.jpg", "thumbnail60": "https://cdn.beefood.com.br/products/2586945_60.jpg", "thumbnail120": "https://cdn.beefood.com.br/products/2586945_120.jpg", "thumbnailWeb": "https://cdn.beefood.com.br/products/2586945_web.jpg" } } ], "page": 1, "limit": 20, "total": 1, "pages": 1 } ``` ## Campos da resposta - `items[].groupId` *number* — Identificador do grupo. - `items[].optionId` *number* — Identificador da opção. - `items[].productId` *number* — Identificador do produto ou complemento. - `items[].name` *string* — Nome da opção. - `items[].type` *string* — Tipo da opção: product ou complement. - `items[].active` *boolean* — Indica se a opção está ativa. - `items[].delivery` *boolean* — Indica se a opção aparece no delivery. - `items[].dineIn` *boolean* — Indica se a opção aparece no presencial. - `items[].minQuantity` *number* — Quantidade mínima. - `items[].maxQuantity` *number* — Quantidade máxima. - `items[].price` *number* — Preço da opção. - `items[].deliveryPrice` *number* — Preço no delivery. - `items[].dineInPrice` *number* — Preço no presencial. - `items[].sortOrder` *number* — Posição da opção no grupo. - `items[].image` *object* — URLs da imagem do produto. - `items[].image.original` *string* — Imagem original. - `items[].image.thumbnail60` *string* — Miniatura de 60 px. - `items[].image.thumbnail120` *string* — Miniatura de 120 px. - `items[].image.thumbnailWeb` *string* — Miniatura para web. - `page` *number* — page da paginação. - `limit` *number* — limit da paginação. - `total` *number* — total da paginação. - `pages` *number* — pages da paginação. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | | 400 | Invalid type | | 404 | Group ID 264428 not found | ## Detalhe do produto --- title: "Detalhe do produto" description: "GET /v1/catalog/products/{productId} — detalhe de um produto no cardápio da BeeFood." method: "GET" path: "/v1/catalog/products/{productId}" url: "https://developer.beefood.com.br/docs/catalogo/produto" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Detalhe do produto `GET /v1/catalog/products/{productId}` - Produção: `https://api.beefood.app/v1/catalog/products/{productId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/products/{productId}` Retorna o detalhe de um produto. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `productId` *integer* **obrigatório** — Identificador do produto. Exemplo: `131822`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/products/{productId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "productId": 2515344, "storeId": 38311, "type": "product", "name": "Combo One Classic", "description": "Pão brioche, carne 100g, queijo prato fatiado, alface americana, tomate fatiado, cebola roxa e maionese verde artesanal da casa\n(Acompanha batata e bebida)\n\nTags\nX-salada, x salada, cheese salada", "unit": "UN", "price": 31, "featured": false, "featuredPrint": false, "serviceFeeActive": true, "scheduleOnly": false, "scaleActive": false, "sectorId": 213750, "sectorName": "Combos (Burger + Porção + Bebida)", "combo": true, "cost": { "base": 0, "supply": 0, "total": 0 }, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202608180903_6UJ.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202608180903_6UJ.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202608180903_6UJ.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202608180903_6UJ.webp" }, "menus": [ { "merchantId": 39202, "name": "Restaurante Exemplo", "active": true, "delivery": true, "dineIn": true, "totem": true, "sortOrder": 5, "cashbackEnabled": true }, { "merchantId": 50502, "name": "Restaurante Exemplo - Sushi", "active": false, "delivery": true, "dineIn": true, "totem": true, "sortOrder": 5, "cashbackEnabled": true } ], "groups": [ { "groupId": 257197, "name": "Burger", "active": true, "delivery": true, "dineIn": true, "required": true, "sortOrder": 1, "priceFormation": "gift", "minQuantity": 1, "maxQuantity": 1, "selectionMode": "single", "options": [ { "optionId": 5616545, "productId": 2515297, "name": "One Classic", "type": "product", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 0, "sortOrder": 0, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202608180910_330.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202608180910_330.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202608180910_330.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202608180910_330.webp" }, "deliveryPrice": 0 } ] }, { "groupId": 257188, "name": "Bebidas", "active": true, "delivery": true, "dineIn": true, "required": true, "sortOrder": 2, "priceFormation": "sum", "minQuantity": 1, "maxQuantity": 1, "selectionMode": "single", "options": [ { "optionId": 5616520, "productId": 2515308, "name": "Coca Cola 350ml", "type": "product", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 8.4, "sortOrder": 0, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281443_4E3.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202503281443_4E3.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202503281443_4E3.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281443_4E3.webp" }, "deliveryPrice": 0 }, { "optionId": 5616521, "productId": 2515311, "name": "Coca Zero 350ml", "type": "product", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 8.4, "sortOrder": 1, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281444_7A0.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202503281444_7A0.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202503281444_7A0.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281444_7A0.webp" }, "deliveryPrice": 0 }, { "optionId": 5616522, "productId": 2515310, "name": "Fanta Laranja 350ml", "type": "product", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 8.4, "sortOrder": 2, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281444_WPL.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202503281444_WPL.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202503281444_WPL.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281444_WPL.webp" }, "deliveryPrice": 0 }, { "optionId": 5616523, "productId": 2515309, "name": "Sprite Zero 350ml", "type": "product", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 8.4, "sortOrder": 3, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281444_0QF.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202503281444_0QF.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202503281444_0QF.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281444_0QF.webp" }, "deliveryPrice": 0 }, { "optionId": 5616524, "productId": 2515327, "name": "Suco de uva 290ml Del Valle", "type": "complement", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 8.4, "sortOrder": 4, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281444_373.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202503281444_373.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202503281444_373.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281444_373.webp" }, "deliveryPrice": 0 }, { "optionId": 5616525, "productId": 2515328, "name": "Suco Maracujá 290ml Del Valle", "type": "product", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 1, "price": 8.4, "sortOrder": 5, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281446_I43.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202503281446_I43.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202503281446_I43.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202503281446_I43.webp" }, "deliveryPrice": 0 } ] } ] } ``` ## Campos da resposta - `productId` *number* — Identificador do produto. - `storeId` *number* — Identificador da empresa. - `barcode` *string* — Código de barras. - `code` *string* — Código interno. - `type` *string* — Tipo derivado do PDV: "product". Somente leitura. - `name` *string* — Nome do produto. - `description` *string* — Descrição do produto. - `internalNotes` *string* — Observações internas. - `label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `price` *number* — Preço padrão. - `featured` *boolean* — Indica se está em destaque. - `featuredPrint` *boolean* — Indica se tem destaque na impressão. - `serviceFeeActive` *boolean* — Indica se a taxa de serviço está ativa. - `scheduleOnly` *boolean* — Indica se a venda é apenas por agendamento. - `scaleActive` *boolean* — Indica se a balança está ativa. - `scaleShelfLifeDays` *number* — Validade em dias na balança. - `sectorId` *number* — Identificador de um setor da mesma empresa. - `sectorName` *string* — Nome do setor. Somente leitura. - `combo` *boolean* — Indica se é combo. Somente leitura: vira true quando o produto tem ao menos um grupo vinculado e volta a false quando o último é desvinculado. - `cost` *object* — Custos do produto. - `cost.base` *number* — Custo base. - `cost.supply` *number* — Custo da composição, calculado dos insumos. Somente leitura. - `cost.total` *number* — Soma do custo base com o custo da composição. Somente leitura. - `image` *object* — URLs da imagem do produto. Somente leitura. Para enviar ou remover, use Enviar imagem e Remover imagem com resourceType = products. - `image.original` *string* — Campo original. - `image.thumbnail60` *string* — Campo thumbnail60. - `image.thumbnail120` *string* — Campo thumbnail120. - `image.thumbnailWeb` *string* — Campo thumbnailWeb. - `menus` *array* — Configurações do produto por cardápio. - `menus[].merchantId` *number* — Cardápio da mesma empresa. - `menus[].name` *string* — Nome do cardápio. Somente leitura. - `menus[].active` *boolean* — Indica se está ativo nesto cardápio. - `menus[].delivery` *boolean* — Indica se aparece no delivery. - `menus[].deliveryPrice` *number* — Preço no delivery. - `menus[].dineIn` *boolean* — Indica se aparece no presencial. - `menus[].dineInPrice` *number* — Preço no presencial. - `menus[].totem` *boolean* — Indica se aparece no totem. - `menus[].promotionPrice` *number* — Preço promocional. - `menus[].sortOrder` *number* — Posição de exibição. - `menus[].featuredOrder` *number* — Posição entre destaques. - `menus[].cashbackEnabled` *boolean* — Indica se o cashback está ativo nesto cardápio. - `menus[].upsell` *array* — Produtos sugeridos nesto cardápio. - `menus[].upsell[].productId` *number* — Produto sugerido no upsell. - `menus[].upsell[].name` *string* — Nome do produto sugerido. Somente leitura. - `restrictions` *object* — Restrições e características alimentares. - `restrictions.vegetarian` *boolean* — Indica se é vegetariano. - `restrictions.vegan` *boolean* — Indica se é vegano. - `restrictions.organic` *boolean* — Indica se é orgânico. - `restrictions.glutenFree` *boolean* — Indica se não contém glúten. - `restrictions.sugarFree` *boolean* — Indica se não contém açúcar. - `restrictions.lactoseFree` *boolean* — Indica se não contém lactose. - `restrictions.natural` *boolean* — Indica se é natural. - `restrictions.iced` *boolean* — Indica se é gelado. - `restrictions.serves` *number* — Número de pessoas servidas. - `groups` *array* — Grupos já existentes vinculados ao produto, ordenados por sortOrder. - `groups[].groupId` *number* — Grupo existente da mesma empresa. - `groups[].name` *string* — Nome do grupo. Somente leitura. - `groups[].active` *boolean* — Indica se o grupo está ativo. - `groups[].delivery` *boolean* — Indica se o grupo aparece no delivery. - `groups[].dineIn` *boolean* — Indica se o grupo aparece no presencial. - `groups[].required` *boolean* — Indica se a escolha é obrigatória. - `groups[].sortOrder` *number* — Posição do grupo neste produto; menor valor aparece primeiro. Omitido quando o produto não tem ordem definida para o grupo. - `groups[].priceFormation` *string* — Regra de preço: gift, highest, proportional ou sum. - `groups[].minQuantity` *number* — Quantidade mínima de opções. - `groups[].maxQuantity` *number* — Quantidade máxima de opções. - `groups[].selectionMode` *string* — Modo de seleção do grupo. - `groups[].options` *array* — Opções do grupo. Somente leitura nesta entrega. - `groups[].options[].optionId` *number* — Campo optionId. - `groups[].options[].productId` *number* — Campo productId. - `groups[].options[].name` *string* — Campo name. - `groups[].options[].type` *string* — Campo type. - `groups[].options[].active` *boolean* — Campo active. - `groups[].options[].delivery` *boolean* — Campo delivery. - `groups[].options[].dineIn` *boolean* — Campo dineIn. - `groups[].options[].minQuantity` *number* — Campo minQuantity. - `groups[].options[].maxQuantity` *number* — Campo maxQuantity. - `groups[].options[].price` *number* — Campo price. - `groups[].options[].deliveryPrice` *number* — Campo deliveryPrice. - `groups[].options[].dineInPrice` *number* — Campo dineInPrice. - `groups[].options[].sortOrder` *number* — Campo sortOrder. - `groups[].options[].image` *object* — Campo image. - `groups[].options[].image.original` *string* — Campo original. - `groups[].options[].image.thumbnail60` *string* — Campo thumbnail60. - `groups[].options[].image.thumbnail120` *string* — Campo thumbnail120. - `groups[].options[].image.thumbnailWeb` *string* — Campo thumbnailWeb. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | | 404 | Product not found | ## Vocabulários usados neste endpoint ## Catálogo · unit Valores aceitos no campo unit dos produtos do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `UN` | Unidade | /v1/catalog/products | | `KG` | Quilograma | /v1/catalog/products | | `G` | Grama | /v1/catalog/products | | `L` | Litro | /v1/catalog/products | | `ML` | Mililitro | /v1/catalog/products | | `PCT` | Pacote | /v1/catalog/products | | `CX` | Caixa | /v1/catalog/products | | `DZ` | Dúzia | /v1/catalog/products | | `FD` | Fardo | /v1/catalog/products | | `BD` | Balde | /v1/catalog/products | | `SC` | Saco | /v1/catalog/products | | `PT` | Pote | /v1/catalog/products | | `CP` | Copo | /v1/catalog/products | | `PC` | Peça | /v1/catalog/products | | `FT` | Fátia | /v1/catalog/products | | `PQ` | Porção | /v1/catalog/products | | `GF` | Garrafa | /v1/catalog/products | | `LT` | Lata | /v1/catalog/products | | `BN` | Bandeja | /v1/catalog/products | ## Listar produtos --- title: "Listar produtos" description: "GET /v1/catalog/products — produtos da empresa BeeFood, com filtros e paginação." method: "GET" path: "/v1/catalog/products" url: "https://developer.beefood.com.br/docs/catalogo/produtos" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Listar produtos `GET /v1/catalog/products` - Produção: `https://api.beefood.app/v1/catalog/products` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/products` Lista os produtos da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de query - `page` *integer* — Página (padrão 1). Exemplo: `1`. - `limit` *integer* — Itens por página (padrão 20). Exemplo: `20`. - `sort` *string* — Ordem por productId: asc ou desc (padrão desc). Exemplo: `desc`. - *Valores:* `asc`, `desc` - `active` *boolean* — Filtra produtos ativos ou inativos em algum cardápio da empresa. Exemplo: `true`. - `sectorId` *integer[]* — Filtra por IDs de setor (array). Exemplo: `1997`. - `sectorName` *string* — Filtra pelo nome do setor (contém). Exemplo: `Pizzas`. - `name` *string* — Filtra pelo nome do produto (contém). Exemplo: `Pizza`. - `code` *string* — Filtra pelo código interno. Exemplo: `25`. - `barcode` *string* — Filtra pelo código de barras. Exemplo: `7891000315507`. - `featured` *boolean* — Filtra produtos em destaque. Exemplo: `true`. - `cashbackEnabled` *boolean* — Filtra produtos com cashback ativo em algum cardápio da empresa. Exemplo: `true`. - `combo` *boolean* — Filtra combos. Exemplo: `false`. - `label` *string[]* — Filtra pelos selos: new, recommended, bestSeller, limitedEdition, soldOut (array). Exemplo: `new`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/products?page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "productId": 2589035, "storeId": 38311, "type": "product", "name": "Água com Gás 500ml", "description": "Importante: imagem meramente ilustrativa. A marca do produto será enviada confirma disponibilidade do mesmo.", "unit": "UN", "price": 6.9, "featured": false, "featuredPrint": false, "serviceFeeActive": true, "scheduleOnly": false, "scaleActive": false, "sectorId": 213756, "sectorName": "Bebidas", "combo": false, "cost": { "base": 0, "supply": 0, "total": 0 }, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202411061918_7F7.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202411061918_7F7.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202411061918_7F7.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202411061918_7F7.webp" }, "menus": [ { "merchantId": 39202, "name": "Restaurante Exemplo", "active": false, "delivery": true, "dineIn": true, "totem": true, "sortOrder": 1, "cashbackEnabled": true }, { "merchantId": 50502, "name": "Restaurante Exemplo - Sushi", "active": true, "delivery": true, "dineIn": true, "totem": true, "sortOrder": 2, "cashbackEnabled": true } ] }, { "productId": 2589034, "storeId": 38311, "type": "product", "name": "Água sem Gás 500ml", "description": "Importante: imagem meramente ilustrativa. A marca do produto será enviada confirma disponibilidade do mesmo.", "unit": "UN", "price": 6, "featured": false, "featuredPrint": false, "serviceFeeActive": true, "scheduleOnly": false, "scaleActive": false, "sectorId": 213756, "sectorName": "Bebidas", "combo": false, "cost": { "base": 0, "supply": 0, "total": 0 }, "image": { "original": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202411061917_KAF.webp", "thumbnail60": "https://beetech-imagens.beefood-r2.work/38311/p/60/202411061917_KAF.jpg", "thumbnail120": "https://beetech-imagens.beefood-r2.work/38311/p/120/202411061917_KAF.jpg", "thumbnailWeb": "https://beetech-imagens.beefood-r2.work/38311/p/webp/202411061917_KAF.webp" }, "menus": [ { "merchantId": 39202, "name": "Restaurante Exemplo", "active": false, "delivery": true, "dineIn": true, "totem": true, "sortOrder": 2, "cashbackEnabled": true }, { "merchantId": 50502, "name": "Restaurante Exemplo - Sushi", "active": true, "delivery": true, "dineIn": true, "totem": true, "sortOrder": 3, "cashbackEnabled": true } ] } ], "page": 1, "limit": 2, "total": 166, "pages": 83 } ``` ## Campos da resposta - `items[].productId` *number* — Identificador do produto. - `items[].storeId` *number* — Identificador da empresa. - `items[].barcode` *string* — Código de barras. - `items[].code` *string* — Código interno. - `items[].type` *string* — Tipo derivado do PDV: "product". Somente leitura. - `items[].name` *string* — Nome do produto. - `items[].description` *string* — Descrição do produto. - `items[].internalNotes` *string* — Observações internas. - `items[].label` *string* — Selo do cardápio: new, recommended, bestSeller, limitedEdition ou soldOut. - `items[].unit` *string* — Unidade de medida (Default: UN): UN, KG, G, L, ML, PCT, CX, DZ, FD, BD, SC, PT, CP, PC, FT, PQ, GF, LT ou BN. - *Valores:* `UN`, `KG`, `G`, `L`, `ML`, `PCT`, `CX`, `DZ`, `FD`, `BD`, `SC`, `PT`, `CP`, `PC`, `FT`, `PQ`, `GF`, `LT`, `BN` - `items[].price` *number* — Preço padrão. - `items[].featured` *boolean* — Indica se está em destaque. - `items[].featuredPrint` *boolean* — Indica se tem destaque na impressão. - `items[].serviceFeeActive` *boolean* — Indica se a taxa de serviço está ativa. - `items[].scheduleOnly` *boolean* — Indica se a venda é apenas por agendamento. - `items[].scaleActive` *boolean* — Indica se a balança está ativa. - `items[].scaleShelfLifeDays` *number* — Validade em dias na balança. - `items[].sectorId` *number* — Identificador de um setor da mesma empresa. - `items[].sectorName` *string* — Nome do setor. Somente leitura. - `items[].combo` *boolean* — Indica se é combo. Somente leitura: vira true quando o produto tem ao menos um grupo vinculado e volta a false quando o último é desvinculado. - `items[].cost` *object* — Custos do produto. - `items[].cost.base` *number* — Custo base. - `items[].cost.supply` *number* — Custo da composição, calculado dos insumos. Somente leitura. - `items[].cost.total` *number* — Soma do custo base com o custo da composição. Somente leitura. - `items[].image` *object* — URLs da imagem do produto. Somente leitura. Para enviar ou remover, use Enviar imagem e Remover imagem com resourceType = products. - `items[].image.original` *string* — Campo original. - `items[].image.thumbnail60` *string* — Campo thumbnail60. - `items[].image.thumbnail120` *string* — Campo thumbnail120. - `items[].image.thumbnailWeb` *string* — Campo thumbnailWeb. - `items[].menus` *array* — Configurações do produto por cardápio. - `items[].menus[].merchantId` *number* — Cardápio da mesma empresa. - `items[].menus[].name` *string* — Nome do cardápio. Somente leitura. - `items[].menus[].active` *boolean* — Indica se está ativo nesto cardápio. - `items[].menus[].delivery` *boolean* — Indica se aparece no delivery. - `items[].menus[].deliveryPrice` *number* — Preço no delivery. - `items[].menus[].dineIn` *boolean* — Indica se aparece no presencial. - `items[].menus[].dineInPrice` *number* — Preço no presencial. - `items[].menus[].totem` *boolean* — Indica se aparece no totem. - `items[].menus[].promotionPrice` *number* — Preço promocional. - `items[].menus[].sortOrder` *number* — Posição de exibição. - `items[].menus[].featuredOrder` *number* — Posição entre destaques. - `items[].menus[].cashbackEnabled` *boolean* — Indica se o cashback está ativo nesto cardápio. - `items[].menus[].upsell` *array* — Produtos sugeridos nesto cardápio. - `items[].menus[].upsell[].productId` *number* — Produto sugerido no upsell. - `items[].menus[].upsell[].name` *string* — Nome do produto sugerido. Somente leitura. - `items[].restrictions` *object* — Restrições e características alimentares. - `items[].restrictions.vegetarian` *boolean* — Indica se é vegetariano. - `items[].restrictions.vegan` *boolean* — Indica se é vegano. - `items[].restrictions.organic` *boolean* — Indica se é orgânico. - `items[].restrictions.glutenFree` *boolean* — Indica se não contém glúten. - `items[].restrictions.sugarFree` *boolean* — Indica se não contém açúcar. - `items[].restrictions.lactoseFree` *boolean* — Indica se não contém lactose. - `items[].restrictions.natural` *boolean* — Indica se é natural. - `items[].restrictions.iced` *boolean* — Indica se é gelado. - `items[].restrictions.serves` *number* — Número de pessoas servidas. - `items[].groups` *array* — Grupos já existentes vinculados ao produto, ordenados por sortOrder. - `items[].groups[].groupId` *number* — Grupo existente da mesma empresa. - `items[].groups[].name` *string* — Nome do grupo. Somente leitura. - `items[].groups[].active` *boolean* — Indica se o grupo está ativo. - `items[].groups[].delivery` *boolean* — Indica se o grupo aparece no delivery. - `items[].groups[].dineIn` *boolean* — Indica se o grupo aparece no presencial. - `items[].groups[].required` *boolean* — Indica se a escolha é obrigatória. - `items[].groups[].sortOrder` *number* — Posição do grupo neste produto; menor valor aparece primeiro. Omitido quando o produto não tem ordem definida para o grupo. - `items[].groups[].priceFormation` *string* — Regra de preço: gift, highest, proportional ou sum. - `items[].groups[].minQuantity` *number* — Quantidade mínima de opções. - `items[].groups[].maxQuantity` *number* — Quantidade máxima de opções. - `items[].groups[].selectionMode` *string* — Modo de seleção do grupo. - `items[].groups[].options` *array* — Opções do grupo. Somente leitura nesta entrega. - `items[].groups[].options[].optionId` *number* — Campo optionId. - `items[].groups[].options[].productId` *number* — Campo productId. - `items[].groups[].options[].name` *string* — Campo name. - `items[].groups[].options[].type` *string* — Campo type. - `items[].groups[].options[].active` *boolean* — Campo active. - `items[].groups[].options[].delivery` *boolean* — Campo delivery. - `items[].groups[].options[].dineIn` *boolean* — Campo dineIn. - `items[].groups[].options[].minQuantity` *number* — Campo minQuantity. - `items[].groups[].options[].maxQuantity` *number* — Campo maxQuantity. - `items[].groups[].options[].price` *number* — Campo price. - `items[].groups[].options[].deliveryPrice` *number* — Campo deliveryPrice. - `items[].groups[].options[].dineInPrice` *number* — Campo dineInPrice. - `items[].groups[].options[].sortOrder` *number* — Campo sortOrder. - `items[].groups[].options[].image` *object* — Campo image. - `items[].groups[].options[].image.original` *string* — Campo original. - `items[].groups[].options[].image.thumbnail60` *string* — Campo thumbnail60. - `items[].groups[].options[].image.thumbnail120` *string* — Campo thumbnail120. - `items[].groups[].options[].image.thumbnailWeb` *string* — Campo thumbnailWeb. - `page` *number* — page da paginação. - `limit` *number* — limit da paginação. - `total` *number* — total da paginação. - `pages` *number* — pages da paginação. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | ## Vocabulários usados neste endpoint ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Catálogo · unit Valores aceitos no campo unit dos produtos do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `UN` | Unidade | /v1/catalog/products | | `KG` | Quilograma | /v1/catalog/products | | `G` | Grama | /v1/catalog/products | | `L` | Litro | /v1/catalog/products | | `ML` | Mililitro | /v1/catalog/products | | `PCT` | Pacote | /v1/catalog/products | | `CX` | Caixa | /v1/catalog/products | | `DZ` | Dúzia | /v1/catalog/products | | `FD` | Fardo | /v1/catalog/products | | `BD` | Balde | /v1/catalog/products | | `SC` | Saco | /v1/catalog/products | | `PT` | Pote | /v1/catalog/products | | `CP` | Copo | /v1/catalog/products | | `PC` | Peça | /v1/catalog/products | | `FT` | Fátia | /v1/catalog/products | | `PQ` | Porção | /v1/catalog/products | | `GF` | Garrafa | /v1/catalog/products | | `LT` | Lata | /v1/catalog/products | | `BN` | Bandeja | /v1/catalog/products | ## Remover imagem --- title: "Remover imagem" description: "DELETE /v1/catalog/{resourceType}/{resourceId}/image — remover a imagem de um setor, produto ou complemento no cardápio BeeFood." method: "DELETE" path: "/v1/catalog/{resourceType}/{resourceId}/image" url: "https://developer.beefood.com.br/docs/catalogo/remover-imagem" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Remover imagem `DELETE /v1/catalog/{resourceType}/{resourceId}/image` - Produção: `https://api.beefood.app/v1/catalog/{resourceType}/{resourceId}/image` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/{resourceType}/{resourceId}/image` Remove a imagem do recurso. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `resourceType` *enum* **obrigatório** — Tipo do recurso dono da imagem. Exemplo: `products`. - *Valores:* `sectors`, `products`, `complements` - `resourceId` *integer* **obrigatório** — ID do setor, produto ou complemento. Exemplo: `221145`. ## Exemplos de requisição ### cURL ```bash curl -X DELETE "https://api.beefood.app/v1/catalog/{resourceType}/{resourceId}/image" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 204 OK ```json ``` ## Erros | Status | Mensagem | | --- | --- | | 400 | 'resourceType' must be one of: sectors, products, complements | | 400 | 'resourceId' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 404 | Product ID {id} not found | | 404 | Complement ID {id} not found | | 404 | Sector ID {id} not found | | 429 | Too many requests | ## Vocabulários usados neste endpoint ## Catálogo · resourceType Tipo do recurso dono da imagem, usado na rota de envio e remoção de imagens do catálogo. | Valor | Significado | Uso | | --- | --- | --- | | `sectors` | Setor | /v1/catalog/{resourceType}/{resourceId}/image | | `products` | Produto | /v1/catalog/{resourceType}/{resourceId}/image | | `complements` | Complemento | /v1/catalog/{resourceType}/{resourceId}/image | ## Remover opção do grupo --- title: "Remover opção do grupo" description: "DELETE /v1/catalog/groups/{groupId}/options/{optionId} — remover uma opção de um grupo BeeFood." method: "DELETE" path: "/v1/catalog/groups/{groupId}/options/{optionId}" url: "https://developer.beefood.com.br/docs/catalogo/remover-opcao-grupo" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Remover opção do grupo `DELETE /v1/catalog/groups/{groupId}/options/{optionId}` - Produção: `https://api.beefood.app/v1/catalog/groups/{groupId}/options/{optionId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups/{groupId}/options/{optionId}` Remove uma opção de um grupo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `groupId` *integer* **obrigatório** — Identificador do grupo. Exemplo: `264006`. - `optionId` *integer* **obrigatório** — Identificador da opção. Exemplo: `5689346`. ## Exemplos de requisição ### cURL ```bash curl -X DELETE "https://api.beefood.app/v1/catalog/groups/{groupId}/options/{optionId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 204 OK ```json ``` ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 404 | Option not found | ## Detalhe do setor --- title: "Detalhe do setor" description: "GET /v1/catalog/sectors/{sectorId} — detalhe de um setor do cardápio BeeFood." method: "GET" path: "/v1/catalog/sectors/{sectorId}" url: "https://developer.beefood.com.br/docs/catalogo/setor" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Detalhe do setor `GET /v1/catalog/sectors/{sectorId}` - Produção: `https://api.beefood.app/v1/catalog/sectors/{sectorId}` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/sectors/{sectorId}` Retorna o detalhe de um setor. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `sectorId` *integer* **obrigatório** — Identificador do setor. Exemplo: `221145`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/sectors/{sectorId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "sectorId": 221145, "storeId": 107, "name": "Campanhas de Desconto", "publicName": "Campanhas", "delivery": true, "dineIn": true, "image": { "original": "https://beetech-imagens.s3-sa-east-1.amazonaws.com/107/001308e84.jpg", "thumbnail80": "https://beetech-imagens.beefood-r2.work/107/s/80/001308e84.jpg", "thumbnail180": "https://beetech-imagens.beefood-r2.work/107/s/180/001308e84.jpg" }, "menus": [ { "merchantId": 122, "name": "Restaurante Exemplo", "active": true, "sortOrder": 1 } ] } ``` ## Campos da resposta - `sectorId` *number* — Identificador do setor. - `storeId` *number* — Identificador da empresa. - `name` *string* — Nome do setor. - `publicName` *string* — Nome exibido no cardápio digital. - `delivery` *boolean* — Indica se o setor aparece no delivery. - `dineIn` *boolean* — Indica se o setor aparece no presencial. - `image` *object* — URLs da imagem do setor. Somente leitura. Para enviar ou remover, use Enviar imagem e Remover imagem com resourceType = sectors. - `image.original` *string* — Imagem original. - `image.thumbnail80` *string* — Miniatura de 80 px. - `image.thumbnail180` *string* — Miniatura de 180 px. - `menus` *array* — Cardápios do setor. - `menus[].merchantId` *number* — Identificador do cardápio. - `menus[].name` *string* — Nome do cardápio. - `menus[].active` *boolean* — Indica se o setor está ativo no cardápio. - `menus[].sortOrder` *number* — Posição do setor no cardápio. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | | 404 | Sector not found | ## Listar setores --- title: "Listar setores" description: "GET /v1/catalog/sectors — setores do cardápio da empresa BeeFood, com filtros e paginação." method: "GET" path: "/v1/catalog/sectors" url: "https://developer.beefood.com.br/docs/catalogo/setores" group: "Catálogo" scope: "catalog:read" lang: "pt" --- # Listar setores `GET /v1/catalog/sectors` - Produção: `https://api.beefood.app/v1/catalog/sectors` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/sectors` Lista os setores da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de query - `page` *integer* — Página (padrão 1). Exemplo: `1`. - `limit` *integer* — Itens por página, de 1 a 100 (padrão 20). Exemplo: `20`. - `sort` *string* — Ordem por sectorId: asc ou desc (padrão desc). Exemplo: `desc`. - *Valores:* `asc`, `desc` - `name` *string* — Filtra pelo nome do setor. Exemplo: `Sobremesas`. - `active` *boolean* — true: ativo em ao menos um cardápio; false: inativo em todos. Exemplo: `true`. - `delivery` *boolean* — Filtra setores ativos para delivery. Exemplo: `true`. - `dineIn` *boolean* — Filtra setores ativos para presencial. Exemplo: `true`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/catalog/sectors?page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "sectorId": 221145, "storeId": 107, "name": "Campanhas de Desconto", "publicName": "Campanhas", "delivery": true, "dineIn": true, "image": { "original": "https://beetech-imagens.s3-sa-east-1.amazonaws.com/107/001308e84.jpg", "thumbnail80": "https://beetech-imagens.beefood-r2.work/107/s/80/001308e84.jpg", "thumbnail180": "https://beetech-imagens.beefood-r2.work/107/s/180/001308e84.jpg" }, "menus": [ { "merchantId": 122, "name": "Restaurante Exemplo", "active": true, "sortOrder": 1 } ] } ], "page": 1, "limit": 20, "total": 1, "pages": 1 } ``` ## Campos da resposta - `items[].sectorId` *number* — Identificador do setor. - `items[].storeId` *number* — Identificador da empresa. - `items[].name` *string* — Nome do setor. - `items[].publicName` *string* — Nome exibido no cardápio digital. - `items[].delivery` *boolean* — Indica se o setor aparece no delivery. - `items[].dineIn` *boolean* — Indica se o setor aparece no presencial. - `items[].image` *object* — URLs da imagem do setor. Somente leitura. Para enviar ou remover, use Enviar imagem e Remover imagem com resourceType = sectors. - `items[].image.original` *string* — Imagem original. - `items[].image.thumbnail80` *string* — Miniatura de 80 px. - `items[].image.thumbnail180` *string* — Miniatura de 180 px. - `items[].menus` *array* — Cardápios do setor. - `items[].menus[].merchantId` *number* — Identificador do cardápio. - `items[].menus[].name` *string* — Nome do cardápio. - `items[].menus[].active` *boolean* — Indica se o setor está ativo no cardápio. - `items[].menus[].sortOrder` *number* — Posição do setor no cardápio. - `page` *number* — page da paginação. - `limit` *number* — limit da paginação. - `total` *number* — total da paginação. - `pages` *number* — pages da paginação. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:read scope | | 429 | Too many requests | ## Vocabulários usados neste endpoint ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Vincular opção ao grupo --- title: "Vincular opção ao grupo" description: "POST /v1/catalog/groups/{groupId}/options — vincular produto ou complemento como opção de um grupo BeeFood." method: "POST" path: "/v1/catalog/groups/{groupId}/options" url: "https://developer.beefood.com.br/docs/catalogo/vincular-opcao-grupo" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Vincular opção ao grupo `POST /v1/catalog/groups/{groupId}/options` - Produção: `https://api.beefood.app/v1/catalog/groups/{groupId}/options` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups/{groupId}/options` Vincula um produto ou complemento como opção de um grupo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `groupId` *integer* **obrigatório** — Identificador do grupo. Exemplo: `264006`. ## Parâmetros do body - `productId` *integer* **obrigatório** — Identificador do produto ou complemento. - `active` *boolean* — Indica se a opção está ativa (padrão true). - `delivery` *boolean* — Indica se a opção aparece no delivery (padrão true). - `dineIn` *boolean* — Indica se a opção aparece no presencial (padrão true). - `minQuantity` *integer* — Quantidade mínima, inteiro maior ou igual a 0. - `maxQuantity` *integer* — Quantidade máxima, inteiro maior ou igual a 1. - `price` *number* — Preço, número maior ou igual a 0 ou null. - `deliveryPrice` *number* — Preço no delivery, número maior ou igual a 0 ou null. - `dineInPrice` *number* — Preço no presencial, número maior ou igual a 0 ou null. - `sortOrder` *integer* — Posição da opção no grupo, inteiro maior ou igual a 0. ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/catalog/groups/{groupId}/options" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "productId": 2586945, "price": 5.5, "minQuantity": 1, "maxQuantity": 3, "sortOrder": 1 }' ``` ## Exemplos de resposta ### 201 OK ```json { "groupId": 264428, "optionId": 5689346, "productId": 2586945, "name": "Onion rings", "type": "product", "active": true, "delivery": true, "dineIn": true, "minQuantity": 1, "maxQuantity": 3, "price": 5.5, "sortOrder": 1, "image": { "original": "https://cdn.beefood.com.br/products/2586945.jpg", "thumbnail60": "https://cdn.beefood.com.br/products/2586945_60.jpg", "thumbnail120": "https://cdn.beefood.com.br/products/2586945_120.jpg", "thumbnailWeb": "https://cdn.beefood.com.br/products/2586945_web.jpg" } } ``` ## Campos da resposta - `groupId` *number* — Identificador do grupo. - `optionId` *number* — Identificador da opção. - `productId` *number* — Identificador do produto ou complemento. - `name` *string* — Nome da opção. - `type` *string* — Tipo da opção: product ou complement. - `active` *boolean* — Indica se a opção está ativa. - `delivery` *boolean* — Indica se a opção aparece no delivery. - `dineIn` *boolean* — Indica se a opção aparece no presencial. - `minQuantity` *number* — Quantidade mínima. - `maxQuantity` *number* — Quantidade máxima. - `price` *number* — Preço da opção. - `deliveryPrice` *number* — Preço no delivery. - `dineInPrice` *number* — Preço no presencial. - `sortOrder` *number* — Posição da opção no grupo. - `image` *object* — URLs da imagem do produto. - `image.original` *string* — Imagem original. - `image.thumbnail60` *string* — Miniatura de 60 px. - `image.thumbnail120` *string* — Miniatura de 120 px. - `image.thumbnailWeb` *string* — Miniatura para web. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Invalid option data | | 404 | Group not found | | 404 | Product not found | ## Vincular produtos ao grupo --- title: "Vincular produtos ao grupo" description: "POST /v1/catalog/groups/{groupId}/products — vincular produtos a um grupo de opções BeeFood." method: "POST" path: "/v1/catalog/groups/{groupId}/products" url: "https://developer.beefood.com.br/docs/catalogo/vincular-produtos-grupo" group: "Catálogo" scope: "catalog:write" lang: "pt" --- # Vincular produtos ao grupo `POST /v1/catalog/groups/{groupId}/products` - Produção: `https://api.beefood.app/v1/catalog/groups/{groupId}/products` - Sandbox: `https://api-sandbox.beefood.app/v1/catalog/groups/{groupId}/products` Vincula produtos a um grupo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `catalog:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `groupId` *integer* **obrigatório** — Identificador do grupo. Exemplo: `264006`. ## Parâmetros do body - `productIds` *integer[]* **obrigatório** — Identificadores dos produtos a vincular. ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/catalog/groups/{groupId}/products" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "productIds": [ 2586713, 2587101 ] }' ``` ## Exemplos de resposta ### 200 OK ```json { "groupId": 264006, "name": "Acompanhamentos", "active": true, "delivery": true, "dineIn": true, "required": true, "pizza": false, "sortOrder": 0, "priceFormation": "gift", "minQuantity": 1, "maxQuantity": 1, "products": [ { "productId": 2585290, "name": "Combo Supreme", "image": { "original": "https://cdn.beefood.com.br/products/2585290.jpg", "thumbnail60": "https://cdn.beefood.com.br/products/2585290_60.jpg", "thumbnail120": "https://cdn.beefood.com.br/products/2585290_120.jpg", "thumbnailWeb": "https://cdn.beefood.com.br/products/2585290_web.jpg" } } ] } ``` ## Campos da resposta - `groupId` *number* — Identificador do grupo. - `name` *string* — Nome do grupo. - `active` *boolean* — Indica se o grupo está ativo. - `delivery` *boolean* — Indica se o grupo aparece no delivery. - `dineIn` *boolean* — Indica se o grupo aparece no presencial. - `required` *boolean* — Indica se a escolha é obrigatória. - `pizza` *boolean* — Indica se o grupo é de pizza. - `sortOrder` *number* — Posição de exibição. - `priceFormation` *string* — Formação de preço: sum, gift, highest ou proportional. - `minQuantity` *number* — Quantidade mínima de opções. - `maxQuantity` *number* — Quantidade máxima de opções. - `products` *array* — Produtos vinculados ao grupo. - `products[].productId` *number* — Identificador do produto. - `products[].name` *string* — Nome do produto. - `products[].image` *object* — URLs da imagem do produto. - `products[].image.original` *string* — Imagem original. - `products[].image.thumbnail60` *string* — Miniatura de 60 px. - `products[].image.thumbnail120` *string* — Miniatura de 120 px. - `products[].image.thumbnailWeb` *string* — Miniatura para web. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the catalog:write scope | | 429 | Too many requests | | 400 | Invalid productIds | | 404 | Group not found | | 404 | Products not found: 2586713 | ## Detalhe do cliente --- title: "Detalhe do cliente" description: "GET /v1/customers/{customerId} — detalhe de um cliente do estabelecimento." method: "GET" path: "/v1/customers/{customerId}" url: "https://developer.beefood.com.br/docs/clientes/detalhe" group: "Clientes" scope: "customers:read" lang: "pt" --- # Detalhe do cliente `GET /v1/customers/{customerId}` - Produção: `https://api.beefood.app/v1/customers/{customerId}` - Sandbox: `https://api-sandbox.beefood.app/v1/customers/{customerId}` Retorna o detalhe de um cliente. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `customers:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `customerId` *integer* **obrigatório** — ID do cliente. Exemplo: `123456`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/customers/{customerId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "customerId": "123456", "customerName": "Mariana Souza", "tradeName": "Mariana Souza", "personType": "individual", "documentNumber": "12345678900", "email": "contato@exemplo.com", "phone": { "number": "11999990000", "extension": "+55" }, "observations": "teste", "active": true, "balance": { "cashback": [ { "merchantId": 39202, "merchantName": "Restaurante Exemplo", "cashback": 0.8, "cashbackActive": true } ], "rewardPoints": [ { "merchantId": 39202, "merchantName": "Restaurante Exemplo", "rewardPoints": 120, "rewardPointsActive": true } ], "storeCredit": -0.5 }, "addresses": [ { "addressId": 11707136, "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "Sorocaba", "state": "SP", "postalCode": "18040370", "latitude": -23.5015, "longitude": -47.4526 }, { "addressId": 11723846, "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "Sorocaba", "state": "SP", "latitude": -23.5015, "longitude": -47.4526 } ] } ``` ## Campos da resposta - `customerId` *string* — ID do cliente. - `customerName` *string* — Nome completo / razão social. - `documentNumber` *string* — CPF ou CNPJ. - `phone` *object* — Telefone. - `birthDate` *string* — Data de nascimento. - `tradeName` *string* — Nome fantasia. - `personType` *string* — Pessoa física ou jurídica. - *Valores:* `individual`, `company` - `email` *string* — E-mail. - `observations` *string* — Observações internas sobre o cliente. - `active` *boolean* — Indica se o cliente está ativo. - `indicators` *object* — Indicadores de consumo do cliente. - `balance.cashback` *array* — Saldos de cashback por cardápio. - `balance.rewardPoints` *array* — Saldos de pontos por cardápio. - `balance.storeCredit` *number* — Crédito de restaurante disponível. - `addresses[]` *array* — Endereços cadastrados do cliente. - `phone.number` *string* — Número do telefone. Exemplo: `"11999990000"`. - `phone.extension` *string* — DDI (ex.: +55). Exemplo: `"+55"`. - `indicators.ordersCount` *number* — Quantidade de pedidos. Exemplo: `12`. - `indicators.averageTicket` *number* — Ticket médio. Exemplo: `48.5`. - `indicators.averageRating` *number* — Nota média. Exemplo: `4.7`. - `indicators.firstOrderDate` *string* — Data do primeiro pedido. Exemplo: `"2024-01-15"`. - `indicators.origin` *string* — Origem do cliente. Exemplo: `"DIGITAL_MENU"`. - *Valores:* `DIGITAL_MENU`, `DIGITAL_MENU_DELIVERY`, `DIGITAL_MENU_LOCAL`, `DELIVERY`, `TABLE`, `OTHER` - `balance` *object* — Saldos do cliente: cashback e pontos por cardápio e crédito de restaurante. - `balance.cashback.merchantId` *number* — ID do cardápio. Exemplo: `39202`. - `balance.cashback.merchantName` *string* — Nome do cardápio. Exemplo: `"Restaurante Exemplo"`. - `balance.cashback.cashback` *number* — Saldo de cashback. Exemplo: `0.8`. - `balance.cashback.cashbackActive` *boolean* — Indica se o cashback está ativo. Exemplo: `true`. - `balance.rewardPoints.merchantId` *number* — ID do cardápio. Exemplo: `39202`. - `balance.rewardPoints.merchantName` *string* — Nome do cardápio. Exemplo: `"Restaurante Exemplo"`. - `balance.rewardPoints.rewardPoints` *number* — Saldo de pontos. Exemplo: `120`. - `balance.rewardPoints.rewardPointsActive` *boolean* — Indica se o programa de pontos está ativo. Exemplo: `true`. - `addresses[].addressId` *string* — ID do endereço. Exemplo: `445566`. - `addresses[].street` *string* — Rua. - `addresses[].number` *string* — Número. - `addresses[].complement` *string* — Complemento. - `addresses[].neighborhood` *string* — Bairro. - `addresses[].city` *string* — Cidade. - `addresses[].state` *string* — UF. - `addresses[].postalCode` *string* — CEP, só dígitos. - `addresses[].latitude` *number* — Latitude. - `addresses[].longitude` *number* — Longitude. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'id' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the customers:read scope | | 404 | Customer ID 123 not found | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Clientes · personType | Valor | Significado | Uso | | --- | --- | --- | | `individual` | Pessoa física | Lista e detalhe de clientes | | `company` | Pessoa jurídica | Lista e detalhe de clientes | ## Clientes · origin | Valor | Significado | Uso | | --- | --- | --- | | `DIGITAL_MENU` | Cardápio digital | Clientes | | `DIGITAL_MENU_DELIVERY` | Cardápio digital delivery | Clientes | | `DIGITAL_MENU_LOCAL` | Cardápio digital presencial | Clientes | | `DELIVERY` | Delivery | Clientes | | `TABLE` | Mesa / comanda | Clientes | | `OTHER` | Outro | Clientes | ## Listar clientes --- title: "Listar clientes" description: "GET /v1/customers — listagem paginada de clientes do estabelecimento." method: "GET" path: "/v1/customers" url: "https://developer.beefood.com.br/docs/clientes/listar" group: "Clientes" scope: "customers:read" lang: "pt" --- # Listar clientes `GET /v1/customers` - Produção: `https://api.beefood.app/v1/customers` - Sandbox: `https://api-sandbox.beefood.app/v1/customers` Retorna os clientes do estabelecimento. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `customers:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de query - `page` *integer* — Página atual da lista. Exemplo: `1`. - `limit` *integer* — Quantidade de itens por página. Exemplo: `20`. - `sort` *string* — Ordem da lista: mais recentes (desc) ou mais antigos (asc). Exemplo: `"desc"`. - *Valores:* `asc`, `desc` - `active` *boolean* — Filtra clientes ativos ou inativos. Exemplo: `true`. - `customerName` *string* — Filtra pelos clientes cujo nome contém o texto informado. Exemplo: `"Cliente Exemplo"`. - `email` *string* — Filtra pelo e-mail do cliente. Exemplo: `"cliente@exemplo.com"`. - `documentNumber` *string* — Filtra pelo CPF ou CNPJ exato do cliente (somente dígitos). Exemplo: `"12345678900"`. - `phone` *string* — Filtra pelos clientes cujo telefone contém os dígitos informados. Exemplo: `"11999990000"`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/customers?page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "customerId": "13188863", "customerName": "Simone Costa" }, { "customerId": "13188849", "customerName": "Rafael Lima" } ], "page": 1, "limit": 2, "total": 471, "pages": 236 } ``` ## Campos da resposta - `items[].customerId` *string* — ID do cliente. - `items[].customerName` *string* — Nome do cliente. - `items[].documentNumber` *string* — CPF ou CNPJ. - `items[].email` *string* — E-mail. - `items[].phone` *object* — Telefone. - `items[].birthDate` *string* — Data de nascimento. - `items[].averageTicket` *number* — Ticket médio do cliente. - `items[].averageRating` *number* — Nota média nas avaliações. - `items[].firstOrderDate` *string* — Data do primeiro pedido. - `items[].origin` *string* — Origem do cadastro/cliente. - *Valores:* `DIGITAL_MENU`, `DIGITAL_MENU_DELIVERY`, `DIGITAL_MENU_LOCAL`, `DELIVERY`, `TABLE`, `OTHER` - `page` *number* — Página atual da lista. - `limit` *number* — Quantidade de itens por página. - `total` *number* — Total de registros encontrados. - `pages` *number* — Total de páginas. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'page' must be an integer >= 1 | | 400 | 'limit' must be an integer between 1 and 100 | | 400 | 'sort' must be asc or desc | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the customers:read scope | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Clientes · origin | Valor | Significado | Uso | | --- | --- | --- | | `DIGITAL_MENU` | Cardápio digital | Clientes | | `DIGITAL_MENU_DELIVERY` | Cardápio digital delivery | Clientes | | `DIGITAL_MENU_LOCAL` | Cardápio digital presencial | Clientes | | `DELIVERY` | Delivery | Clientes | | `TABLE` | Mesa / comanda | Clientes | | `OTHER` | Outro | Clientes | ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Erros e paginação — BeeFood API --- title: "Erros e paginação — BeeFood API" description: "Formato de erro message/status, códigos HTTP usados pela API BeeFood e o contrato de paginação das listas." url: "https://developer.beefood.com.br/docs/erros" group: "Referência" lang: "pt" --- # Erros e paginação Toda falha responde com o mesmo corpo: { "message": "...", "status": 400 }. Respostas 204 não têm corpo. ## Status HTTP | Status | Uso típico | | --- | --- | | 400 | Validação / body inválido / JSON malformado | | 401 | Token ausente, inválido ou expirado | | 403 | Token válido, mas sem permissão (scope) para o recurso | | 404 | Recurso não encontrado | | 413 | Body acima do limite (request entity too large): 1 MB, ou 50 MB no envio de imagem | | 415 | Charset/encoding do body não suportado | | 429 | Limite de requisições excedido (header Retry-After, em segundos) | | 500 | Erro interno / banco; erro inesperado responde "Internal server error" | ## Paginação | Query | Regra | Default | | --- | --- | --- | | page | inteiro maior ou igual a 1 | 1 | | limit | inteiro 1–100 | 20 | | sort | asc ou desc | desc | `pages = ceil(total / limit)` — `0` quando `total = 0`. ## Scopes - `orders:read`: /v1/orders - `customers:read`: /v1/customers - `store:read`: /v1/store/* - `coupons:read` / `coupons:write`: /v1/store/coupons - `reviews:read`: /v1/store/reviews - `catalog:read` / `catalog:write`: /v1/catalog/* ## Health check — BeeFood API --- title: "Health check — BeeFood API" description: "GET /health: verificação de disponibilidade da API BeeFood e do ambiente." url: "https://developer.beefood.com.br/docs/health" group: "Começando" lang: "pt" --- # Health check `GET /health` - Produção: `https://api.beefood.app/health` - Sandbox: `https://api-sandbox.beefood.app/health` Verifica a disponibilidade da API. ## Parâmetros da resposta - `status` *string* — Sempre "ok" quando a API está disponível. Exemplo: `"ok"`. - `sandbox` *boolean* — Indica o ambiente atendido pela base URL. Exemplo: `true`. ## Introdução — BeeFood API --- title: "Introdução — BeeFood API" description: "Base URL, headers e fluxo sugerido de integração com a API BeeFood /v1." url: "https://developer.beefood.com.br/docs" group: "Começando" lang: "pt" --- # Introdução Todas as rotas de negócio ficam sob o prefixo /v1. Use a base URL de sandbox para testes e a de produção nas integrações reais. ## Base URL - Produção: `https://api.beefood.app` - Sandbox: `https://api-sandbox.beefood.app` ## Headers - `Content-Type: application/json` — em requisições com body JSON. - `Authorization: Bearer ` — rotas autenticadas da API. ## Fluxo sugerido 1. O restaurante cria a credential → clientId + clientSecret (exibidos uma vez) 2. POST /v1/oauth/token → accessToken + refreshToken 3. Chamadas /v1/… → Authorization: Bearer 4. POST /v1/oauth/token → renovação com refreshToken 5. POST /v1/oauth/revoke → logout da integração ## Limites de requisição — BeeFood API --- title: "Limites de requisição — BeeFood API" description: "Limites de requisição e proteção contra uso indevido da API BeeFood: consultas repetidas, bloqueios progressivos e Retry-After." url: "https://developer.beefood.com.br/docs/limites" group: "Referência" lang: "pt" --- # Limites de requisição Os limites são aplicados por estabelecimento (empresaId da credencial) e por ambiente. Sandbox e produção têm os mesmos limites. Ao exceder, a API responde 429 Too Many Requests com o header Retry-After, em segundos. ## Grupos e limites | Grupo | Limite | Rotas | | --- | --- | --- | | Pesado | 15 / 60s | GET /v1/store/merchants, GET /v1/store/merchants/{merchantId}, GET /v1/orders | | Relatórios | 15 / 60s | GET /v1/orders/summary, /grouped, /sectors, /products e /options (cota única entre as cinco rotas) | | Catálogo | 100 / 180s | Cupons, avaliações, formas de pagamento e rotas de delivery e presencial em /v1/store | | Polling | 15 / 300s | GET /v1/orders/polling | | Demais | 300 / 180s | Clientes, catálogo (/v1/catalog), GET /v1/orders/{orderId}, criação e edição de pedidos e demais rotas | As rotas de OAuth (/v1/oauth/token e /v1/oauth/revoke) não entram nos limites. Prefira webhooks a consultas repetidas para reduzir o número de requisições. No polling, o intervalo recomendado é de 30 segundos. Ao passar da cota, o 429 traz um Retry-After de poucos segundos, sem penalidade: respeite o header e siga. ### Como tratar o 429 - Leia o Retry-After (em segundos) e espere esse tempo antes de tentar de novo. - Não repita durante o bloqueio: no uso indevido, insistir aumenta a penalidade. - Use a message para distinguir os casos: a de uso indevido cita "the same query was repeated"; a de cota é apenas "Too Many Requests". ## Uso indevido Além dos limites por janela de tempo, as consultas de pedidos, relatórios e detalhe do pedido têm uma proteção contra a repetição automática da mesma consulta. Ela protege o sistema do restaurante de consultas que não produzem informação nova. ### Rotas afetadas | Rota | Consulta | | --- | --- | | `GET /v1/orders` | Histórico de pedidos | | `GET /v1/orders/summary` | Resumo de vendas | | `GET /v1/orders/summary/grouped` | Resumo por dimensão | | `GET /v1/orders/summary/sectors` | Ranking por setor | | `GET /v1/orders/summary/products` | Ranking por produto | | `GET /v1/orders/summary/options` | Ranking por opção | | `GET /v1/orders/{orderId}` | Detalhe do pedido (contado por pedido) | Não entram: `GET /v1/orders/polling` e as rotas de criação e edição de pedidos. ### A regra > A mesma consulta — mesma rota, mesmos filtros — não pode se repetir **20 vezes ou mais por hora**. O período observado depende da rota: | Rotas | Período observado | | --- | --- | | `GET /v1/orders/{orderId}` | Na última hora | | `GET /v1/orders` e os cinco `GET /v1/orders/summary*` | Em cada uma de duas horas seguidas | No detalhe, reler o mesmo pedido nesse ritmo interrompe o laço já na primeira hora. No histórico e nos relatórios, um pico isolado não bloqueia: o padrão precisa persistir por duas horas seguidas. "Mesma consulta" é a URL completa com a querystring. Trocar o período, o `groupBy` ou a página faz uma consulta diferente. No detalhe do pedido, a contagem é por pedido: percorrer pedidos diferentes não conta. Nenhum pedido muda a ponto de justificar 20 leituras na mesma hora; para saber de mudanças, use webhook ou polling. A repetição nesse ritmo é uso indevido, mesmo respeitando os limites por janela. ### Onde fica a linha | Periodicidade da sua rotina | Chamadas por hora | Resultado | | --- | --- | --- | | A cada 1 hora | 1 | Liberado | | A cada 10 minutos | 6 | Liberado | | A cada 5 minutos | 12 | Liberado | | A cada 4 minutos | 15 | Liberado | | A cada 3 minutos | 20 | **Bloqueado** | | A cada 1 minuto | 60 | **Bloqueado** | Na prática, use intervalos de **5 minutos ou mais**: nesse ritmo nenhuma das janelas é atingida. ### Proteção contra repetição da mesma consulta | Rota | Limite da mesma consulta | Período | | --- | --- | --- | | `GET /v1/orders` e os cinco `GET /v1/orders/summary*` | 20 por hora | Duas horas seguidas | | `GET /v1/orders/{orderId}` | 20 por hora, para o mesmo pedido | Uma hora | | `GET /v1/orders/polling` | Fora desta regra (cota própria, sem penalidade) | — | ### A resposta Todas as rotas da lista ficam bloqueadas para o estabelecimento, não apenas a consulta que disparou. O bloqueio vale para o `empresaId` da credencial no ambiente em que ocorreu (produção ou sandbox). ```http HTTP/1.1 429 Too Many Requests Retry-After: 900 ``` ```json { "message": "Too Many Requests: the same query was repeated too many times; reduce the polling frequency. See https://docs.beefood.app/docs/limites", "status": 429 } ``` O status é o mesmo dos limites por janela. A diferença está na `message`, que cita `the same query was repeated`, e no tempo maior em `Retry-After`. ### A penalidade aumenta O primeiro bloqueio dura **15 minutos** e dobra a cada nova detecção, até **24 horas**. | Detecção | Duração | | --- | --- | | 1ª | 15 minutos | | 2ª | 30 minutos | | 3ª | 1 hora | | 4ª | 2 horas | | 5ª | 4 horas | | 6ª | 8 horas | | 7ª | 16 horas | | 8ª em diante | 24 horas | As chamadas que recebem `429` continuam contando. O degrau só sobe com uma chamada nova feita depois do bloqueio em vigor. Parando o laço, o bloqueio atual é o último e expira sozinho, sem chamado. Após 24 horas sem reincidência, a contagem volta ao primeiro degrau. ### Como ajustar a integração - **Pedidos em tempo real:** use [webhooks](/docs/webhooks). Se não puder recebê-los, use `GET /v1/orders/polling` a cada 30 segundos, que está fora desta regra. - **Acompanhar um pedido:** não reconsulte `GET /v1/orders/{orderId}` em laço. Use webhooks ou o polling. - **Relatórios:** consulte em intervalos de 5 minutos ou mais e guarde o resultado em cache. Para dias fechados, consulte uma vez e reaproveite. - **Pedido específico:** use `GET /v1/orders/{orderId}` em vez de listar e filtrar. - **Resposta `429`:** respeite o `Retry-After`. Repetir a chamada durante o bloqueio aumenta a penalidade. ### Perguntas frequentes **Fui bloqueado mas minha rotina é legítima.** Verifique o intervalo: a linha fica entre 3 e 4 minutos. Use 5 minutos ou mais; se seu caso não se encaixa, fale com o suporte. **O bloqueio afeta meus outros aplicativos?** Sim. A penalidade é do estabelecimento, não da credencial; todas as integrações do restaurante no mesmo ambiente são afetadas. **Paginar conta como repetição?** Não, cada página é uma consulta diferente. Reiniciar a varredura a cada poucos minutos, porém, repete a página 1 e pode disparar a regra. **Preciso pedir desbloqueio?** Não. Corrigida a frequência, a penalidade expira sozinha. ## Área de entrega --- title: "Área de entrega" description: "GET /v1/store/merchants/:merchantId/delivery/delivery-area — área de entrega, zonas e origem do merchant." method: "GET" path: "/v1/store/merchants/{merchantId}/delivery/delivery-area" url: "https://developer.beefood.com.br/docs/loja/area-entrega" group: "Restaurante" scope: "store:read" lang: "pt" --- # Área de entrega `GET /v1/store/merchants/{merchantId}/delivery/delivery-area` - Produção: `https://api.beefood.app/v1/store/merchants/{merchantId}/delivery/delivery-area` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants/{merchantId}/delivery/delivery-area` Retorna a área de entrega do cardápio. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de path - `merchantId` *integer* **obrigatório** — ID do cardápio. Exemplo: `39202`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants/{merchantId}/delivery/delivery-area" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "storeId": 38311, "merchantId": 39202, "origin": { "address": { "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "zipCode": "18040370", "city": "Sorocaba", "state": "São Paulo" }, "latitude": -23.5015, "longitude": -47.4526, "timezoneId": 1, "timezoneName": "Brasília (UTC-3)" }, "modes": { "neighborhoodZipCode": false, "fixedZipCode": false, "distanceKm": false, "map": true }, "mapZones": [ { "zoneId": 110025, "title": "Campolim", "fee": 7.9, "freeDeliveryMinimum": 50, "additionalDeliveryTimeMinutes": 10, "courierFee": 4, "type": "Livre", "color": "#3b82f6", "polygon": "POLYGON ((-23.512 -47.472, -23.512 -47.462, -23.52 -47.462, -23.52 -47.472, -23.512 -47.472))", "active": true, "noDelivery": false }, { "zoneId": 110024, "title": "Até 2 km", "fee": 5.99, "freeDeliveryMinimum": 40, "additionalDeliveryTimeMinutes": 5, "courierFee": 3, "radiusKm": 2, "type": "Raio", "color": "#22c55e", "polygon": "POINT (-23.5061438 -47.465792699999987)", "active": true, "noDelivery": false }, { "zoneId": 110026, "title": "Zona industrial", "radiusKm": 0.8, "type": "Raio", "color": "#000000", "polygon": "POINT (-23.52 -47.49)", "active": true, "noDelivery": true } ], "distanceKmZones": [ { "zoneId": 9176, "distanceKm": 3, "fee": 5.99, "freeDeliveryMinimum": 40, "additionalDeliveryTimeMinutes": 5, "courierFee": 3, "active": true }, { "zoneId": 9177, "distanceKm": 6, "fee": 8.99, "freeDeliveryMinimum": 60, "additionalDeliveryTimeMinutes": 10, "courierFee": 5, "active": true }, { "zoneId": 9178, "distanceKm": 10, "fee": 14.99, "freeDeliveryMinimum": 0, "additionalDeliveryTimeMinutes": 20, "courierFee": 8, "active": true } ], "neighborhoodZipCodeZones": [ { "zoneId": 89448, "active": true, "fee": 6.5, "freeDeliveryMinimum": 45, "additionalDeliveryTimeMinutes": 8, "courierFee": 3.5, "matchNeighborhood": true, "matchZipCode": false, "matchZipCodeRange": false, "options": [ { "optionId": 230154, "neighborhood": "Centro", "city": "Sorocaba" } ] } ], "fixedZipCode": { "zipCode": "18040370", "fee": 7 } } ``` ## Campos da resposta - `storeId` *number* — ID do restaurante. - `merchantId` *number* — ID do cardápio. - `origin.address.street` *string* — Logradouro de origem. - `origin.address.number` *string* — Número. - `origin.address.neighborhood` *string* — Bairro. - `origin.address.zipCode` *string* — CEP, só dígitos. - `origin.address.complement` *string* — Complemento. - `origin.address.city` *string* — Cidade. - `origin.address.state` *string* — Estado. - `origin.latitude` *number* — Latitude da origem. - `origin.longitude` *number* — Longitude da origem. - `origin.timezoneId` *number* — ID do fuso horário. - `origin.timezoneName` *string* — Nome do fuso horário. - `modes.neighborhoodZipCode` *boolean* — Por bairro/CEP. - `modes.fixedZipCode` *boolean* — Por CEP fixo. - `modes.distanceKm` *boolean* — Por distância em km. - `modes.map` *boolean* — Por zonas no mapa. - `mapZones[].zoneId` *number* — Identificador da zona. - `mapZones[].title` *string* — Nome da zona. - `mapZones[].fee` *number* — Taxa de entrega da zona. - `mapZones[].freeDeliveryMinimum` *number* — Valor mínimo para entrega grátis. - `mapZones[].additionalDeliveryTimeMinutes` *number* — Tempo adicional de entrega em minutos. - `mapZones[].courierFee` *number* — Valor pago ao entregador. - `mapZones[].radiusKm` *number* — Raio em km, quando aplicável. - `mapZones[].type` *string* — Tipo da zona no mapa. - `mapZones[].color` *string* — Cor da zona no mapa. - `mapZones[].polygon` *string* — Polígono da zona. - `mapZones[].active` *boolean* — Zona ativa. - `mapZones[].noDelivery` *boolean* — Zona sem entrega. - `distanceKmZones[]` *array* — Faixas por quilometragem. - `neighborhoodZipCodeZones[]` *array* — Zonas por bairro/CEP. - `fixedZipCode` *object* — Regra de CEP fixo (quando houver). ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 404 | Merchant ID 99 not found | ## Atualizar cupom --- title: "Atualizar cupom" description: "PATCH /v1/store/coupons/:couponId — atualização parcial de cupons." method: "PATCH" path: "/v1/store/coupons/{couponId}" url: "https://developer.beefood.com.br/docs/loja/atualizar-cupom" group: "Restaurante" scope: "coupons:write" lang: "pt" --- # Atualizar cupom `PATCH /v1/store/coupons/{couponId}` - Produção: `https://api.beefood.app/v1/store/coupons/{couponId}` - Sandbox: `https://api-sandbox.beefood.app/v1/store/coupons/{couponId}` Atualiza parcialmente um cupom da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `coupons:write`. Limite: 100 requisições a cada 3 minutos. ## Observações - Os campos não enviados terão seu valor preservado; apenas os campos enviados (ou enviados como null) serão alterados. ## Parâmetros de path - `couponId` *integer* **obrigatório** — ID do cupom a atualizar. Exemplo: `15283`. ## Parâmetros do body - `active` *boolean* — Indica se o cupom está ativo. - `code` *string* — Código para a utilização do cupom. - `benefit` *object* — Benefício concedido pelo cupom; na atualização, faz merge campo a campo (envie só o que mudar). - `benefit.appliesTo` *string* — Sobre o que o benefício incide (pedido, frete ou produto). - *Valores:* `discount`, `deliveryFee`, `product` - `benefit.type` *string* — Percentual ou valor fixo. - *Valores:* `percentage`, `fixed` - `benefit.amount` *number* — Valor do benefício. - `validity` *object* — Período e dias em que o cupom vale; na atualização, faz merge campo a campo. - `validity.startsAt` *string (ISO 8601) | null* — Início da validade; null remove a data de início. - `validity.endsAt` *string (ISO 8601) | null* — Fim da validade; null remove a data de término (cupom sem data fim). - `validity.weekdays` *object* — Dias da semana em que o cupom vale. - `channels` *object* — Canais em que o cupom vale. - *Valores:* `delivery`, `pdv`, `tables`, `totem` - `rules` *object* — Regras de uso do cupom. - `rules.minimumOrderAmount` *number | null* — Valor mínimo do pedido; null remove o pedido mínimo. - `rules.limitOnePerCustomer` *boolean* — Limita a 1 uso por cliente. - `rules.hasQuantityLimit` *boolean* — Indica se há limite total de usos. - `rules.maxQuantity` *number | null* — Quantidade máxima de usos; null remove o teto (use junto com hasQuantityLimit: false). - `rules.firstPurchaseOnly` *boolean* — Só na primeira compra. - `rules.showOnMenu` *boolean* — Exibe o cupom no cardápio. - `rules.pickupOrLocalOnly` *boolean* — Só para retirada ou presencial. - `rules.excludePromotionalProducts` *boolean* — Não aplica em produtos em promoção. - `rules.requirePhoneSms` *boolean* — Exige validação de telefone por SMS. - `advanced` *object* — Restrições avançadas do cupom. - `advanced.paymentMethods` *array* — Formas de pagamento que liberam o cupom; na atualização, a lista enviada substitui a atual (vazia = sem restrição). - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.paymentMethods[].paymentMethodId` *number* — ID da forma de pagamento. - `advanced.paymentMethods[].name` *string* — Nome da forma. - `advanced.paymentMethods[].type` *string* — Tipo da forma. - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.application` *object* — Como o cupom se aplica a setores/produtos; na atualização, sectors e products substituem as listas atuais. - `advanced.application.mode` *string* — Modo de aplicação: order, unlockByItems ou itemsOnly. - *Valores:* `order`, `unlockByItems`, `itemsOnly` - `advanced.application.sectors` *array* — Setores relacionados; a lista enviada substitui a atual. - `advanced.application.sectors[].sectorId` *number* — ID do setor (obrigatório no envio). - `advanced.application.products` *array* — Produtos relacionados; a lista enviada substitui a atual. - `advanced.application.products[].productId` *number* — ID do produto (obrigatório no envio). ## Exemplos de body ### Atualizações pontuais · Desativar o cupom ```json { "active": false } ``` ### Atualizações pontuais · Mudar o valor do benefício ```json { "benefit": { "amount": 20 } } ``` ### Atualizações pontuais · Remover a data de término ```json { "validity": { "endsAt": null } } ``` ### Atualizações pontuais · Remover o pedido mínimo ```json { "rules": { "minimumOrderAmount": null } } ``` ### Atualizações pontuais · Remover o limite de quantidade ```json { "rules": { "hasQuantityLimit": false, "maxQuantity": null } } ``` ### Atualizações pontuais · Alterar só a quinta-feira ```json { "validity": { "weekdays": { "thursday": true } } } ``` ### Atualizações pontuais · Aceitar todas as formas de pagamento ```json { "advanced": { "paymentMethods": [] } } ``` ### Formas de aplicação · order · Ao pedido inteiro (padrão) ```json { "advanced": { "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Formas de aplicação · unlockByItems · Só quando o carrinho tiver certos itens ```json { "advanced": { "application": { "mode": "unlockByItems", "sectors": [ { "sectorId": 45 } ], "products": [ { "productId": 1234 }, { "productId": 5678 } ] } } } ``` ### Formas de aplicação · itemsOnly · Só sobre certos itens do pedido ```json { "benefit": { "appliesTo": "discount" }, "advanced": { "application": { "mode": "itemsOnly", "sectors": [], "products": [ { "productId": 1234 } ] } } } ``` ## Exemplos de requisição ### cURL ```bash curl -X PATCH "https://api.beefood.app/v1/store/coupons/{couponId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "benefit": { "amount": 20 } }' ``` ## Exemplos de resposta ### 200 OK ```json { "couponId": 15237, "storeId": 38311, "merchantId": 39202, "code": "PIX15%", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 15 }, "validity": { "startsAt": "2026-08-22T23:34:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": true }, "advanced": { "paymentMethods": [ { "paymentMethodId": 486229, "name": "PIX Bee", "type": "PIX_BEEFOOD" }, { "paymentMethodId": 381233, "name": "PIX Online", "type": "PIX_BEEFOOD" } ], "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Formas de aplicação · order · Ao pedido inteiro (padrão) ```json { "couponId": 15233, "storeId": 38311, "merchantId": 39202, "code": "10%SETIVERBOX", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 10 }, "validity": { "startsAt": "2026-08-23T13:14:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "unlockByItems", "sectors": [], "products": [ { "productId": 2515304, "name": "(Box) Batata frita" } ] } } } ``` ### Formas de aplicação · unlockByItems · Só quando o carrinho tiver certos itens ```json { "couponId": 15231, "storeId": 38311, "merchantId": 39202, "code": "10%BEBIDA", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 10 }, "validity": { "startsAt": "2026-08-22T18:11:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "itemsOnly", "sectors": [], "products": [] } } } ``` ## Campos da resposta - `couponId` *number* — ID do cupom a atualizar. - `storeId` *number* — ID do restaurante. - `merchantId` *number* — Cardápio em que o cupom vale. - `code` *string* — Código para a utilização do cupom. - `active` *boolean* — Indica se o cupom está ativo. - `usageCount` *number* — Quantas vezes já foi usado. - `benefit.appliesTo` *string* — Sobre o que o benefício incide (pedido, frete ou produto). - *Valores:* `discount`, `deliveryFee`, `product` - `benefit.type` *string* — Percentual ou valor fixo. - *Valores:* `percentage`, `fixed` - `benefit.amount` *number* — Valor do benefício. - `validity.startsAt` *string (ISO 8601)* — Início da validade; null remove a data de início. - `validity.endsAt` *string (ISO 8601)* — Fim da validade; null remove a data de término (cupom sem data fim). - `validity.weekdays` *object* — Dias da semana em que o cupom vale. - `channels` *object* — Canais em que o cupom vale. - *Valores:* `delivery`, `pdv`, `tables`, `totem` - `rules` *object* — Regras de uso do cupom. - `advanced.paymentMethods` *array* — Formas de pagamento que liberam o cupom; na atualização, a lista enviada substitui a atual (vazia = sem restrição). - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.paymentMethods[].paymentMethodId` *number* — ID da forma de pagamento. - `advanced.paymentMethods[].name` *string* — Nome da forma de pagamento. - `advanced.paymentMethods[].type` *string* — Tipo da forma de pagamento. - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.application` *object* — Como o cupom se aplica a setores/produtos; na atualização, sectors e products substituem as listas atuais. - `advanced.application.mode` *string* — Modo de aplicação. - *Valores:* `order`, `unlockByItems`, `itemsOnly` - `advanced.application.sectors` *array* — Setores relacionados ao cupom. - `advanced.application.sectors[].sectorId` *number* — ID do setor. - `advanced.application.sectors[].name` *string* — Nome do setor. - `advanced.application.products` *array* — Produtos relacionados ao cupom. - `advanced.application.products[].productId` *number* — ID do produto. - `advanced.application.products[].name` *string* — Nome do produto. - `channels.delivery` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo delivery. - `channels.pdv` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo PDV. - `channels.tables` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo mesa. - `channels.totem` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo totem. - `rules.minimumOrderAmount` *number* — Valor mínimo do pedido; null remove o pedido mínimo. - `rules.limitOnePerCustomer` *boolean* — Limita a 1 uso por cliente. - `rules.hasQuantityLimit` *boolean* — Indica se há limite total de usos. - `rules.maxQuantity` *number* — Quantidade máxima de usos; null remove o teto (use junto com hasQuantityLimit: false). - `rules.firstPurchaseOnly` *boolean* — Só na primeira compra. - `rules.showOnMenu` *boolean* — Exibe o cupom no cardápio. - `rules.pickupOrLocalOnly` *boolean* — Só para retirada ou presencial. - `rules.excludePromotionalProducts` *boolean* — Não aplica em produtos em promoção. - `rules.requirePhoneSms` *boolean* — Exige validação de telefone por SMS. ## Erros | Status | Mensagem | | --- | --- | | 400 | body must include at least one field | | 400 | 'benefit' must include at least one field | | 400 | 'merchantId' is not allowed | | 400 | 'extra' is not allowed | | 400 | 'benefit.type' must be one of percentage, fixed | | 400 | 'validity.startsAt' must be an ISO 8601 date-time | | 400 | rules.maxQuantity must be >= 1 when rules.hasQuantityLimit is true | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the coupons:write scope | | 404 | Coupon ID 99 not found | ## Vocabulários usados neste endpoint ## Pagamento · method.type Mesmo vocabulário usado no bloco payments do pedido e nas formas de pagamento permitidas em cupons. | Valor | Significado | Uso | | --- | --- | --- | | `CASH` | Dinheiro | Pedidos e cupons | | `CREDIT_CARD` | Cartão de crédito | Pedidos e cupons | | `DEBIT_CARD` | Cartão de débito | Pedidos e cupons | | `PIX_BEEFOOD` | Pix BeeFood | Pedidos e cupons | | `FOOD_VOUCHER` | Vale-alimentação | Pedidos e cupons | | `MEAL_VOUCHER` | Vale-refeição | Pedidos e cupons | | `DIGITAL_WALLET` | Carteira digital | Pedidos e cupons | | `STORE_CREDIT` | Crédito no restaurante | Pedidos e cupons | | `OTHER` | Outro | Pedidos e cupons | ## Cupons · benefit.type | Valor | Significado | Uso | | --- | --- | --- | | `percentage` | Percentual | Cupons | | `fixed` | Valor fixo | Cupons | ## Cupons · benefit.appliesTo | Valor | Significado | Uso | | --- | --- | --- | | `discount` | Desconto no pedido | Cupons | | `deliveryFee` | Taxa de entrega | Cupons | | `product` | Produto | Cupons | ## Cupons · advanced.application.mode | Valor | Significado | Uso | | --- | --- | --- | | `order` | Ao pedido inteiro (padrão) | sectors e products devem ser [] | | `unlockByItems` | Só quando o carrinho tiver certos itens | Exige ao menos um setor ou produto | | `itemsOnly` | Só sobre certos itens do pedido | Exige itens e appliesTo: discount | ## Cupons · channels Cada canal é um booleano. | Valor | Significado | Uso | | --- | --- | --- | | `delivery` | Delivery | Cupons | | `pdv` | PDV | Cupons | | `tables` | Mesas | Cupons | | `totem` | Totem | Cupons | ## Listar avaliações --- title: "Listar avaliações" description: "GET /v1/store/reviews — avaliações do restaurante na API BeeFood." method: "GET" path: "/v1/store/reviews" url: "https://developer.beefood.com.br/docs/loja/avaliacoes" group: "Restaurante" scope: "reviews:read" lang: "pt" --- # Listar avaliações `GET /v1/store/reviews` - Produção: `https://api.beefood.app/v1/store/reviews` - Sandbox: `https://api-sandbox.beefood.app/v1/store/reviews` Retorna as avaliações da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `reviews:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de query - `page` *integer* — Página atual da lista. Exemplo: `1`. - `limit` *integer* — Quantidade de itens por página. Exemplo: `20`. - `sort` *string* — Ordem da lista: mais recentes (desc) ou mais antigos (asc). Exemplo: `"desc"`. - *Valores:* `asc`, `desc` - `merchantId` *integer* — Filtra por cardápio. Exemplo: `39202`. - `createdAtFrom` *string (yyyy-mm-dd)* — Início do período, o dia inicial é incluído. Pode ser enviado sozinho. Exemplo: `"2026-10-01"`. - `createdAtTo` *string (yyyy-mm-dd)* — Fim do período; o dia final é incluído. Pode ser enviado sozinho e não pode ser menor que createdAtFrom. Exemplo: `"2026-10-09"`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/reviews?createdAtFrom=2026-10-01&createdAtTo=2026-10-09&page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### Uma nota preenchida ```json { "items": [ { "reviewId": 670978, "storeId": 38311, "merchantId": 39202, "customerId": 1001, "consumerId": 2001, "orderId": 123, "name": "Cliente Exemplo", "phone": "11999990000", "comment": "Muito bom", "averageRating": 5, "origin": "DIGITAL_MENU_DELIVERY", "published": false, "createdAt": "2026-08-31T10:11:26.450Z" } ], "page": 1, "limit": 20, "total": 1, "pages": 1 } ``` ### Duas notas preenchidas ```json { "items": [ { "reviewId": 670979, "storeId": 38311, "merchantId": 39202, "name": "Cliente Exemplo", "comment": "Comida boa, demorou um pouco", "averageRating": 4.5, "origin": "TABLE", "published": true, "createdAt": "2026-09-01T20:42:10.000Z" } ], "page": 1, "limit": 20, "total": 1, "pages": 1 } ``` ### Três notas, com arredondamento ```json { "items": [ { "reviewId": 670980, "storeId": 38311, "merchantId": 39202, "averageRating": 4.3, "origin": "DELIVERY", "published": true, "createdAt": "2026-09-02T19:05:00.000Z" } ], "page": 1, "limit": 20, "total": 1, "pages": 1 } ``` ### Avaliação sem nota ```json { "items": [ { "reviewId": 670981, "storeId": 38311, "merchantId": 39202, "comment": "Já pedi outras vezes", "origin": "DELIVERY", "published": false, "createdAt": "2026-09-03T12:00:00.000Z" } ], "page": 1, "limit": 20, "total": 1, "pages": 1 } ``` ## Campos da resposta - `items[].reviewId` *number* — ID da avaliação. - `items[].storeId` *number* — ID do restaurante. - `items[].merchantId` *number* — ID do cardápio. - `items[].customerId` *number* — ID do cliente. - `items[].consumerId` *number* — ID do consumidor. - `items[].orderId` *number* — ID do pedido avaliado. - `items[].name` *string* — Nome de quem avaliou. - `items[].phone` *string* — Telefone informado. - `items[].comment` *string* — Comentário escrito. - `items[].averageRating` *number* — Média das notas preenchidas, de 0 a 5, arredondada a uma casa decimal. Omitida quando não há notas. Exemplo: `4.3`. - `items[].howDidYouHear` *string* — Como conheceu o restaurante. - `items[].origin` *string* — Canal de origem da avaliação. - *Valores:* `DIGITAL_MENU_DELIVERY`, `DIGITAL_MENU_LOCAL`, `DELIVERY`, `TABLE`, `OTHER` - `items[].published` *boolean* — Indica se a avaliação está publicada. - `items[].createdAt` *string (ISO 8601)* — Quando a avaliação foi feita. - `page` *number* — Página atual da lista. - `limit` *number* — Quantidade de itens por página. - `total` *number* — Total de registros encontrados. - `pages` *number* — Total de páginas. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'page' must be an integer >= 1 | | 400 | 'limit' must be an integer between 1 and 100 | | 400 | 'sort' must be asc or desc | | 400 | 'createdAtFrom' must be a date (yyyy-mm-dd) | | 400 | 'createdAtTo' must be a date (yyyy-mm-dd) | | 400 | 'createdAtFrom' must be <= 'createdAtTo' | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the reviews:read scope | | 404 | Merchant ID 99 not found | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Avaliações · origin | Valor | Significado | Uso | | --- | --- | --- | | `DIGITAL_MENU_DELIVERY` | Cardápio digital delivery | GET /v1/store/reviews | | `DIGITAL_MENU_LOCAL` | Cardápio digital presencial | GET /v1/store/reviews | | `DELIVERY` | Delivery | GET /v1/store/reviews | | `TABLE` | Mesa / comanda | GET /v1/store/reviews | | `OTHER` | Outro | GET /v1/store/reviews | ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Criar cupom --- title: "Criar cupom" description: "POST /v1/store/coupons — criação de cupom de desconto na API BeeFood." method: "POST" path: "/v1/store/coupons" url: "https://developer.beefood.com.br/docs/loja/criar-cupom" group: "Restaurante" scope: "coupons:write" lang: "pt" --- # Criar cupom `POST /v1/store/coupons` - Produção: `https://api.beefood.app/v1/store/coupons` - Sandbox: `https://api-sandbox.beefood.app/v1/store/coupons` Cria um cupom para um cardápio da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `coupons:write`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros do body - `merchantId` *integer* **obrigatório** — Cardápio em que o cupom vale. - `code` *string* **obrigatório** — Código para a utilização do cupom. - `active` *boolean* **obrigatório** — Indica se o cupom está ativo. - `benefit` *object* **obrigatório** — Benefício concedido pelo cupom. - `validity` *object* **obrigatório** — Período e dias em que o cupom vale. - `channels` *object* **obrigatório** — Canais em que o cupom vale. - *Valores:* `delivery`, `pdv`, `tables`, `totem` - `rules` *object* **obrigatório** — Regras de uso do cupom. - `advanced` *object* — Restrições avançadas do cupom. - `advanced.paymentMethods` *array* — Formas de pagamento que liberam o cupom. - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.paymentMethods[].paymentMethodId` *number* — ID da forma de pagamento. - `advanced.paymentMethods[].name` *string* — Nome da forma de pagamento. - `advanced.paymentMethods[].type` *string* — Tipo da forma de pagamento. - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.application` *object* — Como o cupom se aplica a setores/produtos. - `advanced.application.mode` *string* — Modo de aplicação. - *Valores:* `order`, `unlockByItems`, `itemsOnly` - `advanced.application.sectors` *array* — Setores relacionados ao cupom. - `advanced.application.sectors[].sectorId` *number* **obrigatório** — ID do setor. - `advanced.application.products` *array* — Produtos relacionados ao cupom. - `advanced.application.products[].productId` *number* **obrigatório** — ID do produto. ## Exemplos de body ### Formas de aplicação · order · Ao pedido inteiro (padrão) ```json { "merchantId": 122, "active": true, "validity": { "startsAt": "2026-09-01T00:00:00.000-03:00", "endsAt": null, "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": null, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "code": "PIX15", "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 15 }, "advanced": { "paymentMethods": [ { "paymentMethodId": 229029, "name": "PIX Bee", "type": "PIX_BEEFOOD" } ], "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Formas de aplicação · unlockByItems · Só quando o carrinho tiver certos itens ```json { "merchantId": 122, "active": true, "validity": { "startsAt": "2026-09-01T00:00:00.000-03:00", "endsAt": "2026-12-31T23:59:59.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 50, "limitOnePerCustomer": true, "hasQuantityLimit": false, "maxQuantity": null, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": true, "requirePhoneSms": false }, "code": "LIBERA10", "benefit": { "appliesTo": "discount", "type": "fixed", "amount": 10 }, "advanced": { "paymentMethods": [], "application": { "mode": "unlockByItems", "sectors": [ { "sectorId": 45 }, { "sectorId": 12 } ], "products": [ { "productId": 1234 } ] } } } ``` ### Formas de aplicação · itemsOnly · Só sobre certos itens do pedido ```json { "merchantId": 122, "active": true, "validity": { "startsAt": "2026-09-01T00:00:00.000-03:00", "endsAt": null, "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": null, "limitOnePerCustomer": false, "hasQuantityLimit": true, "maxQuantity": 100, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "code": "SOBEBIDAS", "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 20 }, "advanced": { "paymentMethods": [], "application": { "mode": "itemsOnly", "sectors": [ { "sectorId": 45 } ], "products": [ { "productId": 5678 } ] } } } ``` ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/store/coupons" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "merchantId": 1, "code": "PIX15%", "active": true, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 15 }, "validity": { "startsAt": "2026-08-22T23:34:00.000-03:00", "endsAt": null, "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": null, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": true }, "advanced": { "paymentMethods": [ { "paymentMethodId": 486229, "name": "PIX Bee", "type": "PIX_BEEFOOD" } ], "application": { "mode": "order", "sectors": [], "products": [] } } }' ``` ## Exemplos de resposta ### 201 OK ```json { "couponId": 15283, "storeId": 38311, "merchantId": 1, "code": "PIX15%", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 15 }, "validity": { "startsAt": "2026-08-22T23:34:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": true }, "advanced": { "paymentMethods": [], "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Formas de aplicação · order · Ao pedido inteiro (padrão) ```json { "couponId": 15283, "storeId": 38311, "merchantId": 122, "code": "PIX15", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 15 }, "validity": { "startsAt": "2026-09-01T00:00:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [ { "paymentMethodId": 229029, "name": "PIX Bee", "type": "PIX_BEEFOOD" } ], "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Formas de aplicação · unlockByItems · Só quando o carrinho tiver certos itens ```json { "couponId": 15283, "storeId": 38311, "merchantId": 122, "code": "LIBERA10", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "fixed", "amount": 10 }, "validity": { "startsAt": "2026-09-01T00:00:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "unlockByItems", "sectors": [ { "sectorId": 45, "name": "Bebidas" }, { "sectorId": 12, "name": "Pizzas" } ], "products": [ { "productId": 1234, "name": "Pizza Calabresa" } ] } } } ``` ### Formas de aplicação · itemsOnly · Só sobre certos itens do pedido ```json { "couponId": 15283, "storeId": 38311, "merchantId": 122, "code": "SOBEBIDAS", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 20 }, "validity": { "startsAt": "2026-09-01T00:00:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "itemsOnly", "sectors": [ { "sectorId": 45, "name": "Bebidas" } ], "products": [ { "productId": 5678, "name": "Refrigerante Lata" } ] } } } ``` ## Campos da resposta - `couponId` *number* — ID do cupom a atualizar. - `storeId` *number* — ID do restaurante. - `merchantId` *number* — Cardápio em que o cupom vale. - `code` *string* — Código para a utilização do cupom. - `active` *boolean* — Indica se o cupom está ativo. - `usageCount` *number* — Quantas vezes já foi usado. - `benefit.appliesTo` *string* — Sobre o que o benefício incide (pedido, frete ou produto). - *Valores:* `discount`, `deliveryFee`, `product` - `benefit.type` *string* — Percentual ou valor fixo. - *Valores:* `percentage`, `fixed` - `benefit.amount` *number* — Valor do benefício. - `validity.startsAt` *string (ISO 8601)* — Início da validade; null remove a data de início. - `validity.endsAt` *string (ISO 8601)* — Fim da validade; null remove a data de término (cupom sem data fim). - `validity.weekdays` *object* — Dias da semana em que o cupom vale. - `channels` *object* — Canais em que o cupom vale. - *Valores:* `delivery`, `pdv`, `tables`, `totem` - `rules` *object* — Regras de uso do cupom. - `advanced.paymentMethods` *array* — Formas de pagamento que liberam o cupom; na atualização, a lista enviada substitui a atual (vazia = sem restrição). - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.paymentMethods[].paymentMethodId` *number* — ID da forma de pagamento. - `advanced.paymentMethods[].name` *string* — Nome da forma de pagamento. - `advanced.paymentMethods[].type` *string* — Tipo da forma de pagamento. - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.application` *object* — Como o cupom se aplica a setores/produtos; na atualização, sectors e products substituem as listas atuais. - `advanced.application.mode` *string* — Modo de aplicação. - *Valores:* `order`, `unlockByItems`, `itemsOnly` - `advanced.application.sectors` *array* — Setores relacionados ao cupom. - `advanced.application.sectors[].sectorId` *number* — ID do setor. - `advanced.application.sectors[].name` *string* — Nome do setor. - `advanced.application.products` *array* — Produtos relacionados ao cupom. - `advanced.application.products[].productId` *number* — ID do produto. - `advanced.application.products[].name` *string* — Nome do produto. - `channels.delivery` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo delivery. - `channels.pdv` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo PDV. - `channels.tables` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo mesa. - `channels.totem` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo totem. - `rules.minimumOrderAmount` *number* — Valor mínimo do pedido; null remove o pedido mínimo. - `rules.limitOnePerCustomer` *boolean* — Limita a 1 uso por cliente. - `rules.hasQuantityLimit` *boolean* — Indica se há limite total de usos. - `rules.maxQuantity` *number* — Quantidade máxima de usos; null remove o teto (use junto com hasQuantityLimit: false). - `rules.firstPurchaseOnly` *boolean* — Só na primeira compra. - `rules.showOnMenu` *boolean* — Exibe o cupom no cardápio. - `rules.pickupOrLocalOnly` *boolean* — Só para retirada ou presencial. - `rules.excludePromotionalProducts` *boolean* — Não aplica em produtos em promoção. - `rules.requirePhoneSms` *boolean* — Exige validação de telefone por SMS. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'merchantId' is required | | 400 | 'extra' is not allowed | | 400 | 'benefit.type' must be one of percentage, fixed | | 400 | 'validity.startsAt' must be an ISO 8601 date-time | | 400 | 'advanced.paymentMethods[0].name' is required | | 400 | rules.maxQuantity must be >= 1 when rules.hasQuantityLimit is true | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the coupons:write scope | | 404 | Merchant ID 99 not found (filial inexistente, inativa ou sem cardápio) | ## Vocabulários usados neste endpoint ## Pagamento · method.type Mesmo vocabulário usado no bloco payments do pedido e nas formas de pagamento permitidas em cupons. | Valor | Significado | Uso | | --- | --- | --- | | `CASH` | Dinheiro | Pedidos e cupons | | `CREDIT_CARD` | Cartão de crédito | Pedidos e cupons | | `DEBIT_CARD` | Cartão de débito | Pedidos e cupons | | `PIX_BEEFOOD` | Pix BeeFood | Pedidos e cupons | | `FOOD_VOUCHER` | Vale-alimentação | Pedidos e cupons | | `MEAL_VOUCHER` | Vale-refeição | Pedidos e cupons | | `DIGITAL_WALLET` | Carteira digital | Pedidos e cupons | | `STORE_CREDIT` | Crédito no restaurante | Pedidos e cupons | | `OTHER` | Outro | Pedidos e cupons | ## Cupons · benefit.type | Valor | Significado | Uso | | --- | --- | --- | | `percentage` | Percentual | Cupons | | `fixed` | Valor fixo | Cupons | ## Cupons · benefit.appliesTo | Valor | Significado | Uso | | --- | --- | --- | | `discount` | Desconto no pedido | Cupons | | `deliveryFee` | Taxa de entrega | Cupons | | `product` | Produto | Cupons | ## Cupons · advanced.application.mode | Valor | Significado | Uso | | --- | --- | --- | | `order` | Ao pedido inteiro (padrão) | sectors e products devem ser [] | | `unlockByItems` | Só quando o carrinho tiver certos itens | Exige ao menos um setor ou produto | | `itemsOnly` | Só sobre certos itens do pedido | Exige itens e appliesTo: discount | ## Cupons · channels Cada canal é um booleano. | Valor | Significado | Uso | | --- | --- | --- | | `delivery` | Delivery | Cupons | | `pdv` | PDV | Cupons | | `tables` | Mesas | Cupons | | `totem` | Totem | Cupons | ## Detalhe do cupom --- title: "Detalhe do cupom" description: "GET /v1/store/coupons/:couponId — detalhe de um cupom do restaurante." method: "GET" path: "/v1/store/coupons/{couponId}" url: "https://developer.beefood.com.br/docs/loja/cupom" group: "Restaurante" scope: "coupons:read" lang: "pt" --- # Detalhe do cupom `GET /v1/store/coupons/{couponId}` - Produção: `https://api.beefood.app/v1/store/coupons/{couponId}` - Sandbox: `https://api-sandbox.beefood.app/v1/store/coupons/{couponId}` Retorna o detalhe de um cupom. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `coupons:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de path - `couponId` *integer* **obrigatório** — ID do cupom. Exemplo: `15283`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/coupons/{couponId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### Desconto percentual ```json { "couponId": 15237, "storeId": 38311, "merchantId": 39202, "code": "PIX15%", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 15 }, "validity": { "startsAt": "2026-08-22T23:34:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": true }, "advanced": { "paymentMethods": [ { "paymentMethodId": 486229, "name": "PIX Bee", "type": "PIX_BEEFOOD" }, { "paymentMethodId": 381233, "name": "PIX Online", "type": "PIX_BEEFOOD" } ], "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Tipos de benefício · Desconto valor fixo ```json { "couponId": 12249, "storeId": 38311, "merchantId": 39202, "code": "TESTEBEEFOOD", "active": false, "usageCount": 2, "benefit": { "appliesTo": "discount", "type": "fixed", "amount": 10 }, "validity": { "startsAt": "2026-02-25T19:18:45.847-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Tipos de benefício · Frete valor fixo ```json { "couponId": 13336, "storeId": 38311, "merchantId": 39202, "code": "FRETEGRATIS", "active": false, "usageCount": 2, "benefit": { "appliesTo": "deliveryFee", "type": "fixed", "amount": 0 }, "validity": { "startsAt": "2026-05-15T03:02:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": false, "tables": false, "totem": false }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Tipos de benefício · Frete percentual ```json { "couponId": 7516, "storeId": 1001, "merchantId": 2005, "code": "FRETE10", "active": false, "usageCount": 37, "benefit": { "appliesTo": "deliveryFee", "type": "percentage", "amount": 10 }, "validity": { "startsAt": "2024-12-30T12:13:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": false, "tables": false, "totem": false }, "rules": { "minimumOrderAmount": 59.9, "limitOnePerCustomer": true, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "order", "sectors": [], "products": [] } } } ``` ### Regras especiais · Primeira compra ```json { "couponId": 15143, "storeId": 38311, "merchantId": 39202, "code": "FIRST", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 15 }, "validity": { "startsAt": "2026-08-21T03:54:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": true, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "itemsOnly", "sectors": [ { "sectorId": 213752, "name": "Acompanhamentos" } ], "products": [ { "productId": 2515342, "name": "Fatia de queijo" } ] } } } ``` ### Formas de aplicação · unlockByItems · Só quando o carrinho tiver certos itens ```json { "couponId": 15233, "storeId": 38311, "merchantId": 39202, "code": "10%SETIVERBOX", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 10 }, "validity": { "startsAt": "2026-08-23T13:14:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "unlockByItems", "sectors": [], "products": [ { "productId": 2515304, "name": "(Box) Batata frita" } ] } } } ``` ### Formas de aplicação · itemsOnly · Só sobre certos itens do pedido ```json { "couponId": 15231, "storeId": 38311, "merchantId": 39202, "code": "10%BEBIDA", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 10 }, "validity": { "startsAt": "2026-08-22T18:11:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "itemsOnly", "sectors": [], "products": [] } } } ``` ## Campos da resposta - `couponId` *number* — ID do cupom a atualizar. - `storeId` *number* — ID do restaurante. - `merchantId` *number* — Cardápio em que o cupom vale. - `code` *string* — Código para a utilização do cupom. - `active` *boolean* — Indica se o cupom está ativo. - `usageCount` *number* — Quantas vezes já foi usado. - `benefit.appliesTo` *string* — Sobre o que o benefício incide (pedido, frete ou produto). - *Valores:* `discount`, `deliveryFee`, `product` - `benefit.type` *string* — Percentual ou valor fixo. - *Valores:* `percentage`, `fixed` - `benefit.amount` *number* — Valor do benefício. - `validity.startsAt` *string (ISO 8601)* — Início da validade; null remove a data de início. - `validity.endsAt` *string (ISO 8601)* — Fim da validade; null remove a data de término (cupom sem data fim). - `validity.weekdays` *object* — Dias da semana em que o cupom vale. - `channels` *object* — Canais em que o cupom vale. - *Valores:* `delivery`, `pdv`, `tables`, `totem` - `rules` *object* — Regras de uso do cupom. - `advanced.paymentMethods` *array* — Formas de pagamento que liberam o cupom; na atualização, a lista enviada substitui a atual (vazia = sem restrição). - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.paymentMethods[].paymentMethodId` *number* — ID da forma de pagamento. - `advanced.paymentMethods[].name` *string* — Nome da forma de pagamento. - `advanced.paymentMethods[].type` *string* — Tipo da forma de pagamento. - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `advanced.application` *object* — Como o cupom se aplica a setores/produtos; na atualização, sectors e products substituem as listas atuais. - `advanced.application.mode` *string* — Modo de aplicação. - *Valores:* `order`, `unlockByItems`, `itemsOnly` - `advanced.application.sectors` *array* — Setores relacionados ao cupom. - `advanced.application.sectors[].sectorId` *number* — ID do setor. - `advanced.application.sectors[].name` *string* — Nome do setor. - `advanced.application.products` *array* — Produtos relacionados ao cupom. - `advanced.application.products[].productId` *number* — ID do produto. - `advanced.application.products[].name` *string* — Nome do produto. - `channels.delivery` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo delivery. - `channels.pdv` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo PDV. - `channels.tables` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo mesa. - `channels.totem` *boolean* — Define se o cupom pode ser aplicado em pedidos tipo totem. - `rules.minimumOrderAmount` *number* — Valor mínimo do pedido; null remove o pedido mínimo. - `rules.limitOnePerCustomer` *boolean* — Limita a 1 uso por cliente. - `rules.hasQuantityLimit` *boolean* — Indica se há limite total de usos. - `rules.maxQuantity` *number* — Quantidade máxima de usos; null remove o teto (use junto com hasQuantityLimit: false). - `rules.firstPurchaseOnly` *boolean* — Só na primeira compra. - `rules.showOnMenu` *boolean* — Exibe o cupom no cardápio. - `rules.pickupOrLocalOnly` *boolean* — Só para retirada ou presencial. - `rules.excludePromotionalProducts` *boolean* — Não aplica em produtos em promoção. - `rules.requirePhoneSms` *boolean* — Exige validação de telefone por SMS. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the coupons:read scope | | 404 | Coupon ID 99 not found | ## Vocabulários usados neste endpoint ## Pagamento · method.type Mesmo vocabulário usado no bloco payments do pedido e nas formas de pagamento permitidas em cupons. | Valor | Significado | Uso | | --- | --- | --- | | `CASH` | Dinheiro | Pedidos e cupons | | `CREDIT_CARD` | Cartão de crédito | Pedidos e cupons | | `DEBIT_CARD` | Cartão de débito | Pedidos e cupons | | `PIX_BEEFOOD` | Pix BeeFood | Pedidos e cupons | | `FOOD_VOUCHER` | Vale-alimentação | Pedidos e cupons | | `MEAL_VOUCHER` | Vale-refeição | Pedidos e cupons | | `DIGITAL_WALLET` | Carteira digital | Pedidos e cupons | | `STORE_CREDIT` | Crédito no restaurante | Pedidos e cupons | | `OTHER` | Outro | Pedidos e cupons | ## Cupons · benefit.type | Valor | Significado | Uso | | --- | --- | --- | | `percentage` | Percentual | Cupons | | `fixed` | Valor fixo | Cupons | ## Cupons · benefit.appliesTo | Valor | Significado | Uso | | --- | --- | --- | | `discount` | Desconto no pedido | Cupons | | `deliveryFee` | Taxa de entrega | Cupons | | `product` | Produto | Cupons | ## Cupons · advanced.application.mode | Valor | Significado | Uso | | --- | --- | --- | | `order` | Ao pedido inteiro (padrão) | sectors e products devem ser [] | | `unlockByItems` | Só quando o carrinho tiver certos itens | Exige ao menos um setor ou produto | | `itemsOnly` | Só sobre certos itens do pedido | Exige itens e appliesTo: discount | ## Cupons · channels Cada canal é um booleano. | Valor | Significado | Uso | | --- | --- | --- | | `delivery` | Delivery | Cupons | | `pdv` | PDV | Cupons | | `tables` | Mesas | Cupons | | `totem` | Totem | Cupons | ## Listar cupons --- title: "Listar cupons" description: "GET /v1/store/coupons — cupons de desconto do restaurante BeeFood." method: "GET" path: "/v1/store/coupons" url: "https://developer.beefood.com.br/docs/loja/cupons" group: "Restaurante" scope: "coupons:read" lang: "pt" --- # Listar cupons `GET /v1/store/coupons` - Produção: `https://api.beefood.app/v1/store/coupons` - Sandbox: `https://api-sandbox.beefood.app/v1/store/coupons` Retorna os cupons da empresa. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `coupons:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de query - `page` *integer* — Página atual da lista. Exemplo: `1`. - `limit` *integer* — Quantidade de itens por página. Exemplo: `20`. - `sort` *string* — Ordem da lista: mais recentes (desc) ou mais antigos (asc). Exemplo: `"desc"`. - *Valores:* `asc`, `desc` - `merchantId` *integer* — Filtra por cardápio. Exemplo: `1`. - `code` *string* — Filtra pelo código digitado pelo cliente. Exemplo: `"PIX15%"`. - `active` *boolean* — Filtra por cupons ativos ou inativos. Ausente = todos. Exemplo: `true`. - `type` *string* — Filtra pelo tipo do benefício: percentage ou fixed. Exemplo: `"percentage"`. - `appliesTo` *string* — Filtra pelo alvo do benefício: discount, deliveryFee ou product. Exemplo: `"discount"`. - `validFrom` *string (ISO 8601)* — Filtra pelos cupons vigentes a partir dessa data. Exemplo: `"2026-03-01T00:00:00-03:00"`. - `validUntil` *string (ISO 8601)* — Filtra pelos cupons vigentes até essa data. Exemplo: `"2026-03-31T23:59:59-03:00"`. - `paymentMethodType` *string* — Filtra pelos cupons restritos a uma forma de pagamento listada em advanced.paymentMethods. Exemplo: `"PIX_BEEFOOD"`. - `applicationMode` *string* — Filtra pelo modo de aplicação: order, unlockByItems ou itemsOnly. Exemplo: `"order"`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/coupons?page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "couponId": 15237, "storeId": 38311, "merchantId": 39202, "code": "PIX15%", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 15 }, "validity": { "startsAt": "2026-08-22T23:34:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": true }, "advanced": { "paymentMethods": [ { "paymentMethodId": 486229, "name": "PIX Bee", "type": "PIX_BEEFOOD" }, { "paymentMethodId": 381233, "name": "PIX Online", "type": "PIX_BEEFOOD" } ], "application": { "mode": "order", "sectors": [], "products": [] } } }, { "couponId": 15233, "storeId": 38311, "merchantId": 39202, "code": "10%SETIVERBOX", "active": true, "usageCount": 0, "benefit": { "appliesTo": "discount", "type": "percentage", "amount": 10 }, "validity": { "startsAt": "2026-08-23T13:14:00.000-03:00", "weekdays": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": true, "sunday": true } }, "channels": { "delivery": true, "pdv": true, "tables": true, "totem": true }, "rules": { "minimumOrderAmount": 0, "limitOnePerCustomer": false, "hasQuantityLimit": false, "maxQuantity": 0, "firstPurchaseOnly": false, "showOnMenu": true, "pickupOrLocalOnly": false, "excludePromotionalProducts": false, "requirePhoneSms": false }, "advanced": { "paymentMethods": [], "application": { "mode": "unlockByItems", "sectors": [], "products": [ { "productId": 2515304, "name": "(Box) Batata frita" } ] } } } ], "page": 1, "limit": 2, "total": 13, "pages": 7 } ``` ## Campos da resposta - `items[].couponId` *number* — ID do cupom. - `items[].code` *string* — Código para a utilização do cupom. - `items[].benefit` *object* — Benefício concedido pelo cupom. - `items[].validity` *object* — Período e dias em que o cupom vale. - `items[].channels` *object* — Canais em que o cupom vale. - *Valores:* `delivery`, `pdv`, `tables`, `totem` - `items[].rules` *object* — Regras de uso do cupom. - `items[].advanced` *object* — Restrições avançadas do cupom. - `page` *number* — Página atual da lista. - `limit` *number* — Quantidade de itens por página. - `total` *number* — Total de registros encontrados. - `pages` *number* — Total de páginas. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'page' must be an integer >= 1 | | 400 | 'limit' must be an integer between 1 and 100 | | 400 | 'sort' must be asc or desc | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the coupons:read scope | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Cupons · channels Cada canal é um booleano. | Valor | Significado | Uso | | --- | --- | --- | | `delivery` | Delivery | Cupons | | `pdv` | PDV | Cupons | | `tables` | Mesas | Cupons | | `totem` | Totem | Cupons | ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Horários do delivery --- title: "Horários do delivery" description: "GET /v1/store/merchants/:merchantId/delivery/opening-hours — horários de atendimento do delivery." method: "GET" path: "/v1/store/merchants/{merchantId}/delivery/opening-hours" url: "https://developer.beefood.com.br/docs/loja/delivery-horarios" group: "Restaurante" scope: "store:read" lang: "pt" --- # Horários do delivery `GET /v1/store/merchants/{merchantId}/delivery/opening-hours` - Produção: `https://api.beefood.app/v1/store/merchants/{merchantId}/delivery/opening-hours` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants/{merchantId}/delivery/opening-hours` Retorna os horários de atendimento do canal delivery do cardápio. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de path - `merchantId` *integer* **obrigatório** — ID do cardápio. Exemplo: `1`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants/{merchantId}/delivery/opening-hours" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "monday": [ { "open": "01:00", "close": "23:59" }, { "open": "18:00", "close": "22:00" } ], "tuesday": [ { "open": "01:00", "close": "23:59" } ], "wednesday": [ { "open": "01:30", "close": "14:00" } ], "thursday": [ { "open": "01:00", "close": "23:59" } ], "friday": [ { "open": "01:00", "close": "23:59" } ], "saturday": [ { "open": "01:00", "close": "23:59" } ], "sunday": [ { "open": "01:00", "close": "23:59" } ] } ``` ## Campos da resposta - `monday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `tuesday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `wednesday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `thursday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `friday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `saturday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "15:00" }, { "open": "18:00", "close": "23:00" }]`. - `sunday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 404 | Merchant ID 99 not found | ## Canal delivery --- title: "Canal delivery" description: "GET /v1/store/merchants/:merchantId/delivery — configuração do canal delivery." method: "GET" path: "/v1/store/merchants/{merchantId}/delivery" url: "https://developer.beefood.com.br/docs/loja/delivery" group: "Restaurante" scope: "store:read" lang: "pt" --- # Canal delivery `GET /v1/store/merchants/{merchantId}/delivery` - Produção: `https://api.beefood.app/v1/store/merchants/{merchantId}/delivery` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants/{merchantId}/delivery` Retorna a configuração do canal delivery do cardápio. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de path - `merchantId` *integer* **obrigatório** — ID do cardápio. Exemplo: `1`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants/{merchantId}/delivery" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "storeId": 38311, "merchantId": 39202, "open": true, "deliveryTimeMinutes": 45, "pickupTimeMinutes": 25, "operationModes": { "delivery": true, "takeout": true }, "minimumOrderAmount": 0, "deliveryFee": 0 } ``` ## Campos da resposta - `storeId` *number* — ID do restaurante. - `merchantId` *number* — ID do cardápio. - `open` *boolean* — Indica se o delivery está aberto agora. - `operationModes.delivery` *boolean* — Indica se aceita entrega. - `operationModes.takeout` *boolean* — Indica se aceita retirada. - `deliveryTimeMinutes` *number* — Tempo médio de entrega (minutos). - `pickupTimeMinutes` *number* — Tempo médio de retirada (minutos). - `minimumOrderAmount` *number* — Valor mínimo do pedido. - `deliveryFee` *number* — Taxa de entrega padrão (quando aplicável). ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 404 | Merchant ID 99 not found | ## Formas de pagamento --- title: "Formas de pagamento" description: "GET /v1/store/payment-methods — formas de pagamento ativas do restaurante." method: "GET" path: "/v1/store/payment-methods" url: "https://developer.beefood.com.br/docs/loja/formas-pagamento" group: "Restaurante" scope: "store:read" lang: "pt" --- # Formas de pagamento `GET /v1/store/payment-methods` - Produção: `https://api.beefood.app/v1/store/payment-methods` - Sandbox: `https://api-sandbox.beefood.app/v1/store/payment-methods` Retorna as formas de pagamento do restaurante. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 100 requisições a cada 3 minutos. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/payment-methods" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json [ { "paymentMethodId": 381396, "name": "Fiadoxx", "kind": "STORE_CREDIT", "brands": [] }, { "paymentMethodId": 486229, "name": "PIX Bee", "kind": "PIX_BEEFOOD", "brands": [] }, { "paymentMethodId": 381233, "name": "PIX Online", "kind": "PIX_BEEFOOD", "brands": [] }, { "paymentMethodId": 856273, "name": "Vale Refeição Sodexo", "kind": "MEAL_VOUCHER", "brands": [] }, { "paymentMethodId": 381234, "name": "Dinheiro", "kind": "CASH", "brands": [] }, { "paymentMethodId": 381235, "name": "Débito", "kind": "DEBIT_CARD", "brands": [ { "brandId": 1, "name": "Visa" }, { "brandId": 2, "name": "Mastercard" } ] }, { "paymentMethodId": 381236, "name": "Crédito", "kind": "CREDIT_CARD", "brands": [] }, { "paymentMethodId": 381237, "name": "PIX Manual", "kind": "DIGITAL_WALLET", "brands": [] }, { "paymentMethodId": 381238, "name": "Vale Alimentação", "kind": "FOOD_VOUCHER", "brands": [] }, { "paymentMethodId": 381239, "name": "Vale Refeição", "kind": "MEAL_VOUCHER", "brands": [] } ] ``` ## Campos da resposta - `paymentMethodId` *number* — ID da forma de pagamento. - `name` *string* — Nome da forma. - `kind` *string* — Tipo do pagamento. - `brands` *array* — Bandeiras associadas. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 500 | Database error when trying to … | ## Detalhe do merchant --- title: "Detalhe do merchant" description: "GET /v1/store/merchants/:merchantId — perfil do cardápio (identidade, contato, endereço e mídia)." method: "GET" path: "/v1/store/merchants/{merchantId}" url: "https://developer.beefood.com.br/docs/loja/merchant" group: "Restaurante" scope: "store:read" lang: "pt" --- # Detalhe do merchant `GET /v1/store/merchants/{merchantId}` - Produção: `https://api.beefood.app/v1/store/merchants/{merchantId}` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants/{merchantId}` Retorna o perfil de uma filial ativa, com ou sem cardápio de delivery. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 15 requisições por minuto. ## Parâmetros de path - `merchantId` *integer* **obrigatório** — ID do cardápio. Exemplo: `1`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants/{merchantId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "storeId": 38311, "merchantId": 39202, "tradeName": "Restaurante Exemplo", "legalName": "Restaurante Exemplo", "cnpj": "12345678000199", "accessLink": "https://menu.exemplo.com.br/restaurante-exemplo", "email": "contato@exemplo.com", "whatsapp": "11999990000", "address": { "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "Sorocaba", "state": "SP", "zipCode": "18040370", "latitude": -23.5015, "longitude": -47.4526 }, "media": { "logoUrl": "https://cdn.exemplo.com.br/restaurante-exemplo/logoUrl.webp", "logoUrl180": "https://cdn.exemplo.com.br/restaurante-exemplo/logoUrl180.webp", "logoUrl360": "https://cdn.exemplo.com.br/restaurante-exemplo/logoUrl360.webp", "coverUrl": "https://cdn.exemplo.com.br/restaurante-exemplo/coverUrl.webp", "coverUrl828": "https://cdn.exemplo.com.br/restaurante-exemplo/coverUrl828.webp", "coverUrl1920": "https://cdn.exemplo.com.br/restaurante-exemplo/coverUrl1920.webp" }, "primaryColor": "#b91c1c", "actionColor": "#ffc107", "deliveryCategoryId": 2, "main": true } ``` ## Campos da resposta - `storeId` *number* — ID do restaurante. - `merchantId` *number* — ID do cardápio. - `tradeName` *string* — Nome fantasia. - `legalName` *string* — Razão social. - `cnpj` *string* — CNPJ do cardápio. - `description` *string* — Descrição pública do restaurante. - `accessLink` *string* — Link de acesso ao cardápio/restaurante. - `email` *string* — E-mail de contato. - `phone` *string* — Telefone de contato. - `whatsapp` *string* — WhatsApp de contato. - `address.street` *string* — Rua. - `address.number` *string* — Número. - `address.neighborhood` *string* — Bairro. - `address.city` *string* — Cidade. - `address.state` *string* — UF. - `address.zipCode` *string* — CEP. - `address.latitude` *number* — Latitude. - `address.longitude` *number* — Longitude. - `media.logoUrl` *string* — Logo. - `media.logoUrl180` *string* — Logo 180px. - `media.logoUrl360` *string* — Logo 360px. - `media.coverUrl` *string* — Capa. - `media.coverUrl828` *string* — Capa 828px. - `media.coverUrl1920` *string* — Capa 1920px. - `primaryColor` *string* — Cor principal da identidade. - `actionColor` *string* — Cor de destaque/ações. - `deliveryCategoryId` *number* — Categoria do delivery. - `main` *boolean* — Indica se é o cardápio principal. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 404 | Merchant ID 99 not found | ## Listar merchants --- title: "Listar merchants" description: "GET /v1/store/merchants — listagem paginada dos cardápios (merchants) do restaurante na API BeeFood." method: "GET" path: "/v1/store/merchants" url: "https://developer.beefood.com.br/docs/loja/merchants" group: "Restaurante" scope: "store:read" lang: "pt" --- # Listar merchants `GET /v1/store/merchants` - Produção: `https://api.beefood.app/v1/store/merchants` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants` Lista as filiais ativas do restaurante (matriz e demais), com ou sem cardápio de delivery. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 15 requisições por minuto. ## Parâmetros de query - `page` *integer* — Página atual da lista. Exemplo: `1`. - `limit` *integer* — Quantidade de itens por página. Exemplo: `20`. - `sort` *string* — Ordem da lista: mais recentes (desc) ou mais antigos (asc). Exemplo: `"desc"`. - *Valores:* `asc`, `desc` - `main` *boolean* — Filtra a matriz (true) ou os demais cardápios (false). Ausente = todos. Exemplo: `true`. - `city` *string* — Filtra pela cidade do cardápio. Exemplo: `"São Paulo"`. - `state` *string* — Filtra pelo estado (UF) do cardápio. Exemplo: `"SP"`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants?page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "storeId": 38311, "merchantId": 50502, "tradeName": "Restaurante Exemplo - Sushi", "main": false }, { "storeId": 38311, "merchantId": 39202, "tradeName": "Restaurante Exemplo", "main": true, "city": "Sorocaba", "state": "SP" } ], "page": 1, "limit": 20, "total": 2, "pages": 1 } ``` ## Campos da resposta - `items[].storeId` *number* — ID do restaurante. - `items[].merchantId` *number* — ID do cardápio. - `items[].tradeName` *string* — Nome fantasia do cardápio. - `items[].main` *boolean* — Indica se é o cardápio principal. - `items[].city` *string* — Cidade. - `items[].state` *string* — UF. - `page` *number* — Página atual da lista. - `limit` *number* — Quantidade de itens por página. - `total` *number* — Total de registros encontrados. - `pages` *number* — Total de páginas. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'page' must be an integer >= 1 | | 400 | 'limit' must be an integer between 1 and 100 | | 400 | 'sort' must be asc or desc | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Pagamento online --- title: "Pagamento online" description: "GET /v1/store/merchants/:merchantId/delivery/online-payments — configuração de Pix e cartão online." method: "GET" path: "/v1/store/merchants/{merchantId}/delivery/online-payments" url: "https://developer.beefood.com.br/docs/loja/pagamento-online" group: "Restaurante" scope: "store:read" lang: "pt" --- # Pagamento online `GET /v1/store/merchants/{merchantId}/delivery/online-payments` - Produção: `https://api.beefood.app/v1/store/merchants/{merchantId}/delivery/online-payments` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants/{merchantId}/delivery/online-payments` Retorna a configuração de pagamento online do cardápio. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de path - `merchantId` *integer* **obrigatório** — ID do cardápio. Exemplo: `39202`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants/{merchantId}/delivery/online-payments" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "storeId": 38311, "merchantId": 39202, "pix": { "enabled": true, "feePercent": 0.8, "adjustment": { "mode": "discount", "unit": "percent", "value": 5 } }, "creditCard": { "enabled": true } } ``` ## Campos da resposta - `storeId` *number* — ID do restaurante. - `merchantId` *number* — ID do cardápio. - `pix.enabled` *boolean* — Indica se esta forma está habilitada. - `pix.feePercent` *number* — Percentual de taxa - `pix.adjustment` *object* — Desconto ou acréscimo aplicado. - `creditCard.enabled` *boolean* — Indica se esta forma está habilitada. - `creditCard.adjustment` *object* — Desconto ou acréscimo aplicado. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 404 | Merchant ID 99 not found | ## Horários do presencial --- title: "Horários do presencial" description: "GET /v1/store/merchants/:merchantId/local/opening-hours — horários de atendimento presencial." method: "GET" path: "/v1/store/merchants/{merchantId}/local/opening-hours" url: "https://developer.beefood.com.br/docs/loja/presencial-horarios" group: "Restaurante" scope: "store:read" lang: "pt" --- # Horários do presencial `GET /v1/store/merchants/{merchantId}/local/opening-hours` - Produção: `https://api.beefood.app/v1/store/merchants/{merchantId}/local/opening-hours` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants/{merchantId}/local/opening-hours` Retorna os horários de atendimento do canal presencial do cardápio. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de path - `merchantId` *integer* **obrigatório** — ID do cardápio. Exemplo: `1`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants/{merchantId}/local/opening-hours" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "monday": [ { "open": "01:00", "close": "23:59" } ], "tuesday": [ { "open": "01:00", "close": "23:59" } ], "wednesday": [], "thursday": [ { "open": "01:00", "close": "23:59" } ], "friday": [], "saturday": [], "sunday": [] } ``` ## Campos da resposta - `monday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `tuesday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `wednesday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `thursday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `friday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `saturday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. - `sunday` *array* — Faixas de atendimento do dia, com intervalos { open, close } no formato HH:mm. Vazio quando o cardápio não abre. Exemplo: `[{ "open": "11:00", "close": "23:00" }]`. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 404 | Merchant ID 99 not found | ## Canal presencial --- title: "Canal presencial" description: "GET /v1/store/merchants/:merchantId/local — configuração do canal presencial." method: "GET" path: "/v1/store/merchants/{merchantId}/local" url: "https://developer.beefood.com.br/docs/loja/presencial" group: "Restaurante" scope: "store:read" lang: "pt" --- # Canal presencial `GET /v1/store/merchants/{merchantId}/local` - Produção: `https://api.beefood.app/v1/store/merchants/{merchantId}/local` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants/{merchantId}/local` Retorna a configuração do canal presencial do cardápio. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de path - `merchantId` *integer* **obrigatório** — ID do cardápio. Exemplo: `1`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants/{merchantId}/local" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "storeId": 38311, "merchantId": 39202, "open": true, "operationModes": { "local": true } } ``` ## Campos da resposta - `storeId` *number* — ID do restaurante. - `merchantId` *number* — ID do cardápio. - `open` *boolean* — Indica se o canal presencial está aberto agora. - `operationModes` *object* — Modos disponíveis. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 404 | Merchant ID 99 not found | ## Recebimentos do delivery --- title: "Recebimentos do delivery" description: "GET /v1/store/merchants/:merchantId/delivery/payment-methods — formas de recebimento do canal delivery." method: "GET" path: "/v1/store/merchants/{merchantId}/delivery/payment-methods" url: "https://developer.beefood.com.br/docs/loja/recebimentos-delivery" group: "Restaurante" scope: "store:read" lang: "pt" --- # Recebimentos do delivery `GET /v1/store/merchants/{merchantId}/delivery/payment-methods` - Produção: `https://api.beefood.app/v1/store/merchants/{merchantId}/delivery/payment-methods` - Sandbox: `https://api-sandbox.beefood.app/v1/store/merchants/{merchantId}/delivery/payment-methods` Retorna as formas de recebimento do canal delivery do cardápio. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `store:read`. Limite: 100 requisições a cada 3 minutos. ## Parâmetros de path - `merchantId` *integer* **obrigatório** — ID do cardápio. Exemplo: `39202`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/store/merchants/{merchantId}/delivery/payment-methods" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "storeId": 38311, "merchantId": 39202, "items": [ { "receiptMethodId": 687811, "name": "Dinheiro", "paymentMethodId": 381234, "active": true, "sortOrder": 1, "channels": { "delivery": true, "takeout": true }, "adjustment": { "mode": "discount", "unit": "percent", "value": 5 } }, { "receiptMethodId": 687812, "name": "Cartão de Débito", "paymentMethodId": 381235, "active": true, "sortOrder": 2, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687813, "name": "Cartão de Crédito", "paymentMethodId": 381236, "active": true, "sortOrder": 3, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687827, "name": "Ben Visa Refeição", "paymentMethodId": 381239, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687828, "name": "Nutricard Refeicão E Alimentação", "paymentMethodId": 381239, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687815, "name": "PicPay", "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687814, "name": "Pix", "paymentMethodId": 381237, "active": true, "instructions": "BeeFood Testes", "pixKey": "53533159000138", "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687822, "name": "Vale - Alelo Refeição / Visa Vale", "paymentMethodId": 381238, "active": true, "channels": { "delivery": true, "takeout": true }, "adjustment": { "mode": "surcharge", "unit": "percent", "value": 5 } }, { "receiptMethodId": 687825, "name": "Vale - Cooper Card", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687824, "name": "Vale - Green Card", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687819, "name": "Vale - Green Card", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687816, "name": "Vale - Refeisul", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687820, "name": "Vale - Sodexo", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687818, "name": "Vale - Ticket Restaurante", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687817, "name": "Vale - Vale Card", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687821, "name": "Vale - Verocard", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687823, "name": "Vale - VR Smart", "paymentMethodId": 381238, "active": false, "channels": { "delivery": true, "takeout": true } }, { "receiptMethodId": 687826, "name": "Visa Refeição", "paymentMethodId": 381239, "active": false, "channels": { "delivery": true, "takeout": true } } ] } ``` ## Campos da resposta - `storeId` *number* — ID do restaurante. - `merchantId` *number* — ID do cardápio. - `items[].receiptMethodId` *number* — ID do recebimento configurado. - `items[].name` *string* — Nome exibido. - `items[].paymentMethodId` *number* — ID da forma de pagamento. - `items[].active` *boolean* — Indica se está ativo. - `items[].sortOrder` *number* — Ordem de exibição. - `items[].instructions` *string* — Instruções para o cliente. - `items[].pixKey` *string* — Chave Pix - `items[].channels.delivery` *boolean* — Disponível na entrega. - `items[].channels.takeout` *boolean* — Disponível na retirada. - `items[].adjustment` *object* — Desconto/acréscimo desta forma. ## Erros | Status | Mensagem | | --- | --- | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the store:read scope | | 404 | Merchant ID 99 not found | ## Servidor MCP — BeeFood API --- title: "Servidor MCP — BeeFood API" description: "Conecte Claude, ChatGPT, Cursor ou outro assistente ao servidor MCP da documentação da API BeeFood." url: "https://developer.beefood.com.br/docs/mcp" group: "Referência" lang: "pt" --- # MCP Servidor MCP (Model Context Protocol) com toda a documentação da API BeeFood, para assistentes de IA integrarem mais rápido. ## URL do servidor `https://docs.beefood.app/mcp` ## Ferramentas disponíveis - `listar_endpoints` — Lista todos os endpoints documentados. - `detalhe_endpoint` — Detalha um endpoint, com parâmetros, erros e um exemplo de requisição em curl. - `search_beefood_api` — Busca por texto livre. - `query_docs_filesystem_beefood_api` — Lê uma página inteira em Markdown. - `execute_beefood_request` — Autentica e executa uma chamada real. - `submit_feedback` — Reporta um problema na documentação. ## Conectar a BeeFood ao ChatGPT --- title: "Conectar a BeeFood ao ChatGPT" description: "Conecte seu restaurante BeeFood ao ChatGPT e consulte pedidos, cardápio e clientes com os acessos que você liberar." url: "https://developer.beefood.com.br/docs/mcp/chatgpt" group: "Referência" lang: "pt" --- # Conectar a BeeFood ao ChatGPT Com a BeeFood conectada, você pergunta ao ChatGPT sobre o seu restaurante em linguagem natural: pedidos do dia, cardápio, clientes, cupons e avaliações. O ChatGPT consulta os dados reais do restaurante, apenas com os acessos que você liberar. A conexão leva cerca de 3 minutos e é feita uma única vez. ## Antes de começar Você vai precisar de: - Uma conta no [ChatGPT](https://chatgpt.com). O plano gratuito funciona. - O login e a senha do painel BeeFood do seu restaurante. Deixe estes dados à mão, você vai copiá-los no passo 3: | Campo | Valor | |---|---| | Nome | `BeeFood` | | URL do servidor | `https://docs.beefood.app/mcp` | | Autenticação | `OAuth` | ## Passo a passo ### 1. Abra a página de Plugins No ChatGPT, clique em **Plugins** no menu lateral. ![Menu Plugins no ChatGPT](/__l5e/assets-v1/3a933956-324c-4222-ab69-f55eb7ce88ab/chatgpt-01-menu-plugins.png) ### 2. Adicione um servidor MCP personalizado No canto superior direito, clique em **Adicionar** e escolha **Adicionar servidor MCP personalizado**. ![Adicionar servidor MCP personalizado](/__l5e/assets-v1/e46ea4e3-c070-413b-a6a0-3d6e9b0bfd15/chatgpt-02-adicionar-servidor-mcp.png) ### 3. Preencha o formulário 1. Em **Nome**, digite `BeeFood`. 2. Deixe **Descrição** em branco, se preferir. O campo é opcional. 3. Em **Conexão**, mantenha **URL do servidor** selecionado e cole `https://docs.beefood.app/mcp`. 4. Em **Autenticação**, escolha **OAuth**. 5. Não altere as **Configurações avançadas de OAuth**. O ChatGPT detecta tudo sozinho. 6. Leia o aviso e marque **Entendo e quero continuar**. 7. Clique em **Criar como plugin**. ![Formulário do servidor MCP](/__l5e/assets-v1/868a0d3f-ba61-47ce-968f-55ba6d269249/chatgpt-03-formulario-mcp.png) ### 4. Continue para a BeeFood O ChatGPT mostra a tela **Conectar a BeeFood**. Clique em **Continuar em BeeFood**. ![Botão Continuar em BeeFood](/__l5e/assets-v1/321d6b22-1b73-4295-944e-aeff85b83c87/chatgpt-04-continuar-em-beefood.png) ### 5. Entre com a sua conta BeeFood Você é levado para o site da BeeFood. Digite o login e a senha do painel do seu restaurante e clique em **Entrar**. Se você já estiver logado no painel BeeFood nesse navegador, esta tela não aparece e você vai direto para o passo 6. ![Login da BeeFood](/__l5e/assets-v1/bcc35705-c68b-4f9e-962c-e6f3a106759e/chatgpt-05-login-beefood.png) ### 6. Escolha o que o ChatGPT pode acessar Na tela **Conectar com BeeFood**: 1. Confira se a tela diz **ChatGPT está pedindo acesso ao seu restaurante**. 2. Confira em **Autorizando como** se o restaurante está correto. Se você tem mais de um restaurante, troque pela lista logo abaixo do nome. 3. Marque as permissões que deseja liberar nas colunas **Leitura** e **Escrita**. O botão **Permitir** só fica ativo depois que você marca pelo menos uma. 4. Clique em **Permitir**. O que cada coluna libera: - **Leitura**: o ChatGPT pode consultar os dados. Exemplo: listar pedidos. - **Escrita**: o ChatGPT também pode alterar os dados. Exemplo: mudar o status de um pedido ou criar um cupom. Se preferir, marque só **Leitura** e libere **Escrita** depois, quando precisar. | Permissão | O que o ChatGPT consegue ver ou alterar | |---|---| | Restaurante | Dados do restaurante | | Pedidos | Pedidos e seus status | | Catálogo | Cardápio: grupos, produtos e complementos | | Clientes | Cadastro de clientes | | Cupons | Cupons de desconto | | Avaliações | Avaliações dos clientes | | Entregadores | Em breve | | Estoque | Em breve | ![Tela de permissões da BeeFood](/__l5e/assets-v1/126285ee-5428-49c9-a58c-5b915af0845a/chatgpt-06-permissoes.png) ### 7. Volte ao ChatGPT e abra um novo chat Depois de clicar em **Permitir**, você volta para a página de Plugins do ChatGPT, com o BeeFood na lista de **Instalados**. Clique em **Novo chat**. ![Botão Novo chat](/__l5e/assets-v1/ff5ffcca-26f1-4f64-8980-41ac2cae245f/chatgpt-07-novo-chat.png) ### 8. Faça a primeira pergunta Pergunte algo sobre o seu restaurante. Por exemplo: > Liste os últimos 5 pedidos realizados em meu restaurante ![Primeira pergunta no ChatGPT](/__l5e/assets-v1/3beca9d4-ed2d-4ebc-bed1-d912b5a432e8/chatgpt-08-primeira-pergunta.png) ### 9. Pronto O ChatGPT consulta a BeeFood e responde com os dados do seu restaurante. ![Resposta com os pedidos](/__l5e/assets-v1/5b05b919-3be9-4db5-bf24-e7bed80ed6b2/chatgpt-09-resposta-pedidos.png) ## Exemplos de perguntas - Quanto vendi hoje? - Liste os produtos do meu cardápio. - Quais pedidos ainda estão em aberto? - Liste os cupons ativos. - Mostre as últimas avaliações dos clientes. Antes de qualquer alteração, como mudar o status de um pedido ou criar um cupom, o ChatGPT pede a sua confirmação. ## Segurança - O ChatGPT acessa os **dados reais** do seu restaurante, apenas com as permissões que você marcou no passo 6. - A sua senha da BeeFood é digitada no site da BeeFood e nunca é compartilhada com o ChatGPT. - Você pode cancelar o acesso a qualquer momento. ## Como desconectar Você pode cancelar o acesso por qualquer um dos dois lados: - **No painel BeeFood**: no menu de API, revogue o acesso do ChatGPT. - **No ChatGPT**: em **Plugins**, abra o BeeFood na lista de **Instalados** e desconecte ou remova o plugin. ## Problemas comuns **"Já existe um aplicativo com esse nome. Escolha outro nome."** Já existe um plugin com o nome `BeeFood` na sua conta do ChatGPT. Use outro nome, como `BeeFood API`, ou remova o plugin antigo em **Plugins**. **O botão "Permitir" não fica ativo.** Marque pelo menos uma permissão na tabela do passo 6. **O ChatGPT diz que não tem permissão para ver ou alterar algo.** A permissão necessária não foi marcada no passo 6. Desconecte e conecte de novo, marcando o acesso que falta. Por exemplo, para perguntas sobre pedidos, marque **Pedidos**. **Demorei para fazer o login e a conexão deu erro.** O link de autorização expira em poucos minutos. Volte para **Plugins**, abra o BeeFood e clique em **Continuar em BeeFood** de novo. **O ChatGPT respondeu sem consultar a BeeFood.** Cite a BeeFood ou o seu restaurante na pergunta. Por exemplo: "No meu restaurante BeeFood, quais pedidos estão em aberto?". ## Conectar a BeeFood ao Claude --- title: "Conectar a BeeFood ao Claude" description: "Conecte seu restaurante BeeFood ao Claude e consulte pedidos, cardápio e clientes com os acessos que você liberar." url: "https://developer.beefood.com.br/docs/mcp/claude" group: "Referência" lang: "pt" --- # Conectar a BeeFood ao Claude Com a BeeFood conectada, você pergunta ao Claude sobre o seu restaurante em linguagem natural: pedidos do dia, cardápio, clientes, cupons e avaliações. O Claude consulta os dados reais do restaurante, apenas com os acessos que você liberar. A conexão leva cerca de 3 minutos e é feita uma única vez. ## Antes de começar Você vai precisar de: - Uma conta no [Claude](https://claude.ai). O plano gratuito funciona, mas permite apenas um conector personalizado. - O login e a senha do painel BeeFood do seu restaurante. Deixe estes dados à mão, você vai copiá-los no passo 3: | Campo | Valor | |---|---| | Nome | `BeeFood` | | URL | `https://docs.beefood.app/mcp` | ## Passo a passo ### 1. Abra a Personalização No Claude, clique em **Personalização** no menu lateral. ![Menu Personalização no Claude](/__l5e/assets-v1/530bc3aa-64c1-4e2e-886d-1f55d2f48060/claude-01-menu-personalizacao.png) ### 2. Adicione um conector personalizado Abra a aba **Conectores**, clique em **Adicionar**, no canto superior direito, e escolha **Adicionar conector personalizado**. ![Adicionar conector personalizado](/__l5e/assets-v1/67a75716-045a-4d73-9f55-87d813ddc5db/claude-02-adicionar-conector.png) ### 3. Informe o nome e a URL 1. No primeiro campo, digite `BeeFood`. 2. No segundo campo, cole `https://docs.beefood.app/mcp`. 3. Clique em **Continuar**. ![Nome e URL do conector](/__l5e/assets-v1/617e4036-6c37-42e4-ba78-ac1ff610e583/claude-03-nome-url.png) ### 4. Escolha a autenticação 1. Em **Autenticação**, marque **Entrar agora**. O Claude pode sugerir **Sem login** com a etiqueta **Detectado**. Não use essa opção: o Claude precisa do login para acessar os dados do seu restaurante. 2. Em **Cliente OAuth**, mantenha **Usar a identidade publicada do Claude**. 3. Clique em **Adicionar**. ![Opções de autenticação](/__l5e/assets-v1/99e50002-d403-4d2a-8c3a-8ee0cdf993d4/claude-04-autenticacao.png) ### 5. Vincule a sua conta O Claude abre o site da BeeFood para você entrar. Se a janela não abrir, ou se você a fechou antes de terminar, a página do conector mostra **Você começou a se conectar a BeeFood, mas não concluiu**. Clique em **Vincular**. ![Botão Vincular](/__l5e/assets-v1/f8c15ee6-4189-49f6-adf1-c01bb2a5b532/claude-05-vincular.png) ### 6. Entre com a sua conta BeeFood Digite o login e a senha do painel do seu restaurante e clique em **Entrar**. Se você já estiver logado no painel BeeFood nesse navegador, esta tela não aparece e você vai direto para o passo 7. ![Login da BeeFood](/__l5e/assets-v1/f849bf6f-5e98-44a1-9641-257f83cb787e/claude-06-login-beefood.png) ### 7. Escolha o que o Claude pode acessar Na tela **Conectar com BeeFood**: 1. Confira se a tela diz **Claude está pedindo acesso ao seu restaurante**. 2. Confira em **Autorizando como** se o restaurante está correto. Se você tem mais de um restaurante, troque pela lista logo abaixo do nome. 3. Marque as permissões que deseja liberar nas colunas **Leitura** e **Escrita**. O botão **Permitir** só fica ativo depois que você marca pelo menos uma. 4. Clique em **Permitir**. O que cada coluna libera: - **Leitura**: o Claude pode consultar os dados. Exemplo: listar pedidos. - **Escrita**: o Claude também pode alterar os dados. Exemplo: mudar o status de um pedido ou criar um cupom. Se preferir, marque só **Leitura** e libere **Escrita** depois, quando precisar. | Permissão | O que o Claude consegue ver ou alterar | |---|---| | Restaurante | Dados do restaurante | | Pedidos | Pedidos e seus status | | Catálogo | Cardápio: grupos, produtos e complementos | | Clientes | Cadastro de clientes | | Cupons | Cupons de desconto | | Avaliações | Avaliações dos clientes | | Entregadores | Em breve | | Estoque | Em breve | ![Tela de permissões da BeeFood](/__l5e/assets-v1/a3e18921-4791-406a-9dce-aeefa8f2f0e5/claude-07-permissoes.png) ### 8. Ajuste as permissões das ferramentas Depois de clicar em **Permitir**, você volta para o Claude, na página do conector BeeFood. Ela lista as ferramentas da BeeFood em dois grupos: - **Ferramentas somente leitura**: consultam a documentação da BeeFood. Já vêm como **Sempre permitir**. - **Ferramentas de gravação/exclusão**: acessam os dados do seu restaurante. Vêm como **Requer aprovação**. Para o Claude não pedir a sua autorização a cada pergunta, mude **Ferramentas de gravação/exclusão** para **Sempre permitir**. Em seguida, clique em **Novo** no menu lateral. A ferramenta **Authenticate and execute BeeFood request** é a mesma para consultar e para alterar dados. Com **Sempre permitir**, o Claude também deixa de pedir confirmação antes de alterações, como mudar o status de um pedido. Se preferir confirmar cada uso, mantenha **Requer aprovação**: a cada consulta, o Claude vai perguntar se você quer **Permitir uma vez**, **Sempre permitir** ou **Negar**. ![Permissões das ferramentas no Claude](/__l5e/assets-v1/138057f5-fba1-4f37-8763-732f76a33f4f/claude-08-permissoes-ferramentas.png) ### 9. Faça a primeira pergunta Pergunte algo sobre o seu restaurante. Por exemplo: > Liste os últimos 5 pedidos realizados em meu restaurante ![Primeira pergunta no Claude](/__l5e/assets-v1/ab42a924-8fe2-4e95-a093-28c35572d5ce/claude-09-primeira-pergunta.png) ### 10. Pronto O Claude consulta a BeeFood e responde com os dados do seu restaurante. ![Resposta com os pedidos](/__l5e/assets-v1/a61009a2-9395-4e2b-a487-aeb4a3cc0776/claude-10-resposta-pedidos.png) ## Exemplos de perguntas - Quanto vendi hoje? - Liste os produtos do meu cardápio. - Quais pedidos ainda estão em aberto? - Liste os cupons ativos. - Mostre as últimas avaliações dos clientes. ## Segurança - O Claude acessa os **dados reais** do seu restaurante, apenas com as permissões que você marcou no passo 7. - A sua senha da BeeFood é digitada no site da BeeFood e nunca é compartilhada com o Claude. - Você pode cancelar o acesso a qualquer momento. ## Como desconectar Você pode cancelar o acesso por qualquer um dos dois lados: - **No painel BeeFood**: no menu de API, revogue o acesso do Claude. - **No Claude**: em **Personalização → Conectores**, abra o BeeFood e clique em **Desvincular**. ## Problemas comuns **Não consigo adicionar o conector no plano gratuito.** O plano gratuito do Claude permite apenas um conector personalizado. Remova o conector que você já tem em **Personalização → Conectores** e adicione o BeeFood. **O Claude não consegue acessar os dados do restaurante.** Confira se a autenticação ficou como **Entrar agora** no passo 4. Se ficou como **Sem login**, remova o conector e adicione de novo, marcando **Entrar agora**. **O botão "Permitir" não fica ativo.** Marque pelo menos uma permissão na tabela do passo 7. **O Claude diz que não tem permissão para ver ou alterar algo.** A permissão necessária não foi marcada no passo 7. Clique em **Desvincular**, depois em **Vincular**, e marque o acesso que falta. Por exemplo, para perguntas sobre pedidos, marque **Pedidos**. **Demorei para fazer o login e a conexão deu erro.** O link de autorização expira em poucos minutos. Abra o BeeFood em **Personalização → Conectores** e clique em **Vincular** de novo. ## Autorizar conexão — BeeFood API --- title: "Autorizar conexão — BeeFood API" description: "GET https://beefood.app/oauth/authorize: autorização do lojista via Authorization Code com PKCE." url: "https://developer.beefood.com.br/docs/oauth/autorizar-conexao" group: "OAuth" lang: "pt" --- # Autorizar conexão `GET https://beefood.app/oauth/authorize` Sandbox: https://api-sandbox.beefood.app/oauth/authorize Solicita a autorização da conta principal do restaurante para a integradora. Cadastre o aplicativo e redirect URIs HTTPS com a BeeFood. Monte uma URL nova no servidor a cada clique. redirect_uri deve corresponder exatamente ao cadastrado (inclusive barra final e query string). | Query | Required | Description | | --- | --- | --- | | response_type | yes | code | | client_id | yes | BeeFood-provided integrator identifier | | redirect_uri | yes | Exactly registered HTTPS callback | | code_challenge | yes | BASE64URL(SHA256(code_verifier)) | | code_challenge_method | yes | S256 | | state | recommended | Fresh random value, verify on callback | ```text https://beefood.app/oauth/authorize?response_type=code&client_id=Repediu&redirect_uri=https%3A%2F%2Fapp.integradora.com%2Fbeefood%2Fcallback&code_challenge=YZepGGrPF9LWl8rmMFjUP67rBrik9zXyJtrM_mxZ99c&code_challenge_method=S256&state=8f26c4a1d9e34b60a27f15e8c90d6b43 ``` O lojista escolhe os escopos no consentimento, não na URL. Apenas a conta principal pode autorizar. Se client_id ou redirect_uri for inválido, a BeeFood mostra erro sem redirecionar. O lojista entra com o login do beefood.app (conta principal do restaurante). Se já estiver logado, vai direto para a tela de consentimento. > Recomendado: não fixe o endereço da tela no código. Leia authorization_endpoint em GET https://api.beefood.app/.well-known/oauth-authorization-server (sandbox: https://api-sandbox.beefood.app/.well-known/oauth-authorization-server). Assim sua integração acompanha mudanças futuras sem ajuste. ## Callback ```text https://app.integradora.com/beefood/callback?code=bf_ac_4af8c92e1b6742d7a0539ec8640f2b1d&state=8f26c4a1d9e34b60a27f15e8c90d6b43&iss=https%3A%2F%2Fapi.beefood.app ``` ```text https://app.integradora.com/beefood/callback?error=access_denied&error_description=The%20user%20denied%20the%20request&state=8f26c4a1d9e34b60a27f15e8c90d6b43 ``` Confira state com a sessão antes da troca. O code vale 10 minutos e só pode ser usado uma vez. O iss do callback continua sendo o da API (https://api.beefood.app), não o do beefood.app. ## Revogar token — BeeFood API --- title: "Revogar token — BeeFood API" description: "POST /v1/oauth/revoke: revogar os tokens de Conectar com BeeFood sem client_secret." url: "https://developer.beefood.com.br/docs/oauth/desconectar" group: "OAuth" lang: "pt" --- # Revogar token `POST /v1/oauth/revoke` - Produção: `https://api.beefood.app/v1/oauth/revoke` - Sandbox: `https://api-sandbox.beefood.app/v1/oauth/revoke` Encerra a conexão autorizada pelo lojista. Content-Type: application/x-www-form-urlencoded | Body | Required | Description | | --- | --- | --- | | client_id | yes | Integrator identifier | | token | yes | Access or refresh token | ```bash curl -X POST 'https://api.beefood.app/v1/oauth/revoke' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=Repediu' --data-urlencode 'token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5iZWVmb29kLmFwcCIsInN1YiI6InN0b3JlXzhhMTJkNmVmIiwiYXVkIjoiYmVlZm9vZC1hcGkiLCJzY29wZSI6Im9mZmxpbmVfYWNjZXNzIiwianRpIjoiZjAzYTE5YjciLCJpYXQiOjE3OTA5MzUyMDAsImV4cCI6MTc5MzUyNzIwMH0.c2ltdWxhZG8tYXBlbmFzLWV4ZW1wbG8' ``` Resposta 200 sem corpo, mesmo para token já inválido. Revogar access ou refresh invalida ambos; não exige client_secret. O lojista também pode desconectar pelo portal Developers. ## Gerar token — BeeFood API --- title: "Gerar token — BeeFood API" description: "POST /v1/oauth/token com grantType client_credentials: emissão do par accessToken e refreshToken." url: "https://developer.beefood.com.br/docs/oauth/emitir-tokens" group: "OAuth" lang: "pt" --- # Gerar token `POST /v1/oauth/token` - Produção: `https://api.beefood.app/v1/oauth/token` - Sandbox: `https://api-sandbox.beefood.app/v1/oauth/token` Emite o par de tokens da credencial. ## Body | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | grantType | string | sim | Define o contrato do body. Valor: `"client_credentials"`. | | clientId | uuid | sim | Identificador público da credencial. | | clientSecret | string | sim | Segredo devolvido apenas na criação da credencial. | ## Resposta de sucesso ```json { "accessToken": "", "refreshToken": "", "expiresAt": "2026-08-18T16:00:00.000Z" } ``` ## Erros | Status | Mensagem | | --- | --- | | 400 | grantType is required | | 400 | grantType must be client_credentials or refresh_token | | 400 | clientId is required | | 400 | clientSecret is required | | 401 | Invalid client credentials | | 500 | Database error when trying to … | ## OAuth — BeeFood API --- title: "OAuth — BeeFood API" description: "Autenticação do parceiro BeeFood: emitir, renovar e revogar tokens OAuth." url: "https://developer.beefood.com.br/docs/oauth/index" group: "OAuth" lang: "pt" --- # Autenticação — API BeeFood As duas opções são OAuth 2.0 e geram tokens para as mesmas rotas /v1, escopos e header Authorization: Bearer. O que muda é como o token é obtido. | | Integração direta | Conectar com BeeFood | | --- | --- | --- | | Fluxo | Client Credentials | Authorization Code + PKCE | | Credencial | Lojista cria no portal Developers | Lojista conecta no site da integradora | | Integradora recebe | clientId + clientSecret | Tokens sem ver segredo | | Indicado para | Sistema próprio ou poucos clientes | Muitos lojistas | | Cadastro prévio | Não | Não | ## Ambientes - Produção: https://api.beefood.app - Sandbox: https://api-sandbox.beefood.app - Descoberta OAuth: GET /.well-known/oauth-authorization-server - Autorização (login + consentimento): produção https://beefood.app/oauth/authorize; sandbox https://api-sandbox.beefood.app/oauth/authorize - Token: POST /v1/oauth/token - Revogação: POST /v1/oauth/revoke ## Guia 1 — Integração direta (Client Credentials) O lojista cria uma credencial no portal Developers, escolhe os escopos e entrega clientId e clientSecret. O segredo aparece uma única vez e deve ficar apenas no servidor. a) Gerar token: ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/json' -d '{"grantType":"client_credentials","clientId":"","clientSecret":""}' ``` ```javascript const response = await fetch("https://api.beefood.app/v1/oauth/token", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ grantType: "client_credentials", clientId: "", clientSecret: "" }) }); const tokens = await response.json(); ``` Resposta 200: `{ "accessToken": "", "refreshToken": "", "expiresAt": "" }`. b) Renovar (refresh rotaciona imediatamente o par anterior): ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/json' -d '{"grantType":"refresh_token","clientId":"","refreshToken":""}' ``` ```javascript await fetch("https://api.beefood.app/v1/oauth/token", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ grantType: "refresh_token", clientId: "", refreshToken: "" }) }); ``` c) Revogar (200 sem corpo): ```bash curl -X POST 'https://api.beefood.app/v1/oauth/revoke' -H 'Content-Type: application/json' -d '{"clientId":"","clientSecret":"","token":""}' ``` ```javascript await fetch("https://api.beefood.app/v1/oauth/revoke", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ clientId: "", clientSecret: "", token: "" }) }); ``` ## Guia 2 — Conectar com BeeFood (Authorization Code + PKCE) Não existe cadastro prévio: a integradora escolhe o client_id (o nome do aplicativo, visto pelo lojista) e o redirect_uri. Não há client_secret; use os mesmos valores em todo o fluxo. 1. Backend gera code_verifier (43–128 caracteres), code_challenge = BASE64URL(SHA256(code_verifier)) sem padding e state novo a cada clique; guarda verifier e state na sessão. ```javascript import { randomBytes, createHash } from "node:crypto"; const codeVerifier = randomBytes(32).toString("base64url"); const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url"); const state = randomBytes(16).toString("base64url"); ``` 2. Redireciona o navegador a `https://beefood.app/oauth/authorize?response_type=code&client_id=&redirect_uri=&code_challenge=&code_challenge_method=S256&state=`. Só a conta principal pode autorizar; o lojista escolhe escopos no consentimento (não enviar scope na URL). 3. BeeFood devolve `code`, `state` e `iss` ao callback. Se recusado, `error=access_denied`. Conferir state com a sessão; descartar divergências. Client ID/redirect URI inválidos não redirecionam. 4. O backend troca o code (10 minutos, uso único) com code_verifier: ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'client_id=' --data-urlencode 'code=' --data-urlencode 'redirect_uri=' --data-urlencode 'code_verifier=' ``` ```javascript const body = new URLSearchParams({ grant_type: "authorization_code", client_id: "", code: "", redirect_uri: "", code_verifier: codeVerifier }); const response = await fetch("https://api.beefood.app/v1/oauth/token", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body }); const tokens = await response.json(); ``` Resposta 200: `{ "access_token": "", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "" }`. 5. GET /v1/store/merchants com Authorization: Bearer identifica os restaurantes autorizados. Renovar: ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode 'client_id=' --data-urlencode 'refresh_token=' ``` ```javascript await fetch("https://api.beefood.app/v1/oauth/token", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ grant_type: "refresh_token", client_id: "", refresh_token: "" }) }); ``` Desconectar (200 sem corpo, mesmo se token já inválido): ```bash curl -X POST 'https://api.beefood.app/v1/oauth/revoke' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=' --data-urlencode 'token=' ``` ```javascript await fetch("https://api.beefood.app/v1/oauth/revoke", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ client_id: "", token: "" }) }); ``` ## Uso, escopos e erros Use `Authorization: Bearer ` em /v1. Access token dura 1 hora, refresh token 30 dias. Renove antes de expirar ou após 401; salve o par novo de forma atômica, uma renovação por restaurante. Se falhar com 401, reconecte. Escrita inclui leitura do mesmo recurso. Veja https://developer.beefood.com.br/docs/scopes. Ausência do escopo retorna 403. Erro padrão: `{ "message": "Invalid client credentials", "status": 401 }`. 400: campo obrigatório ou grant_type inválido; 401: credencial, code, verifier, refresh ou token inválido/expirado; 403: escopo insuficiente. Segurança: PKCE e state novos no backend a cada clique; conferir state; trocar code no backend; criptografar tokens por restaurante; salvar refresh rotacionado atomicamente; nunca repetir escritas POST/PUT/PATCH/DELETE após timeout; oferecer Desconectar chamando /v1/oauth/revoke. Página: https://developer.beefood.com.br/docs/oauth/usar-token ## Renovar token — BeeFood API --- title: "Renovar token — BeeFood API" description: "POST /v1/oauth/token com grant_type refresh_token: renovar tokens de Conectar com BeeFood." url: "https://developer.beefood.com.br/docs/oauth/renovar-conexao" group: "OAuth" lang: "pt" --- # Renovar token `POST /v1/oauth/token` - Produção: `https://api.beefood.app/v1/oauth/token` - Sandbox: `https://api-sandbox.beefood.app/v1/oauth/token` Renova os tokens da conexão autorizada pelo lojista. Content-Type: application/json (application/x-www-form-urlencoded também aceito) | Body | Required | Description | | --- | --- | --- | | grant_type | yes | refresh_token | | client_id | yes | Integrator identifier | | refresh_token | yes | Current store refresh token | ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/json' -d '{"grant_type":"refresh_token","client_id":"Repediu","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5iZWVmb29kLmFwcCIsInN1YiI6InN0b3JlXzhhMTJkNmVmIiwiYXVkIjoiYmVlZm9vZC1hcGkiLCJzY29wZSI6Im9mZmxpbmVfYWNjZXNzIiwianRpIjoiY2Q3MWE4NDAiLCJpYXQiOjE3OTA5MzUyMDAsImV4cCI6MTc5MzUyNzIwMH0.c2ltdWxhZG8tYXBlbmFzLWV4ZW1wbG8"}' ``` ## Resposta 200 ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5iZWVmb29kLmFwcCIsInN1YiI6InN0b3JlXzhhMTJkNmVmIiwiYXVkIjoiYmVlZm9vZC1hcGkiLCJzY29wZSI6Im9yZGVyczpyZWFkIG1lbnU6cmVhZCIsImp0aSI6ImU4ZDJjMzE0IiwiaWF0IjoxNzkwOTM1MjAwLCJleHAiOjE3OTA5Mzg4MDB9.c2ltdWxhZG8tYXBlbmFzLWV4ZW1wbG8", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5iZWVmb29kLmFwcCIsInN1YiI6InN0b3JlXzhhMTJkNmVmIiwiYXVkIjoiYmVlZm9vZC1hcGkiLCJzY29wZSI6Im9mZmxpbmVfYWNjZXNzIiwianRpIjoiZjAzYTE5YjciLCJpYXQiOjE3OTA5MzUyMDAsImV4cCI6MTc5MzUyNzIwMH0.c2ltdWxhZG8tYXBlbmFzLWV4ZW1wbG8" } ``` O access token vale 1 hora e o refresh token 30 dias. Cada renovação invalida o refresh anterior imediatamente. Salve o novo par de forma atômica, uma renovação por restaurante de cada vez. Após 401, solicite nova conexão. ## Renovar token — BeeFood API --- title: "Renovar token — BeeFood API" description: "POST /v1/oauth/token com grantType refresh_token: renovação do par de tokens sem usar o clientSecret." url: "https://developer.beefood.com.br/docs/oauth/renovar-tokens" group: "OAuth" lang: "pt" --- # Renovar token `POST /v1/oauth/token` - Produção: `https://api.beefood.app/v1/oauth/token` - Sandbox: `https://api-sandbox.beefood.app/v1/oauth/token` Renova o par de tokens da credencial. ## Body | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | grantType | string | sim | Define o contrato do body. Valor: `"refresh_token"`. | | clientId | uuid | sim | Identificador público da credencial. | | refreshToken | string (jwt) | sim | Refresh token atual da integração. | ## Resposta de sucesso ```json { "accessToken": "", "refreshToken": "", "expiresAt": "2026-08-18T16:00:00.000Z" } ``` ## Comportamento A cada renovação a API gera um novo par accessToken + refreshToken. O refreshToken anterior deixa de valer imediatamente. ## Erros | Status | Mensagem | | --- | --- | | 400 | refreshToken is required | | 400 | grantType must be client_credentials or refresh_token | | 400 | clientId is required | | 401 | Invalid client credentials | ## Revogar token — BeeFood API --- title: "Revogar token — BeeFood API" description: "POST /v1/oauth/revoke: revogação da geração atual de tokens de uma credencial da API BeeFood." url: "https://developer.beefood.com.br/docs/oauth/revogar-tokens" group: "OAuth" lang: "pt" --- # Revogar token `POST /v1/oauth/revoke` - Produção: `https://api.beefood.app/v1/oauth/revoke` - Sandbox: `https://api-sandbox.beefood.app/v1/oauth/revoke` Revoga os tokens da credencial. ## Body | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | clientId | uuid | sim | Identificador público da credencial. | | clientSecret | string | sim | Segredo devolvido apenas na criação da credencial. | | token | string | sim | accessToken ou refreshToken da credencial. | ## Resposta de sucesso Sucesso responde 200 sem corpo. ## Erros | Status | Mensagem | | --- | --- | | 400 | clientId is required | | 400 | clientSecret is required | | 400 | token is required | | 401 | Invalid client credentials | ## Trocar código por token — BeeFood API --- title: "Trocar código por token — BeeFood API" description: "POST /v1/oauth/token com grant_type authorization_code e PKCE para Conectar com BeeFood." url: "https://developer.beefood.com.br/docs/oauth/trocar-codigo" group: "OAuth" lang: "pt" --- # Trocar código por token `POST /v1/oauth/token` - Produção: `https://api.beefood.app/v1/oauth/token` - Sandbox: `https://api-sandbox.beefood.app/v1/oauth/token` Troca o código de autorização por tokens no fluxo Conectar com BeeFood. Envie JSON ou application/x-www-form-urlencoded do servidor após validar state. Não usa client_secret. | Body | Required | Description | | --- | --- | --- | | grant_type | yes | authorization_code | | client_id | yes | Integrator identifier | | code | yes | Callback code, valid 10 minutes and one use | | redirect_uri | yes | Exact same URI sent during authorization | | code_verifier | yes | Original PKCE verifier from the session | ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/json' -d '{"grant_type":"authorization_code","client_id":"Repediu","code":"bf_ac_4af8c92e1b6742d7a0539ec8640f2b1d","redirect_uri":"https://app.integradora.com/beefood/callback","code_verifier":"R7qY4uW9pL2mC8xB5nK3dF6sA0hT1jV4eZ7gQ2rM9wP5yN8bD3cH6kS0fU1aX4zJ"}' ``` ## Resposta 200 ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5iZWVmb29kLmFwcCIsInN1YiI6InN0b3JlXzhhMTJkNmVmIiwiYXVkIjoiYmVlZm9vZC1hcGkiLCJzY29wZSI6Im9yZGVyczpyZWFkIG1lbnU6cmVhZCIsImp0aSI6ImI5ZjRjMTBlIiwiaWF0IjoxNzkwOTM1MjAwLCJleHAiOjE3OTA5Mzg4MDB9.c2ltdWxhZG8tYXBlbmFzLWV4ZW1wbG8", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5iZWVmb29kLmFwcCIsInN1YiI6InN0b3JlXzhhMTJkNmVmIiwiYXVkIjoiYmVlZm9vZC1hcGkiLCJzY29wZSI6Im9mZmxpbmVfYWNjZXNzIiwianRpIjoiY2Q3MWE4NDAiLCJpYXQiOjE3OTA5MzUyMDAsImV4cCI6MTc5MzUyNzIwMH0.c2ltdWxhZG8tYXBlbmFzLWV4ZW1wbG8" } ``` GET /v1/store/merchants com Authorization: Bearer identifica os restaurantes autorizados. Erros seguem {message, status}: 400 para parâmetros inválidos; 401 para code expirado, reutilizado ou PKCE incorreto. ## Autenticação — BeeFood API --- title: "Autenticação — BeeFood API" description: "Integração direta (Client Credentials) e Conectar com BeeFood (Authorization Code + PKCE)." url: "https://developer.beefood.com.br/docs/oauth/usar-token" group: "OAuth" lang: "pt" --- # Autenticação — API BeeFood As duas opções são OAuth 2.0 e geram tokens para as mesmas rotas /v1, escopos e header Authorization: Bearer. O que muda é como o token é obtido. | | Integração direta | Conectar com BeeFood | | --- | --- | --- | | Fluxo | Client Credentials | Authorization Code + PKCE | | Credencial | Lojista cria no portal Developers | Lojista conecta no site da integradora | | Integradora recebe | clientId + clientSecret | Tokens sem ver segredo | | Indicado para | Sistema próprio ou poucos clientes | Muitos lojistas | | Cadastro prévio | Não | Não | ## Ambientes - Produção: https://api.beefood.app - Sandbox: https://api-sandbox.beefood.app - Descoberta OAuth: GET /.well-known/oauth-authorization-server - Autorização (login + consentimento): produção https://beefood.app/oauth/authorize; sandbox https://api-sandbox.beefood.app/oauth/authorize - Token: POST /v1/oauth/token - Revogação: POST /v1/oauth/revoke ## Guia 1 — Integração direta (Client Credentials) O lojista cria uma credencial no portal Developers, escolhe os escopos e entrega clientId e clientSecret. O segredo aparece uma única vez e deve ficar apenas no servidor. a) Gerar token: ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/json' -d '{"grantType":"client_credentials","clientId":"","clientSecret":""}' ``` ```javascript const response = await fetch("https://api.beefood.app/v1/oauth/token", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ grantType: "client_credentials", clientId: "", clientSecret: "" }) }); const tokens = await response.json(); ``` Resposta 200: `{ "accessToken": "", "refreshToken": "", "expiresAt": "" }`. b) Renovar (refresh rotaciona imediatamente o par anterior): ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/json' -d '{"grantType":"refresh_token","clientId":"","refreshToken":""}' ``` ```javascript await fetch("https://api.beefood.app/v1/oauth/token", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ grantType: "refresh_token", clientId: "", refreshToken: "" }) }); ``` c) Revogar (200 sem corpo): ```bash curl -X POST 'https://api.beefood.app/v1/oauth/revoke' -H 'Content-Type: application/json' -d '{"clientId":"","clientSecret":"","token":""}' ``` ```javascript await fetch("https://api.beefood.app/v1/oauth/revoke", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ clientId: "", clientSecret: "", token: "" }) }); ``` ## Guia 2 — Conectar com BeeFood (Authorization Code + PKCE) Não existe cadastro prévio: a integradora escolhe o client_id (o nome do aplicativo, visto pelo lojista) e o redirect_uri. Não há client_secret; use os mesmos valores em todo o fluxo. 1. Backend gera code_verifier (43–128 caracteres), code_challenge = BASE64URL(SHA256(code_verifier)) sem padding e state novo a cada clique; guarda verifier e state na sessão. ```javascript import { randomBytes, createHash } from "node:crypto"; const codeVerifier = randomBytes(32).toString("base64url"); const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url"); const state = randomBytes(16).toString("base64url"); ``` 2. Redireciona o navegador a `https://beefood.app/oauth/authorize?response_type=code&client_id=&redirect_uri=&code_challenge=&code_challenge_method=S256&state=`. Só a conta principal pode autorizar; o lojista escolhe escopos no consentimento (não enviar scope na URL). 3. BeeFood devolve `code`, `state` e `iss` ao callback. Se recusado, `error=access_denied`. Conferir state com a sessão; descartar divergências. Client ID/redirect URI inválidos não redirecionam. 4. O backend troca o code (10 minutos, uso único) com code_verifier: ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'client_id=' --data-urlencode 'code=' --data-urlencode 'redirect_uri=' --data-urlencode 'code_verifier=' ``` ```javascript const body = new URLSearchParams({ grant_type: "authorization_code", client_id: "", code: "", redirect_uri: "", code_verifier: codeVerifier }); const response = await fetch("https://api.beefood.app/v1/oauth/token", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body }); const tokens = await response.json(); ``` Resposta 200: `{ "access_token": "", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "" }`. 5. GET /v1/store/merchants com Authorization: Bearer identifica os restaurantes autorizados. Renovar: ```bash curl -X POST 'https://api.beefood.app/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode 'client_id=' --data-urlencode 'refresh_token=' ``` ```javascript await fetch("https://api.beefood.app/v1/oauth/token", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ grant_type: "refresh_token", client_id: "", refresh_token: "" }) }); ``` Desconectar (200 sem corpo, mesmo se token já inválido): ```bash curl -X POST 'https://api.beefood.app/v1/oauth/revoke' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=' --data-urlencode 'token=' ``` ```javascript await fetch("https://api.beefood.app/v1/oauth/revoke", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ client_id: "", token: "" }) }); ``` ## Uso, escopos e erros Use `Authorization: Bearer ` em /v1. Access token dura 1 hora, refresh token 30 dias. Renove antes de expirar ou após 401; salve o par novo de forma atômica, uma renovação por restaurante. Se falhar com 401, reconecte. Escrita inclui leitura do mesmo recurso. Veja https://developer.beefood.com.br/docs/scopes. Ausência do escopo retorna 403. Erro padrão: `{ "message": "Invalid client credentials", "status": 401 }`. 400: campo obrigatório ou grant_type inválido; 401: credencial, code, verifier, refresh ou token inválido/expirado; 403: escopo insuficiente. Segurança: PKCE e state novos no backend a cada clique; conferir state; trocar code no backend; criptografar tokens por restaurante; salvar refresh rotacionado atomicamente; nunca repetir escritas POST/PUT/PATCH/DELETE após timeout; oferecer Desconectar chamando /v1/oauth/revoke. Página: https://developer.beefood.com.br/docs/oauth/usar-token ## Cancelar pedido --- title: "Cancelar pedido" description: "POST /v1/orders/{orderId}/cancel — cancela um pedido na API BeeFood." method: "POST" path: "/v1/orders/{orderId}/cancel" url: "https://developer.beefood.com.br/docs/pedidos/cancelar" group: "Pedidos" scope: "orders:write" lang: "pt" --- # Cancelar pedido `POST /v1/orders/{orderId}/cancel` - Produção: `https://api.beefood.app/v1/orders/{orderId}/cancel` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/{orderId}/cancel` Cancela um pedido DELIVERY, PDV ou TABLE. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `orderId` *integer* **obrigatório** — ID do pedido, maior ou igual a 1. Exemplo: `58449271`. ## Parâmetros do body - `cancellationReason` *string* **obrigatório** — Motivo do cancelamento. Exemplo: `"Cliente desistiu do pedido"`. ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/orders/{orderId}/cancel" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "cancellationReason": "Cliente desistiu do pedido" }' ``` ## Exemplos de resposta ### 200 OK ```json ``` ## Regras de cancelamento O sucesso responde 200 sem corpo; consulte `GET /v1/orders/{orderId}` para ver o pedido. O cancelamento devolve o estoque e dispara o webhook `order_updated`. ### Regras - Pedido com pagamento pago responde 409: remova o pagamento no PDV e repita a chamada. Pagamento só provisionado não bloqueia. - Pedido já cancelado responde 409, sem repetir webhook, estoque ou registro. - Pedido inexistente ou de outro restaurante responde 404. - A rota não remove pagamentos, não cancela a corrida na integradora de entrega e não emite aviso em tempo real para o painel. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'id' must be a positive integer | | 400 | 'cancellationReason' is required | | 400 | preVendaID is required | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:write scope | | 404 | Order 123 not found for company 1234. | | 409 | Order 123 is already canceled. | | 409 | Order 123 has 1 paid payment totaling R$ 48,90. Remove the payment before canceling. | | 429 | Too Many Requests | | 500 | Could not cancel order 123. | | 502 | Cancel order service unavailable | ## Criar pedido --- title: "Criar pedido" description: "POST /v1/orders — cria um pedido aberto no restaurante pela API BeeFood." method: "POST" path: "/v1/orders" url: "https://developer.beefood.com.br/docs/pedidos/criar" group: "Pedidos" scope: "orders:write" lang: "pt" --- # Criar pedido `POST /v1/orders` - Produção: `https://api.beefood.app/v1/orders` - Sandbox: `https://api-sandbox.beefood.app/v1/orders` Cria um pedido aberto no restaurante, sempre com canal de venda EXTERNAL. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros do body - `merchantId` *integer* **obrigatório** — Filial do restaurante. Aceita só merchant com cardápio publicado. Exemplo: `1`. - `orderType` *string* **obrigatório** — Tipo do pedido. Exemplo: `"DELIVERY"`. - *Valores:* `DELIVERY`, `PDV`, `TABLE` - `external` *object* — Identificadores externos do pedido. - `external.externalOrderId` *string* — ID do pedido no seu sistema, até 36 caracteres. Exemplo: `"PARCEIRO-123"`. - `usuarioId` *integer* — Usuário PDV do restaurante. Se ausente, usa o usuário vinculado ao dono da credencial. Exemplo: `12`. - `employeeId` *integer* — Funcionário que lançou o pedido. Exemplo: `5`. - `orderObservations` *string* — Observações do pedido. Exemplo: `"Sem cebola"`. - `customer` *object* — Cliente do pedido. Obrigatório em DELIVERY e com Fiado; encontrado pelo telefone ou criado. - `customer.customerName` *string* **obrigatório** — Nome do pedido e do cliente criado. Exemplo: `"Ana Souza"`. - `customer.email` *string* — E-mail, até 250 caracteres. Gravado só se o cadastro estiver vazio. Exemplo: `"joao@exemplo.com"`. - `customer.birthDate` *string (YYYY-MM-DD)* — Nascimento, não futuro. Gravado só se o cadastro estiver vazio. Exemplo: `"1990-12-31"`. - `customer.phone` *object* **obrigatório** — Telefone que identifica o cliente do restaurante. - `customer.phone.number` *string* **obrigatório** — Só dígitos, com DDD. Exemplo: `"11988887777"`. - `customer.phone.extension` *string* **obrigatório** — DDI. Exemplo: `"+55"`. - `customer.address` *object* — Endereço de entrega. Obrigatório em DELIVERY; proibido em TAKEOUT e DINE_IN. Encontrado por CEP, rua e número ou criado. - `customer.address.street` *string* **obrigatório** — Logradouro. Exemplo: `"Av. Paulista"`. - `customer.address.number` *string* **obrigatório** — Número. Exemplo: `"1000"`. - `customer.address.neighborhood` *string* — Bairro, até 100 caracteres. Informe o bairro ou o CEP. Exemplo: `"Bela Vista"`. - `customer.address.city` *string* **obrigatório** — Cidade, até 30 caracteres. Exemplo: `"São Paulo"`. - `customer.address.state` *string* **obrigatório** — Sigla ou nome do estado, até 20 caracteres. Exemplo: `"SP"`. - `customer.address.postalCode` *string* — CEP, só dígitos. Informe o CEP ou o bairro. Exemplo: `"01310100"`. - `customer.address.complement` *string* — Complemento. Exemplo: `"Apto 12"`. - `customer.address.latitude` *string | number* — Latitude. Exemplo: `"-23.5614"`. - `customer.address.longitude` *string | number* — Longitude. Exemplo: `"-46.6559"`. - `delivery` *object* — Obrigatório em DELIVERY; proibido em PDV e TABLE. - `delivery.deliveryType` *string* **obrigatório** — Modalidade da entrega. Exemplo: `"DELIVERY"`. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `delivery.deliveryStatus` *string* — Status inicial do pedido. Padrão WAITING. Com WAITING, o pedido aguarda o aceite do restaurante e gera o alerta de novo pedido no PDV; qualquer outro status cria o pedido já aceito, sem alerta. Exemplo: `"WAITING"`. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED` - `delivery.scheduledDateTime` *string (ISO 8601)* — Data e hora do pedido agendado. Exemplo: `"2026-10-04T19:30:00-03:00"`. - `delivery.driverId` *integer* — Entregador (funcionário). Exemplo: `7`. - `delivery.paymentIntent` *object* — Intenção de pagamento: o combinado com o cliente, guardado só como aviso, sem lançar pagamento. Forma e troco são opcionais; se vier com payments, o pagamento substitui a intenção. - `delivery.paymentIntent.paymentMethod` *string* — Forma de pagamento em texto livre, até 50 caracteres. Exemplo: `"Cartão de crédito"`. - `delivery.paymentIntent.brand` *string* — Bandeira em texto livre, até 50 caracteres. Exemplo: `"Visa"`. - `delivery.paymentIntent.changeFor` *number* — Troco para, maior ou igual a 0. Exemplo: `100`. - `delivery.additionalDeliveryTime` *number* — Minutos adicionais, maior ou igual a 0. Exemplo: `10`. - `indoor` *object* — Dados de mesa/balcão (TABLE e PDV). - `indoor.tableId` *integer* — Mesa. Exemplo: `3`. - `indoor.commandId` *integer* — Comanda. Exemplo: `21`. - `indoor.waiterId` *integer* — Garçom (funcionário). Exemplo: `4`. - `items` *array* **obrigatório** — Itens do pedido (ao menos 1). - `items[].productId` *integer | null* **obrigatório** — ID do produto no catálogo do restaurante. null para item avulso (produto fora do catálogo); veja "Item avulso". Exemplo: `1`. - `items[].itemName` *string* — Nome do item. No item avulso, é o nome que aparece como "não vinculado" no PDV. Exemplo: `"X-Burguer"`. - `items[].quantity` *number* **obrigatório** — Quantidade, maior que 0. Exemplo: `1`. - `items[].unitPrice` *number* **obrigatório** — Preço unitário, maior ou igual a 0. Exemplo: `25`. - `items[].itemObservations` *string* — Observações do item. Exemplo: `"Bem passado"`. - `items[].noServiceFee` *boolean* — Item sem taxa de serviço. Exemplo: `false`. - `items[].options` *array* — Opções do item. - `items[].options[].optionId` *integer* **obrigatório** — Opção de GET /v1/catalog/options; grupo e produto vêm do cadastro dela. Exemplo: `1`. - `items[].options[].optionName` *string* — Nome da opção. Exemplo: `"Bacon"`. - `items[].options[].quantity` *number* **obrigatório** — Quantidade, maior que 0. Exemplo: `1`. - `items[].options[].unitPrice` *number* **obrigatório** — Preço unitário, maior ou igual a 0. Exemplo: `4`. - `total` *object* **obrigatório** — Totais do pedido. - `total.itemsPrice` *number* **obrigatório** — Soma dos itens, maior ou igual a 0. Exemplo: `39`. - `total.orderAmount` *number* **obrigatório** — Valor total, maior ou igual a 0. Exemplo: `45`. - `total.deliveryFee` *number* — Taxa de entrega, maior ou igual a 0. Exemplo: `6`. - `total.additionalFees` *number* — Taxas adicionais, maior ou igual a 0. Exemplo: `0`. - `total.discount` *number* — Desconto, maior ou igual a 0. Exemplo: `0`. - `total.waiterServiceFee` *number* — Taxa de serviço, maior ou igual a 0. Exemplo: `0`. - `payments` *array* — Pagamentos já recebidos; entram como pagos. Sem caixa aberto, entram no próximo caixa aberto. Fiado não usa caixa, exige customer (nome e telefone) e lança a dívida na conta do cliente. - `payments[].paymentMethodId` *integer* **obrigatório** — Forma de pagamento de GET /v1/store/payment-methods. PIX Beetech e Fiado ainda não aceitos. Exemplo: `3`. - `payments[].value` *number* **obrigatório** — Valor pago, maior que 0. Em dinheiro, o excedente vira troco. Exemplo: `45`. - `payments[].brandId` *integer* — Bandeira, da lista brands da forma de pagamento. Exemplo: `2`. ## Exemplos de requisição ### cURL ```bash curl -X POST "https://api.beefood.app/v1/orders" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "merchantId": 1, "external": { "externalOrderId": "PARCEIRO-123" }, "orderType": "DELIVERY", "orderObservations": "Sem cebola", "customer": { "customerName": "Ana Souza", "phone": { "number": "11988887777", "extension": "+55" }, "address": { "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "postalCode": "01310100" } }, "delivery": { "deliveryType": "DELIVERY", "deliveryStatus": "WAITING", "paymentIntent": { "paymentMethod": "Cartão de crédito", "brand": "Visa", "changeFor": 100 } }, "items": [ { "productId": 1, "itemName": "X-Burguer", "quantity": 1, "unitPrice": 25, "itemObservations": "Bem passado", "options": [ { "optionId": 1, "optionName": "Bacon", "quantity": 1, "unitPrice": 4 } ] }, { "productId": null, "itemName": "Item avulso", "quantity": 2, "unitPrice": 5 } ], "total": { "itemsPrice": 39, "deliveryFee": 6, "discount": 0, "orderAmount": 45 } }' ``` ## Exemplos de resposta ### 201 OK ```json { "orderId": 1234 } ``` ## Campos da resposta - `orderId` *integer* — ID do pedido criado. Detalhe em GET /v1/orders/{orderId}. Exemplo: `1234`. ## Alerta de aceite Pedidos DELIVERY com `delivery.deliveryStatus` `WAITING` chegam como pedido novo aguardando aceite. O PDV toca o alerta de novo pedido, o restaurante aceita ou cancela. A impressão na cozinha é feita apenas quando o pedido é aceito. ### Regras - Pedidos DELIVERY criados em outro status (`ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED` ou `DELIVERED`) já são aceitos: não geram alerta e vão direto para a impressão da cozinha. - Pedidos PDV e TABLE nunca geram alerta de aceite. - A resposta 201 não confirma que o alerta tocou: o pedido é criado mesmo se o aviso ao restaurante falhar. ## Item avulso Use `productId: null` quando o produto não existe no catálogo. Com `itemName`, o PDV mostra o nome como "não vinculado" até o restaurante associá-lo a um produto. ### Regras - A pendência é uma por restaurante e nome; pedidos seguintes com o mesmo `itemName` não duplicam. Sem `itemName`, não há pendência. - O item não emite nota fiscal, não baixa estoque e não entra nas rotinas de produto do PDV. - Nos relatórios, o item vem com `productId: null`. - Associar a pendência no PDV não corrige pedidos já criados. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'merchantId' is required | | 400 | 'orderType' must be one of DELIVERY, PDV, TABLE | | 400 | 'items' must be a non-empty array | | 400 | 'items[0].quantity' must be a number > 0 | | 400 | 'total.orderAmount' must be a number >= 0 | | 400 | 'delivery.scheduledDateTime' must be an ISO 8601 date-time | | 400 | 'customer.phone.number' must contain only digits | | 400 | 'customer.address.postalCode' must be a postal code like 01310-100 | | 400 | 'customer.address.city' must have at most 30 characters | | 400 | 'customer.address.neighborhood' must have at most 100 characters | | 400 | 'customer.address.neighborhood' or 'customer.address.postalCode' is required | | 400 | 'customer.email' must be a valid email | | 400 | 'customer.birthDate' must be a date like 1990-12-31 | | 400 | 'customer.birthDate' must not be in the future | | 400 | Store ID 107 does not have user ID 99 | | 400 | 'delivery.paymentIntent.changeFor' must be a number >= 0 | | 400 | 'delivery.paymentIntent.paymentMethod' must have at most 50 characters | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:write scope | | 422 | 'delivery' is required when 'orderType' is DELIVERY | | 422 | 'delivery.paymentIntent.paymentMethod' is required when 'delivery.paymentIntent.brand' is sent | | 422 | 'customer.customerName' and 'customer.phone' are required | | 422 | 'customer.address' is required when 'deliveryType' is DELIVERY | | 422 | 'customer.address' is not allowed when 'deliveryType' is TAKEOUT | | 422 | Merchant ID 99 not found (filial inexistente, inativa ou sem cardápio publicado) | | 422 | Product IDs 10, 11 not found | | 422 | Payment method ID 9 not found | | 422 | Payment method ID 9 is not supported | | 422 | Brand ID 4 does not belong to payment method ID 3 | | 422 | 'customer.customerName' and 'customer.phone' are required for Fiado payments | | 429 | Too Many Requests | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | ## Pedidos · deliveryType | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Entrega | Lista e detalhe de pedidos | | `TAKEOUT` | Retirada | Lista e detalhe de pedidos | | `DINE_IN` | Consumo no local | Lista e detalhe de pedidos | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Detalhe do pedido --- title: "Detalhe do pedido" description: "GET /v1/orders/{orderId} — detalhe completo do pedido na API BeeFood." method: "GET" path: "/v1/orders/{orderId}" url: "https://developer.beefood.com.br/docs/pedidos/detalhe" group: "Pedidos" scope: "orders:read" lang: "pt" --- # Detalhe do pedido `GET /v1/orders/{orderId}` - Produção: `https://api.beefood.app/v1/orders/{orderId}` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/{orderId}` Retorna o detalhe de um pedido. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:read`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `orderId` *integer* **obrigatório** — ID do pedido. Exemplo: `123`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/orders/{orderId}" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### Tipo Mesa ```json { "orderId": 58672815, "saleNumber": 939, "orderType": "TABLE", "salesChannel": "MANUAL", "orderStatus": "RECEIVED", "createdAt": "2026-09-05T21:44:59.000-03:00", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "items": [ { "itemId": "137397466", "productId": "2515303", "itemName": "Chicken Deluxe", "quantity": 1, "unitPrice": 14.5, "optionsPrice": 0, "finalPrice": 14.5, "excluded": false, "user": { "userId": 125334, "userLogin": "ana.operadora", "employeeId": 279482, "employeeName": "Ana Souza" } }, { "itemId": "137397467", "productId": "2515373", "itemName": "Anéis de Cebola Empanada", "quantity": 1, "unitPrice": 19.2, "optionsPrice": 0, "finalPrice": 19.2, "excluded": false, "user": { "userId": 125334, "userLogin": "ana.operadora", "employeeId": 279482, "employeeName": "Ana Souza" } } ], "discount": { "type": "OTHER", "value": 0.34 }, "payments": { "prepaid": 34.81, "pending": 0, "methods": [ { "paymentId": 66006198, "value": 34.81, "valueLiquid": 34.81, "paid": true, "paidOnline": false, "dueDate": "2026-09-05T00:00:00.000-03:00", "paymentDateTime": "2026-09-05T21:45:05.000-03:00", "method": { "methodId": 381234, "name": "Dinheiro", "type": "CASH" }, "user": { "userId": 125334, "userLogin": "ana.operadora" } } ] }, "total": { "itemsPrice": 33.7, "deliveryFee": 0, "discount": 0.34, "additionalFees": 0, "waiterServiceFee": 1.45, "orderAmount": 34.81 }, "indoor": { "tableId": "1192721", "tableCode": "16", "tableDescription": "Mesa 16", "waiter": { "employeeId": 279482, "employeeName": "Ana Souza", "waiterServiceFeeType": "PERCENT", "waiterServiceFeeValue": 10 } }, "user": { "userId": 125334, "userLogin": "ana.operadora", "employeeId": 279482, "employeeName": "Ana Souza" } } ``` ### Pedido Mesa Agrupado ```json { "orderId": 58702878, "saleNumber": 941, "orderType": "TABLE", "salesChannel": "MANUAL", "orderStatus": "GROUPED", "orderIdGrouped": 60181832, "createdAt": "2026-09-06T14:00:38.000-03:00", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "items": [ { "itemId": "137460772", "productId": "2515373", "itemName": "Anéis de Cebola Empanada", "quantity": 1, "unitPrice": 19.2, "optionsPrice": 0, "finalPrice": 19.2, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com", "employeeId": 194115, "employeeName": "Restaurante Exemplo" } } ], "total": { "itemsPrice": 19.2, "deliveryFee": 0, "discount": 0, "additionalFees": 0, "waiterServiceFee": 0, "orderAmount": 19.2 }, "indoor": { "tableId": "1192721", "tableCode": "16", "tableDescription": "Mesa 16", "waiter": { "employeeId": 194115, "employeeName": "Restaurante Exemplo", "waiterServiceFeeType": "PERCENT", "waiterServiceFeeValue": 10 } }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com", "employeeId": 194115, "employeeName": "Restaurante Exemplo" } } ``` ### Tipo PDV ```json { "orderId": 59204137, "saleNumber": 968, "orderNumber": 32, "orderType": "PDV", "salesChannel": "MANUAL", "orderStatus": "RECEIVED", "createdAt": "2026-09-13T12:44:50.000-03:00", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "items": [ { "itemId": "138434648", "productId": "2515341", "itemName": "Combo One Burger", "quantity": 1, "unitPrice": 39, "optionsPrice": 11, "finalPrice": 50, "excluded": false, "options": [ { "optionId": "100055486", "productId": "2515296", "optionName": "One Burger", "productGroupId": "257194", "quantity": 1, "unitPrice": 0 }, { "optionId": "100055487", "productId": "2515323", "optionName": "Batata frita", "productGroupId": "257187", "quantity": 1, "unitPrice": 3 }, { "optionId": "100055488", "productId": "2515308", "optionName": "Coca Cola 350ml", "productGroupId": "257188", "quantity": 1, "unitPrice": 8 }, { "optionId": "100055489", "productId": "2515343", "optionName": "Sem Maionese Verde", "productGroupId": "257196", "quantity": 1, "unitPrice": 0 } ], "user": { "userId": 88711, "userLogin": "operador@exemplo.com", "employeeId": 194115, "employeeName": "Restaurante Exemplo" } }, { "itemId": "138434650", "productId": "2515377", "itemName": "Mozza Sticks + Molho", "quantity": 1, "unitPrice": 35.9, "optionsPrice": 0, "finalPrice": 35.9, "excluded": false, "options": [ { "optionId": "100055490", "productId": "2515378", "optionName": "Molho verde", "productGroupId": "257216", "quantity": 1, "unitPrice": 0 } ], "user": { "userId": 88711, "userLogin": "operador@exemplo.com", "employeeId": 194115, "employeeName": "Restaurante Exemplo" } } ], "discount": { "type": "OTHER", "value": 0.75 }, "payments": { "prepaid": 74.15, "pending": 0, "methods": [ { "paymentId": 66691961, "value": 74.15, "valueLiquid": 74.15, "paid": true, "paidOnline": false, "dueDate": "2026-09-13T00:00:00.000-03:00", "paymentDateTime": "2026-09-13T12:45:00.000-03:00", "method": { "methodId": 381234, "name": "Dinheiro", "type": "CASH" }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ] }, "total": { "itemsPrice": 74.9, "deliveryFee": 0, "discount": 0.75, "additionalFees": 0, "waiterServiceFee": 0, "orderAmount": 74.15 }, "delivery": { "deliveryType": "TAKEOUT", "deliveryStatus": "PREPARING", "timeline": { "acceptedDateTime": "2026-09-13T12:44:50.000-03:00" } }, "indoor": { "waiter": { "employeeId": 194115, "employeeName": "Restaurante Exemplo" } }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com", "employeeId": 194115, "employeeName": "Restaurante Exemplo" } } ``` ### Marketplaces · Aiqfome ```json { "orderId": 57938276, "saleNumber": 865, "orderNumber": 12, "orderType": "DELIVERY", "salesChannel": "AIQFOME", "orderStatus": "CLOSED", "createdAt": "2026-08-27T12:09:32.000-03:00", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "external": { "externalOrderId": "140079601" }, "customer": { "customerId": "123456", "customerName": "Mariana Souza", "documentNumber": "12345678900", "email": "contato@exemplo.com", "phone": { "number": "11999990000", "extension": "+55" } }, "schedule": { "scheduledDateTimeStart": "2026-08-27T00:00:00.000-03:00" }, "items": [ { "itemId": "135946483", "productId": "", "itemName": "sorvete 1 medio", "quantity": 3, "unitPrice": 10, "optionsPrice": 0, "finalPrice": 30, "excluded": false, "itemObservations": "sorvetes medio" } ], "payments": { "prepaid": 36.03, "pending": 0, "methods": [ { "paymentId": 65095637, "value": 36.03, "valueLiquid": 36.03, "paid": true, "paidOnline": false, "dueDate": "2026-09-02T00:00:00.000-03:00", "paymentDateTime": "2026-09-02T00:00:00.000-03:00", "method": { "methodId": 381234, "name": "Dinheiro", "type": "CASH" }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ] }, "total": { "itemsPrice": 0, "deliveryFee": 5, "discount": 0, "additionalFees": 1, "waiterServiceFee": 0, "orderAmount": 36.03 }, "delivery": { "deliveryType": "DELIVERY", "deliveryStatus": "DELIVERED", "timeline": { "acceptedDateTime": "2026-08-27T12:09:32.000-03:00", "startedDateTime": "2026-08-27T12:12:29.000-03:00" }, "address": { "addressId": 12137092, "street": "Rua das Flores", "number": "123", "complement": " -", "neighborhood": "Centro", "city": "Tupiratins", "state": "TO", "postalCode": "18040370", "latitude": -23.5015, "longitude": -47.4526 } } } ``` ### Marketplaces · iFood ```json { "orderId": 59621229, "saleNumber": 1133, "orderNumber": 1133, "orderType": "DELIVERY", "salesChannel": "IFOOD", "orderStatus": "RECEIVED", "createdAt": "2026-09-19T17:11:17.953-03:00", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "external": { "externalOrderId": "b4e2f7a1-6c39-4d08-85b7-1f2ae906c34d", "externalOrderShortId": "2740 - Coleta 6118", "phoneTempCode": "12345678" }, "customer": { "customerId": "13118938", "customerName": "Ana Moraes" }, "schedule": { "scheduledDateTimeStart": "2026-09-19T00:00:00.000-03:00" }, "items": [ { "itemId": "139230562", "productId": "1965722", "itemName": "Shake de Açaí (330 ml)", "quantity": 1, "unitPrice": 12.9, "optionsPrice": 0, "finalPrice": 12.9, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ], "total": { "itemsPrice": 12.9, "deliveryFee": 7, "discount": 0, "additionalFees": 0, "waiterServiceFee": 0, "orderAmount": 19.9 }, "delivery": { "deliveryType": "DELIVERY", "deliveryStatus": "DELIVERED", "timeline": { "acceptedDateTime": "2026-09-19T17:11:17.953-03:00", "startedDateTime": "2026-09-19T17:11:17.953-03:00" }, "pickupCode": "90612447", "address": { "addressId": 13268347, "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "Sorocaba", "state": "SP", "postalCode": "18040370", "latitude": -23.5015, "longitude": -47.4526 } }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ``` ### Marketplaces · 99Food ```json { "orderId": 59621231, "saleNumber": 1135, "orderNumber": 1135, "orderType": "DELIVERY", "salesChannel": "99FOOD", "orderStatus": "RECEIVED", "createdAt": "2026-09-19T17:11:17.953-03:00", "orderObservations": "Cód. retirada 99: 4821", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "external": { "externalOrderId": "5764687533109824571", "externalOrderShortId": "392011" }, "customer": { "customerId": "13118940", "customerName": "Fernanda Lima" }, "schedule": { "scheduledDateTimeStart": "2026-09-19T00:00:00.000-03:00" }, "items": [ { "itemId": "139230565", "productId": "1965728", "itemName": "Açai Mini 220ml", "quantity": 1, "unitPrice": 17.9, "optionsPrice": 0, "finalPrice": 17.9, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } }, { "itemId": "139230566", "productId": "1965729", "itemName": "Sorvete Pequeno", "quantity": 1, "unitPrice": 20, "optionsPrice": 0, "finalPrice": 20, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } }, { "itemId": "139230568", "productId": "1965730", "itemName": "Sorvete Pequeno", "quantity": 1, "unitPrice": 20, "optionsPrice": 0, "finalPrice": 20, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ], "total": { "itemsPrice": 57.9, "deliveryFee": 6, "discount": 0, "additionalFees": 0, "waiterServiceFee": 0, "orderAmount": 63.9 }, "delivery": { "deliveryType": "DELIVERY", "deliveryStatus": "DELIVERED", "timeline": { "acceptedDateTime": "2026-09-19T17:11:17.953-03:00", "startedDateTime": "2026-09-19T17:11:17.953-03:00" }, "address": { "addressId": 13268349, "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "Sorocaba", "state": "SP", "postalCode": "18040370", "latitude": -23.5015, "longitude": -47.4526 } }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ``` ### Método de pagamento · Cartão de crédito ```json { "orderId": 59816986, "saleNumber": 1151, "orderType": "DELIVERY", "salesChannel": "MANUAL", "orderStatus": "RECEIVED", "createdAt": "2026-09-22T10:33:37.173-03:00", "orderObservations": "Portão azul, chamar no interfone.", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "customer": { "customerId": "13183068", "customerName": "Gustavo Almeida" }, "schedule": { "scheduledDateTimeStart": "2026-09-22T00:00:00.000-03:00" }, "items": [ { "itemId": "139618936", "productId": "1965731", "itemName": "Shake de Açaí C/ Laranja (550 ML)", "quantity": 1, "unitPrice": 20.9, "optionsPrice": 0, "finalPrice": 20.9, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ], "payments": { "prepaid": 32.9, "pending": 0, "methods": [ { "paymentId": 67485277, "value": 32.9, "taxType": "PERCENT", "taxValue": 3.49, "valueLiquid": 31.75, "paid": true, "paidOnline": false, "dueDate": "2026-09-22T00:00:00.000-03:00", "paymentDateTime": "2026-09-22T15:15:56.000-03:00", "estimatedReceivedDate": "2026-10-22T00:00:00.000-03:00", "receivedDate": "2026-10-22T00:00:00.000-03:00", "method": { "methodId": 381236, "name": "Crédito", "type": "CREDIT_CARD" }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ] }, "total": { "itemsPrice": 20.9, "deliveryFee": 12, "discount": 0, "additionalFees": 0, "waiterServiceFee": 0, "orderAmount": 32.9 }, "delivery": { "deliveryType": "DELIVERY", "deliveryStatus": "DELIVERED", "timeline": { "acceptedDateTime": "2026-09-22T10:33:37.173-03:00", "startedDateTime": "2026-09-22T10:33:37.173-03:00", "deliveredDateTime": "2026-09-22T15:15:56.000-03:00" }, "address": { "addressId": 13334577, "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "Sorocaba", "state": "SP", "postalCode": "18040370", "latitude": -23.5015, "longitude": -47.4526 }, "driver": { "employeeId": 194115, "employeeName": "Restaurante Exemplo" } }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ``` ### Método de pagamento · Cartão de débito ```json { "orderId": 59816985, "saleNumber": 1150, "orderType": "DELIVERY", "salesChannel": "MANUAL", "orderStatus": "RECEIVED", "createdAt": "2026-09-22T10:33:37.173-03:00", "orderObservations": "Portão azul, chamar no interfone.", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "customer": { "customerId": "13183067", "customerName": "Fernanda Lima" }, "schedule": { "scheduledDateTimeStart": "2026-09-22T00:00:00.000-03:00" }, "items": [ { "itemId": "139618932", "productId": "1965728", "itemName": "Açai Mini 220ml", "quantity": 1, "unitPrice": 17.9, "optionsPrice": 0, "finalPrice": 17.9, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } }, { "itemId": "139618933", "productId": "1965729", "itemName": "Sorvete Pequeno", "quantity": 1, "unitPrice": 20, "optionsPrice": 0, "finalPrice": 20, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } }, { "itemId": "139618934", "productId": "1965730", "itemName": "Sorvete Pequeno", "quantity": 1, "unitPrice": 20, "optionsPrice": 0, "finalPrice": 20, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ], "payments": { "prepaid": 63.9, "pending": 0, "methods": [ { "paymentId": 67485276, "value": 63.9, "taxType": "PERCENT", "taxValue": 2.5, "valueLiquid": 62.3, "paid": true, "paidOnline": false, "dueDate": "2026-09-22T00:00:00.000-03:00", "paymentDateTime": "2026-09-22T15:15:56.000-03:00", "estimatedReceivedDate": "2026-09-22T00:00:00.000-03:00", "receivedDate": "2026-09-22T00:00:00.000-03:00", "method": { "methodId": 381235, "name": "Débito", "type": "DEBIT_CARD" }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ] }, "total": { "itemsPrice": 57.9, "deliveryFee": 6, "discount": 0, "additionalFees": 0, "waiterServiceFee": 0, "orderAmount": 63.9 }, "delivery": { "deliveryType": "DELIVERY", "deliveryStatus": "DELIVERED", "timeline": { "acceptedDateTime": "2026-09-22T10:33:37.173-03:00", "startedDateTime": "2026-09-22T10:33:37.173-03:00", "deliveredDateTime": "2026-09-22T15:15:56.000-03:00" }, "address": { "addressId": 13334576, "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "Sorocaba", "state": "SP", "postalCode": "18040370", "latitude": -23.5015, "longitude": -47.4526 }, "driver": { "employeeId": 194115, "employeeName": "Restaurante Exemplo" } }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ``` ### Método de pagamento · Dinheiro ```json { "orderId": 59835415, "saleNumber": 1167, "orderType": "DELIVERY", "salesChannel": "MANUAL", "orderStatus": "RECEIVED", "createdAt": "2026-09-22T15:57:03.513-03:00", "orderObservations": "[SEED-ENTREGAS] 2026-09-22 19:00", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "customer": { "customerId": "13188863", "customerName": "Simone Costa" }, "schedule": { "scheduledDateTimeStart": "2026-09-22T00:00:00.000-03:00" }, "items": [ { "itemId": "139647789", "productId": "1965746", "itemName": "Açaí Grande 770ml", "quantity": 1, "unitPrice": 33.9, "optionsPrice": 0, "finalPrice": 33.9, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } }, { "itemId": "139647790", "productId": "1965747", "itemName": "Açaí Médio com Nutella & Brownie", "quantity": 1, "unitPrice": 36, "optionsPrice": 0, "finalPrice": 36, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } }, { "itemId": "139647791", "productId": "1965748", "itemName": "Açaí Grande e Nutella", "quantity": 1, "unitPrice": 39.9, "optionsPrice": 0, "finalPrice": 39.9, "excluded": false, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ], "payments": { "prepaid": 120.8, "pending": 0, "methods": [ { "paymentId": 67487770, "value": 120.8, "valueLiquid": 120.8, "paid": true, "paidOnline": false, "dueDate": "2026-09-22T00:00:00.000-03:00", "paymentDateTime": "2026-09-22T16:10:47.000-03:00", "method": { "methodId": 381234, "name": "Dinheiro", "type": "CASH" }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ] }, "total": { "itemsPrice": 109.8, "deliveryFee": 11, "discount": 0, "additionalFees": 0, "waiterServiceFee": 0, "orderAmount": 120.8 }, "delivery": { "deliveryType": "DELIVERY", "deliveryStatus": "DELIVERED", "timeline": { "acceptedDateTime": "2026-09-22T15:57:03.513-03:00", "startedDateTime": "2026-09-22T15:57:03.513-03:00", "deliveredDateTime": "2026-09-22T16:10:47.000-03:00" }, "address": { "addressId": 13340615, "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "Sorocaba", "state": "SP", "postalCode": "18040370", "latitude": -23.5015, "longitude": -47.4526 } }, "user": { "userId": 88711, "userLogin": "operador@exemplo.com" } } ``` ### Método de pagamento · Outro ```json { "orderId": 59434595, "saleNumber": 1012, "orderNumber": 46, "orderType": "DELIVERY", "salesChannel": "IFOOD", "orderStatus": "RECEIVED", "createdAt": "2026-09-17T10:10:44.707-03:00", "invoiceDocument": "FS999999", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "external": { "externalOrderId": "c8219a1f-9cea-4ce8-94e6-b25a28f81608", "externalOrderShortId": "3257 - Coleta 0771", "phoneTemp": "0800 000 0000", "phoneTempCode": "12345678" }, "customer": { "customerId": "12578119", "customerName": "Pedido de teste de integracao", "documentNumber": "FS999999" }, "schedule": { "scheduledDateTimeStart": "2026-09-17T00:00:00.000-03:00", "scheduledDateTimeEnd": "2026-09-17T10:55:00.000-03:00" }, "items": [ { "itemId": "138862961", "productId": "2515323", "itemName": "PRODUTO 1 - NÃO ENTREGAR - Primeiro Nível", "quantity": 1, "unitPrice": 5, "optionsPrice": 0, "finalPrice": 5, "excluded": false }, { "itemId": "138862962", "productId": "2515390", "itemName": "PRODUTO 2 (COMBO) - NÃO ENTREGAR - Primeiro Nível", "quantity": 1, "unitPrice": 16, "optionsPrice": 8, "finalPrice": 24, "excluded": false, "options": [ { "optionId": "100486278", "productId": "2515375", "optionName": "Complemento 1 - Segundo Nível", "quantity": 1, "unitPrice": 2 }, { "optionId": "100486279", "productId": "", "optionName": "Complemento 2 - Segundo Nível", "quantity": 1, "unitPrice": 2 }, { "optionId": "100486280", "productId": "", "optionName": "Complemento 3 - Segundo Nível", "quantity": 1, "unitPrice": 2 }, { "optionId": "100486281", "productId": "", "optionName": "Complemento 4 - Segundo Nível", "quantity": 1, "unitPrice": 2 } ] } ], "payments": { "prepaid": 27, "pending": 0, "methods": [ { "paymentId": 66987864, "value": 10, "valueLiquid": 10, "paid": true, "paidOnline": true, "dueDate": "2026-09-17T00:00:00.000-03:00", "brand": "Mastercard", "paymentDateTime": "2026-09-17T10:10:44.706-03:00", "method": { "methodId": 381240, "name": "iFood Online", "type": "OTHER" } }, { "paymentId": 66987863, "value": 17, "valueLiquid": 17, "paid": true, "paidOnline": true, "dueDate": "2026-09-17T00:00:00.000-03:00", "brand": "Visa", "paymentDateTime": "2026-09-17T10:10:44.706-03:00", "method": { "methodId": 381240, "name": "iFood Online", "type": "OTHER" } } ] }, "total": { "itemsPrice": 0, "deliveryFee": 5, "discount": 0, "additionalFees": 1, "waiterServiceFee": 0, "orderAmount": 27 }, "delivery": { "deliveryType": "DELIVERY", "estimatedDeliveryDateTime": "2026-09-17T10:55:00.000-03:00", "deliveryStatus": "DELIVERED", "timeline": { "acceptedDateTime": "2026-09-17T10:10:44.707-03:00", "startedDateTime": "2026-09-17T10:10:58.000-03:00", "deliveredDateTime": "2026-09-17T10:13:19.000-03:00" }, "pickupCode": "34391005", "address": { "addressId": 12721762, "street": "Rua das Flores", "number": "123", "complement": "Complemento TESTE - TESTE", "neighborhood": "Centro", "city": "", "state": "", "postalCode": "18040370" }, "driver": { "employeeId": 194115, "employeeName": "Restaurante Exemplo" } } } ``` ### Método de pagamento · Pix BeeFood ```json { "orderId": 55993945, "saleNumber": 767, "orderNumber": 43, "orderType": "DELIVERY", "salesChannel": "DIGITAL_MENU", "orderStatus": "RECEIVED", "createdAt": "2026-07-29T13:53:18.000-03:00", "merchant": { "storeId": 38311, "merchantId": 39202, "merchantName": "Restaurante Exemplo" }, "customer": { "customerId": "11900342", "customerName": "Gabriel Souza", "phone": { "number": "11999990000", "extension": "+55" } }, "schedule": { "scheduledDateTimeStart": "2026-07-29T00:00:00.000-03:00" }, "items": [ { "itemId": "132052797", "productId": "2207978", "itemName": "Coca Cola 350ml", "quantity": 3, "unitPrice": 4.44, "optionsPrice": 0, "finalPrice": 13.32, "excluded": false } ], "payments": { "prepaid": 13.32, "pending": 0, "methods": [ { "paymentId": 62649829, "value": 13.32, "taxType": "PERCENT", "taxValue": 1, "valueLiquid": 13.19, "paid": true, "paidOnline": true, "dueDate": "2026-07-29T00:00:00.000-03:00", "paymentDateTime": "2026-07-29T13:54:00.000-03:00", "estimatedReceivedDate": "2026-07-31T00:00:00.000-03:00", "receivedDate": "2026-07-29T00:00:00.000-03:00", "method": { "methodId": 486229, "name": "PIX Bee", "type": "PIX_BEEFOOD", "pix": { "pixId": 1114738, "txId": "g27LVdyEyGsCzBh9fgGbVzsNwxcQTE0uF2E", "status": "PAID", "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAS...", "qrCodeText": "", "createdAt": "2026-07-29T13:53:19.000-03:00", "expiresAt": "2026-07-29T14:07:19.000-03:00" } } } ] }, "total": { "itemsPrice": 13.32, "deliveryFee": 0, "discount": 0, "additionalFees": 0, "waiterServiceFee": 0, "orderAmount": 13.32 }, "delivery": { "deliveryType": "TAKEOUT", "deliveryStatus": "DELIVERED", "timeline": { "acceptedDateTime": "2026-07-29T13:53:18.000-03:00", "deliveredDateTime": "2026-07-29T13:55:17.000-03:00" } } } ``` ## Campos da resposta - `orderId` *number* — ID do pedido. - `saleNumber` *number* — Número da venda no PDV. - `orderNumber` *number* — Número sequencial do pedido. - `displayId` *number* — Código amigável exibido ao cliente/restaurante. - `invoiceDocument` *string* — Documento para nota fiscal, se informado. - `cancellationReason` *string* — Motivo do cancelamento - `orderObservations` *string* — Observações gerais do pedido. - `orderType` *string* — Tipo do pedido. - *Valores:* `DELIVERY`, `PDV`, `TABLE` - `salesChannel` *string* — Canal de origem da venda. - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `EXTERNAL`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL` - `orderStatus` *string* — Situação atual do pedido. - *Valores:* `OPEN`, `RECEIVED`, `GROUPED`, `CLOSED`, `CANCELLED` - `orderIdGrouped` *number* — Identificador do pedido principal quando o pedido foi agrupado a outro (orderStatus GROUPED). - `merchant` *object* — Cardápio responsável pelo pedido. - `customer` *object* — Cliente do pedido. - `schedule` *object* — Agendamento do pedido - `items[]` *array* — Itens do pedido. - `discount` *object* — Desconto aplicado ao pedido. - `discount.coupon.target` *string* — Abrangência do cupom aplicado. - `payments` *object* — Pagamentos do pedido. - `payments.prepaid` *number* — Valor já pago antecipadamente. - `payments.pending` *number* — Valor pendente de pagamento. - `payments.methods[]` *array* — Lista de pagamentos realizados no pedido. - `payments.methods[].paymentId` *number* — Identificador único do pagamento. - `payments.methods[].value` *number* — Valor bruto do pagamento. - `payments.methods[].taxType` *string* — Tipo de taxa aplicada (PERCENT ou FIXED). - `payments.methods[].taxValue` *number* — Valor da taxa descontada. - `payments.methods[].valueLiquid` *number* — Valor líquido do pagamento após taxas. - `payments.methods[].paid` *boolean* — Indica se o pagamento já foi recebido. - `payments.methods[].paidOnline` *boolean* — Indica se o pagamento foi realizado online. - `payments.methods[].method` *object* — Método de pagamento utilizado (methodId, name, type). - `payments.methods[].method.methodId` *number* — Identificador do método de pagamento. - `payments.methods[].method.name` *string* — Nome legível do método de pagamento. - `payments.methods[].method.type` *string* — Tipo do método de pagamento (CREDIT_CARD, DEBIT_CARD, CASH, OTHER, PIX_BEEFOOD). - *Valores:* `CASH`, `CREDIT_CARD`, `DEBIT_CARD`, `PIX_BEEFOOD`, `FOOD_VOUCHER`, `MEAL_VOUCHER`, `DIGITAL_WALLET`, `STORE_CREDIT`, `OTHER` - `payments.methods[].brand` *string* — Bandeira do cartão, quando aplicável. - `payments.methods[].changeFor` *number* — Valor para troco, quando o pagamento for em dinheiro. - `payments.methods[].paymentDateTime` *string* — Data e hora em que o pagamento foi realizado. - `payments.methods[].estimatedReceivedDate` *string* — Data estimada de recebimento do valor. - `payments.methods[].receivedDate` *string* — Data efetiva de recebimento do valor. - `payments.methods[].dueDate` *string* — Data de vencimento do pagamento. - `payments.methods[].user` *object* — Operador responsável pelo registro do pagamento. - `payments.methods[].user.userId` *number* — Identificador do operador no sistema. - `payments.methods[].user.userLogin` *string* — Login do operador. - `payments.methods[].user.employeeId` *number* — Identificador do funcionário vinculado ao operador. - `payments.methods[].user.employeeName` *string* — Nome do funcionário vinculado ao operador. - `total` *object* — Totais do pedido. - `delivery` *object* — Dados da entrega ou retirada. - `indoor` *object* — Dados de mesa/salão. - `external` *object* — Dados do canal externo - `user` *object* — Quem registrou o pedido. - `user.userId` *number* — ID do usuário no sistema. - `user.employeeId` *number* — ID do funcionário. - `items[].user` *object* — Operador que registrou o item. - `items[].user.userId` *number* — ID do usuário no sistema. - `items[].user.employeeId` *number* — ID do funcionário. - `merchant.storeId` *number* — ID do restaurante. - `merchant.merchantId` *number* — ID do cardápio. - `merchant.merchantName` *string* — Nome do cardápio. - `external.externalOrderId` *string* — ID do pedido no marketplace ou, sem marketplace, o identificador enviado na criação. - `external.externalOrderShortId` *string* — ID curto do pedido no canal externo. - `external.phoneTemp` *string* — Telefone temporário do canal (quando houver). - `external.phoneTempCode` *string* — Código do telefone temporário. - `external.observation` *string* — Observação vinda do canal externo. - `customer.customerId` *string* — ID do cliente. - `customer.customerName` *string* — Nome principal do cadastro do cliente. - `customer.tradeName` *string* — Apelido do cliente, o mesmo de GET /v1/customers. - `customer.documentNumber` *string* — CPF/CNPJ do cliente. - `customer.email` *string* — E-mail do cliente. - `customer.phone` *object* — Telefone do cliente. - `customer.phone.number` *string* — Número do telefone. - `customer.phone.extension` *string* — DDI (ex.: +55). - `customer.ordersCount` *number* — Quantidade de pedidos deste cliente. - `schedule.scheduledDateTimeStart` *string (ISO 8601)* — Início da janela agendada. - `schedule.scheduledDateTimeEnd` *string (ISO 8601)* — Fim da janela agendada. - `items[].itemId` *string* — ID do item no pedido. - `items[].productId` *string* — ID do produto no cardápio. - `items[].itemName` *string* — Nome do item. - `items[].quantity` *number* — Quantidade pedida. - `items[].unitPrice` *number* — Preço unitário do item. - `items[].optionsPrice` *number* — Soma dos preços dos adicionais deste item. - `items[].finalPrice` *number* — Valor final do item, incluindo adicionais. - `items[].excluded` *boolean* — Indica se o item foi excluído do pedido. - `items[].itemObservations` *string* — Observação específica do item. - `items[].options` *array* — Lista de adicionais/opções do item. - `items[].options[].optionId` *string* — ID da opção adicional. - `items[].options[].productId` *string* — ID do produto da opção adicional. - `items[].options[].optionName` *string* — Nome da opção adicional. - `items[].options[].productGroupId` *string* — Grupo de opções a que pertence. - `items[].options[].quantity` *number* — Quantidade da opção adicional. - `items[].options[].unitPrice` *number* — Preço unitário da opção adicional. - `items[].user.userLogin` *string* — Login do usuário. - `items[].user.employeeName` *string* — Nome do funcionário. - `discount.type` *string* — Tipo do desconto aplicado. - `discount.value` *number* — Valor do desconto. - `discount.coupon` *object* — Cupom usado - `discount.coupon.couponId` *number* — ID do cupom. - `discount.coupon.code` *string* — Código do cupom. - `discount.coupon.type` *string* — Tipo do benefício do cupom. - `discount.coupon.discountValue` *number* — Valor concedido pelo cupom. - `payments.methods` *array* — Formas de pagamento usadas. - `total.itemsPrice` *number* — Soma dos itens. - `total.deliveryFee` *number* — Taxa de entrega. - `total.discount` *number* — Total de descontos. - `total.additionalFees` *number* — Taxas adicionais. - `total.waiterServiceFee` *number* — Valor da taxa de serviço cobrado no pedido. - `total.orderAmount` *number* — Valor final do pedido. - `delivery.deliveryType` *string* — Modalidade de entrega/retirada. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `delivery.deliveredBy` *string* — Quem realiza a entrega. - `delivery.estimatedDeliveryDateTime` *string* — Previsão de entrega. - `delivery.deliveryStatus` *string* — Status atual da entrega. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `delivery.paymentIntent` *object* — Intenção de pagamento avisada no pedido; omitido sem forma e sem troco. O que foi pago fica em payments. - `delivery.paymentIntent.paymentMethod` *string* — Forma avisada na intenção, em texto livre (ex.: Dinheiro). - `delivery.paymentIntent.brand` *string* — Bandeira avisada na intenção. - `delivery.paymentIntent.changeFor` *number* — Troco para. Omitido quando não informado. - `delivery.pickupCode` *string* — Código para retirada. - `delivery.timeline` *object* — Marcos de tempo da entrega. - `delivery.timeline.acceptedDateTime` *string* — Quando o pedido foi aceito. - `delivery.timeline.startedDateTime` *string* — Quando a preparação começou. - `delivery.timeline.readyDateTime` *string* — Quando ficou pronto. - `delivery.timeline.pickupDateTime` *string* — Quando saiu para entrega / foi retirado. - `delivery.timeline.deliveredDateTime` *string* — Quando foi entregue. - `delivery.address` *object* — Endereço de entrega. - `delivery.address.addressId` *string* — ID do endereço. - `delivery.address.street` *string* — Rua. - `delivery.address.number` *string* — Número. - `delivery.address.complement` *string* — Complemento. - `delivery.address.neighborhood` *string* — Bairro. - `delivery.address.city` *string* — Cidade. - `delivery.address.state` *string* — UF. - `delivery.address.postalCode` *string* — CEP, só dígitos. - `delivery.address.latitude` *number* — Latitude. - `delivery.address.longitude` *number* — Longitude. - `delivery.driver` *object* — Entregador vinculado. - `delivery.driver.employeeId` *number* — ID do entregador. - `delivery.driver.employeeName` *string* — Nome do entregador. - `delivery.driver.driverEarning` *number* — Valor pago ao entregador. - `indoor.commandId` *string* — ID da comanda. - `indoor.commandCode` *string* — Código da comanda. - `indoor.commandDescription` *string* — Descrição da comanda. - `indoor.tableId` *string* — ID da mesa cadastrada. - `indoor.tableCode` *string* — Código da mesa cadastrada. - `indoor.tableDescription` *string* — Descrição da mesa cadastrada. - `indoor.randomName` *string* — Nome avulso informado na mesa. - `indoor.waiter` *object* — Garçom responsável. - `indoor.waiter.employeeId` *number* — ID do garçom. - `indoor.waiter.employeeName` *string* — Nome do garçom. - `indoor.waiter.waiterServiceFeeType` *string* — Tipo da taxa de serviço: PERCENT ou FIXED. - `indoor.waiter.waiterServiceFeeValue` *number* — Alíquota quando PERCENT ou valor em reais quando FIXED. - `user.userLogin` *string* — Login do usuário. - `user.employeeName` *string* — Nome do funcionário. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'id' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:read scope | | 404 | Order ID 123 not found | | 429 | Too Many Requests | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Pedidos · orderStatus | Valor | Significado | Uso | | --- | --- | --- | | `OPEN` | Aberto | Lista e detalhe de pedidos | | `RECEIVED` | Recebido | Lista e detalhe de pedidos | | `GROUPED` | Agrupado a outro pedido | Pedido somado a outro; orderIdGrouped indica o pedido principal | | `CLOSED` | Fechado | Lista e detalhe de pedidos | | `CANCELLED` | Cancelado | Lista e detalhe de pedidos | ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | | `CANCELLED` | Cancelado | Pedidos e webhooks | ## Pedidos · deliveryType | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Entrega | Lista e detalhe de pedidos | | `TAKEOUT` | Retirada | Lista e detalhe de pedidos | | `DINE_IN` | Consumo no local | Lista e detalhe de pedidos | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Pedidos · salesChannel | Valor | Significado | Uso | | --- | --- | --- | | `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks | | `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks | | `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks | | `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks | | `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks | | `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks | | `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks | | `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks | | `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks | | `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks | | `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks | | `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks | ## Pagamento · method.type Mesmo vocabulário usado no bloco payments do pedido e nas formas de pagamento permitidas em cupons. | Valor | Significado | Uso | | --- | --- | --- | | `CASH` | Dinheiro | Pedidos e cupons | | `CREDIT_CARD` | Cartão de crédito | Pedidos e cupons | | `DEBIT_CARD` | Cartão de débito | Pedidos e cupons | | `PIX_BEEFOOD` | Pix BeeFood | Pedidos e cupons | | `FOOD_VOUCHER` | Vale-alimentação | Pedidos e cupons | | `MEAL_VOUCHER` | Vale-refeição | Pedidos e cupons | | `DIGITAL_WALLET` | Carteira digital | Pedidos e cupons | | `STORE_CREDIT` | Crédito no restaurante | Pedidos e cupons | | `OTHER` | Outro | Pedidos e cupons | ## Listar pedidos --- title: "Listar pedidos" description: "GET /v1/orders — histórico paginado de pedidos do estabelecimento na API BeeFood." method: "GET" path: "/v1/orders" url: "https://developer.beefood.com.br/docs/pedidos/listar" group: "Pedidos" scope: "orders:read" lang: "pt" --- # Listar pedidos `GET /v1/orders` - Produção: `https://api.beefood.app/v1/orders` - Sandbox: `https://api-sandbox.beefood.app/v1/orders` Retorna o histórico de pedidos do estabelecimento. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:read`. Limite: 15 requisições por minuto. ## Parâmetros de query - `page` *integer* — Página atual da lista. Exemplo: `1`. - `limit` *integer* — Quantidade de itens por página. Exemplo: `20`. - `sort` *string* — Ordem da lista: mais recentes (desc) ou mais antigos (asc). Exemplo: `"desc"`. - *Valores:* `asc`, `desc` - `saleDateFrom` *string (yyyy-mm-dd)* **obrigatório** — Início do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-01"`. - `saleDateTo` *string (yyyy-mm-dd)* **obrigatório** — Fim do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-31"`. - `orderType` *string* — Filtra pelo tipo do pedido: DELIVERY, PDV ou TABLE. Exemplo: `"DELIVERY"`. - *Valores:* `DELIVERY`, `PDV`, `TABLE` - `orderStatus` *string* — Filtra pelo status do pedido: OPEN, RECEIVED, GROUPED, CLOSED ou CANCELLED. Exemplo: `"CLOSED"`. - *Valores:* `OPEN`, `RECEIVED`, `GROUPED`, `CLOSED`, `CANCELLED` - `deliveryType` *string* — Filtra pela modalidade da entrega: DELIVERY, TAKEOUT ou DINE_IN. Exemplo: `"DELIVERY"`. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `deliveryStatus` *string* — Filtra pelo status da entrega: WAITING, ACCEPTED, PREPARING, READY, DISPATCHED, DELIVERED ou CANCELLED. Exemplo: `"DELIVERED"`. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `salesChannel` *string* — Filtra pelo canal de venda: IFOOD, 99FOOD, KEETA, AIQFOME, RAPPI, DELIVERYMUCH, UAIRANGO, TOTEM, EXTERNAL, WHATSAPP, DIGITAL_MENU ou MANUAL. Exemplo: `"DIGITAL_MENU"`. - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `EXTERNAL`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL` - `merchantId` *integer* — Filtra os pedidos de um cardápio. Exemplo: `1`. - `customerId` *integer* — Filtra pedidos de um cliente. Exemplo: `123456`. - `documentNumber` *string* — Filtra pelo CPF ou CNPJ do cliente do pedido (somente dígitos). Exemplo: `"12345678900"`. - `email` *string* — Filtra pelo e-mail do cliente do pedido. Exemplo: `"cliente@exemplo.com"`. - `phone` *string* — Filtra pelo telefone do cliente do pedido (somente dígitos). Exemplo: `"11999990000"`. - `couponCode` *string* — Filtra pelos pedidos que usaram um cupom específico. Exemplo: `"PIX15%"`. - `commandCode` *integer | integer[]* — Filtra pelo código da comanda. Exemplo: `12`. - `tableCode` *integer | integer[]* — Filtra pelo código da mesa. Exemplo: `5`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/orders?saleDateFrom=2026-03-01&saleDateTo=2026-03-31&page=1&limit=20&sort=desc" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "orderId": 60181897, "createdAt": "2026-09-27T10:30:02.000-03:00", "orderStatus": "GROUPED", "orderIdGrouped": 60181902, "deliveryStatus": "PREPARING", "orderType": "TABLE", "deliveryType": "TAKEOUT", "orderAmount": 19.58, "paidAmount": 0 }, { "orderId": 60181831, "createdAt": "2026-09-27T10:27:41.000-03:00", "orderStatus": "GROUPED", "orderIdGrouped": 60181832, "deliveryStatus": "PREPARING", "orderType": "TABLE", "deliveryType": "TAKEOUT", "orderAmount": 29.37, "paidAmount": 0 }, { "orderId": 60181902, "createdAt": "2026-09-27T10:26:55.717-03:00", "orderStatus": "OPEN", "orderType": "TABLE", "orderAmount": 63.7, "paidAmount": 0 } ], "page": 1, "limit": 3, "total": 252, "pages": 84 } ``` ## Campos da resposta - `items[].orderId` *number* — ID do pedido. - `items[].createdAt` *string (ISO 8601)* — Data/hora em que o pedido foi criado. - `items[].orderStatus` *string* — Situação geral do pedido. - *Valores:* `OPEN`, `RECEIVED`, `GROUPED`, `CLOSED`, `CANCELLED` - `items[].deliveryStatus` *string* — Situação da entrega. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `items[].orderType` *string* — Tipo do pedido. - *Valores:* `DELIVERY`, `PDV`, `TABLE` - `items[].deliveryType` *string* — Como o pedido será entregue ou retirado. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `items[].orderAmount` *number* — Valor total do pedido. - `items[].paidAmount` *number* — Quanto já foi pago. - `page` *number* — Página atual da lista. - `limit` *number* — Quantidade de itens por página. - `total` *number* — Total de registros encontrados. - `pages` *number* — Total de páginas. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'page' must be an integer >= 1 | | 400 | 'limit' must be an integer between 1 and 100 | | 400 | 'sort' must be asc or desc | | 400 | saleDateFrom and saleDateTo are required | | 400 | The range between saleDateFrom and saleDateTo cannot exceed 6 months | | 400 | 'commandCode' must be a positive integer | | 400 | 'tableCode' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:read scope | | 429 | Too Many Requests | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Pedidos · orderStatus | Valor | Significado | Uso | | --- | --- | --- | | `OPEN` | Aberto | Lista e detalhe de pedidos | | `RECEIVED` | Recebido | Lista e detalhe de pedidos | | `GROUPED` | Agrupado a outro pedido | Pedido somado a outro; orderIdGrouped indica o pedido principal | | `CLOSED` | Fechado | Lista e detalhe de pedidos | | `CANCELLED` | Cancelado | Lista e detalhe de pedidos | ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | | `CANCELLED` | Cancelado | Pedidos e webhooks | ## Pedidos · deliveryType | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Entrega | Lista e detalhe de pedidos | | `TAKEOUT` | Retirada | Lista e detalhe de pedidos | | `DINE_IN` | Consumo no local | Lista e detalhe de pedidos | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Pedidos · salesChannel | Valor | Significado | Uso | | --- | --- | --- | | `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks | | `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks | | `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks | | `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks | | `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks | | `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks | | `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks | | `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks | | `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks | | `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks | | `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks | | `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks | ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Polling de pedidos --- title: "Polling de pedidos" description: "GET /v1/orders/polling — polling leve dos pedidos das últimas 8h na fila de eventos da API BeeFood." method: "GET" path: "/v1/orders/polling" url: "https://developer.beefood.com.br/docs/pedidos/polling" group: "Pedidos" scope: "orders:read" lang: "pt" --- # Polling de pedidos `GET /v1/orders/polling` - Produção: `https://api.beefood.app/v1/orders/polling` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/polling` Retorna o último evento de cada pedido com eventos nas últimas 8 horas. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:read`. Limite: 15 requisições a cada 5 minutos; recomendado a cada 30 segundos. ## Parâmetros de query - `updatedSince` *string (ISO 8601)* — Só eventos a partir desta data/hora (até 24h). Exemplo: `"2025-03-15T18:00:00.000-03:00"`. - `events` *string | string[]* — Filtra pelos tipos de evento desejados. Exemplo: `"order_updated"`. - *Valores:* `order_created`, `order_updated`, `order_delivery_updated`, `payment_created`, `payment_updated` ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/orders/polling" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json [ { "orderId": 58449271, "event": "order_created", "orderType": "DELIVERY", "salesChannel": "MANUAL", "orderStatusDelivery": "WAITING", "createdAt": "2025-03-15T16:27:48.000-03:00" }, { "orderId": 58449215, "event": "order_updated", "orderType": "DELIVERY", "salesChannel": "DIGITAL_MENU", "orderStatusDelivery": "ACCEPTED", "createdAt": "2025-03-15T16:03:13.000-03:00" }, { "orderId": 58449271, "event": "order_delivery_updated", "orderType": "DELIVERY", "salesChannel": "MANUAL", "orderStatusDelivery": "PREPARING", "createdAt": "2025-03-15T16:27:48.000-03:00" }, { "orderId": 58449280, "event": "payment_created", "orderType": "PDV", "salesChannel": "TOTEM", "orderStatusDelivery": "READY", "createdAt": "2025-03-15T15:40:00.000-03:00" }, { "orderId": 58449281, "event": "payment_updated", "orderType": "TABLE", "salesChannel": "IFOOD", "orderStatusDelivery": "DISPATCHED", "createdAt": "2025-03-15T15:20:00.000-03:00" }, { "orderId": 58449271, "event": "order_delivery_updated", "orderType": "DELIVERY", "salesChannel": "MANUAL", "orderStatusDelivery": "DELIVERED", "createdAt": "2025-03-15T16:32:13.000-03:00" }, { "orderId": 58449282, "event": "order_updated", "orderType": "DELIVERY", "salesChannel": "DIGITAL_MENU", "orderStatusDelivery": "CANCELLED", "createdAt": "2025-03-15T14:10:00.000-03:00" } ] ``` ## Campos da resposta - `[].orderId` *number* — ID do pedido. - `[].event` *string* — Último evento ocorrido no pedido. - *Valores:* `order_created`, `order_updated`, `order_delivery_updated`, `payment_created`, `payment_updated` - `[].orderType` *string* — Tipo do pedido. - *Valores:* `DELIVERY`, `PDV`, `TABLE` - `[].salesChannel` *string* — Canal de venda do pedido. - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `EXTERNAL`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL` - `[].orderStatusDelivery` *string* — Situação da entrega no momento do evento. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `[].createdAt` *string (ISO 8601)* — Quando o pedido foi criado. ## Erros | Status | Mensagem | | --- | --- | | 400 | 'updatedSince' must be a valid date-time | | 400 | 'updatedSince' must be within the last 24 hours | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:read scope | | 429 | Too Many Requests | | 500 | Database error when trying to … | ## Vocabulários usados neste endpoint ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | | `CANCELLED` | Cancelado | Pedidos e webhooks | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Pedidos · salesChannel | Valor | Significado | Uso | | --- | --- | --- | | `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks | | `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks | | `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks | | `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks | | `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks | | `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks | | `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks | | `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks | | `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks | | `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks | | `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks | | `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks | ## Polling · event | Valor | Significado | Uso | | --- | --- | --- | | `order_created` | Pedido criado | GET /v1/orders/polling | | `order_updated` | Pedido atualizado | GET /v1/orders/polling | | `order_delivery_updated` | Entrega do pedido atualizada | GET /v1/orders/polling | | `payment_created` | Pagamento criado | GET /v1/orders/polling | | `payment_updated` | Pagamento atualizado | GET /v1/orders/polling | ## Resumo agrupado --- title: "Resumo agrupado" description: "GET /v1/orders/summary/grouped — métricas de pedidos quebradas por hora, dia, canal, filial ou forma de pagamento." method: "GET" path: "/v1/orders/summary/grouped" url: "https://developer.beefood.com.br/docs/pedidos/resumo-agrupado" group: "Relatórios" scope: "orders:read" lang: "pt" --- # Resumo agrupado `GET /v1/orders/summary/grouped` - Produção: `https://api.beefood.app/v1/orders/summary/grouped` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/summary/grouped` As métricas do resumo, quebradas por uma dimensão. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:read`. Limite: 15 requisições por minuto. ## Parâmetros de query - `groupBy` *string* **obrigatório** — Dimensão do agrupamento. Exemplo: `"orderType"`. - *Valores:* `hour`, `day`, `dayOfWeek`, `week`, `month`, `orderType`, `orderStatus`, `deliveryType`, `deliveryStatus`, `salesChannel`, `merchantId`, `driverId`, `paymentMethodId` - `saleDateFrom` *string (yyyy-mm-dd)* **obrigatório** — Início do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-01"`. - `saleDateTo` *string (yyyy-mm-dd)* **obrigatório** — Fim do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-31"`. - `orderType` *string* — Tipo do pedido. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:DELIVERY"`. - *Valores:* `TABLE`, `DELIVERY`, `PDV` - `orderStatus` *string* — Status do pedido; sem filtro, entram OPEN, RECEIVED e CLOSED. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `OPEN`, `RECEIVED`, `CLOSED`, `GROUPED`, `CANCELLED` - `deliveryType` *string* — Modalidade da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:TAKEOUT"`. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `deliveryStatus` *string* — Status da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `salesChannel` *string* — Canal de venda. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:IFOOD,99FOOD"`. - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL`, `EXTERNAL` - `merchantId` *string* — IDs de filial (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:10,11"`. - `customerId` *string* — IDs de cliente (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:77"`. - `documentNumber` *string* — CPF/CNPJ; só os dígitos contam. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:12345678900"`. - `email` *string* — E-mail do cliente, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:ana@exemplo.com,bia@exemplo.com"`. - `phone` *string* — Telefone do cliente; só dígitos, busca por trecho. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:11999990000"`. - `couponCode` *string* — Código do cupom, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:BEMVINDO"`. - `commandCode` *integer | integer[]* — Filtra pelo código da comanda. Exemplo: `12`. - `tableCode` *integer | integer[]* — Filtra pelo código da mesa. Exemplo: `5`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/orders/summary/grouped?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&groupBy=orderType" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "groupBy": "orderType", "groups": [ { "key": "DELIVERY", "orderCount": 1, "totalRevenue": 60, "averageOrderValue": 60 }, { "key": "PDV", "orderCount": 1, "totalRevenue": 40, "averageOrderValue": 40 } ] } ``` ## Campos da resposta - `groupBy` *string* — Dimensão usada. - *Valores:* `hour`, `day`, `dayOfWeek`, `week`, `month`, `orderType`, `orderStatus`, `deliveryType`, `deliveryStatus`, `salesChannel`, `merchantId`, `driverId`, `paymentMethodId` - `groups` *array* — Grupos com pedidos. - `groups[].key` *string | null* — Identificador do grupo; null sem valor na dimensão. - `groups[].label` *string* — Nome de exibição em merchantId, driverId e paymentMethodId. - `groups[].orderCount` *integer* — Pedidos no grupo. - `groups[].totalRevenue` *number* — Faturamento, 2 casas. - `groups[].averageOrderValue` *number* — Ticket médio, 2 casas. ## Filtros Os filtros usam o formato `campo=operador:valor1,valor2` (`in` ou `notIn`). Regras e exemplos em [Resumo de pedidos](/docs/pedidos/resumo#filtros). ## Erros | Status | Mensagem | | --- | --- | | 400 | 'groupBy' is required | | 400 | 'groupBy' must be one of: hour, day, dayOfWeek, week, month, orderType, orderStatus, deliveryType, deliveryStatus, salesChannel, merchantId, driverId, paymentMethodId | | 400 | 'saleDateFrom' is required | | 400 | 'saleDateFrom' must be a date (yyyy-mm-dd) | | 400 | 'saleDateFrom'..'saleDateTo' must span at most 6 months | | 400 | 'orderStatus' must be sent once; use orderStatus=in:value1,value2 | | 400 | 'orderStatus' operator must be one of: in, notIn | | 400 | 'orderStatus' must be one of: OPEN, RECEIVED, CLOSED, GROUPED, CANCELLED | | 400 | 'merchantId' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:read scope | | 429 | Too Many Requests | ## Vocabulários usados neste endpoint ## Pedidos · orderStatus | Valor | Significado | Uso | | --- | --- | --- | | `OPEN` | Aberto | Lista e detalhe de pedidos | | `RECEIVED` | Recebido | Lista e detalhe de pedidos | | `GROUPED` | Agrupado a outro pedido | Pedido somado a outro; orderIdGrouped indica o pedido principal | | `CLOSED` | Fechado | Lista e detalhe de pedidos | | `CANCELLED` | Cancelado | Lista e detalhe de pedidos | ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | | `CANCELLED` | Cancelado | Pedidos e webhooks | ## Pedidos · deliveryType | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Entrega | Lista e detalhe de pedidos | | `TAKEOUT` | Retirada | Lista e detalhe de pedidos | | `DINE_IN` | Consumo no local | Lista e detalhe de pedidos | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Pedidos · salesChannel | Valor | Significado | Uso | | --- | --- | --- | | `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks | | `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks | | `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks | | `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks | | `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks | | `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks | | `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks | | `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks | | `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks | | `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks | | `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks | | `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks | ## Relatórios · groupBy Dimensões aceitas no filtro groupBy do resumo agrupado de pedidos. | Valor | Significado | Uso | | --- | --- | --- | | `hour` | Hora do pedido | /v1/orders/summary/grouped | | `day` | Dia do pedido | /v1/orders/summary/grouped | | `dayOfWeek` | Dia da semana | /v1/orders/summary/grouped | | `week` | Semana do pedido | /v1/orders/summary/grouped | | `month` | Mês do pedido | /v1/orders/summary/grouped | | `orderType` | Tipo do pedido | /v1/orders/summary/grouped | | `orderStatus` | Status do pedido | /v1/orders/summary/grouped | | `deliveryType` | Tipo de entrega | /v1/orders/summary/grouped | | `deliveryStatus` | Status da entrega | /v1/orders/summary/grouped | | `salesChannel` | Canal de vendas | /v1/orders/summary/grouped | | `merchantId` | Estabelecimento | /v1/orders/summary/grouped | | `driverId` | Entregador | /v1/orders/summary/grouped | | `paymentMethodId` | Forma de pagamento | /v1/orders/summary/grouped | ## Resumo de pedidos --- title: "Resumo de pedidos" description: "GET /v1/orders/summary — quantidade, faturamento e ticket médio dos pedidos do período na API BeeFood." method: "GET" path: "/v1/orders/summary" url: "https://developer.beefood.com.br/docs/pedidos/resumo" group: "Relatórios" scope: "orders:read" lang: "pt" --- # Resumo de pedidos `GET /v1/orders/summary` - Produção: `https://api.beefood.app/v1/orders/summary` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/summary` Retorna quantidade, faturamento e ticket médio dos pedidos do período, sem a lista. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:read`. Limite: 15 requisições por minuto. ## Parâmetros de query - `saleDateFrom` *string (yyyy-mm-dd)* **obrigatório** — Início do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-01"`. - `saleDateTo` *string (yyyy-mm-dd)* **obrigatório** — Fim do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-31"`. - `orderType` *string* — Tipo do pedido. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:DELIVERY"`. - *Valores:* `TABLE`, `DELIVERY`, `PDV` - `orderStatus` *string* — Status do pedido; sem filtro, entram OPEN, RECEIVED e CLOSED. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `OPEN`, `RECEIVED`, `CLOSED`, `GROUPED`, `CANCELLED` - `deliveryType` *string* — Modalidade da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:TAKEOUT"`. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `deliveryStatus` *string* — Status da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `salesChannel` *string* — Canal de venda. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:IFOOD,99FOOD"`. - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL`, `EXTERNAL` - `merchantId` *string* — IDs de filial (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:10,11"`. - `customerId` *string* — IDs de cliente (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:77"`. - `documentNumber` *string* — CPF/CNPJ; só os dígitos contam. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:12345678900"`. - `email` *string* — E-mail do cliente, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:ana@exemplo.com,bia@exemplo.com"`. - `phone` *string* — Telefone do cliente; só dígitos, busca por trecho. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:11999990000"`. - `couponCode` *string* — Código do cupom, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:BEMVINDO"`. - `commandCode` *integer | integer[]* — Filtra pelo código da comanda. Exemplo: `12`. - `tableCode` *integer | integer[]* — Filtra pelo código da mesa. Exemplo: `5`. ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/orders/summary?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&orderType=DELIVERY" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "orderCount": 2, "totalRevenue": 150, "averageOrderValue": 75 } ``` ## Campos da resposta - `orderCount` *integer* — Quantidade de pedidos. - `totalRevenue` *number* — Soma de orderAmount, 2 casas. - `averageOrderValue` *number* — Ticket médio; 0 sem pedidos. ## Filtros Todo filtro segue o formato `campo=operador:valor1,valor2`. Sem operador, vale `in`: `orderStatus=OPEN,CANCELLED` é o mesmo que `orderStatus=in:OPEN,CANCELLED`. | Operador | Significado | Exemplo | |---|---|---| | `in` (padrão) | o campo é um dos valores (OU) | `orderStatus=in:OPEN,CANCELLED` | | `notIn` | o campo não é nenhum dos valores | `orderStatus=notIn:CLOSED,RECEIVED` | Campos: `orderStatus`, `orderType`, `deliveryType`, `deliveryStatus`, `salesChannel`, `customerId`, `merchantId`, `documentNumber`, `email`, `phone` e `couponCode` — todos aceitam `in` e `notIn`. ### Regras - Cada campo aparece uma vez só; chave repetida responde `400`. Por isso não dá para usar `in` e `notIn` no mesmo campo. - A vírgula sempre separa valores; não é possível filtrar um valor com vírgula. - O operador é o trecho antes do primeiro `:`. Para um valor com `:`, informe o operador: `couponCode=in:PROMO:10`. - Operador e enums não diferenciam maiúsculas (`IN:open` = `in:OPEN`). - Valor vazio (`orderStatus=` ou `orderStatus=in:`) equivale a não enviar o filtro. - Valores do mesmo campo combinam com OU; campos diferentes, com E. - `notIn` em `customerId`, `documentNumber`, `email`, `phone` e `couponCode` mantém pedidos sem cliente ou sem cupom. ### Status do pedido - Sem `orderStatus`, entram só `OPEN`, `RECEIVED` e `CLOSED`. - `orderStatus=in:…` substitui o padrão; `orderStatus=notIn:…` parte de todos os status. - Pedidos `GROUPED` nunca entram. ### Exemplos de filtros `GET /v1/orders/summary?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&orderType=DELIVERY` — `in` implícito: só pedidos de delivery. `GET /v1/orders/summary?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&orderStatus=in:OPEN,CANCELLED` — pedidos abertos ou cancelados. `GET /v1/orders/summary?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&orderStatus=notIn:CANCELLED` — todos os status menos cancelados. `GET /v1/orders/summary?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&salesChannel=notIn:IFOOD,99FOOD` — todos os canais menos iFood e 99Food. `GET /v1/orders/summary/grouped?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&groupBy=salesChannel&orderType=in:DELIVERY&deliveryStatus=notIn:CANCELLED` — delivery e não cancelado na entrega, agrupado por canal. `GET /v1/orders/summary/sectors?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&merchantId=in:10,11&customerId=notIn:77` — filial 10 ou 11, e cliente diferente de 77. ### Quero → Query | Quero | Query | |---|---| | Padrão (abertos, recebidos e fechados) | sem `orderStatus` | | Só cancelados | `orderStatus=CANCELLED` | | Abertos e cancelados | `orderStatus=in:OPEN,CANCELLED` | | Tudo, inclusive cancelados | `orderStatus=in:OPEN,RECEIVED,CLOSED,CANCELLED` | | Tudo menos cancelados | `orderStatus=notIn:CANCELLED` | | Delivery, exceto iFood e 99Food | `orderType=DELIVERY&salesChannel=notIn:IFOOD,99FOOD` | | Duas filiais | `merchantId=in:10,11` | | Todas as filiais menos uma | `merchantId=notIn:12` | | Pedidos sem o cupom X | `couponCode=notIn:BEMVINDO` | ## Erros | Status | Mensagem | | --- | --- | | 400 | 'saleDateFrom' is required | | 400 | 'saleDateFrom' must be a date (yyyy-mm-dd) | | 400 | 'saleDateFrom'..'saleDateTo' must span at most 6 months | | 400 | 'orderStatus' must be sent once; use orderStatus=in:value1,value2 | | 400 | 'orderStatus' operator must be one of: in, notIn | | 400 | 'orderStatus' must be one of: OPEN, RECEIVED, CLOSED, GROUPED, CANCELLED | | 400 | 'merchantId' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:read scope | | 429 | Too Many Requests | ## Vocabulários usados neste endpoint ## Pedidos · orderStatus | Valor | Significado | Uso | | --- | --- | --- | | `OPEN` | Aberto | Lista e detalhe de pedidos | | `RECEIVED` | Recebido | Lista e detalhe de pedidos | | `GROUPED` | Agrupado a outro pedido | Pedido somado a outro; orderIdGrouped indica o pedido principal | | `CLOSED` | Fechado | Lista e detalhe de pedidos | | `CANCELLED` | Cancelado | Lista e detalhe de pedidos | ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | | `CANCELLED` | Cancelado | Pedidos e webhooks | ## Pedidos · deliveryType | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Entrega | Lista e detalhe de pedidos | | `TAKEOUT` | Retirada | Lista e detalhe de pedidos | | `DINE_IN` | Consumo no local | Lista e detalhe de pedidos | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Pedidos · salesChannel | Valor | Significado | Uso | | --- | --- | --- | | `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks | | `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks | | `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks | | `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks | | `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks | | `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks | | `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks | | `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks | | `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks | | `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks | | `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks | | `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks | ## Atualizar status de entrega --- title: "Atualizar status de entrega" description: "PATCH /v1/orders/{orderId}/delivery-status — altera o status de entrega de um pedido na API BeeFood." method: "PATCH" path: "/v1/orders/{orderId}/delivery-status" url: "https://developer.beefood.com.br/docs/pedidos/status-entrega" group: "Pedidos" scope: "orders:write" lang: "pt" --- # Atualizar status de entrega `PATCH /v1/orders/{orderId}/delivery-status` - Produção: `https://api.beefood.app/v1/orders/{orderId}/delivery-status` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/{orderId}/delivery-status` Movimenta o status de entrega de um pedido DELIVERY. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:write`. Limite: 300 requisições a cada 3 minutos. ## Parâmetros de path - `orderId` *integer* **obrigatório** — ID do pedido, maior ou igual a 1. Exemplo: `58449271`. ## Parâmetros do body - `deliveryStatus` *string* **obrigatório** — Novo status de entrega. Exemplo: `"DISPATCHED"`. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED` ## Exemplos de requisição ### cURL ```bash curl -X PATCH "https://api.beefood.app/v1/orders/{orderId}/delivery-status" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "deliveryStatus": "DISPATCHED" }' ``` ## Exemplos de resposta ### 200 OK ```json ``` ## Erros | Status | Mensagem | | --- | --- | | 400 | 'id' must be a positive integer | | 400 | 'deliveryStatus' must be one of WAITING, ACCEPTED, PREPARING, READY, DISPATCHED, DELIVERED | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:write scope | | 404 | Order ID 123 not found | | 422 | Order ID 123 is not a delivery order | | 422 | Order ID 123 is cancelled | | 429 | Too Many Requests | | 500 | Database error when trying to … | | 502 | Delivery status service unavailable | | 502 | Delivery status service failed to update the order | ## Vocabulários usados neste endpoint ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | ## Vendas por opção --- title: "Vendas por opção" description: "GET /v1/orders/summary/options — ranking de vendas por opção na API BeeFood." method: "GET" path: "/v1/orders/summary/options" url: "https://developer.beefood.com.br/docs/pedidos/vendas-opcao" group: "Relatórios" scope: "orders:read" lang: "pt" --- # Vendas por opção `GET /v1/orders/summary/options` - Produção: `https://api.beefood.app/v1/orders/summary/options` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/summary/options` Ranking de vendas por nome de opção, como gravado no pedido. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:read`. Limite: 15 requisições por minuto. ## Parâmetros de query - `saleDateFrom` *string (yyyy-mm-dd)* **obrigatório** — Início do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-01"`. - `saleDateTo` *string (yyyy-mm-dd)* **obrigatório** — Fim do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-31"`. - `orderType` *string* — Tipo do pedido. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:DELIVERY"`. - *Valores:* `TABLE`, `DELIVERY`, `PDV` - `orderStatus` *string* — Status do pedido; sem filtro, entram OPEN, RECEIVED e CLOSED. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `OPEN`, `RECEIVED`, `CLOSED`, `GROUPED`, `CANCELLED` - `deliveryType` *string* — Modalidade da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:TAKEOUT"`. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `deliveryStatus` *string* — Status da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `salesChannel` *string* — Canal de venda. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:IFOOD,99FOOD"`. - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL`, `EXTERNAL` - `merchantId` *string* — IDs de filial (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:10,11"`. - `customerId` *string* — IDs de cliente (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:77"`. - `documentNumber` *string* — CPF/CNPJ; só os dígitos contam. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:12345678900"`. - `email` *string* — E-mail do cliente, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:ana@exemplo.com,bia@exemplo.com"`. - `phone` *string* — Telefone do cliente; só dígitos, busca por trecho. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:11999990000"`. - `couponCode` *string* — Código do cupom, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:BEMVINDO"`. - `commandCode` *integer | integer[]* — Filtra pelo código da comanda. Exemplo: `12`. - `tableCode` *integer | integer[]* — Filtra pelo código da mesa. Exemplo: `5`. - `name` *string* — Busca parcial no nome da opção. Exemplo: `"Pizza"`. - `sectorId` *integer* — Filtra por setor do produto. Exemplo: `221027`. - `page` *integer* — Página, padrão 1. Exemplo: `1`. - `limit` *integer* — Itens por página, de 1 a 100 (padrão 20). Exemplo: `20`. - `orderBy` *string* — Ordenação, padrão totalRevenue. Exemplo: `"totalRevenue"`. - *Valores:* `totalRevenue`, `totalQuantity`, `averagePrice`, `name` - `sort` *string* — asc ou desc (padrão desc). Exemplo: `"desc"`. - *Valores:* `asc`, `desc` ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/orders/summary/options?saleDateFrom=2026-09-01&saleDateTo=2026-09-30" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "name": "Batata c/ cheddar e bacon", "totalQuantity": 112, "totalRevenue": 1008, "averagePrice": 9 } ], "page": 1, "limit": 20, "total": 1, "pages": 1, "totals": { "totalQuantity": 112, "totalRevenue": 1008 } } ``` ## Campos da resposta - `items` *array* — Opções da página. - `items[].name` *string* — Nome da opção; omitido quando vazio. - `items[].totalQuantity` *number* — Unidades vendidas, até 3 casas. - `items[].totalRevenue` *number* — Faturamento, 2 casas. - `items[].averagePrice` *number* — Preço médio por unidade, 2 casas. - `page` *integer* — Página atual. - `limit` *integer* — Itens por página. - `total` *integer* — Total de linhas no resultado. - `pages` *integer* — Total de páginas. - `totals.totalQuantity` *number* — Soma da quantidade de todas as páginas. - `totals.totalRevenue` *number* — Soma do faturamento de todas as páginas. ## Filtros Os filtros usam o formato `campo=operador:valor1,valor2` (`in` ou `notIn`). Regras e exemplos em [Resumo de pedidos](/docs/pedidos/resumo#filtros). ## Erros | Status | Mensagem | | --- | --- | | 400 | 'sectorId' must be a positive integer | | 400 | 'page' must be an integer >= 1 | | 400 | 'limit' must be an integer between 1 and 100 | | 400 | 'orderBy' must be one of: totalRevenue, totalQuantity, averagePrice, name | | 400 | 'sort' must be asc or desc | | 400 | 'saleDateFrom' is required | | 400 | 'saleDateFrom' must be a date (yyyy-mm-dd) | | 400 | 'saleDateFrom'..'saleDateTo' must span at most 6 months | | 400 | 'orderStatus' must be sent once; use orderStatus=in:value1,value2 | | 400 | 'orderStatus' operator must be one of: in, notIn | | 400 | 'orderStatus' must be one of: OPEN, RECEIVED, CLOSED, GROUPED, CANCELLED | | 400 | 'merchantId' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:read scope | | 429 | Too Many Requests | ## Vocabulários usados neste endpoint ## Pedidos · orderStatus | Valor | Significado | Uso | | --- | --- | --- | | `OPEN` | Aberto | Lista e detalhe de pedidos | | `RECEIVED` | Recebido | Lista e detalhe de pedidos | | `GROUPED` | Agrupado a outro pedido | Pedido somado a outro; orderIdGrouped indica o pedido principal | | `CLOSED` | Fechado | Lista e detalhe de pedidos | | `CANCELLED` | Cancelado | Lista e detalhe de pedidos | ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | | `CANCELLED` | Cancelado | Pedidos e webhooks | ## Pedidos · deliveryType | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Entrega | Lista e detalhe de pedidos | | `TAKEOUT` | Retirada | Lista e detalhe de pedidos | | `DINE_IN` | Consumo no local | Lista e detalhe de pedidos | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Pedidos · salesChannel | Valor | Significado | Uso | | --- | --- | --- | | `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks | | `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks | | `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks | | `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks | | `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks | | `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks | | `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks | | `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks | | `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks | | `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks | | `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks | | `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks | ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Vendas por produto --- title: "Vendas por produto" description: "GET /v1/orders/summary/products — ranking de vendas por produto na API BeeFood." method: "GET" path: "/v1/orders/summary/products" url: "https://developer.beefood.com.br/docs/pedidos/vendas-produto" group: "Relatórios" scope: "orders:read" lang: "pt" --- # Vendas por produto `GET /v1/orders/summary/products` - Produção: `https://api.beefood.app/v1/orders/summary/products` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/summary/products` Ranking de vendas por produto; opções não contam na quantidade, mas entram no faturamento. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:read`. Limite: 15 requisições por minuto. ## Parâmetros de query - `saleDateFrom` *string (yyyy-mm-dd)* **obrigatório** — Início do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-01"`. - `saleDateTo` *string (yyyy-mm-dd)* **obrigatório** — Fim do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-31"`. - `orderType` *string* — Tipo do pedido. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:DELIVERY"`. - *Valores:* `TABLE`, `DELIVERY`, `PDV` - `orderStatus` *string* — Status do pedido; sem filtro, entram OPEN, RECEIVED e CLOSED. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `OPEN`, `RECEIVED`, `CLOSED`, `GROUPED`, `CANCELLED` - `deliveryType` *string* — Modalidade da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:TAKEOUT"`. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `deliveryStatus` *string* — Status da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `salesChannel` *string* — Canal de venda. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:IFOOD,99FOOD"`. - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL`, `EXTERNAL` - `merchantId` *string* — IDs de filial (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:10,11"`. - `customerId` *string* — IDs de cliente (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:77"`. - `documentNumber` *string* — CPF/CNPJ; só os dígitos contam. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:12345678900"`. - `email` *string* — E-mail do cliente, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:ana@exemplo.com,bia@exemplo.com"`. - `phone` *string* — Telefone do cliente; só dígitos, busca por trecho. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:11999990000"`. - `couponCode` *string* — Código do cupom, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:BEMVINDO"`. - `commandCode` *integer | integer[]* — Filtra pelo código da comanda. Exemplo: `12`. - `tableCode` *integer | integer[]* — Filtra pelo código da mesa. Exemplo: `5`. - `name` *string* — Busca parcial no nome do produto. Exemplo: `"Pizza"`. - `sectorId` *integer* — Filtra por setor do produto. Exemplo: `221027`. - `page` *integer* — Página, padrão 1. Exemplo: `1`. - `limit` *integer* — Itens por página, de 1 a 100 (padrão 20). Exemplo: `20`. - `orderBy` *string* — Ordenação, padrão totalRevenue. Exemplo: `"totalRevenue"`. - *Valores:* `totalRevenue`, `totalQuantity`, `averagePrice`, `name` - `sort` *string* — asc ou desc (padrão desc). Exemplo: `"desc"`. - *Valores:* `asc`, `desc` ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/orders/summary/products?saleDateFrom=2026-09-01&saleDateTo=2026-09-30§orId=221027" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "productId": 1561258, "name": "2 Pizzas Grandes", "sectorId": 221027, "totalQuantity": 2, "totalRevenue": 134.9, "averagePrice": 67.45 } ], "page": 1, "limit": 20, "total": 1, "pages": 1, "totals": { "totalQuantity": 2, "totalRevenue": 134.9 } } ``` ## Campos da resposta - `items` *array* — Produtos da página. - `items[].productId` *integer | null* — ID do produto; null para item avulso. - `items[].name` *string* — Nome atual do produto. - `items[].sectorId` *integer | null* — Setor atual do produto. - `items[].totalQuantity` *number* — Unidades vendidas, sem opções. - `items[].totalRevenue` *number* — Faturamento, 2 casas. - `items[].averagePrice` *number* — Preço médio por unidade, 2 casas. - `page` *integer* — Página atual. - `limit` *integer* — Itens por página. - `total` *integer* — Total de linhas no resultado. - `pages` *integer* — Total de páginas. - `totals.totalQuantity` *number* — Soma da quantidade de todas as páginas. - `totals.totalRevenue` *number* — Soma do faturamento de todas as páginas. ## Filtros Os filtros usam o formato `campo=operador:valor1,valor2` (`in` ou `notIn`). Regras e exemplos em [Resumo de pedidos](/docs/pedidos/resumo#filtros). ## Erros | Status | Mensagem | | --- | --- | | 400 | 'sectorId' must be a positive integer | | 400 | 'page' must be an integer >= 1 | | 400 | 'limit' must be an integer between 1 and 100 | | 400 | 'orderBy' must be one of: totalRevenue, totalQuantity, averagePrice, name | | 400 | 'sort' must be asc or desc | | 400 | 'saleDateFrom' is required | | 400 | 'saleDateFrom' must be a date (yyyy-mm-dd) | | 400 | 'saleDateFrom'..'saleDateTo' must span at most 6 months | | 400 | 'orderStatus' must be sent once; use orderStatus=in:value1,value2 | | 400 | 'orderStatus' operator must be one of: in, notIn | | 400 | 'orderStatus' must be one of: OPEN, RECEIVED, CLOSED, GROUPED, CANCELLED | | 400 | 'merchantId' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:read scope | | 429 | Too Many Requests | ## Vocabulários usados neste endpoint ## Pedidos · orderStatus | Valor | Significado | Uso | | --- | --- | --- | | `OPEN` | Aberto | Lista e detalhe de pedidos | | `RECEIVED` | Recebido | Lista e detalhe de pedidos | | `GROUPED` | Agrupado a outro pedido | Pedido somado a outro; orderIdGrouped indica o pedido principal | | `CLOSED` | Fechado | Lista e detalhe de pedidos | | `CANCELLED` | Cancelado | Lista e detalhe de pedidos | ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | | `CANCELLED` | Cancelado | Pedidos e webhooks | ## Pedidos · deliveryType | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Entrega | Lista e detalhe de pedidos | | `TAKEOUT` | Retirada | Lista e detalhe de pedidos | | `DINE_IN` | Consumo no local | Lista e detalhe de pedidos | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Pedidos · salesChannel | Valor | Significado | Uso | | --- | --- | --- | | `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks | | `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks | | `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks | | `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks | | `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks | | `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks | | `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks | | `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks | | `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks | | `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks | | `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks | | `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks | ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Vendas por setor --- title: "Vendas por setor" description: "GET /v1/orders/summary/sectors — ranking de vendas por setor do catálogo na API BeeFood." method: "GET" path: "/v1/orders/summary/sectors" url: "https://developer.beefood.com.br/docs/pedidos/vendas-setor" group: "Relatórios" scope: "orders:read" lang: "pt" --- # Vendas por setor `GET /v1/orders/summary/sectors` - Produção: `https://api.beefood.app/v1/orders/summary/sectors` - Sandbox: `https://api-sandbox.beefood.app/v1/orders/summary/sectors` Ranking de quantidade, faturamento e preço médio por setor do catálogo. ## Autenticação Envie o access token no header `Authorization: Bearer `. Escopo necessário: `orders:read`. Limite: 15 requisições por minuto. ## Parâmetros de query - `saleDateFrom` *string (yyyy-mm-dd)* **obrigatório** — Início do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-01"`. - `saleDateTo` *string (yyyy-mm-dd)* **obrigatório** — Fim do período da data de venda. O intervalo entre saleDateFrom e saleDateTo não pode passar de 6 meses. Exemplo: `"2026-03-31"`. - `orderType` *string* — Tipo do pedido. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:DELIVERY"`. - *Valores:* `TABLE`, `DELIVERY`, `PDV` - `orderStatus` *string* — Status do pedido; sem filtro, entram OPEN, RECEIVED e CLOSED. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `OPEN`, `RECEIVED`, `CLOSED`, `GROUPED`, `CANCELLED` - `deliveryType` *string* — Modalidade da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:TAKEOUT"`. - *Valores:* `DELIVERY`, `TAKEOUT`, `DINE_IN` - `deliveryStatus` *string* — Status da entrega. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:CANCELLED"`. - *Valores:* `WAITING`, `ACCEPTED`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED` - `salesChannel` *string* — Canal de venda. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:IFOOD,99FOOD"`. - *Valores:* `IFOOD`, `99FOOD`, `KEETA`, `AIQFOME`, `RAPPI`, `DELIVERYMUCH`, `UAIRANGO`, `TOTEM`, `WHATSAPP`, `DIGITAL_MENU`, `MANUAL`, `EXTERNAL` - `merchantId` *string* — IDs de filial (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:10,11"`. - `customerId` *string* — IDs de cliente (inteiros maior ou igual a 1). Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:77"`. - `documentNumber` *string* — CPF/CNPJ; só os dígitos contam. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:12345678900"`. - `email` *string* — E-mail do cliente, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:ana@exemplo.com,bia@exemplo.com"`. - `phone` *string* — Telefone do cliente; só dígitos, busca por trecho. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"in:11999990000"`. - `couponCode` *string* — Código do cupom, sem diferenciar maiúsculas. Formato `in:v1,v2` ou `notIn:v1,v2`; sem operador vale `in`. Exemplo: `"notIn:BEMVINDO"`. - `commandCode` *integer | integer[]* — Filtra pelo código da comanda. Exemplo: `12`. - `tableCode` *integer | integer[]* — Filtra pelo código da mesa. Exemplo: `5`. - `name` *string* — Busca parcial no nome do setor. Exemplo: `"Pizza"`. - `page` *integer* — Página, padrão 1. Exemplo: `1`. - `limit` *integer* — Itens por página, de 1 a 100 (padrão 20). Exemplo: `20`. - `orderBy` *string* — Ordenação, padrão totalRevenue. Exemplo: `"totalRevenue"`. - *Valores:* `totalRevenue`, `totalQuantity`, `averagePrice`, `name` - `sort` *string* — asc ou desc (padrão desc). Exemplo: `"desc"`. - *Valores:* `asc`, `desc` ## Exemplos de requisição ### cURL ```bash curl -X GET "https://api.beefood.app/v1/orders/summary/sectors?saleDateFrom=2026-09-01&saleDateTo=2026-09-30&orderBy=totalQuantity" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## Exemplos de resposta ### 200 OK ```json { "items": [ { "sectorId": 12, "name": "Lanches", "totalQuantity": 140, "totalRevenue": 3120.5, "averagePrice": 22.29 }, { "sectorId": 15, "name": "Bebidas", "totalQuantity": 270, "totalRevenue": 4452.49, "averagePrice": 16.49 } ], "page": 1, "limit": 20, "total": 2, "pages": 1, "totals": { "totalQuantity": 410, "totalRevenue": 7572.99 } } ``` ## Campos da resposta - `items` *array* — Setores da página. - `items[].sectorId` *integer | null* — ID do setor; null para itens sem setor. - `items[].name` *string* — Nome do setor. - `items[].totalQuantity` *number* — Itens e opções vendidos, até 3 casas. - `items[].totalRevenue` *number* — Faturamento, 2 casas. - `items[].averagePrice` *number* — Preço médio por unidade, 2 casas. - `page` *integer* — Página atual. - `limit` *integer* — Itens por página. - `total` *integer* — Total de linhas no resultado. - `pages` *integer* — Total de páginas. - `totals.totalQuantity` *number* — Soma da quantidade de todas as páginas. - `totals.totalRevenue` *number* — Soma do faturamento de todas as páginas. ## Filtros Os filtros usam o formato `campo=operador:valor1,valor2` (`in` ou `notIn`). Regras e exemplos em [Resumo de pedidos](/docs/pedidos/resumo#filtros). ## Erros | Status | Mensagem | | --- | --- | | 400 | 'page' must be an integer >= 1 | | 400 | 'limit' must be an integer between 1 and 100 | | 400 | 'orderBy' must be one of: totalRevenue, totalQuantity, averagePrice, name | | 400 | 'sort' must be asc or desc | | 400 | 'saleDateFrom' is required | | 400 | 'saleDateFrom' must be a date (yyyy-mm-dd) | | 400 | 'saleDateFrom'..'saleDateTo' must span at most 6 months | | 400 | 'orderStatus' must be sent once; use orderStatus=in:value1,value2 | | 400 | 'orderStatus' operator must be one of: in, notIn | | 400 | 'orderStatus' must be one of: OPEN, RECEIVED, CLOSED, GROUPED, CANCELLED | | 400 | 'merchantId' must be a positive integer | | 401 | Authentication token is missing | | 401 | Invalid or expired access token | | 403 | This credential does not include the orders:read scope | | 429 | Too Many Requests | ## Vocabulários usados neste endpoint ## Pedidos · orderStatus | Valor | Significado | Uso | | --- | --- | --- | | `OPEN` | Aberto | Lista e detalhe de pedidos | | `RECEIVED` | Recebido | Lista e detalhe de pedidos | | `GROUPED` | Agrupado a outro pedido | Pedido somado a outro; orderIdGrouped indica o pedido principal | | `CLOSED` | Fechado | Lista e detalhe de pedidos | | `CANCELLED` | Cancelado | Lista e detalhe de pedidos | ## Pedidos · deliveryStatus Situação operacional do pedido. Aparece na lista e no detalhe e é espelhada nos webhooks de status. | Valor | Significado | Uso | | --- | --- | --- | | `WAITING` | Aguardando | Pedidos e webhooks | | `ACCEPTED` | Aceito | Pedidos e webhooks | | `PREPARING` | Em preparo | Pedidos e webhooks | | `READY` | Pronto | Pedidos e webhooks | | `DISPATCHED` | Despachado | Pedidos e webhooks | | `DELIVERED` | Entregue | Pedidos e webhooks | | `CANCELLED` | Cancelado | Pedidos e webhooks | ## Pedidos · deliveryType | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Entrega | Lista e detalhe de pedidos | | `TAKEOUT` | Retirada | Lista e detalhe de pedidos | | `DINE_IN` | Consumo no local | Lista e detalhe de pedidos | ## Pedidos · orderType Outros literais vindos do PDV podem aparecer sem tradução. | Valor | Significado | Uso | | --- | --- | --- | | `DELIVERY` | Pedido delivery | Detalhe do pedido | | `PDV` | Pedido lançado no PDV | Detalhe do pedido | | `TABLE` | Mesa / presencial | Detalhe do pedido | ## Pedidos · salesChannel | Valor | Significado | Uso | | --- | --- | --- | | `IFOOD` | iFood | Detalhe, listagem (filtro), polling e webhooks | | `99FOOD` | 99Food | Detalhe, listagem (filtro), polling e webhooks | | `KEETA` | Keeta | Detalhe, listagem (filtro), polling e webhooks | | `AIQFOME` | Aiqfome | Detalhe, listagem (filtro), polling e webhooks | | `RAPPI` | Rappi | Detalhe, listagem (filtro), polling e webhooks | | `DELIVERYMUCH` | Delivery Much | Detalhe, listagem (filtro), polling e webhooks | | `UAIRANGO` | UaiRango | Detalhe, listagem (filtro), polling e webhooks | | `TOTEM` | Totem | Detalhe, listagem (filtro), polling e webhooks | | `EXTERNAL` | Integração externa | Detalhe, listagem (filtro), polling e webhooks | | `WHATSAPP` | Cardápio digital via WhatsApp | Detalhe, listagem (filtro), polling e webhooks | | `DIGITAL_MENU` | Cardápio digital | Detalhe, listagem (filtro), polling e webhooks | | `MANUAL` | Lançamento manual / PDV | Detalhe, listagem (filtro), polling e webhooks | ## Listagens · sort | Valor | Significado | Uso | | --- | --- | --- | | `asc` | Crescente | Todas as listagens | | `desc` | Decrescente (padrão) | Todas as listagens | ## Publicar aplicativo — BeeFood Developers --- title: "Publicar aplicativo — BeeFood Developers" description: "Etapas e benefícios para publicar um aplicativo integrado no sistema BeeFood." url: "https://developer.beefood.com.br/docs/publicar-aplicativo" group: "Integrações" lang: "pt" --- # Publicar aplicativo Publique seu aplicativo integrado dentro do sistema BeeFood e dê acesso à sua ferramenta a todos os clientes da BeeFood. ## Sua integração ganha visibilidade - Uma postagem no Instagram anunciando a nova integração. - Uma postagem nas [novidades da BeeFood](https://beefood.app/novidades). - Acesso ao seu aplicativo para todos os clientes da BeeFood. ## 1. Crie sua conta no developer Seu primeiro passo é criar uma conta no portal de desenvolvedores da BeeFood. Com seu acesso, você pode começar a preparar a integração do seu aplicativo. ## 2. Desenvolva e teste seu aplicativo Use a documentação da API para construir sua integração e faça seus testes no sandbox. Deixe os fluxos do aplicativo prontos para apresentar ao nosso time. ## 3. Agende uma demonstração Entre em contato com o time de integração pelo WhatsApp e agende uma demonstração. Apresente seu aplicativo, como ele se conecta à BeeFood e o que ele oferece aos clientes. ## 4. Seu aplicativo dentro da BeeFood Depois da demonstração e do alinhamento com o time, seu aplicativo é publicado na área de aplicativos da BeeFood e fica visível para todos os clientes, que passam a ter acesso à sua ferramenta. [Criar acesso](https://developer.beefood.com.br/auth?tab=provision) [Documentação](https://developer.beefood.com.br/docs) [WhatsApp: (15) 99185-3430](https://wa.me/5515991853430?text=Ol%C3%A1%2C%20time%20de%20integra%C3%A7%C3%A3o%20BeeFood!%20Desenvolvi%20um%20aplicativo%20integrado%20%C3%A0%20BeeFood%20e%20gostaria%20de%20agendar%20uma%20demonstra%C3%A7%C3%A3o%20para%20public%C3%A1-lo%20nos%20aplicativos%20da%20BeeFood.) ## Webhooks — BeeFood API --- title: "Webhooks — BeeFood API" description: "Como receber eventos de pedido da BeeFood em tempo real: assinatura, formato do evento, segurança e política de reentrega." url: "https://developer.beefood.com.br/docs/webhooks" group: "Webhooks" lang: "pt" --- # Webhooks O webhook avisa a sua aplicação, em tempo real, que **alguma coisa mudou em um pedido**: ele nasceu, foi alterado, mudou de status de entrega ou recebeu um pagamento. É a alternativa recomendada ao [polling](https://docs.beefood.app/docs/pedidos/polling): em vez de perguntar de tempos em tempos se mudou algo, você recebe um POST no momento em que muda. ## Cadastrando um webhook O cadastro é feito **no painel do desenvolvedor**, em *Webhooks*. Não há rota pública para criar webhook por código. No cadastro você informa: | Campo | Descrição | | --- | --- | | **URL** | O endereço que vai receber os POSTs. Precisa ser HTTPS e estar acessível pela internet | | **Eventos** | Quais dos eventos abaixo esse webhook recebe | | **E-mail do responsável** | Para onde avisamos se as entregas começarem a falhar | | **Usuário e senha** | Opcionais. Preenchidos, enviamos Basic Auth na URL de destino (os dois ou nenhum) | | **Ativo** | Desmarque para pausar as entregas sem perder o cadastro | Você pode ter mais de um webhook por estabelecimento, cada um assinando eventos diferentes. O **secret** é exibido **uma única vez**, no momento da criação. Guarde-o: é com ele que você valida que a chamada veio mesmo da BeeFood. Se perder, gere um novo webhook. ## Eventos disponíveis | `eventType` | Quando dispara | | --- | --- | | `order_created` | Pedido criado | | `order_updated` | Pedido alterado (inclusive devolução de Pix) | | `order_delivery_updated` | Mudança no status de entrega | | `payment_created` | Pagamento registrado | | `payment_updated` | Pagamento alterado ou excluído | ## O que você recebe O corpo do POST é o **evento**, não o pedido: ```json { "eventType": "order_delivery_updated", "orderId": 58449268, "event": "order_delivery_updated", "orderType": "DELIVERY", "salesChannel": "IFOOD", "orderStatusDelivery": "PREPARING", "createdAt": "2025-03-15T18:42:10.000Z" } ``` | Campo | Descrição | | --- | --- | | `eventType` / `event` | O tipo do evento. Os dois campos trazem sempre o mesmo valor; `event` é o nome que a rota de polling usa. Escolha um | | `orderId` | Identificador do pedido, o mesmo aceito em `GET /v1/orders/{orderId}` | | `orderType` | `DELIVERY`, `PDV` ou `TABLE` | | `salesChannel` | Canal de venda (`IFOOD`, `DIGITAL_MENU`, `MANUAL`, …) | | `orderStatusDelivery` | Status de entrega no momento do evento (`WAITING`, `PREPARING`, `READY`, `DISPATCHED`, `DELIVERED`, `CANCELLED`) | | `createdAt` | Momento do evento, em UTC | Campos que o evento não carrega são **omitidos** do JSON — trate todos como opcionais, exceto `eventType`, `event` e `orderId`. É exatamente o mesmo formato de um item de `GET /v1/orders/polling`. Quem já consome o polling pode reaproveitar o mesmo código de tratamento nos dois caminhos. ## Exemplos por evento O formato é o mesmo para todos os eventos — o que varia é quais campos opcionais vêm preenchidos, porque cada evento nasce de uma operação diferente no sistema do restaurante. ### `order_created` Pedido novo. É o evento mais completo, e o melhor momento para buscar o detalhe e guardar o que você precisa. ```json { "eventType": "order_created", "orderId": 61398399, "event": "order_created", "orderType": "DELIVERY", "salesChannel": "IFOOD", "orderStatusDelivery": "PREPARING", "createdAt": "2026-10-13T12:44:25.000Z" } ``` ### `order_delivery_updated` Mudança de status de entrega. É o evento de maior volume: um pedido de delivery costuma gerar de 3 a 6 deles até ser entregue. ```json { "eventType": "order_delivery_updated", "orderId": 61398393, "event": "order_delivery_updated", "orderType": "DELIVERY", "salesChannel": "IFOOD", "orderStatusDelivery": "PREPARING", "createdAt": "2026-10-13T12:44:11.000Z" } ``` Acompanhe o `orderStatusDelivery` para saber onde o pedido está. A sequência típica é `WAITING` → `ACCEPTED` → `PREPARING` → `READY` → `DISPATCHED` → `DELIVERED`, e qualquer etapa pode terminar em `CANCELLED`. ### `order_updated` Pedido alterado. Dispara em situações variadas — devolução de Pix, alteração de itens, reabertura — e por isso é o evento que costuma trazer menos campos: ```json { "eventType": "order_updated", "orderId": 61398324, "event": "order_updated", "createdAt": "2026-10-13T12:44:00.000Z" } ``` Como o evento não diz **o que** mudou, este é o caso em que buscar o detalhe faz sentido, se o seu sistema precisa refletir alterações no conteúdo do pedido. ### `payment_created` Pagamento registrado no pedido. ```json { "eventType": "payment_created", "orderId": 61398383, "event": "payment_created", "orderType": "TABLE", "createdAt": "2026-10-13T12:44:26.000Z" } ``` ### `payment_updated` Pagamento alterado ou excluído. ```json { "eventType": "payment_updated", "orderId": 61398097, "event": "payment_updated", "orderType": "TABLE", "createdAt": "2026-10-13T12:43:10.000Z" } ``` > **Informação** > > Os eventos de pagamento avisam que *houve* movimento de pagamento no pedido, mas **não trazem valor, forma de pagamento nem o identificador do pagamento**. Para esses dados, consulte `payments` em `GET /v1/orders/{orderId}`. ## Como usar o evento O evento diz **o que mudou e em qual pedido**. Quando você precisar do conteúdo do pedido — itens, cliente, pagamentos, endereço — chame o detalhe: ``` GET /v1/orders/{orderId} ``` Na prática, a maior parte das integrações não precisa do detalhe em todo evento. Um `order_delivery_updated` que leva o pedido para `DELIVERED`, por exemplo, já traz tudo o que é preciso para dar baixa: o `orderId` e o novo status. Buscar o pedido inteiro nesse momento é trabalho jogado fora, porque nada mudou além do status que o próprio evento já informou. A recomendação é: **leia o detalhe uma vez**, normalmente no `order_created`, guarde o que você precisa, e depois use os eventos seguintes só para atualizar o status na sua base. > **Atenção** > > Buscar o detalhe do pedido a cada evento recebido é o erro mais comum de integração. Além de desnecessário, é a chamada mais cara da API, porque ela consulta o sistema do restaurante em tempo real. Consultas repetidas em excesso podem acionar a [proteção de uso indevido](https://docs.beefood.app/docs/limites). ## Segurança Toda entrega inclui o header: ``` X-Webhook-Secret: ``` Valide esse header e rejeite o que não bater. Se a sua URL exigir Basic Auth, informe `user` e `password` no cadastro do webhook (os dois ou nenhum) e nós enviaremos o header `Authorization` junto. ## Entrega e reentrega | Regra | Comportamento | | --- | --- | | Método | `POST` com `Content-Type: application/json` | | Sucesso | Qualquer `2xx` | | Timeout | 15 segundos | | Tentativas | Até 5, com cerca de 2 segundos entre elas | | Após 5 falhas | O evento é marcado como erro e o dono do webhook recebe um e-mail | Responda `2xx` **assim que receber**, antes de processar. Se a sua aplicação demora para responder, a entrega entra em retry e os eventos seguintes do mesmo estabelecimento ficam na fila atrás dela — a ordem é preservada por estabelecimento. Projete o seu endpoint para ser **idempotente**: uma reentrega pode repetir um evento que você já processou. ## Onde encontrar o resto do pedido O evento é propositalmente enxuto: ele avisa **o que mudou**, não transporta o pedido. Os dados de conteúdo ficam em `GET /v1/orders/{orderId}`: | O que você precisa | Onde buscar | | --- | --- | | Identificar o pedido e o que mudou | O próprio evento | | Itens, complementos e observações | `items` do detalhe | | Cliente, telefone e endereço | `customer` e `delivery.address` do detalhe | | Pagamentos, valores e descontos | `payments`, `total` e `discount` do detalhe | | Entregador e linha do tempo da entrega | `delivery.driver` e `delivery.timeline` do detalhe | ## Perguntas frequentes **Webhook ou polling: qual usar?** Os dois entregam o mesmo formato de evento, então são caminhos alternativos para a mesma informação. O webhook é o recomendado, por ser imediato e não gastar requisições. O polling (`GET /v1/orders/polling`) serve a quem não tem como expor uma URL pública, e também para reconciliar. **Perdi eventos enquanto meu servidor estava fora. E agora?** Use `GET /v1/orders/polling`, que mantém uma janela das últimas 8 horas, para reconciliar. **O `createdAt` é a data do pedido ou do evento?** Do evento. Para a data de criação do pedido, use o `createdAt` do detalhe em `GET /v1/orders/{orderId}`. **Preciso tratar os dois campos, `event` e `eventType`?** Não. Eles sempre trazem o mesmo valor; escolha um.