Skip to main content
POST
API de parceiro. Este endpoint é destinado a integradores de plataforma. Clientes padrão do Fire não têm acesso direto — fale com seu account manager se precisar desta integração.
Registra o fechamento de um turno e faz o Fire comparar com o que ele diz que deveria haver na gaveta. A diferença (SHORTAGE, OVERAGE ou MATCH) é calculada pelo Fire.
A v1 continua viva, sem data de descontinuação. Se sua integração já a consome, não precisa fazer nada. A migração para a v2 acontece quando você quiser, sem deploy coordenado.

​
O que muda

Uma só coisa, e não é um campo novo: muda quem faz a conta. discrepancy é a mesma subtração nas duas versões: declaredCash − systemCash. Na v2 o fundo está dos dois lados, então a diferença significa exatamente o mesmo e uma linha v1 e uma v2 se comparam sem conversão nenhuma.
O passo que não se detecta sozinho. Se você aponta para a v2 e continua subtraindo o fundo de declaredCash, a requisição passa sem erro nenhum e todos os fechamentos saem com uma falta do tamanho do fundo — todos os dias, com o operador aparecendo como devedor de um dinheiro que nunca tirou. O Fire não consegue distinguir uma contagem líquida de uma bruta: só você sabe qual enviou.Antes de migrar, confira contra um dia de teste que a discrepancy devolvida pelo Fire é a mesma que você calcula.

​
Autenticação e tenancy

​
string
obrigatório
Sua API key do Fire, com o escopo cash-management:write.Precisa ser vendor-scoped: trazer account e vendor. Se faltar algum, a resposta é 403.
Aqui a chave é o tenant. O storeId é buscado dentro do escopo da sua chave; se a loja for de outra conta ou de outro vendor, a resposta é 404 sem revelar se ela existe.Essa é uma diferença real em relação à v1, que aceita qualquer storeId válido. Se hoje você posta na v1 com uma chave compartilhada entre contas, essa chave não entra na v2 — vai precisar de uma própria.

​
Um fechamento por turno

Duas regras, e vale entender as duas antes de integrar:
​
string
obrigatório
O identificador do turno no seu PDV. É a chave de idempotência: reenviar o mesmo fechamento devolve 409 em vez de duplicá-lo.Único por loja para sempre, não por dia. Não carrega a data, então um contador que reinicia todo dia (T01-1, T01-2, …) colide com o fechamento de ontem. Se o seu id de turno reinicia, prefixe-o com o dia operacional: T01-20260901-1.Um turno que trabalha com duas moedas envia dois POSTs com o mesmo sessionExternalId e currency diferente: a chave inclui a moeda, então os dois entram.
E a outra, que é a que surpreende: um turno fecha uma única vez, não importa o id. Se você enviar um segundo fechamento para o mesmo dia, loja, operador, moeda e shiftStart com outro sessionExternalId, a resposta é 409. Gerar um id novo a cada envio não é uma retentativa: é um fechamento novo, e o Fire o trata como tal.

​
Corpo da requisição

​
string
obrigatório
UUID da loja. Precisa pertencer ao escopo da sua API key.
​
string
obrigatório
Código ISO 4217 de 3 caracteres (BRL, USD, ARS, CLP, COP, VES).
​
number
obrigatório
O dinheiro contado na gaveta, bruto — com o fundo incluído. Decimal com até 2 casas, não negativo.É o campo que mudou de significado em relação à v1. Leia o aviso acima.
​
number
obrigatório
O fundo com que o caixa abriu neste turno, nesta moeda. Decimal com até 2 casas, não negativo. Envie sempre, mesmo que seja 0.
​
string
obrigatório
Início do turno, ISO 8601 com offset (2026-09-01T13:00:00-03:00). O Fire usa a janela para atribuir as vendas do turno.
​
string
obrigatório
Fim do turno, mesmo formato. Precisa ser posterior a shiftStart.
​
string
obrigatório
Causa categórica da diferença. Uma de: WRONG_CHANGE_GIVEN, COUNTING_ERROR, INCOMPLETE_CUSTOMER_PAYMENT, MINOR_UNIDENTIFIED_DIFFERENCE, THEFT_SUSPECTED, UNRECORDED_PAYMENT, OTHER.Obrigatória mesmo quando o fechamento bate. Quando há sobra, o único valor aceito é OTHER — qualquer outro volta 400: dinheiro a mais não se explica por erro de contagem do cliente.
​
array
O dinheiro que saiu da gaveta durante o turno. Até 100 entradas. São subtraídas do esperado; o detalhe de cada uma fica guardado para auditoria.
​
string
Dia operacional em YYYY-MM-DD. O padrão é o dia operacional atual da loja. Use para registrar um fechamento de um dia passado — o Fire marca o resultado com details.post_close: true se o dia já estiver fechado.
​
string
O operador do turno. Opcional: omita quando o fechamento é da loja inteira.Com operador, o Fire conta só as vendas dessa pessoa — e rejeita um operador que não teve nenhuma transação e mesmo assim declara dinheiro de vendas.
​
string
Nome do operador, exibido nas telas de conciliação.
​
string
O caixa físico do turno. Permite agrupar os fechamentos do mesmo caixa no relatório.
​
string
Texto livre, até 2000 caracteres.
​
string
UUID de um token de autorização, quando o fechamento precisou de assinatura de um supervisor.

​
Campos da resposta

Os mesmos da v1, mais estes:
​
number
2 para as linhas que entraram por este endpoint. As da v1 trazem 1. A UI do Fire ramifica por este campo para exibir as duas de forma comparável.
​
number
O fundo, como você enviou.
​
number
A soma de withdrawals[]. O detalhe de cada uma fica em details.withdrawals.
​
string
Eco da requisição. null nas linhas da v1.
​
string | null
Eco da requisição.
​
number
O que o Fire calculou que deveria haver na gaveta: openingBalance + vendas em dinheiro − withdrawalsTotal.
​
number
declaredCash − systemCash. Negativo é falta, positivo é sobra.

​
Erros

​
Migrar da v1

  1. Trocar a URL: /api/v1/adapters/xmart/cash-management/reconciliations → /api/v2/external/cash-management/reconciliations. Se sua chave não for vendor-scoped, peça uma nova.
  2. Parar de subtrair o fundo de declaredCash. Enviar o dinheiro contado como está.
  3. Enviar sempre openingBalance — mesmo que 0 — e o par shiftStart / shiftEnd.
  4. Enviar sempre sessionExternalId, único por loja para sempre.
  5. Se houver sangrias durante o turno, declará-las em withdrawals[].
  6. Conferir contra um dia de teste que a discrepancy devolvida pelo Fire é a mesma que você calcula.
Não há GET na v2. A listagem da v1 já devolve todas as linhas do dia, não importa com qual versão entraram — é onde você vai ver um fechamento v1 e um v2 lado a lado.