Emitindo notas fiscais

Quando você pede para emitir uma nota fiscal, o sistema não espera a prefeitura responder para até devolver o resultado. Ele faz assim:

1. Salva a solicitação no banco de dados com status "aguardando".
2. Envia para o eNotas em segundo plano (sem travar a sua tela).
3. Devolve a resposta na hora com status "enviado para processamento".
4. Recebe a confirmacao da prefeitura depois, via retorno automatico.
5. Atualiza o status para "emitida" ou "falhou", conforme o resultado.

Esse modelo "disparar e esquecer" é o que faz o sistema ser rapido: você não fica esperando a prefeitura, que pode demorar segundos ou minutos.

Cada nota fiscal passa por varios estados até chegar ao resultado final:

Caminho normal

Quando da erro

Cancelamento

A interface deve mostrar o status atual e atualizar automaticamente quando o resultado chegar.

Para emitir uma nota, você precisa informar:

• Data fiscal — o dia em que o serviço foi prestado.
• Itens — descricao, quantidade, valor unitario de cada serviço prestado.
• Comprador (opcional) — quem contratou o serviço. Pode ser pessoa fisica (CPF) ou juridica (CNPJ).
• Observacoes (opcional) — notas internas que aparecem na nota fiscal.

O sistema calcula o valor total automaticamente e aplica os impostos corretos. você não precisa se preocupar com a matematica.

E se o retorno automatico da prefeitura se perder (falha de internet, restart do servidor)? A nota ficaria travada em "enviada" para sempre?

Nao. Existe um verificador automatico que roda a cada 2 minutos e verifica o status de todas as notas que estao esperando. Se o retorno se perdeu, o verificador busca o status direto na prefeitura e atualiza a nota.

Isso significa: em no maximo 2 minutos, qualquer nota vai chegar ao seu status final, mesmo que algo de errado aconteca com a comunicacao.

Depois que uma nota foi emitida, você pode cancela-la se precisar (por exemplo, o cliente cancelou o serviço, ou houve um erro de digitacao).

Como funciona

1. você pede o cancelamento.
2. O sistema marca a nota como "cancelando" e avisa a prefeitura.
3. A prefeitura confirma o cancelamento.
4. A nota passa para "cancelada".

Atencao

Algumas prefeituras tem prazo maximo para cancelamento (geralmente 24 horas apos a emissão). Depois desse prazo, o cancelamento pode ser rejeitado. O sistema mostra o erro explicando o motivo.

Se você quiser ser avisado quando a nota mudar de status, pode pedir um retorno automatico no momento da emissão. O sistema manda uma mensagem para o seu sistema toda vez que a nota muda de estado.

Eventos que podem ser enviados

• sucesso — a nota foi emitida pela prefeitura.
• negada — a prefeitura rejeitou a nota.
• erro do provedor — a prefeitura ou o eNotas retornou um erro.
• erro da requisicao — os dados enviados estavam incorretos.
• cancelada — a nota foi cancelada com sucesso.
• erro ao cancelar — o cancelamento foi rejeitado.

Cada evento inclui o status atual, a data/hora, e detalhes do erro (se houver). Seu sistema pode usar essas informações para atualizar a interface em tempo real.

Cada prefeitura tem suas proprias regras para notas fiscais. O sistema tem adaptacoes especificas para 11 cidades:

Rio de Janeiro, Taboão da Serra, Vitória da Conquista, Andradas, Santana de Parnaíba, Caxias do Sul, Sobral, Cabo Frio, São Paulo, Osasco.

Se a entidade fiscal é de uma dessas cidades, o sistema ajusta o pedido automaticamente para seguir as regras locais. Por exemplo, São Paulo tem regras especiais para certos tipos de serviço.

Se a cidade não esta na lista, o sistema usa um formato padrao que funciona na maioria das prefeituras.

Em ambiente de desenvolvimento ou testes, existe um modo especial que simula a emissão de notas sem realmente gerar NFS-e na prefeitura. Isso permite testar o fluxo sem custos ou riscos.

Quando esse modo esta ativo:

• A "emissão" termina instantaneamente com status "emitida".
• Nenhuma nota real é gerada na prefeitura.
• O verificador automatico fica desativado.
• Um email de debug é enviado para avisar que foi um teste.

Em produção, esse modo precisa estar desligado, senao nenhuma nota real sera gerada.

"Entidade não está pronta para emitir"

A entidade fiscal ainda não foi configurada. Volte para o guia de configuração e complete os passos.

Nota presa em "enviada"

O retorno automatico da prefeitura se perdeu. O verificador automatico vai resolver em até 2 minutos. Se não resolver, entre em contato com o suporte.

Nota marcada como "falhou"

A prefeitura rejeitou a nota. Verifique o motivo do erro (CNPJ invalido, codigo de serviço errado, etc.), corrija os dados e tente novamente.

Cancelamento rejeitado

A prefeitura não permite cancelar apos o prazo. O sistema mostra o motivo e sugere o que fazer.

1. ☐ Confirmar que a entidade fiscal esta com status "Ativo"
2. ☐ Pedir a emissão da nota com os dados do serviço
3. ☐ Mostrar a nota como "enviada" na interface
4. ☐ Quando a prefeitura confirmar, mostrar como "emitida"
5. ☐ Disponibilizar o link do PDF e do XML para o cliente
6. ☐ Se o cliente pedir cancelamento, iniciar o fluxo de cancelamento
7. ☐ Guardar o historico de todas as notas para consulta futura

Quando tudo está funcionando, a interface deve ser simples: o usuario preenche os dados do serviço, clica em "emitir", e o sistema cuida de tudo.