Como funciona o processo de emissão na API Rest?
A integração Oobj via API REST permite realizar o gerenciamento das empresas cadastradas na Oobj e também realiza a emissão e recebimento de Documentos Fiscais Eletrônicos. Para utilizar esses serviços é necessário registrar o Aplicativo que irá utilizar a API na Conta habilitada a gerenciar a(s) Empresa(s) do cliente ou parceiro.
Abaixo, descreveremos como funciona todo o processo, desde a autenticação até a geração do documento auxiliar, para a emissão Normal e em Contingência através da API Rest.
A sua integração começa pelo Serviço de Autenticação. Apenas através dela, e do x-auth-token, é possível utilizar os Serviços de Emissão, Recebimento e Gerenciamento de Empresas.
O processo de autenticação é realizado entre o cliente e a Oobj. O cliente faz a requisição Post(/session) para a geração do X-Auth-Token:
Após a obtenção do X-Auth-Token, é possível realizar a emissão de DF-e. Para isso, basta utilizar a requisição Post (/api/empresas/{empresa}/docs/{ambiente}/{codModelo}).
A aplicação receberá o documento, fará a validação do mesmo e, se válido, enviará para processamento da SEFAZ. Caso não esteja válido, a aplicação gravará o retorno de arquivo inválido no banco. Após processamento do documento pela SEFAZ, haverá a geração e gravação do retorno ao banco de dados.
Após a emissão do documento fiscal, orienta-se que seja consultado o retorno de processamento. Para isso, pode-se realizar uma entre as requisições Get abaixo:
- (/api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{ano}/{serie}/{numero})
- (/api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{chaveAcesso}).
A aplicação consultará o retorno gravado no banco de dados e disponibilizará para o usuário.
- Caso o retorno seja de arquivo inválido ou rejeição, é necessário a correção do arquivo e novo envio do documento fiscal (processo anterior).
- Caso o retorno seja de autorização, pode-se gerar o documento auxiliar (processo que será citado posteriormente).
- Caso não haja retorno, ou seja de falha de transmissão/não processado ou inconclusivo, é necessário analisar a situação e seguir uma das opções: aguardar e realizar nova consulta ou ativar a contingência.
Essa Contingência deverá ser acionada somente quando, depois de um tempo definido pelo desenvolvedor (normalmente 5 minutos - essa orientação se deve, principalmente, pela qualidade de rede ou eventual indisponibilidade da SEFAZ), não houver retorno ou o retorno for insatisfatório (Falha na transmissão/Não processado). A ativação da Contingência é realizada através do método Post - (/api/empresas/{empresa}/{codModelo}/{tpEmis}). Após a Contingência estar ativa, é necessário requisitar a emissão da NF-e.
Posterior ao envio da NFe em Contingência, é necessário verificar se o Evento EPEC foi homologado junto ao Ambiente Nacional. Basta realizar uma das requisições Get abaixo:
- (/api/empresas/{empresa}/docs/{ambiente}/{chaveAcesso}/eventos) ou
- (/api/empresas/{empresa}/docs/{ambiente}/{chaveAcesso}/eventos/{tipoEvento}) .
A aplicação consultará o retorno gravado no banco de dados e disponibilizará para o usuário.
- Caso o Evento esteja homologado, pode-se gerar o Documento Auxiliar da NF-e;
- Caso o Evento esteja rejeitado, é necessário verificar a possibilidade de Correção e Reenviar o Documento;
Essa contingência deverá ser acionada quando não houver retorno ou o retorno for insatisfatório (Falha na transmissão/Não processado). Como a NFC-e possui um prazo máximo de 5 minutos para transmissão, não há orientação para aguardar determinado tempo. A ativação da Contingência é realizada através do método Post - (/api/empresas/{empresa}/{codModelo}/{tpEmis}) . Após a ativação, é necessário requisitar a emissão da NFC-e. Ao emitir uma NFC-e em Contingência, pode-se solicitar a geração do documento auxiliar, sem a autorização prévia da SEFAZ.
O passo final para o processo de emissão de um documento é a geração do documento auxiliar. Basta requisitar um dos métodos GET abaixo:
- /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{chaveAcesso}.pdf
- /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{ano}/{serie}/{numero}.pdf .