Apenas o arquivo md relativo a operação em contingencia SVC

robmachado · Jun 11, 2024 · 230b7eb · 230b7eb
1 parent 03bb7f2
commit 230b7eb
Showing 1 changed file with 145 additions and 87 deletions.
diff --git a/docs/Contingency.md b/docs/Contingency.md
@@ -2,97 +2,111 @@
 
 Em condições normais as NFe emitidas tem a propriedade &lt;tpEmis&gt; com o valor igual a 1-Emissão normal.
 
-Quando a conexão via internet com a SEFAZ autorizadora não é possivel, existem alternativas para permitir a emissão dos documentos mesmo nessas condições (offline).
-
-Para uma melhor compreensão, o ENCAT lançou um documento que visa facilitar o entendimento, ele pode ser encontrado em:
-
-[Página Principal](http://www.nfe.fazenda.gov.br/portal/principal.aspx) > Documentos > Manuais > Manual de Boas Práticas no desenvolvimento de emissor de NFC-e – BP 2018.001 – versão 1.0
-
-Após lê-lo, os procedimentos abaixo podem ser realizadas na biblioteca, há uma sessão interessante sobre contigência.
+Quando a conexão via internet com a SEFAZ autorizadora não é possivel, existem alternativas para permitir a emissão dos documentos mesmo nessas condições.
 
 Ao ativar qualquer contigência o XML da NFe deve ser remontado ou modificado e assinado novamente com as seguintes alterações:
 - &lt;tpEmis&gt; indicar o número do modo de contingência utilizado
 - &lt;dhCont&gt; Data e Hora da entrada em contingência no formato com TZD
 - &lt;xJust&gt; Justificativa da entrada em contingência com 15 até 256 caracteres
 
-### ~~FS-IA IMPRESSOR AUTÔNOMO (tpEmis = 2 OBSOLETO)~~
-Este modo de contingência permite que a NFe seja emitida sem que haja a prévia autorização pela SEFAZ autorizadora através da impressão do DANFE em formulário de segurança de impressor autônomo.
+## FS-DA DOCUMENTO AUXILIAR (tpEmis = 5) *apenas NFe (mod 55)*
+Este modo de contingência permite que a NFe seja emitida sem que haja a prévia autorização pela SEFAZ autorizadora através da impressão do DANFE em formulário de segurança.
 
-**Uso: Não mais pode ser usado**
+**Uso: Sem acesso a internet ou com a SEFAZ offline.**
 
-**Este modelo de contingência está desabilitado desde 2011. E não pode mais ser usado**
+Este modo de contingência permite que a NFe seja emitida sem que haja a prévia autorização pela SEFAZ autorizadora através da impressão do DANFE em formulário de segurança.
 
-Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 2
+**E ao retornar o serviço da SEFAZ autorizadora estes documentos deverão ser enviados dentro do prazo limite de 24 horas**.
 
-### ~~SCAN (tpEmis = 3 OBSOLETO)~~
-Sistema de Contingência do Ambiente Nacional, **este serviço foi desabilitado e portanto não está mais disponivel para uso**.
+Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 5
+> Não é recomendável o uso desse tipo de contingência com a NFe, por vários motivos. O primeiro é o custo, pois os formulários de segurança são caros e deve-se manter controle estrito sobre os mesmos, pois cada folha é identificada individualmente e pode ser usada indevidamente.
 
-**Uso: Não mais pode ser usado**
+> Devemos considerar também a necessidade adicional de controle dessas notas e posterior envio à SEFAZ autorizadora quando o sistema estiver novamente on-line.
 
-Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 3
+> Outro motivo é a possibilidade de a NFe ser reprovada após o processo posterior de envio a SEFAZ autorizadora, com isso o transporte e recebimento da mercadoria se torna uma operação "ilegal" e sujeita a punições.
+> Se for usar esse método melhore o sistema emissão com muitas validações, para garantir que erros sejam identificados antes de geração do ducumento, para evitar problemas posteriores e multas. 
 
-### ~~DPEC (tpEmis = 4 OBSOLETO)~~
-Declaração Prévia da Emissão em Contingência
 
-Este tipo de contingência foi substituido pelo modo EPEC que utiliza eventos para registrar a emissão. Veja EPEC.
+## SVC-AN (tpEmis = 6) *Apenas NFe (modelo 55)*
 
-**Uso: Não mais pode ser usado**
+SEFAZ Virtual de Contingência do Ambiente Nacional
 
-Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 4
+Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 6
 
-### EPEC (tpEmis = 4) *NFe e NFCe*
-Evento Prévio da Emissão em Contingência
+Este sistema de contingência é o **melhor de todos** e permite que as notas sejam emitidas com poucas alterações e sem a necessidade de reenvio posterior. Nesse modo as notas enviadas serão sincronizadas automaticamente pelos orgãos autorizadores sem a necessidade que qualquer outra ação pelo emitente. Este serviço atende:
+AC, AL, AP, CE, DF, ES, MG, PA, PB, PI, RJ, RN, RO, RR, RS, SC, SE, SP, TO 
 
-**Uso: SEFAZ OFF e SVC OFF mas emitente com acesso à internet.**
+> Este é o caso de uso da classe Contingency da nossa biblioteca, inclusive NFe emitidas em modo normal será automaticamente ajustadas para o ambiente de contingência e novamente assinadas quando contingencia SVCAN estiver ativada na class Tools.
 
-Este modo de contingência é diferente dos demais por que na verdade irá enviar um evento especifico para o webservices de Registro de Eventos do Ambiente Nacional. Normalmente usa-se esse tipo de contingência em caso da SEFAZ autorizadora estar fora do ar, bem como o Serviço Virtual de Contingência também, e isso é uma situação muito rara de ocorrer.
+> IMPORTANTE: este processo irá alterar a chave da NFe, e portanto deverá ser regravada em sua base de dados (com a chave nova gerada pelo processo de envio).  
 
-Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 4
+**Uso: SEFAZ OFFLINE, mas emitente com acesso à internet, e sistema de contigência SVCAN ativado pela SEFAZ autorizadora do seu estado.**
 
-### FS-DA DOCUMENTO AUXILIAR (tpEmis = 5) *NFe e NFCe*
-Este modo de contingência permite que a NFe seja emitida sem que haja a prévia autorização pela SEFAZ autorizadora através da impressão do DANFE em formulário de segurança.
 
-**Uso: Sem acesso a internet.**
+## SVC-RS (tpEmis = 7) *Apenas NFe (modelo 55)*
 
-Este modo de contingência permite que a NFe seja emitida sem que haja a prévia autorização pela SEFAZ autorizadora através da impressão do DANFE em formulário de segurança.
+SEFAZ Virtual de Contingência do RS
 
-Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 2
-> Não é recomendável o uso desse tipo de contingência com a NFe, por vários motivos. O primeiro é o custo, pois os formulários de segurança são caros e deve-se manter controle estrito sobre os mesmos, pois cada folha é identificada individualmente e pode ser usada indevidamente.
+Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 7
 
-> Devemos considerar também a necessidade adicional de controle dessas notas e posterior envio à SEFAZ autorizadora quando o sistema estiver novamente on-line.
+Este sistema de contingência é o **melhor de todos** e permite que as notas sejam emitidas com poucas altereções e sem a necessidade de reenvio posterior. Nesse modo as notas enviadas serão sincronizadas automaticamente pelos orgãos autorizadores sem a necessidade que qualquer outra ação pelo emitente. Este serviço atende:
+AM, BA, GO, MA, MS, MT, PE, PR
 
-> Outro motivo é a possibilidade de a NFe ser reprovada após o processo posterior de envio a SEFAZ autorizadora, com isso o transporte e recebimento da mercadoria se torna uma operação "ilegal" e sujeita a punições.
+> Este é o caso de uso da classe Contingency da nossa biblioteca, inclusive NFe emitidas em modo normal será automaticamente ajustadas para o ambiente de contingência e novamente assinadas quando contingencia SVCAN estiver ativada na class Tools.
 
-Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 5
+> IMPORTANTE: este processo irá alterar a chave da NFe, e portanto deverá ser regravada em sua base de dados (com a chave nova gerada pelo processo de envio).
 
-### SVC-AN (tpEmis = 6) *Apenas NFe (modelo 55)*
-SEFAZ Virtual de Contingência do Ambiente Nacional
+**Uso: SEFAZ OFFLINE, mas emitente com acesso à internet, e sistema de contigência SVCRS ativado pela SEFAZ autorizadora do seu estado.**
 
-Este sistema de contingência é o **melhor de todos** e permite que as notas sejam emitidas com poucas alterações e sem a necessidade de reenvio posterior. Nesse modo as notas enviadas serão sincronizadas automaticamente pelos orgãos autorizadores sem a necessidade que qualquer outra ação pelo emitente. Este serviço atende:
-AC, AL, AP, DF, ES, MG, PB, RJ, RN, RO, RR, RS, SC, SE, SP, TO 
 
-**Uso: SEFAZ OFF, mas emitente com acesso à internet.**
+## OFF-LINE (tpEmis = 9) *EXCLUSIVO PARA NFCe*
 
-Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 6
+Este modo de contingência permite que a NFCe seja emitida sem que haja a prévia autorização pela SEFAZ autorizadora através da impressão do DANFCE.
 
-### SVC-RS (tpEmis = 7) *Apenas NFe (modelo 55)*
-SEFAZ Virtual de Contingência do RS
+**E ao retornar o serviço da SEFAZ autorizadora estes documentos deverão ser enviados dentro do prazo limite de 24 horas**.
 
-Este sistema de contingência é o melhor de todos e permite que as notas sejam emitidas com poucas altereções e sem a necessidade de reenvio posterior. Nesse modo as notas enviadas serão sincronizadas automaticamente pelos orgãos autorizadores sem a necessidade que qualquer outra ação pelo emitente. Este serviço atende:
-AM, BA, CE, GO, MA, MS, MT, PA, PE, PI, PR
+Nesse caso o xml da NFCe deve indicar na propriedade &lt;tpEmis&gt; o valor 9
 
-**Uso: SEFAZ OFF, mas emitente com acesso à internet.**
+> *IMPORTANTE*: Esse modo de contingência serve exclusivamente para as notas modelo 65 e não podem ser usadas em notas modelo 55.
 
-Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 7
+> Todos os estados permitem a emissão de NFCe em modo OFFLINE, exceto SP, onde é obrigátorio o uso do SAT@ecf ou da emissão por EPEC NFCe
 
-### OFF-LINE (tpEmis = 9) *EXCLUSIVO PARA NFCe*
-Para a NFCe somente estão disponíveis e são válidas as opções de contingência 5 (FS-DA) e 9 (OFF-LINE).
+**Uso: Sem acesso a internet ou com a SEFAZ offline.**
 
-> *IMPORTANTE*: Esse modo de contingência serve exclusivamente para as notas modelo 65 e não podem ser usadas em notas modelo 55.
 
-**Uso: Sem acesso a internet.**
+## EPEC (tpEmis = 4) *NFe e NFCe*
 
-Nesse caso o xml da NFCe deve indicar na propriedade &lt;tpEmis&gt; o valor 9
+Evento Prévio da Emissão em Contingência
+
+Nesse caso o xml da NFe deve indicar na propriedade &lt;tpEmis&gt; o valor 4
+
+Este é o processo mais complexo e "arriscado" entre todos os modos de contigência.
+
+São dois tipos diferentes mas que seguem basicamente as mesmas regras estruturas e condições, apenas são direcionados para webservices diferentes.
+
+Em ambos os casos são criados eventos EPEC Evento Prévio de Emissão em Contingência, para emitir em EPEC devem ser observados os seguintes passos:
+
+1. criar a NFe ou a NFCe já marcada em contignência EPEC com **tpEmis = 4**, **dhCont = data hora de entrada em contingência** e **xJust = justificativa**
+2. criar e enviar o evento EPEC pelos métodos da classe Tools, sendo:
+  - $tools->sefazEPEC($xml, $verAplic) para NFe (mod 55)
+  - $tools->sefazEpecNfce($xml, $verAplic) para NFCe (mod 65)
+3. verificar se o evento foi autorizado, se sim protocolar, se não tratar o erro até ser autorizado
+4. usar o xml e os dados do EPEC autorizado para imprimir o DANFE ou DANFCE
+5. enviar o xml assim que a SEFAZ autorizadora retornar a operção normal
+
+### EPEC NFe (mod 55)
+
+Este processo envia o EPEC para o ambiente nacional 
+
+### EPEC NFCe (mod 65)
+
+Este processo envia o EPEC para o webservice de registro de EPEC especifico para NFCe exclusivamente no estado de São Paulo.
+
+> NOTA: não existe EPEC para NFCe em outros estados, neles deve ser usado a contingência OFFLINE
+
+Este modo de contingência é diferente dos demais por que na verdade irá enviar um evento especifico para o webservices de Registro de Eventos do Ambiente Nacional. Normalmente usa-se esse tipo de contingência em caso da SEFAZ autorizadora estar fora do ar, bem como o Serviço Virtual de Contingência também, e isso é uma situação muito rara de ocorrer.
+
+**Uso: SEFAZ OFF e SVC OFF mas emitente com acesso à internet.**
 
 # [Esclarecimentos sobre TIMEOUT](TimeOut.md)
 
@@ -103,21 +117,63 @@ Nesse caso o xml da NFCe deve indicar na propriedade &lt;tpEmis&gt; o valor 9
 
 **Habilitando o modo de contingência**
 
+A classe Contingency somente será usada para envio de NFe (mod 55) para as contigências SVC-AN ou SVC-RS, que são substitutos diretos à emissão normal.
+
+Os demais tipos de contingência como:
+
+- FS-DA DOCUMENTO AUXILIAR (tpEmis = 5), o xml é criado em modo contigência e a NFe é impressa nesse formulário e posteriormente enviada para a SEFAZ autorizadora.
+- OFFLINE NFCe (mod 65), o xml é criado já em modo de contingência OFFLINE (tpEmis = 9) e a NFCe é impressa e posteriormente enviada para a SEFAZ autorizadora.
+- EPEC NFe (mod 55), o xml é criado em modo de contingência EPEC, e usado para criar o evento EPEC, se o evento for aceito poderá ser usado conjuntamente com a NFe para imprimir a DANFE e posteriormente enviar a NFe para a SEFAZ autorizadora.  
+- EPEC NFCe (mod 65) exclusivo para o estado de SP, o xml é criado em modo de contingência EPEC, e usado para criar o evento EPEC NFCe (apenas em SP), se o evento for aceito poderá ser usado conjuntamente com a NFCe para imprimir a DANFCE e posteriormente enviar a NFCe para a SEFAZ SP.
+
+Como deve ser feito o processo no seu sistema:
+
+1. ao entrar em contingência, sempre verifique se a mesma está ativa para o seu estado
+2. ative o modo de contingência e grave o json retornado em um cache ou pbase de dados, para habilitar seu uso continuo
+3. ao enviar uma NFe (mod 55), sempre verifique esse json no cache ou na base de dados e o recarregue em Contingency::class
+4. injete a Contingency::class na classe principal Tools::class
+```php
+
+$cert = Certificate::readPfx(file_get_contents('certificado.pfx'), 'senha');
+//recarrega a contingencia que foi enteriormente ativada e gravada em cache
+$cont = null;
+if (!empty($json_contingencia_do_cache)) {
+    $cont = new Contingency($json_contingencia_do_cache);
+}    
+//inicia o serviço da Tools::class em contingência se ela estiver ativa
+$tools = new Tools($configJson, $cert, $cont);
+$tools->model(55); 
+```
+5. ou carregue a proriedade publica da classe $tools->contingency 
+```php
+$cert = Certificate::readPfx(file_get_contents('certificado.pfx'), 'senha');
+//recarrega a contingencia que foi enteriormente ativada e gravada em cache
+$cont = null;
+if (!empty($json_contingencia_do_cache)) {
+    $cont = new Contingency($json_contingencia_do_cache);
+}    
+//inicia o serviço da Tools::class em contingência se ela estiver ativa
+$tools = new Tools($configJson, $cert);
+$tools->contingency = $cont;
+$tools->model(55); 
 ```
+
+```php
 use NFePHP\NFe\Factories\Contingency;
 
 $contingency = new Contingency();
 
-$acronym = 'SP';
-$motive = 'SEFAZ fora do AR';
-$type = 'SVCAN';
+$acronym = 'SP'; //Obrigatório
+$motive = 'SEFAZ fora do AR'; //Obrigatório
+$type = 'SVCAN'; //opcional, opções SVCAN ou SVCRS, se não informado será usado o tipo relativo à UF informada
 
 $status = $contingency->activate($acronym, $motive, $type);
 
 ```
-$status irá conter uma string JSON ENCODED, com as informações sobre a condição de contingência. 
+$status irá conter uma string JSON ENCODED, com as informações sobre a condição de contingência.
 
-```
+
+```json
 {
    "motive":"SEFAZ fora do AR",
    "timestamp":1484747583,
@@ -127,24 +183,29 @@ $status irá conter uma string JSON ENCODED, com as informações sobre a condi
 ```
 Essa string deverá ser arquivada, em disco ou em base de dados para uso posterior, até que o modo de contingencia seja desabilitado. 
 Ou seja, a cada vez que carregar a classe Tools deverá ser passada a classe contingency, ou será considerado que o ambiente é normal. Exemplo:
-```
+```php
+$status_contingencia = '{
+   "motive":"SEFAZ fora do AR",
+   "timestamp":1484747583,
+   "type":"SVCAN",
+   "tpEmis":6
+}';
+
+$contingency = (new Contingency())->load($status_contingencia);
 $tools->contingency = $contingency;
 ```
 
-
-
 **Desabilitando o modo de contingência**
-```
+```php
 use NFePHP\NFe\Factories\Contingency;
 
-//onde $status é a string obtida quando entrou em modo de contingência.
+//onde $status é a string json obtida quando entrou em modo de contingência.
 $contingency = new Contingency($status);
-
 $status = $contingency->deactivate();
 
 ```
 $status irá conter dados padrões em condições normais.
-```
+```json
 {
    "motive":"",
    "timestamp":0,
@@ -160,20 +221,20 @@ Essa string deverá ser arquivada, em disco ou em base de dados para uso posteri
 public $type;
 
 @var string
-> Tipo da contingência FSDA, SVCAN, SVCRS, EPEC, OFFLINE 
+> Tipo da contingência SVCAN, SVCRS 
 
 
 public $motive;
 
 @var string
 > Motivo da entrada em contingência, texto com no minimo 15 caracteres e no máximo 255.
 
-> NOTA: remova todo e qualquer caracter especial desse texto.
+> NOTA: somente são aceitos caracteres UTF-8 e não devem ser usados simbolos.
 
 public $timestamp;
 
 @var int
->Timestmap do PHP que representa a data e hora em que a contignência foi ativada.
+>Timestmap do PHP que representa a data e hora em que a contigência foi ativada (GMT).
 
 
 public $tpEmis;
@@ -186,34 +247,31 @@ public $tpEmis;
 
 Construtor, caso seja passado o parametro, uma string JSON, a condição de contingência contida nessa string será registrada na classe.
 Caso nada seja passado a classe irá considerar condição de emissão normal.
-```
-Contingency::construct($string)
+```php
+$cont = new Contingency($string_Json_Contingencia);
 ```
 
 Essa é outra forma de passar o parametro (string JSON) para a classe.
-```
-Contingency::load($string)
+```php
+$cont = (new Contingency())->load($string_Json_Contingencia);
 ```
 
 Esse método ativa o modo de continência da classe.
 Os parametros são:
+```php
+$sigla = 'SP'; //a sigla do estado do emitente da NFe
+$motivo = 'SEFAZ SP fora do ar por problemas técnicos'; //motivo da entrada em contingencia de 15 a 256 caracteres UTF-8
+$tipo = ''; //não é necessario de forma geral 
+$cont = (new Contingency())->activate($sigla, $motivo, $tipo);
 ```
-Contingency::activate($acronym, $motive, $type)
-```
-
-$acronym --- sigla do estado
-
-$motive --- texto com o motivo da entrada em contingência
-
-$type --- podem ser usadas as constantes:
-
-- Contingency::SVCAN
-- Contingency::SVCRS
-- Contingency::FSDA
-- Contingency::OFFLINE
-- Contingency::EPEC
 
 Esse método desativa o modo de contingência e retorna uma string json com os valores padrões.
-```
-Contingency::deactivate()
+```php
+$sigla = 'SP'; //a sigla do estado do emitente da NFe
+$motivo = 'SEFAZ SP fora do ar por problemas técnicos'; //motivo da entrada em contingencia de 15 a 256 caracteres UTF-8
+$tipo = ''; //não é necessario de forma geral
+$cont = new Contingency();
+$status_json_contingencia_ativada = $cont->activate($sigla, $motivo, $tipo);
+
+$status_json_contingencia_desativada = $cont->deactivate();
 ```