• Qual a diferença entre o token client_credentials e o token authorization_code?

Os dois são os principais fluxos de autenticação definidos pelo protocolo OAuth 2.0, que é usado para permitir que aplicativos obtenham acesso autorizado a recursos em nome de um usuário.
A diferença fundamental entre eles está na maneira como a autenticação é realizada e em que cenários são mais apropriados:

     client_credentials:
     É utilizado para integração entre sistemas, quando não é necessária a intervenção humana, assim não há o processo de autenticação através do login de um usuário.

     authorization_code:
     É utilizado para integração entre sistemas, contudo é necessário que o sistema integrado com o spi-servicos possua a autenticação (login de usuário) controlado pela Central de Segurança, gerando um token JWT.
     Deste modo, é possível "aproveitar" o mesmo token gerado no momento do login do usuário para consumir os serviços.


• Quais são as URLs da Central de Segurança para obter o token client_credentials?

     desenv -> http://auth-cs.desenvolvimento.celepar.parana/centralautenticacao/api/v1/token/jwt
     homolog -> https://auth-cs-hml.identidadedigital.pr.gov.br/centralautenticacao/api/v1/token/jwt
     treinamento -> https://auth-cs-hml.identidadedigital.pr.gov.br/centralautenticacao/api/v1/token/jwt
     prod -> https://auth-cs.identidadedigital.pr.gov.br/centralautenticacao/api/v1/token/jwt


• Caso seja utilizado o token do tipo authorization_code, automaticamente o eProtocolo irá reconhecer o usuário logado no sistema integrado como o responsável pelas ações?

Não, o padrão das integrações é que as ações no eProtocolo ocorram com um usuário neutro, cadastrado com o nome do sistema integrado.
Para que o eProtocolo identifique o usuário logado (na Central de Segurança) no sistema integrado, é necessário obter o token do tipo authorization_code incluindo o escopo spiserv.cidadaos.tokens.validar.

• O que são anexos?

Anexos são arquivos que estão vinculados a um protocolo, porém não fazem parte do volume do processo. Podem ser planilhas, áudios, vídeos, imagens, etc.


• Qual o tamanho máximo de um anexo?

Anexos podem ter tamanho máximo de 100MB cada.

• O que são apensados?

Apensados são protocolos que tem relacionamento "pai-filho" entre eles. Ou seja, quando um protocolo é apensado a outro, significa que o protocolo apensado (filho) está relacionado ao protocolo principal (pai).
Desta forma, ao realizar ações no protocolo principal (como alterar situação, tramitar protocolo, etc), os protocolos apensados também sofrerão as mesmas ações, juntamente ao protocolo principal.


• Um protocolo apensado pode possuir também outro protocolo apensado?

Protocolos apensados não podem possuir outros protocolos apensados. Não existe no eProtocolo, relacionamento "pai-filho-neto", o relacionamento restringe-se a "pai-filho" somente.


• O protocolo principal (pai), pode pode possuir apenas um protocolo apensado (filho)?

Não há limite de protocolos apensados. Um protocolo principal pode ter diversos protocolos filhos. Importante é que estejam relacionados ao protocolo principal.

• O que significa arquivar um protocolo?

O arquivamento ocorre quando um protocolo chega ao fim do ciclo de vida, desta forma o protocolo é armazenado por um período determinado de tempo, até a sua eliminação em definitivo.


• O que são unidades de armazenamento?

Unidades de armazenamento são os códigos referentes aos locais em que os protocolos permanecem arquivados até que sejam eliminados.


• Existe limite de quantidade de protocolos arquivados por unidade de armazenamento?

Sim, cada unidade de armazenamento pode ter no máximo 900 protocolos. Caso este limite seja atingido, a unidade de armazenamento é fechada automaticamente, sendo necessária a criação de uma nova unidade.


• O que são temporalidades?

Temporalidades são códigos para arquivamento do protocolo que definem por quanto tempo o protocolo necessita permanecer arquivado antes de ser eliminado.

• Quais os tipos de assinaturas eletrônicas aceitas pelo eProtocolo?

Os serviços do eProtocolo aceitam tanto assinaturas eletrônicas qualificadas do tipo PAdES quanto assinaturas assinaturas eletrônicas qualificadas do tipo CAdES.
Obs.: Somente documentos podem ser assinados eletronicamente no eProtocolo. Os anexos não podem ser assinados.


• Qual a diferença de assinaturas eletrônicas qualificadas do tipo PAdES e assinaturas eletrônicas qualificadas do tipo CAdES?

A assinatura eletrônica qualificada do tipo PAdES (PDF Advanced Electronic Signatures), é um padrão de assinatura eletrônica especificamente projetado para documentos em formato PDF, em que a assinatura é "embutida" ao próprio arquivo PDF.
A assinatura eletrônica qualificada do tipo CAdES (CMS Advanced Electronic Signatures), é um padrão de assinatura digital baseado na estrutura de mensagens criptografadas, em que a assinatura é gravada em um arquivo externo do tipo P7S.


• Como incluir assinaturas eletrônicas qualificadas do tipo PAdES no eProtocolo via spi-servicos?

Ao atualizar um documento da "área temporária" para o volume do processo, se o documento (arquivo PDF) possuir uma assinatura do tipo PAdES realizada externamente ao eProtocolo, esta assinatura será reconhecida e suas informações serão
disponiblizadas no volume do processo e nas demais funcionalidades do eProtocolo.


• Como incluir assinaturas eletrônicas qualificadas do tipo CAdES no eProtocolo via spi-servicos?

Se um documento tiver sido assinado externamente ao eProtocolo com uma assinatura do tipo CAdES, o arquivo de assinatura externo (P7S) pode ser enviado ao eProtocolo com o serviço Incluir Assinatura Externa no Documento do Protocolo
ou com o serviço Incluir Assinatura Externa no Documento do Volume do Processo.

• Quando um serviço pode ser assíncrono?

Alguns serviços do eProtocolo podem demorar um pouco mais que o normal para concluir, de acordo com as ações que devem executar. Nestes serviços foram implementadas as requisições assíncronas.
Desta forma, os endpoints do spi-servicos que possuem na seção Query Parameters, o parâmetro assincrono, têm o seguinte comportamento:

Se parâmetro assincrono:

     Não for enviado -> serviço entrará no modo "híbrido":
          Se a requisição for concluída em até 20s, os dados serão retornados como se a requisição fosse síncrona.
          Se a requisição demorar mais de 20s, o serviço retornará o response status 202 (Accepted), no header Location será retornada a URL para consultar o status da requisição assíncrona e a execução continuará em background.

     true -> serviço assíncrono:
          O serviço sempre retornará o response status 202 (Accepted) e a execução continuará em background.

     false -> serviço síncrono
          O serviço sempre executará como síncrono, se a requisição não for concluída em até 60s, o API Gateway irá exibir o response status 504 (Gateway Timeout).


Para os serviços assíncronos e "híbridos". Se ocorrer uma exceção:

     Antes do retorno com response status 202 (Accepted):
          Será retornado o JSON com a exceção da mesma forma que ocorre nas chamadas síncronas.

     Depois do retorno 202 (Accepted), ou seja, quando a execução já está ocorrendo em background:
          A exceção poderá ser verificada depois que o status retornar TERMINATED, chamando o serviço Consultar Requisição Assíncrona.


• Quais os códigos de status um serviço assíncrono pode retornar?

Os códigos de status de execução assíncrona são:

     NEW -> Nova requisição.
     RUNNABLE -> Requisição em execução.
     TIMED_WAITING -> Execução demorou mais de 20s, aguardando a conclusão.
     TERMINATED -> Requisição concluída.

• O que são assuntos?

No eProtocolo, assuntos são códigos usados para organizar e identificar ao que está relacionado um determinado protocolo.
Obs.: Todo protocolo está vinculado obrigatoriamente a um assunto.

• Para que servem os serviços de De-Para?

Os serviços de De-Para são utilizados para realizar alterações dos códigos nas tabelas utilizadas pelo eProtocolo.


• Quais os tipos de tabelas podem ser alteradas pelos serviços de De-Para?

As tabelas que podem ser alteradas são:

     • Local
     • Espécie
     • Motivo de Tramitação
     • Assunto
     • Palavra-Chave
     • Tipo de Interessado
     • Órgão
     • Interessado
     • Temporalidade


• Quem pode realizar as alterações?

Como as alterações realizadas pelos serviços de De-Para podem impactar no funcionamento do eProtocolo, a liberação dos escopos dos serviços de De-Para deve ser previamente autorizada pela SEAP.

• O que são documentos?

Documentos são arquivos exclusivamente do tipo PDF que poderão fazer parte do volume do processo, possuindo carimbo, rodapé, página de assinaturas, etc.
Obs.: Os documentos podem ser assinados, ou já conter assinaturas do tipo PAdES realizadas externamente ao eProtocolo.


• Qual o tamanho máximo de um documento?

Documentos podem ter tamanho máximo de 30MB cada.
Obs.: Documentos com tamanho superior, devem ser enviados como anexos.


• O que significa atualizar documento para o volume do processo?

Quando o documento é enviado para o protocolo, permanece em uma "área temporária", onde pode sofrer algumas alterações como ter a ordem alterada, ser excluído e outros, até que seja enviado definitivamente ao volume do processo.
Nesta situação o documento não pode mais ser excluído, somente cancelado, assim as folhas do documento cancelado são substituídas por outra com a informação do cancelamento.

• O que são espécies?

No eProtocolo, espécies são códigos que identificam o documento relacionado com o protocolo.
Obs.: Todo protocolo está vinculado obrigatoriamente a uma espécie de documento.

• O que são funcionários?

Apesar dos serviços serem denominados de funcionários, os serviços tratam de todos os usuários do eProtocolo, inclusive os cidadãos.


• Quem pode realizar as alterações?

Como as alterações realizadas pelos serviços de Funcionários podem impactar no funcionamento do eProtocolo, a liberação dos escopos dos serviços de Funcionários deve ser previamente autorizado pela SEAP.


• Por que não consigo atribuir o grupo Sentinela a um funcionário?

Para ser possível atribuir um grupo Sentinela a um usuário, este precisa primeiramente cadastrar-se na Central de Segurança, caso contrário o grupo não será atribuído.

• O que são interessados?

Interessados são pessoas físicas ou pessoas jurídicas que tem interesse no protocolo.


• Quais os tipos de interessados?

Apesar de existir uma lista completa de tipos de interessados, recomenda-se a utilização dos tipos PES.FISICA para pessoas físicas e PES.JURIDICA para pessoas jurídicas. Os demais tipos de interessados serão suprimidos futuramente.


• O que são autoridades?

Autoridades são interessados que possuem mandato político, tais como vereadores, prefeitos, deputados, governadores, etc.

• O que são locais?

Locais são subdivisões de um órgão, o mesmo que um setor interno de um órgão.


• É possível existir um local de mesmo nome em um órgão diferente?

Não é possível. O código de local é único para o eProtocolo. Recomenda-se a criação do nome do local com parte do órgão para diferenciação.

• O que são localidades do processo?

Localidades são os países, estados e municípios cadastrados no eProtocolo que estão disponíveis para a criação de novos protocolos.

• Para que serve o serviço de monitoramento?

Este serviço realiza algumas validações para conferir se os serviços do eProtocolo estão em funcionamento normal, tais como a verificação se os bancos de dados (principal e de segurança de acesso),
o acesso ao NAS e o acesso ao API Gateway estão acessíveis.

• O que são movimentações do processo?

Movimentações trazem as informações de tramitações, inclusões de documentos, cancelamento de documentos, alteração de sigilo, transformação de protocolo físico em digital, etc.

• O que são órgãos?

Órgãos são as instituições do Estado, tais como as secretarias do Estado, empresas públicas, universidades públicas, etc.


• É possível existir mais de um órgão relacionada a mesma instituição?

Sim, para melhor organização, é possível dividir a mesma instituição em órgãos diferentes, como por exemplo: ADAPAR/CURI, ADAPAR/GUAR e ADAPAR/LOND.
Obs.: Neste caso, estes órgãos são agrupados em um órgão pai, no exemplo acima: ADAPAR.

• O que são palavras-chaves?

No eProtocolo, as palavras-chaves são códigos usados para refinar a organização de determinado protocolo. As palavras-chaves são subtipos do assunto do protocolo.
Obs.: Todo protocolo está vinculado obrigatoriamente a uma palavra-chave, de um determinado assunto. O protocolo pode estar vinculado também a uma palavra-chave secundária, embora esta vinculação não é obrigatória.

• O que são pendências do protocolo?

As pendências são tarefas que determinado usuário deve executar no protocolo. A existência de pendências pode impedir ações no protocolo, até a sua conclusão.


• Quais os tipos de pendências podem ser incluídas no eProtocolo via serviços?

As tabelas que podem ser alteradas são:

     • Assinatura
     • Citar/Intimar
     • Dar Ciência
     • Notificar
     • Parecer
     • Prenotar
     • Prorrogação de Prazo
     • Solicitar mais informações

• Como criar um protocolo?

Para criar um protocolo são necessários 3 passos:


     Incluir um protocolo em pré-cadastro

     Chamar o serviço Incluir Protocolo, enviando os dados necessários.


     Enviar documentos ao protocolo

     Chamar o serviço Incluir Documento no Protocolo, enviando o arquivo PDF. O serviço pode ser chamado diversas vezes (uma vez para cada documento).
     Obs.: Esse passo não é necessário para protocolos físicos.


     Concluir cadastro do protocolo

     Chamar o serviço Concluir Cadastro do Protocolo. O serviço irá atualizar os documentos da "área temporária" para o volume do processo, alterar o protocolo de pré-cadastro para normal e tramitará o protocolo para o local definido na criação do protocolo em pré-cadastro.



• O que significa protocolo em pré-cadastro?

Quando o protocolo ainda está sendo organizado, ainda estão sendo definidos os detalhes, incluídos os documentos, etc. Mas o protocolo ainda não está pronto para ser tramitado, ou ter o volume do processo consultado por outrem.


• Qual a diferença entre protocolo físico e digital?

Protocolos físicos possuem cadastro do protocolo da mesma forma que o protocolo digital, porém o volume do processo não é um arquivo PDF como no caso dos protocolos digitais e sim uma pasta com as folhas impressas, que tem a tramitação via malote.
Obs.: A criação de protocolos físicos é desencorajada.


• O que significa receber protocolo no local ou no órgão?

Como os protocolos físicos são tramitados por malote, não há como o sistema saber em que local estão fisicamente. Então após a tramitação do protocolo via sistema, ao chegar fisicamente no local ou órgão de destino, o protocolo deve ser "recebido",
para que o sistema tenha a informação atualizada de onde está fisicamente.


• O que significa sobrestar protocolo?

Sobrestar protocolo é utilizado para paralisar o protocolo, para aguardar alguma ação externa. Esta funcionalidade pode ocultar o protocolo das pendências do usuário, caso necessário.


• Por que os serviços de listagem de protocolos não estão retornando os protocolos?

Os serviços de listagem de protocolos:

     • Listar Protocolos
     • Listar Protocolos por Assunto
     • Listar Protocolos do Local
     • Listar Protocolos do Órgão
     • Listar Protocolos por Motivo de Tramitação

Somente retornam informações se o usuário que está consumindo os serviços estiver vinculado ao órgão que está sendo consultado.

• O que é tramitação de um protocolo?

Tramitação de um protocolo ocorre quando o protocolo é encaminhado de um local para outro. A tramitação pode ocorrer em locais do mesmo órgão ou para um local de órgão diferente.


• O que são motivos de tramitação?

Motivo de tramitação é um código que identifica a razão pela qual o protocolo está sendo tramitado para determinado local.


• O que significa protocolo em trânsito?

Quando o protocolo físico é tramitado para um determinado local, o sistema não tem como saber em que local o protocolo se encontra. Desta forma, tem-se a informação de que o protocolo físico deixou um determinado local e está sendo enviado via malote (está em trânsito para outro local).
Esta situação se mantém até que o protocolo seja recebido no órgão ou no local, informando ao sistema que o protocolo não está mais em trânsito.


• O que significa bloquear tramitação no eProtocolo?

Quando a tramitação do protocolo é bloqueado no eProtocolo, significa que o protocolo não poderá ser tramitado no Sistema eProtocolo. A tramitação só poderá ser realizada via sistema integrado a partir do spi-servicos.

• O que é volume do processo?

Volume do processo é um arquivo PDF que contém todos os documentos atualizados no volume após terem sido enviados na "área temporária" do protocolo.
O volume possui capa com numeração e informações sobre o protocolo, carimbo com a numeração de documentos e folhas, rodapé com informações de inclusão e cancelamento, página de assinaturas, etc.


• O que significa reprocessar o volume do processo?

Em algumas situações pode ser necessário recriar o volume do processo, caso o volume do processo esteja corrompido, por exemplo. Desta forma, deve ser utilizado o serviço Reprocessar Volume do Processo.

• Quais as URLs dos servidores do aplicação do eProtocolo (spiweb)?

     desenv -> https://wfly18des01.seap.parana/spiweb
     homolog -> https://homologacao.eprotocolo.pr.gov.br/spiweb
     treinamento -> https://treinamento.eprotocolo.pr.gov.br/spiweb
     prod -> https://www.eprotocolo.pr.gov.br/spiweb


• Quais as URLs dos servidores do webservice do eProtocolo (spi-servicos)?

     desenv -> https://wfly26des01.seap.parana/spi-servicos
     homolog -> https://homologacao.api.eprotocolo.pr.gov.br/spi-servicos
     treinamento -> https://treinamento.api.eprotocolo.pr.gov.br/spi-servicos
     prod -> https://api.eprotocolo.seap.parana/spi-servicos


• É possível acessar os serviços diretamente, sem passar pelo API Gateway?

Não. Todo acesso deve ocorrer a partir das URLs do API Gateway, não sendo permitido o acesso de forma direta.


• É possível baixar o código dos exemplos?

Sim. Na documentação, ao clicar no ícone do Postman (ao lado do título do grupo), é possível baixar a collection referente ao grupo de serviços.
No Postman é possível gerar o código de cada endpoint, em diversas linguagens diferentes.


• É possível verificar se o token enviado está válido, se possui os escopos necessários ou se é do tipo client_credentials ou authorization_code?
Sim. Ao enviar o token para a URL https://jwt.io, é possível conferir estas informações.

• Mensagens de erros mais comuns

     No API key found in request -> Não foi enviado o header consumerId.
     Please use HTTPS protocol -> A requisição está ocorrendo sem HTTPS.
     Invalid authentication credentials -> O header consumerId é inválido.
     No Route matched with those values -> A URL está errada.
     Too Many Requests -> A quantidade de requisições simultâneas excedeu o limite.
     You cannot consume this service -> O consumerId não está vinculado no API Gateway.
     The upstream server is timing out -> O tempo de espera da requisição excedeu o limite.
     IP [...], consumerId [...], Authorization e/ou clientId [...] sem permissão para acessar [...]. Contate analista responsável pelo spi-servicos. -> IP ou consumerId ou Authorization ou clientId não autorizado(s).
     Token não autorizado pela Central de Segurança. -> Token fora do prazo de validade ou sem o escopo relacionado à chamada ou de ambiente diferente do chamado.
     Parâmetro 'consumerId' não informado. -> O consumerId não foi enviado no header da chamada.
     Parâmetro 'Authorization' não informado. -> O token no formato JWT não foi enviado no header da chamada.
     Acesso negado a esta versão do serviço. Acesse versão superior. -> A integração não está autorizada a consumir serviços de versão anterior. Deve ser chamada a versão mais recente.
     Acesso negado a esta URL. Verifique se acesso HTTP ou HTTPS. -> A requisição está ocorrendo com protocolo não autorizado (HTTP ou HTTPS).
     Acesso negado a esta URL. Verifique se URL interna ou externa. -> A requisição está a partir da rota não autorizada (Internet ou intranet).
     Acesso ao spi-servicos deve ocorrer a partir do API Gateway. -> O acesso ao webservice do eProtocolo está ocorrendo sem passar pelo API Gateway.
     Acesso aos serviços fora do período permitido. -> O acesso está ocorrendo fora dos dias/horários autorizados para a integração.