3020 – Incluir lote de cupons via API
3021 – Consultar status do lote de cupons via API
Com a API de cupons fiscais é possível efetuar a integração do software da frente de caixa com o Bluesoft ERP.
Essa API fornece o mesmo comportamento que o software de venda online, alimentando o monitoramento do venda online e fechamento de caixa.
Com ela é possível receber cupons dos tipos:
- FUNDO_CAIXA
- VENDA
- PAGAMENTO_SERVICO
- SANGRIA
- RELATORIO_OPERADOR
- LEITURA_Z
Os cupons podem ser enviados em lotes que serão armazenados para processamento posterior pelo sistema. Ao enviar um lote de cupons, o ERP irá devolver um ID gerado para o lote, possibilitando a consulta ao resultado de processamento dos cupons do lote.
Todos os tipos de cupons devem ter obrigatoriamente os campos: data, ECF, número do cupom, operador e tipo.
Abaixo segue exemplos de uma operação básica de venda do inicio ao fim do dia.
Tipo FUNDO_CAIXA:
O tipo FUNDO_CAIXA é utilizado para informar o inicio da operação de um operador de caixa, nele são informados o valor do fundo de caixa que o operador irá iniciar.
{
"codigoLoja": 1,
"cuponsFiscais": [
{
"coo": 100001,
"data": "31/10/2022 10:34:36",
"dataAutorizacao": "31/10/2022 10:34:36",
"ecf": 1,
"codigoDoFiscal": 2233,
"finalizadoras": [
{
"finalizadora": "03",
"valor": 210.00
}
],
"numeroDoCupom": 100001,
"codigoDoOperador": 2233,
"tipo": "FUNDO_CAIXA"
}
]
}Tipo VENDA:
O tipo VENDA é o mais utilizado, nele são informados os itens vendidos e as formas de pagamento.
{
"codigoLoja": 1,
"cuponsFiscais": [
{
"cancelado": false,
"chave": "12345678901234567890123456789012345678901234",
"codigoDoFiscal": 0,
"codigoDoOperador": 429,
"coo": 100002,
"data": "22/06/2023 07:10:00",
"dataAutorizacao": "22/06/2023 07:10:00",
"ecf": 1,
"finalizadoras": [
{
"cmc7": "",
"codigoConvenio": "",
"cpfCnpj": "",
"cpfCnpjConveniado": "",
"cpfCnpjInstituicaoBeneficiente": "",
"dataParcela": "22/06/2023 07:10:00",
"finalizadora": "004",
"nsu": 12,
"numeroAgencia": "",
"numeroBanco": "",
"numeroCheque": "",
"numeroConta": "",
"taxaServico": 0.0,
"tefBandeira": 271,
"tefBin": 0,
"tefParcelas": 99,
"tefRede": 271,
"trocoSolidario": false,
"valor": 79.56,
"valorAcrescimoFinalizadora": 0.0,
"valorTroco": 0.0
}
],
"itens": [
{
"cancelado": false,
"codigoDeBarras": 7898215157212,
"codigoIcms": "T12.00",
"codigoPackVirtual": 0,
"codigoPedidoVenda": 0,
"cofins": {
"aliquota": 7.6,
"baseCalculo": 13.99,
"cst": 1,
"valor": 1.06
},
"descontoPackVirtual": 0.0,
"icmsBaseCalculo": 13.99,
"icmsValor": 2.49,
"pis": {
"aliquota": 1.65,
"baseCalculo": 13.99,
"cst": 1,
"valor": 0.23
},
"quantidadePackVirtual": 0.0,
"quantidadeTotal": 1.0,
"sequenciaDoItem": 1,
"valorAcrescimo": 0.0,
"valorDesconto": 0.0,
"valorPackVirtual": 0.0,
"valorTotal": 13.99
},
{
"cancelado": false,
"codigoDeBarras": 7896036090244,
"codigoIcms": "T12.00",
"codigoPackVirtual": 0,
"codigoPedidoVenda": 0,
"cofins": {
"aliquota": 7.6,
"baseCalculo": 25.79,
"cst": 1,
"valor": 1.96
},
"descontoPackVirtual": 0.0,
"icmsBaseCalculo": "",
"icmsValor": "",
"pis": {
"aliquota": 1.65,
"baseCalculo": 25.79,
"cst": 1,
"valor": 0.43
},
"quantidadePackVirtual": 0.0,
"quantidadeTotal": 1.0,
"sequenciaDoItem": 2,
"valorAcrescimo": 0.0,
"valorDesconto": 0.0,
"valorPackVirtual": 0.0,
"valorTotal": 25.79
},
{
"cancelado": false,
"codigoDeBarras": 7891079001004,
"codigoIcms": "T13.30",
"codigoPackVirtual": 0,
"codigoPedidoVenda": 0,
"descontoPackVirtual": 0.0,
"quantidadePackVirtual": 0.0,
"quantidadeTotal": 1.0,
"sequenciaDoItem": 3,
"valorAcrescimo": 0.0,
"valorDesconto": 0.0,
"valorPackVirtual": 0.0,
"valorTotal": 39.78
}
],
"numeroDoCupom": 80842,
"sat": true,
"serie": 710395,
"tipo": "VENDA",
"valorAcrescimo": 0.0,
"valorCancelamento": 0.0,
"valorDesconto": 0.0,
"valorTotal": 79.56,
"valorTroco": 0.0
}
]
}Tipo VENDA CONVÊNIO com lançamento da quilometragem:
Nesta operação, é possível visualizar a placa e quilometragem do veículo do participante do convênio na venda.
No exemplo abaixo temos as seguintes informações:
- Placa: ABC 4321
- Quilometragem: 2700
{
"codigoLoja": 1,
"cuponsFiscais": [
{
"cancelado": false,
"chave": "12345678901234567890123456789012345678901234",
"codigoDoFiscal": 0,
"codigoDoOperador": 00000,
"coo": 000000,
"data": "02/01/2024 07:10:00",
"dataAutorizacao": "02/01/2024 07:10:00",
"ecf": 1,
"finalizadoras": [
{
"cmc7": "",
"codigoConvenio": "",
"cpfCnpj": "",
"cpfCnpjConveniado": "",
"cpfCnpjInstituicaoBeneficiente": "",
"dataParcela": "02/01/2024 07:10:00",
"finalizadora": "009",
"nsu": 12,
"numeroAgencia": "",
"numeroBanco": "",
"numeroCheque": "",
"numeroConta": "",
"taxaServico": 0.0,
"tefBandeira": ,
"tefBin": 0,
"tefParcelas": ,
"tefRede": ,
"trocoSolidario": false,
"valor": 79.56,
"valorAcrescimoFinalizadora": 0.0,
"valorTroco": 0.0
}
],
"itens": [
{
"cancelado": false,
"codigoDeBarras": ,
"codigoIcms": "T07.00",
"codigoPackVirtual": 0,
"codigoPedidoVenda": 0,
"descontoPackVirtual": 0.0,
"quantidadePackVirtual": 0.0,
"quantidadeTotal": 1.0,
"sequenciaDoItem": 3,
"valorAcrescimo": 0.0,
"valorDesconto": 0.0,
"valorPackVirtual": 0.0,
"valorTotal": 79.56,
"icmsBaseCalculo": 13.99,
"icmsValor": "",
"pis": {
"cst": 1,
"aliquota": 1.65,
"baseCalculo": 13.99,
"valor": 0.23
},
"cofins": {
"cst": 1,
"aliquota": 7.6,
"baseCalculo": 13.99,
"valor": 1.06
},
"combustivel": {
"bico": "1",
"placa": "ABC4321",
"quilometragem": 2700,
"tanque": "1",
"numeroDoAbastecimento": "1",
"numeroDaSequenciaDoAbastecimento":"1"
}
}
],
"numeroDoCupom": 80842,
"sat": true,
"serie": 710395,
"tipo": "VENDA",
"valorAcrescimo": 0.0,
"valorCancelamento": 0.0,
"valorDesconto": 0.0,
"valorTotal": 79.56,
"valorTroco": 0.0
}
]
}Tipo PAGAMENTO_SERVICO:
O tipo PAGAMENTO_SERVICO é utilizando nas operações de serviço como recarga de celular por exemplo.
O codigoIntegracaoDeServico informado é o que está informado no cadastro dos tipos de serviços.
Para visualizar ou cadastrar um novo serviço acesse Serviço > Cadastros > Tipos de Venda de Serviço
{
"coo": 700022,
"data": "28/04/2022 10:34:36",
"dataAutorizacao": "28/04/2022 10:34:36",
"chave": "12345678901234567890123456789012345678901239",
"ecf": 4,
"finalizadoras": [
{
"finalizadora": "001",
"valor": 20.00
}
],
"lojaKey": 1,
"numeroDoCupom": 700022,
"codigoDoOperador": 24,
"tipo": "PAGAMENTO_SERVICO",
"valorTotal": 20.00,
"codigoIntegracaoDeServico": 100
}
Tipo VENDA com Troco Solidário Total:
No exemplo abaixo temos:
- Uma venda que totalizou R$ 100,00
- Foi dado ao operador de caixa R$ 110,00 em Dinheiro
- E os R$ 10,00 de troco, foram cedidos como Troco Solidário
{
"codigoLoja": 1,
"cuponsFiscais": [
{
"cancelado": false,
"chave": 12345678901234567890123456789012345678901234,
"coo": 232227,
"data": "23/06/2022 10:49:09",
"dataAutorizacao": "23/06/2022 10:49:09",
"dataCancelamento": "23/06/2022 10:49:09",
"ecf": 1,
"finalizadoras": [
{
"cpfCnpj": "12345678900",
"finalizadora": "001",
"parcelas": "0",
"valor": 110.0,
"valorTrocoSolidario": 10,
"cpfCnpjInstituicaoBeneficiente": 12345678912345
}
],
"itens": [
{
"sequenciaDoItem": 1,
"codigoDeBarras": "1009",
"valorAbatimento": 0.00,
"valorTotal": 100.00,
"codigoIcms": "I00.00",
"quantidadeTotal": 100.00
}
],
"lojaKey": 1,
"numeroDoCupom": 232228,
"codigoDoOperador": 1,
"sat": false,
"serie": 1,
"tipo": "VENDA",
"valorAcrescimo": 0,
"valorDesconto": 0,
"valorTotal": 100,
"valorTroco": 0
}
]
}Tipo VENDA com Troco Solidário Parcial:
No exemplo abaixo temos:
- Uma venda que totalizou R$ 100,00
- Foi dado ao operador de caixa R$ 150,00 em Dinheiro
- Dos R$ 50,00 de troco, R$ 30,00 foram devolvidos ao cliente
- E R$ 20,00 foram cedidos como Troco Solidário
{
"codigoLoja": 1,
"cuponsFiscais": [
{
"cancelado": false,
"chave": 12345678901234567890123456789012345678901234,
"coo": 232227,
"data": "23/06/2022 10:49:09",
"dataAutorizacao": "23/06/2022 10:49:09",
"dataCancelamento": "23/06/2022 10:49:09",
"ecf": 1,
"finalizadoras": [
{
"cpfCnpj": "12345678900",
"finalizadora": "001",
"parcelas": "0",
"valor": 150.0,
"valorTroco": 30,
"valorTrocoSolidario": 20,
"cpfCnpjInstituicaoBeneficiente": 12345678912345
}
],
"itens": [
{
"sequenciaDoItem": 1,
"codigoDeBarras": "1009",
"valorAbatimento": 0.00,
"valorTotal": 100.00,
"codigoIcms": "I00.00",
"quantidadeTotal": 100.00
}
],
"lojaKey": 1,
"numeroDoCupom": 232228,
"codigoDoOperador": 1,
"sat": false,
"serie": 1,
"tipo": "VENDA",
"valorAcrescimo": 0,
"valorDesconto": 0,
"valorTotal": 100,
"valorTroco": 0
}
]
}Tipo SANGRIA:
No tipo SANGRIA são informadas as retiradas que ocorrem pelos fiscais ao longo do dia.
{
"codigoLoja": 1,
"cuponsFiscais": [
{
"coo": 100003,
"data": "31/10/2022 10:34:36",
"dataAutorizacao": "31/10/2022 10:34:36",
"ecf": 1,
"codigoDoFiscal": 2233,
"finalizadoras": [
{
"finalizadora": "03",
"quantidade": 1,
"valor": 210.00
}
],
"numeroDoCupom": 100003,
"codigoDoOperador": 2233,
"tipo": "SANGRIA"
}
]
}Tipo RELATORIO_OPERADOR:
O tipo RELATORIO OPERADOR é enviado sempre que ocorre a troca de operadores no caixa ou antes do envio da LEITURA_Z ao final do dia. Nele é enviado o valor vendido pelo o operador até o momento da saída.
{
"codigoLoja": 1,
"cuponsFiscais": [
{
"coo": 100004,
"data": "31/10/2022 10:34:36",
"dataAutorizacao": "31/10/2022 10:34:36",
"ecf": 1,
"codigoDoFiscal": 2233,
"numeroDoCupom": 100004,
"codigoDoOperador": 2233,
"tipo": "RELATORIO_OPERADOR",
"valorTotal": 210.00
}
]
}Tipo LEITURA_Z:
O tipo LEITURA_Z é o último a ser enviado, nele são consolidadas todas as operações que ocorreram ao longo do dia gerando um resumo do valor vendido e os valores de venda por imposto. Essa informação é bastante importante pois é através dela que é possível validar se todos os cupons de venda foram recebidos corretamente.
{
"codigoLoja": 1,
"cuponsFiscais": [
{
"coo": 100005,
"data": "31/10/2022 10:34:36",
"dataAutorizacao": "31/10/2022 10:34:36",
"ecf": 1,
"codigoDoFiscal": 25,
"leituraZ": {
"numero": "100005",
"cooInicial": 100001,
"cooFinal": 100005,
"gtInicial": 0.00,
"gtFinal": 145.00,
"quantidadeCupons": 1,
"vendaBruta": 210.00,
"vendaLiquida": 210.00,
"valorDescontos": 0.00,
"valorCancelamentos": 0.00,
"valorAcrescimos": 0.00,
"cro": 100006,
"impostos": [
{
"codigoIcms": "I00.00",
"vendaBruta": 210.00
}
]
},
"numeroDoCupom": 100005,
"codigoDoOperador": 2233,
"tipo": "LEITURA_Z"
}
]
}{
"lojaKey": 1,
"cuponsFiscais": [
{
...dadosDoPrimeiroCupom...
},
{
...dadosDoSegundoCupom...
},
{
...dadosDoTerceiroCupom...
},
{
......
},
]
}Os códigos utilizados nos atributos finalizadora e codigoIcms são os códigos configurados no módulo venda online:
Tempo para processamento de cupons
Após envio dos cupons para o Bluesoft ERP será retornado na API um loteId que será utilizado posteriormente para consultar o status do lote enviado.
A consulta será feita através do endpoint Obter.
Recomenda-se aguardar no mínimo 2 minutos após o envio do lote de cupons para consultar seu status.
Esse é o tempo de recorrência para processamento de cupons pendentes.