Referência da BOH API

A BOH API é uma API REST que permite gerenciar o inventário Back of House de forma programática: sincronizar seu catálogo, publicar receitas, registrar documentos operacionais (recebimentos, perdas, contagens), ler relatórios e configurar webhooks.

Identidade

Resolva sua conta, liste vendors, estabelecimentos e fornecedores.

Catálogo: Itens

Criar, listar, atualizar, arquivar e sincronizar itens de inventário.

Catálogo: Sync em massa

Sincronizar unidades, fornecedores e atribuições de classificação em massa.

Receitas

Gerenciar receitas de venda, produção e sub-receitas.

Operações

Registrar recebimentos, contagens, perdas, transferências e produção.

Compras

Gerenciar níveis par e obter quantidades de reabastecimento sugeridas.

Webhooks

Assinar eventos de transações de inventário e pedidos de compra.

URL base

https://boh.api.fire.rest

Todos os endpoints têm o prefixo /api/v1/public/.

A URL base é fornecida pela Fire ao configurar sua integração. Use https://stg.boh.api.fire.rest para staging e a URL de produção para operações em produção.

Autenticação

Cada requisição requer uma API key no header x-api-key. As API keys são criadas e gerenciadas na tela Conta e acessos → API keys do BOH backoffice, ou via os endpoints de API Keys.

x-api-key: boh_live_xxxxxxxxxxxxxxxx

Não é necessário Bearer token nem cookie de sessão. A key resolve a conta; não é preciso passar um header account.

Escopos da key

Cada key tem um ou mais escopos que restringem quais endpoints ela pode chamar. Uma key com o escopo curinga * pode chamar tudo.

Escopo	O que desbloqueia
`catalog:read`	Listar e obter itens, unidades, etiquetas de itens, classificações
`catalog:write`	Criar, atualizar, arquivar recursos do catálogo
`recipes:read`	Listar e obter receitas; expandir para linhas de ingredientes
`recipes:write`	Criar, atualizar, publicar, arquivar receitas
`inventory:read`	Ler documentos operacionais (recebimentos, perdas, contagens…), saldos, movimentações
`inventory:write`	Criar documentos operacionais
`reports:read`	Consultar relatórios de inventário (usos, perdas, rendimento, saldo em uma data)
`admin:keys`	Criar, rotacionar e revogar API keys
`admin:accounts`	Atualizar configurações da conta (moeda, modo de consumo)
`admin:webhooks`	Criar, atualizar, excluir e testar endpoints de webhook

O vendor ID

A maioria das rotas inclui o parâmetro de rota {vendorId}. Um vendor representa uma entidade configurada no BOH (uma marca de restaurante ou unidade operacional). Obtenha seu vendor ID em Listar vendors ou no backoffice.

GET /api/v1/public/vendors/{vendorId}/catalog/items

Formato de requisição e resposta

Todos os corpos de requisição usam Content-Type: application/json.
Todas as respostas são JSON.
Timestamps usam ISO 8601 (2026-08-07T14:30:00.000Z).
Valores monetários usam a moeda da conta (configurada em Configurações da conta).

Modelo de escrita assíncrona

A maioria das operações de escrita (recebimentos, contagens, perdas, transferências, lotes de produção) é assíncrona. A resposta é imediata, mas as movimentações de estoque são registradas em alguns segundos. Uma escrita bem-sucedida retorna um tracking_id:

{
  "tracking_id": "trk_01j5k...",
  "inventory_transaction_id": "txn_01j5k...",
  "goods_receipt_id": "rcpt_01j5k...",
  "idempotent": false
}

Consulte GET /api/v1/public/operations/transactions/{trackingId} ou GET /api/v1/public/operations/transactions para acompanhar o status do processamento.

Idempotência

Envie o mesmo string idempotency_key duas vezes; a segunda chamada retorna a resposta original com "idempotent": true sem reprocessar. As chaves de idempotência expiram após 24 horas.

Erros

Todas as respostas de erro compartilham o mesmo envelope:

{
  "error": {
    "kind": "codigo_de_erro_snake_case",
    "message": "Descrição legível (para depuração, não para exibição)",
    "details": {}
  }
}

Status HTTP	Significado
`400`	Erro de validação — `kind` descreve o campo ou restrição que falhou
`401`	API key ausente ou inválida
`403`	Escopo ou vendor incorreto
`404`	Recurso não encontrado
`409`	Conflito — ex.: chave de idempotência duplicada com payload diferente
`422`	Violação de regra de negócio
`429`	Limite de taxa excedido
`5xx`	Erro do servidor — repetir com backoff exponencial

Os valores de message são para depuração e registro. Não são localizados. Traduza kind para strings voltadas ao usuário em sua aplicação.

Limites de taxa

Limites de taxa padrão por escopo:

Escopo	Requisições / min
`catalog:read`, `catalog:write`, `recipes:`, `inventory:`	1 000
`orders:write`	5 000
`reports:read`	100
`admin:keys`, `admin:accounts`	60

Quando o limite é excedido, a resposta é 429 e inclui os headers Retry-After e X-RateLimit-*. Os limites podem ser sobrescritos por key pelo suporte da Fire.

external_user_id

Os endpoints que criam ou modificam documentos operacionais aceitam um string opcional external_user_id no corpo. O BOH o armazena como o ator humano para fins de auditoria. Para CRUD de catálogo é opcional; para documentos operacionais é fortemente recomendado.

Visão geral

Identidade

Estabelecimentos

Fornecedores

Itens do catálogo

Sincronização de catálogo

Receitas

Recebimentos de mercadoria

Contagens de estoque

Eventos de perda

Transferências

Lotes de produção

Rastreamento

Níveis de reposição

Pedido sugerido

Pedidos de compra

Linhas de PC

Webhooks

Referência da BOH API

Identidade

Catálogo: Itens

Catálogo: Sync em massa

Receitas

Operações

Compras

Webhooks

URL base

Autenticação

Escopos da key

O vendor ID

Formato de requisição e resposta

Modelo de escrita assíncrona

Idempotência

Erros

Limites de taxa

external_user_id

Identidade

Catálogo: Itens

Catálogo: Sync em massa

Receitas

Operações

Compras

Webhooks

​URL base

​Autenticação

​Escopos da key

​O vendor ID

​Formato de requisição e resposta

​Modelo de escrita assíncrona

​Idempotência

​Erros

​Limites de taxa

​external_user_id

URL base

Autenticação

Escopos da key

O vendor ID

Formato de requisição e resposta

Modelo de escrita assíncrona

Idempotência

Erros

Limites de taxa

external_user_id