No intuito de permitir a geração do SAT a partir de integrações com parceiros desenvolvemos a solução de integração via webhooks.
Com ela, é possível configurar uma URL, dados de autenticação e informações do cabeçalho, para que quando for selecionada a opção de Gerar CF-e ao finalizar uma venda pelo Frente de Caixa ou pelo menu da listagem de Pedidos de Venda, e a configuração de integração com o SAT for do tipo Integração, será disparado um POST para a URL configurada com todos os dados necessários para que o parceiro faça a emissão do SAT.
O padrão de respostas aceito está detalhado no anexo.
Após a geração do SAT por parte do parceiro, ele poderá fazer um PUT no pedido, atualizando a situação do pedido.
Veja neste artigo:
Configuração
Deve ser feita uma solicitação de ativação do módulo SAT através para nossa equipe de atendimento.
Após a liberação, a configuração do SAT pode ser acessada pelo ícone do perfil da sua empresa e clique em 'Todas as configurações > Notas fiscais > Configurações SAT'.
A configuração do código de assinatura é utilizada na geração do SAT via arquivo, mas é enviada também na requisição webhook (campo signAC, veja ANEXO 2).
Atualmente só é possível configurar uma única chave.
Após habilitar a integração SAT e selecionar o tipo como 'Integração' serão exibidas as configurações para envio dos webhooks.
O formato de envio pode ser em XML ou JSON, sendo o formato de envio quem define também o formato esperado no payload de resposta da requisição.
O campo 'URL de envio' é obrigatório (Informação obtida diretamente com o seu integrador).
Para endereços externos é obrigatório o uso do protocolo HTTPS.
Os endereços reservados de loopback (localhost e 127.0.0.1) são executados localmente e permitem a utilização do protocolo HTTP.
Os campos usuário e senha definem o header Authorization: Basic <base64> e são obrigatórios.
Na opção 'Adicionar header' é possível configurar headers personalizados para a requisição.
Funcionamento
Ao finalizar a venda no frente de caixa, selecionando a opção de gerar CFe, o cliente recebe a resposta de sucesso ou falha.
A mensagem de sucesso é exibida quando o retorno é 1 (sucesso) ou 2 (aguardando retorno).
A mensagem de erro permite ao usuário tentar novamente, ou, clicando em 'OK', a venda continua com status 'Em aberto' e a requisição pode ser reenviada posteriormente através da tela de pedidos de venda (ANEXO 4).
Request e Response
Fluxo:
- Venda finalizada: Status 'Atendido'
- Envio dos dados: Status 'Atendido'
O tempo limite da requisição é de 5000ms
- Retorno:
- Código 1 (Sucesso):
- Grava ocorrência
- Status da venda atualizado para 'Atendido'
- Código 2 (Aguardando):
- Grava ocorrência
- Status da venda atualizado para 'Em aberto'
- Códigos de erro (ANEXO 1) ou falha na comunicação
- Grava ocorrência com mensagem de erro retornada
- Status da venda atualizado para 'Em aberto'
- Caso retornado código 2 o integrador deve, ao finalizar a geração do documento, enviar uma requisição via API de pedidos
do Bling atualizando a situação do pedido para 'Atendido' ou situação customizada baseada nela.
Request enviado (body)
Exemplo de payload enviado no ANEXO 2
Retorno aguardado
Exemplo de retorno aguardado no ANEXO 3
ANEXO 1 - Códigos de retorno
Tabela com os códigos de retorno e suas respectivas mensagens mostradas ao usuário:
|
Código |
Tipo |
Mensagem |
|
1 |
Sucesso |
SAT gerado com sucesso |
|
2 |
Sucesso |
SAT gerado com sucesso (Na ocorrência: Aguarde atualização do integrador SAT) |
|
3 |
Erro |
Erro desconhecido no integrador SAT |
|
4 |
Erro |
Código de ativação inválido |
|
5 |
Erro |
Vinculação do AC não confere |
|
6 |
Erro |
Erro de validação do conteúdo |
|
7 |
Erro |
Erro desconhecido na emissão |
|
8 |
Erro |
SAT ainda não ativado |
|
9 |
Erro |
SAT bloqueado pela SEFAZ |
|
10 |
Erro |
SAT bloqueado pelo contribuinte |
|
11 |
Erro |
SAT bloqueado por falta de comunicação |
|
12 |
Erro |
SAT bloqueado, código de ativação incorreto |
|
13 |
Erro |
SAT em processamento. Tente novamente |
|
14 |
Erro |
SAT não vinculado ao AC |
|
15 |
Erro |
Tamanho do CF-e-SAT superior a 1.500KB |
Erros de comunicação ou códigos inválidos exibirão a mensagem:
Não foi possível interpretar a resposta do integrador SAT.
Exemplo de mensagem de erro exibida na tela do usuário.
ANEXO 2 - Payload de requisição
Formato XML
<?xml version="1.0" ?>
<CFe>
<infCFe versao="1.00" versaoDadosEnt="0.08">
<ide>
<CNPJ>01056417000139</CNPJ>
<signAC>gvErYT3Xx7Q...</signAC>
<numeroCaixa>001</numeroCaixa>
</ide>
<emit>
<CNPJ>62597336000130</CNPJ>
<IE>612396958183</IE>
<indRatISSQN>N</indRatISSQN>
</emit>
<dest />
<det nItem="1">
<prod>
<cProd>CFOP5102</cProd>
<cEAN>7896090704804</cEAN>
<xProd>ÁLCOOL 46 ZUMBI 1L</xProd>
<NCM>29051100</NCM>
<CFOP>5102</CFOP>
<uCom>un</uCom>
<qCom>1.0000</qCom>
<vUnCom>6.99</vUnCom>
<indRegra>A</indRegra>
<vDesc>0.00</vDesc>
</prod>
<imposto>
<vItem12741>1.94</vItem12741>
<ICMS>
<ICMSSN900>
<Orig>0</Orig>
<CSOSN>900</CSOSN>
<pICMS>0.00</pICMS>
</ICMSSN900>
</ICMS>
<PIS>
<PISNT>
<CST>07</CST>
</PISNT>
</PIS>
<COFINS>
<COFINSNT>
<CST>07</CST>
</COFINSNT>
</COFINS>
</imposto>
</det>
<total />
<pgto>
<MP>
<cMP>99</cMP>
<vMP>6.99</vMP>
</MP>
</pgto>
</infCFe>
<idPedido>289</idPedido>
</CFe>
Formato JSON
{
"CFe": {
"infCFe": {
"@attributes": {
"versao": "1.00",
"versaoDadosEnt": "0.08"
},
"ide": {
"CNPJ": "01056417000139",
"signAC": "eTBYUZy7%25252525252...",
"numeroCaixa": "001"
},
"emit": {
"CNPJ": "58757168000126",
"IE": "2848081133",
"indRatISSQN": "N"
},
"dest": {},
"det": [
{
"@attributes": {
"nItem": "1"
},
"prod": {
"cProd": "MA1",
"xProd": "MASSA PARA PIZZA 10KG",
"NCM": "19023000",
"CFOP": "5102",
"uCom": "UN",
"qCom": "3.0000",
"vUnCom": "10.00",
"indRegra": "A",
"vDesc": "0.00"
},
"imposto": {
"vItem12741": "4.86",
"ICMS": {
"ICMSSN900": {
"Orig": "0",
"CSOSN": "900",
"pICMS": "0.00"
}
},
"PIS": {
"PISNT": {
"CST": "07"
}
},
"COFINS": {
"COFINSNT": {
"CST": "07"
}
}
}
},
{
"@attributes": {
"nItem": "2"
},
"prod": {
"cProd": "ASD12",
"xProd": "ALCOOL ZUMBI 900ML",
"NCM": "29051100",
"CFOP": "5102",
"uCom": "UN",
"qCom": "2.0000",
"vUnCom": "4.99",
"indRegra": "A",
"vDesc": "0.00"
},
"imposto": {
"vItem12741": "0.98",
"ICMS": {
"ICMSSN900": {
"Orig": "0",
"CSOSN": "900",
"pICMS": "0.00"
}
},
"PIS": {
"PISNT": {
"CST": "07"
}
},
"COFINS": {
"COFINSNT": {
"CST": "07"
}
}
}
}
],
"total": {},
"pgto": {
"MP": {
"cMP": "99",
"vMP": "39.98"
}
}
},
"idPedido": "120"
}
}
ANEXO 3 - Exemplos de retorno aguardado
O formato do retorno pode ser XML ou JSON, seguindo a configuração do formato de envio.
Formato JSON:
Sucesso:
{
"result": {
"code": 1
}
}
Sem erro, SAT não gerado imediatamente (aguardando):
{
"result": {
"code": 2
}
}
Erro:
{
"result": {
"code": 3
}
}
Formato XML:
Sucesso:
<?xml version="1.0"?>
<result>
<code>1</code>
</result>
Sem erro, SAT não gerado imediatamente (aguardando):
<?xml version="1.0"?>
<result>
<code>2</code>
</result>
Erro:
<?xml version="1.0"?>
<result>
<code>3</code>
</result>
ANEXO 4 - Envio através da listagem de Pedidos de vendas
A opção Gerar SAT estará disponível no menu à frente do pedido quando a venda estiver
Em Aberto e a integração configurada corretamente.
No caso de sucesso é gravada ocorrência e o status do pedido é atualizado para 'Atendido'.
No caso de resposta código 2 (aguardar) é gravada ocorrência a venda continua com status 'Em aberto'.
Posteriormente atualizado via API de pedidos:
No caso de falha de comunicação ou código de erro, é gravada a ocorrência (status 'Em aberto') e a mensagem é exibida.