Transações

Use esta referência para conciliação, extrato, estorno e baixa. Uma transação é identificada de forma estável pelo par uid + createdAt; o campo idTransaction é uma identificação derivada desse par, conveniente para o parceiro.

Resumo

Método	Endpoint	Finalidade
GET	/places/{idPlace}/transactions?startAt={date}&finishAt={date}	Consultar um período
GET	/places/{idPlace}/transactions/users?...	Consultar por consumidor
GET	/places/{idPlace}/transactions/users/{uid}/date/{createdAt}	Consultar uma transação
DELETE	/places/{idPlace}/transactions/users/{uid}/date/{createdAt}	Estornar uma transação
GET	/places/{idPlace}/transactions/unacknowledged	Listar transações não confirmadas
PUT	/places/{idPlace}/transactions/users/{uid}/date/{createdAt}/acknowledge	Confirmar processamento

Erros comuns

Status	Mensagem	Quando acontece
403	Not authorized to interact with this place (idPlace)	A chave não tem acesso a esse estabelecimento

Modelo de transação

É o objeto devolvido por todos os endpoints de consulta desta página e também pelo webhook de consumo.

Campo	Tipo	Descrição
idTransaction	string	Identificador único. Use para não lançar duas vezes
uid	string	Consumidor na Enjoy.it. Com createdAt, identifica a transação
createdAt	string	Data e hora, em ISO 8601
total	number	Valor a lançar, em reais. Já vem calculado
product	string	Descrição do item
sku	string	Código do produto. Pode carregar o código do seu catálogo
mlServed	number	Volume servido. Ausente em produtos e recargas
sellingPrice	number	Preço por mililitro no consumo de chope
quantity	number	Quantidade, em produtos lançados pelo parceiro
type	string	D consumo, C recarga, P produto do parceiro
reversed	boolean	Se true, foi estornada e não deve ser cobrada
bonus	number	Parte do valor paga com crédito de cortesia
paymentMethod	string	Meio de pagamento, em recargas
billing	string	Informação de faturamento
acknowledged	boolean	Se você já deu baixa nesta transação
acknowledgedAt	string	Data da baixa, em ISO 8601
acknowledgeReference	string	Referência do lançamento no seu sistema, enviada na baixa
idTap	string	Torneira onde o consumo aconteceu
idTab	string	Número da comanda
rfid	string	Chip da credencial
idPlace	string	Estabelecimento
consumerReference	string	Código do consumidor no seu sistema
transactionReference	string	Referência enviada por você ao registrar
plan	string	prepaid ou postpaid
document	string	Documento do consumidor
category	string	Categoria, em produtos do parceiro

{
  "product": "IPA da Casa",
  "total": 12.8,
  "sellingPrice": 0.04,
  "idTap": "T-01",
  "consumerReference": "cliente-123",
  "idTab": "006",
  "rfid": "4623227593",
  "mlServed": 320,
  "idPlace": "P-EXEMPLO",
  "sku": "IPA-001",
  "plan": "postpaid",
  "createdAt": "2026-08-02T19:43:29.416Z",
  "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
  "idTransaction": "980a69f4-d629-5571-8a9f-99aa0293e4d6",
  "type": "D",
  "reversed": false,
  "acknowledged": false
}

Consultar por período

Retorna todos os consumos do estabelecimento em um intervalo, agrupados por consumidor. É o endpoint usado em fechamento de caixa e emissão de cupons em lote.

GET /places/{idPlace}/transactions?startAt=2026-08-02T00:00:00.000Z&finishAt=2026-08-02T23:59:59.999Z

Query string

Parâmetro	Tipo	Obrigatório	Descrição
startAt	string	Sim	Início do período em ISO 8601, inclusivo
finishAt	string	Sim	Fim do período em ISO 8601, inclusivo

Resposta 200

Uma lista de extratos, um por consumidor. Cada extrato tem três partes:

Campo	Tipo	Descrição
customer	objeto	Dados do consumidor: uid, name, document, cellphone, email, gender, birthdate, region, consumerReference e marketing
tab	objeto	Estado da credencial: balance, plan, hasConsumptionLimit, idTab, rfid, idPlace
transactions	lista	Transações no modelo acima, ordenadas por createdAt

O objeto marketing dentro de customer traz acceptMessages e acceptEmails (boolean), que indicam os canais autorizados pelo consumidor.

[
  {
    "customer": {
      "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
      "name": "Maria Silva",
      "consumerReference": "cliente-123",
      "marketing": { "acceptMessages": true, "acceptEmails": false }
    },
    "tab": {
      "balance": 42.5,
      "plan": "prepaid",
      "hasConsumptionLimit": true,
      "idTab": "006",
      "rfid": "4623227593",
      "idPlace": "P-PDV"
    },
    "transactions": []
  }
]

Erros

Status	Mensagem	Quando acontece
400	Missing search params (startAt | finishAt)	Faltou um dos dois, ou a data não é válida

Consultar por consumidor

Retorna o extrato de um consumidor, localizado por comanda, telefone, referência ou RFID.

GET /places/{idPlace}/transactions/users?method=tab&idTab=006
GET /places/{idPlace}/transactions/users?method=phone&phone=%2B5511999999999
GET /places/{idPlace}/transactions/users?method=reference&reference=cliente-123
GET /places/{idPlace}/transactions/users?rfid=4623227593

Query string

Parâmetro	Tipo	Obrigatório	Descrição
method	string	Condicional	tab, phone ou reference. Omita para buscar por rfid
idTab	string	Condicional	Número da comanda, quando method=tab
phone	string	Condicional	Telefone, quando method=phone. Codifique o + como %2B
reference	string	Condicional	Referência do consumidor, quando method=reference
rfid	string	Condicional	Chip, quando nenhum method for informado
startAt	string	Não	Início do período em ISO 8601
finishAt	string	Não	Fim do período em ISO 8601

startAt e finishAt só têm efeito quando enviados juntos.

Resposta 200

Um extrato, no mesmo formato de Consultar por período — com customer, tab e transactions.

O formato aqui é diferente dos endpoints por credencial

GET .../tabs/{idTab}/transactions, .../rfid/{rfid}/transactions e .../customers/{reference}/transactions devolvem apenas a lista de transações.

Este endpoint devolve o objeto de extrato, com a lista dentro de transactions. Se você trocar um pelo outro, o parser quebra.

Só os erros comuns.

Consultar uma transação

Retorna um consumo específico.

GET /places/{idPlace}/transactions/users/{uid}/date/{createdAt}

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
uid	string	Sim	Consumidor na Enjoy.it
createdAt	string	Sim	Data da transação em ISO 8601. Codifique na URL

Resposta 200

Uma transação no modelo acima.

Erros

Status	Mensagem	Quando acontece
404	Transaction not found!	Não existe, é de outro estabelecimento, ou não é um consumo de chope

informação

Este endpoint devolve apenas transações de consumo (type: "D"). Recargas e produtos do parceiro respondem 404 mesmo existindo — para vê-los, use os endpoints de extrato.

Estornar uma transação

Cancela um lançamento, devolvendo o valor ao saldo do consumidor.

DELETE /places/{idPlace}/transactions/users/{uid}/date/{createdAt}

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
uid	string	Sim	Consumidor na Enjoy.it
createdAt	string	Sim	Data da transação em ISO 8601. Codifique na URL

Não possui corpo.

Resposta 200

Corpo vazio.

{}

aviso

O estorno é uma operação financeira. Depois de receber sucesso, não repita a chamada; em caso de timeout, consulte a transação e confira o campo reversed antes de tentar de novo.

Só os erros comuns.

Listar transações não confirmadas

Retorna o que ainda não recebeu baixa. É o caminho para recuperar o que não foi processado, e também uma forma de importar por varredura em vez de consultar cliente a cliente.

GET /places/{idPlace}/transactions/unacknowledged?startAt=2026-08-02T00:00:00.000Z&finishAt=2026-08-02T23:59:59.999Z&type=D&limit=100

Query string

Parâmetro	Tipo	Obrigatório	Descrição
startAt	string	Não	Início do período em ISO 8601. Padrão: três dias atrás
finishAt	string	Não	Fim do período em ISO 8601. Padrão: agora
type	string	Não	Filtra o tipo: D, C ou P
limit	number	Não	Ativa a paginação e define o tamanho da página
cursor	string	Não	Cursor devolvido pela página anterior

Resposta 200

O formato muda conforme você use limit

Chamada	Resposta
Sem limit	Uma lista de transações, direto
Com limit	Um objeto com items, cursor, hasMore e count

Se o seu código sempre espera uma lista, adicionar limit depois vai quebrá-lo.

Campos da resposta paginada:

Campo	Tipo	Descrição
items	lista	Transações no modelo acima
count	number	Quantidade nesta página
hasMore	boolean	Se há mais páginas
cursor	string	Cursor da próxima página. Ausente quando hasMore é false

{
  "items": [],
  "count": 0,
  "hasMore": false
}

Erros

Status	Mensagem	Quando acontece
400	Invalid startAt date	startAt não é uma data válida
400	Invalid finishAt date	finishAt não é uma data válida

Confirmar processamento

Dá baixa em uma transação já lançada no seu sistema, tirando-a da lista de não confirmadas.

PUT /places/{idPlace}/transactions/users/{uid}/date/{createdAt}/acknowledge

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
uid	string	Sim	Consumidor na Enjoy.it
createdAt	string	Sim	Data da transação em ISO 8601
acknowledgeReference	string	Não	Referência do registro criado no seu sistema. Volta nas consultas seguintes

{
  "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
  "createdAt": "2026-08-02T19:43:29.416Z",
  "acknowledgeReference": "lancamento-pdv-55421"
}

O que vale é o corpo, não o caminho

uid e createdAt aparecem também na URL, mas a operação usa os valores do corpo. Se os dois divergirem, a baixa é aplicada no que veio no JSON — mantenha-os iguais para não dar baixa na transação errada.

Resposta 200

Corpo vazio.

{}

Erros

Status	Mensagem	Quando acontece
400	Missing uid	uid ausente no corpo
400	Invalid createdAt date	createdAt ausente ou não é uma data válida

aviso

Só confirme depois que a transação estiver persistida com sucesso no seu sistema. A confirmação a remove das próximas consultas de pendências, e uma baixa dada cedo demais esconde um consumo que nunca foi lançado.

Quem recebe por webhook não precisa chamar este endpoint: responder com sucesso à notificação já dá a baixa. Ver Receber os consumos.