Torneiras

Estes endpoints permitem consultar a disponibilidade das torneiras e, para parceiros habilitados no modo direto, liberar uma torneira sem que o consumidor encoste a credencial no equipamento.

Resumo

Método	Endpoint	Finalidade
GET	/places	Descobrir o estabelecimento pelas torneiras
GET	/places/{idPlace}/taps	Listar torneiras
GET	/places/{idPlace}/taps/{idTap}	Consultar uma torneira
POST	/places/{idPlace}/tap/{idTap}/open	Abrir com dados do consumidor
POST	/places/{idPlace}/rfids/{rfid}/taps/{idTap}/open	Abrir por RFID
POST	/places/{idPlace}/tabs/{idTab}/taps/{idTap}/open	Abrir por comanda
POST	/places/{idPlace}/customers/{reference}/taps/{idTap}/open	Abrir por referência da Wallet

Abertura exige o modo direct

Os quatro endpoints de abertura só funcionam se a sua credencial estiver habilitada no modo direct. Sem essa habilitação, todos respondem 403 Not authorized to interact with this API, mesmo que o idPlace esteja no escopo da chave.

A habilitação é feita pela Enjoy.it na configuração da integração — peça na homologação.

Singular no caminho de abertura direta

POST /places/{idPlace}/tap/{idTap}/open usa tap no singular. Os endpoints de consulta e os de abertura por identificador usam taps.

Parâmetros e erros comuns

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
idPlace	string	Sim	Código do estabelecimento. Precisa estar no escopo da sua chave
idTap	string	Sim	Código da torneira, obtido em Listar torneiras

Erros comuns

Status	Código	Mensagem	Quando acontece
403	—	Not authorized to interact with this place (idPlace)	A chave não tem acesso a esse estabelecimento
423	4231	Place suspended!	O estabelecimento está suspenso

Descobrir o estabelecimento pelas torneiras

Faz o caminho inverso dos outros endpoints: você informa códigos de torneira e recebe os estabelecimentos a que elas pertencem. Use quando o seu equipamento conhece a torneira em que está instalado, mas não o idPlace que todas as outras chamadas exigem.

GET /places

É o único endpoint desta página sem idPlace no caminho.

Query string

Parâmetro	Tipo	Obrigatório	Descrição
idsTap	string	Sim	Um ou mais idTap, separados por vírgula

GET /places?idsTap=T-01,T-02,T-03

Torneiras de estabelecimentos fora do escopo da sua chave são descartadas em silêncio. Se nenhuma das torneiras informadas cair em um estabelecimento seu, a resposta é 404 — inclusive quando o idTap simplesmente não existe.

Resposta 200

Lista de estabelecimentos, sem repetição: várias torneiras da mesma loja resultam em um item só.

Campo	Tipo	Descrição
idPlace	string	Código do estabelecimento. É o valor a usar nas demais chamadas
name	string	Nome da loja
businessName	string	Razão social
document	string	CNPJ da loja
whatsAppNumber	string	WhatsApp de contato
imageUrl	string	Logo da loja
region	objeto	Endereço: street, postalcode, number, neighborhood, city, state
tabModel	string	Modelo de operação: prepaid, postpaid, both-postpaid-prepaid, glass-prepaid ou free
idCompany	string	Código da rede, quando a loja pertence a uma
company	objeto	Dados da rede: idCompany, name, businessName, document, imageUrl. Ausente em loja sem rede

[
  {
    "idPlace": "P-PDV",
    "name": "Bar Exemplo",
    "businessName": "Bar Exemplo Ltda",
    "document": "12345678000199",
    "whatsAppNumber": "+5511999999999",
    "tabModel": "prepaid",
    "region": {
      "street": "Alameda Exemplo",
      "number": "100",
      "neighborhood": "Vila Olímpia",
      "city": "São Paulo",
      "state": "São Paulo",
      "postalcode": "04547000"
    }
  }
]

Erros

Status	Mensagem	Quando acontece
400	Missing idsTap!	A query string não trouxe idsTap
403	Unknown partner!	A chave de API não corresponde a nenhum parceiro
404	Places not found!	Nenhuma das torneiras pertence a um estabelecimento no escopo da sua chave

Listar torneiras

Retorna todas as torneiras do estabelecimento, com o barril que está em cada uma.

GET /places/{idPlace}/taps

Resposta 200

Campo	Tipo	Descrição
idTap	string	Código da torneira
idPlace	string	Estabelecimento
name	string	Nome exibido da torneira
sequence	number	Ordem de exibição
defaultGlassMilliliter	number	Volume padrão do copo, em mililitros
defaultPriceUnitMilliliter	number	Preço padrão por mililitro
lastHardwarePingAt	string	Último sinal do equipamento, em ISO 8601. Use para detectar torneira offline
workingHourStart	string	Início do horário de funcionamento
workingHourEnd	string	Fim do horário de funcionamento
workingWeekDays	lista	Dias da semana em que a torneira opera
kegPresent	boolean	Se há barril conectado. Quando false, keg vem ausente
keg	objeto	Dados do barril. Ver tabela abaixo

Campos de keg:

Campo	Tipo	Descrição
idKeg	string	Código do barril
sku	string	Código do produto. Pode carregar o código do seu catálogo
sellingPrice	number	Preço de venda por mililitro
capacity	number	Capacidade total, em mililitros
consumed	number	Volume já consumido, em mililitros
idBrewery	string	Código da cervejaria
idBreweryBrand	string	Código da marca
brewery	objeto	idBrewery, name, imageUrl, location
breweryBrand	objeto	idBreweryBrand, name, type, description, alcoholContent, ibu, imageUrl, location, idBrewery

[
  {
    "idTap": "T-01",
    "idPlace": "P-PDV",
    "name": "Torneira 1",
    "sequence": 1,
    "defaultGlassMilliliter": 300,
    "defaultPriceUnitMilliliter": 0.04,
    "lastHardwarePingAt": "2026-08-02T19:43:29.416Z",
    "kegPresent": true,
    "keg": {
      "idKeg": "K-991",
      "sku": "IPA-001",
      "sellingPrice": 0.04,
      "capacity": 30000,
      "consumed": 12400
    }
  }
]

Só os erros comuns.

Consultar uma torneira

GET /places/{idPlace}/taps/{idTap}

Resposta 200

Um objeto no mesmo formato de Listar torneiras.

Só os erros comuns.

Abrir diretamente

Libera a torneira informando os dados do consumidor na própria chamada, sem credencial prévia. Use quando o parceiro controla toda a identificação do lado dele.

POST /places/{idPlace}/tap/{idTap}/open

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
consumer	objeto	Sim	Dados do consumidor. Mesmos campos do check-in; name é obrigatório
hasConsumptionLimit	boolean	Não	Se true, a liberação respeita o balance
balance	number	Não	Saldo disponível para esta abertura, em reais
transactionReference	string	Não	Referência do pedido no seu sistema. Volta no webhook de consumo
consumptionIpn	string	Não	URL chamada quando a servida terminar
balanceIpn	string	Não	URL consultada para obter o saldo antes de liberar
openTapIpn	string	Não	URL chamada quando o estado da torneira mudar

{
  "consumer": {
    "name": "Maria Silva",
    "consumerReference": "cliente-123"
  },
  "hasConsumptionLimit": true,
  "balance": 50,
  "transactionReference": "pedido-987",
  "openTapIpn": "https://parceiro.example.com/enjoy/taps"
}

Resposta 201

Corpo vazio. A torneira fica liberada para a servida.

{}

Erros

Além dos comuns e das falhas específicas:

Status	Mensagem	Quando acontece
403	Not authorized to interact with this API	A credencial não está habilitada no modo direct

Abrir com um identificador existente

Libera a torneira para uma credencial que já tem sessão aberta. É a variação usada quando o consumidor já fez check-in por comanda, RFID ou Wallet e o aplicativo apenas dispara a abertura.

POST /places/{idPlace}/rfids/{rfid}/taps/{idTap}/open
POST /places/{idPlace}/tabs/{idTab}/taps/{idTap}/open
POST /places/{idPlace}/customers/{reference}/taps/{idTap}/open

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
rfid	string	Condicional	Na variação por RFID. Completado com zeros à esquerda até 10 dígitos
idTab	string	Condicional	Na variação por comanda. Completado com zeros à esquerda até 3 dígitos
reference	string	Condicional	Na variação por Wallet

Corpo da requisição

Todos os campos são opcionais: quando enviados, substituem o que foi definido no check-in apenas para esta abertura. O consumidor já é conhecido pela credencial, então consumer não se aplica.

Campo	Tipo	Obrigatório	Descrição
balance	number	Não	Sobrescreve o saldo considerado nesta abertura
transactionReference	string	Não	Referência do pedido no seu sistema. Volta no webhook de consumo
consumptionIpn	string	Não	Sobrescreve a URL de notificação de consumo
balanceIpn	string	Não	Sobrescreve a URL de consulta de saldo
openTapIpn	string	Não	Sobrescreve a URL de mudança de estado da torneira

O corpo é obrigatório: envie ao menos {}.

{
  "transactionReference": "pedido-987"
}

Resposta 201

Corpo vazio.

{}

Erros

Status	Mensagem	Quando acontece
403	Not authorized to interact with this API	A credencial não está habilitada no modo direct
404	idTab not found! (4041)	Na variação por comanda, o número não existe no cadastro
404	RFID card not found in userRfid table. (4042)	Não há credencial ativa para o identificador informado

Falhas específicas

Estas falhas são do equipamento ou do saldo, e valem para todos os endpoints de abertura. Todas retornam 422 e são as que o seu aplicativo precisa saber traduzir para o consumidor:

Código	Mensagem	O que dizer ao consumidor
4221	Tap without keg!	A torneira está sem barril conectado
4222	Insufficient balance!	O saldo não cobre a servida
4223	Keg is over!	O barril acabou
4224	Tap offline!	A torneira perdeu comunicação. Confira lastHardwarePingAt
4225	Tap under maintenance!	A torneira está em manutenção
4226	Tap out of service	A torneira está fora de operação, por horário ou configuração