Agora no Bluesoft ERP, é possível cancelar Notas Fiscais Eletrônicas (NF-e modelo 55) integradas como notas do tipo 141 pela API de Cupom Fiscal em Lote, utilizando um payload simplificado.

Objetivo

Sincronizar no ERP os cancelamentos realizados pelo sistema emissor externo (PDV), executando os estornos de estoque, escrita fiscal e demais efeitos aplicáveis, sem exigir o cancelamento manual da nota.

O Que Mudou?

Como Era o Processo Antes?

Anteriormente, reenviar pelo lote uma NF-e cancelada no PDV não acionava o cancelamento da nota vinculada no ERP. A nota podia permanecer ativa, exigindo intervenção manual.

Benefícios:

  • Eliminação do retrabalho com cancelamentos manuais.
  • Resolução rápida de divergências no fechamento de caixa e na contabilidade.
  • Processamento independente e atômico, não paralisando o restante do lote enviado.

Como Irá Funcionar a Partir de Agora?

Enviando Lote para Processamento

O integrador deverá enviar a requisição de lote para o endpoint já existente :

POST {{baseURL}}/api/fiscal/cupomfiscal/lote
Content-Type: application/json
X-Customtoken: {{token}}

O endpoint passa a reconhecer um fluxo específico de cancelamento. Nesse fluxo, o payload exigido foi simplificado, não é necessário reenviar os itens, as finalizadoras nem os demais dados completos da venda. Para isso, a operação deve informar:

  • tipo: "VENDA";
  • cancelado: true;
  • tipoModelo: "NF_E".

Informe também o codigoLoja e, na operação de cancelamento, a chave de acesso de 44 dígitos e o XML procEventoNFe codificado em Base64. O ERP localizará a nota do tipo 141 pela loja e pela chave.

O XML deve representar um evento de cancelamento homologado. A data e o protocolo registrados na nota serão obtidos de retEvento/infEvento/dhRegEvento e retEvento/infEvento/nProt. A justificativa padrão registrada será “Cancelamento realizado via API pelo PDV emissor”.

O cancelamento é atômico por operação, ou seja, se uma operação que falhar não deve deixar efeitos parciais nem impedir o processamento das outras operações válidas do mesmo lote.

Consultando Processamento do Lote

A inclusão do lote retorna HTTP 201 com um loteId. Essa resposta confirma o recebimento do lote, não a conclusão do cancelamento.

Use o identificador retornado para consultar o processamento através do GET {{baseURL}}/api/fiscal/cupomfiscal/lote/{{loteId}}

A consulta apresenta o status geral do lote e o status individual das operações: PENDENTE, PROCESSADO ou FALHOU. Para consultar também os detalhes de erros, utilize o parâmetro exibirDetalhesDoErro.

Em um lote misto, uma operação pode estar PROCESSADO e outra FALHOU; nesse caso, confira o motivo na operação com falha e não apenas o status geral do lote.

Observações e Validações

  • Validação do XML (Evento Homologado): O ERP aceitará apenas documentos que representem um cancelamento homologado, exigindo que o status no XML seja cStat 135 (Evento registrado) ou cStat 155 (Cancelamento homologado fora do prazo).
  • Escrita Fiscal: O cancelamento será permitido e executado caso não exista escrita fiscal ou se a escrita fiscal estiver no estado Aprovada. Caso a escrita esteja Conferida, Apurada, Reprovada ou possua escrita de frete impeditiva, a operação será bloqueada e retornará falha.
  • Preservação de Dados: O sistema não irá armazenar o XML do evento de cancelamento no banco, preservando assim o XML original da NF-e de venda.
  • Permissões de Acesso: O fluxo utilizará as permissões próprias do lote (3020 - Incluir lote de cupons fiscais e 3021 - Obter status de processamento do lote), não sendo exigida a permissão convencional de cancelar notas (1344 - Cancelar Nota Fiscal).

Exemplo de JSON da Requisição:

// POST {{baseURL}}/api/fiscal/cupomfiscal/lote
{
  "codigoLoja": 999,
  "emitirNotaFiscal": false,
  "cuponsFiscais": [
    {
      "tipo": "VENDA",
      "cancelado": true,
      "tipoModelo": "NF_E",
      "chave": "<chave-da-NF-e-com-44-digitos>",
      "xml": "<procEventoNFe+dados_XML-codificado-em-Base64>"
    }
  ]
}

Para conhecer mais sobre como é a utilização dessa ferramenta, clique aqui.

Para saber mais sobre a utilização das APIs do ERP, clique aqui.

Disponível a partir da versão r374.03