Manuais
Comunicação de Documentos de Faturação com a eSPap via Webservice

Passa a ser possível comunicar documentos de faturação (Faturas, Notas de Crédito e Notas de Débito) com a eSPap através de Webservice no PHC CS Desktop.

1) O que há de novo:
3 parâmetros:
- Webservice Comunicação de Documentos de Faturação (UBL eSPap): Username
- Webservice Comunicação de Documentos de Faturação (UBL eSPap): Password
- Webservice Comunicação de Documentos de Faturação (UBL eSPap): URL
Nota: por defeito o parâmetro URL já está preenchido.

Monitor de Comunicação de Documentos eSPap:
Disponível a partir do menu Supervisor ou do ícone no documento de faturação
- Permite comunicar documentos que ainda não tenham sido enviados;
- Permite obter os estados dos documentos já comunicados.



Novas opções no ecrã de Faturação:
Nas Opções Diversas:
1 - Resultado da comunicação via webservice à eSPap - permite visualizar o histórico de comunicações/atualizações de estado do documento;
2 - Atualizar o estado do documento eSPap - permite obter o estado da comunicação do documento - apenas disponível quando o documento já foi comunicado;
3 - Dar documento como finalizado manualmente na eSPap - significa que este documento é fechado manualmente sem ter que aguardar atualizações por parte da eSPap. Após clicar nesta opção, não é possível que este documento entre novamente no circuito da eSPap. No Monitor de Comunicação de Documentos eSPap irá ser apresentada a informação "Fechado manualmente".



No botão Doc. Eletrónicos:
Foram adicionadas as seguintes opções para a comunicação manual:
- Produzir e enviar o documento eletrónico referente a este documento de faturação via webservice à eSPap;
- Produzir o documento eletrónico, enviá-lo via webservice à eSPap e guardá-lo como anexo.



Novas opções no ecrã "Emissão Automática de Documentos Eletrónicos"
Foram adicionadas as seguintes opções:
- Produzir e enviar os documentos eletrónicos via webservice à eSPap;
- Produzir os documentos eletrónicos, enviá-los via webservice à eSPap e guardá-los como anexo.

Novo campo no ecrã de Clientes:
- "Cliente registado como fornecedor no âmbito da eSPap" (separador "Dados financeiros") -> a comunicação apenas é possível para clientes que tenham esta opção ativa.


2) Apenas é possível efetuar a comunicação se estiverem reunidas as seguintes condições:
Requisitos de Sistema
- PHC On ativo;
- Módulo PCS Assinaturas Qualificadas desktop e PHC CS Documentos Eletrónicos;
- Parâmetro geral "Utiliza Documento Eletrónico" ativo;
- Apenas na geografia de Portugal;
- Gamas Advanced ou Enterprise;
- Conter assinaturas qualificadas com a Digital Sign (parceria atual).

Configurações na série de faturação:
- Ter a opção "Inclui Formato XML UBL 2.1" ativo;
- Ter a opção "Versão do Formato XML UBL 2.1" com o valor "CIUS-PT 2.1" (2);
- Ter a opção "Documento para assinar digitalmente" com o valor "Documento XML" (1);
- Ter a opção "Tipo de Certificado a assinar digitalmente" com o valor "Certificado Digital Sign";
- Opcional: configurar a opção "Ao gravar comunica a fatura à eSPap" com o valor "Sim" ou "Sim e anexa"
Notas:
- o valor "Sim e anexa" só está disponível com o módulo PHC CS Documentos;
- por defeito o valor desta opção é "Não", isto significa que os documentos apenas são comunicados quando o utilizados os comunicar manualmente.


3 - Cenários possíveis no ecrã "Faturação a Clientes"
Passamos a ter um ícone que representa a comunicação com a eSPap, este é composto por cores que correspondem ao estado da comunicação, a definição destas cores encontra-se dentro do Monitor de Comunicação de Documentos com a eSPap.

  • Se a série estiver configurada para comunicar ao gravar e com todos os pré-requisitos do ponto anterior passa a ser possível comunicar o documento à eSPap;



  •  
  •  

Ao gravar é apresentado o texto "A comunicar documento à eSPap..."
a) Se a comunicação foi efetuada com sucesso então será apresentada a mensagem "Foi produzido e enviado o Documento de Faturação «XPTO,nº1 de 23.11.2021». Consulte o resultado da comunicação nas Opções Diversas deste documento."
b) Se a comunicação não foi efetuada com sucesso, então será apresentada a mensagem "Ocorreu um erro ao produzir e enviar o documento de faturação «XPTO,nº1 de 23.11.2021». Consulte o resultado da comunicação nas Opções Diversas deste documento."

- Após um documento ser comunicado à eSPap passa a ficar com o estado "Comunicado". Posteriormente, passam a estar disponíveis as seguintes opções diversas do documento:
1 - Resultado da comunicação via webservice à eSPap
2 - Atualizar o estado do documento eSPap
3 - Dar documento como finalizado manualmente na eSPap

- Se o documento estiver num estado final, as seguintes opções diversas deixam de estar disponíveis:
2 - Atualizar o estado do documento eSPap
3 - Dar documento como finalizado manualmente na eSPap

- Na grelha da opção diversa "Resultado da comunicação via webservice à eSPap" são apresentados 4 campos (Estado; Descrição; Data e Hora)
a) Só é adicionado um novo registo ao resultado da comunicação se o estado obtido da eSPap for diferente ao estado atual do documento no PHC;
b) Se o estado for igual, apenas atualiza os dados referentes à DATA e HORA do estado atual (o último estado obtido no resultado da comunicação);
c) Na descrição do estado "Comunicado" é adicionado o RequestID do documento que pode ser pedido pela eSPap ao cliente para verificar algum problema com o documento ou esclarecer alguma dúvida ao cliente;
d) Na descrição de cada estado obtido (sem contar com o estado "Comunicado") é adicionado no final o código original do estado da eSPap dentro de parêntesis;
e) No caso de ocorrer algum erro de comunicação com o servidor da eSPap ou algum erro de configuração, se já existir um estado para o documento então esse estado mantém-se mas é adicionada uma das seguintes descrições no resultado da comunicação:
1 - Falha ao comunicar com o servidor da eSPap. Por favor, tente mais tarde comunicar através do menu Supervisor > opção Monitor de Comunicação de Documentos eSPap.
2 - Não foi possível produzir o documento XML CIUS-PT.
3 - Ocorreu um erro ao tentar assinar o documento XML CIUS-PT. Verifique se configurou corretamente os parâmetros para o Certificado Digital.
4 - Ocorreu um erro ao tentar assinar o documento XML CIUS-PT. (+Erro específico)
 

  • Se a série estiver configurada para não comunicar ao gravar e com todos os pré-requisitos do ponto anterior passa a ser possível comunicar o documento à eSPap através do botão Doc. Eletrónicos;



  •  
  •  

- estas opções só aparecem visíveis se o documento de faturação ainda não foi comunicado ou se foi comunicado mas obteve posteriormente o estado "Validação com erros" que indica ao utilizador para corrigir o erro e voltar a enviar;
- a opção "Produzir o documento eletrónico, enviá-lo via webservice à eSPap e guardá-lo como anexo" só aparece disponível com o módulo Documentos;
- ao clicar em executar selecionando uma destas opções será apresentada a mensagem "A comunicar documento à eSPap...";
a) Se a comunicação foi efetuada com sucesso então será apresentada a mensagem "Foi produzido e enviado o Documento de Faturação «XPTO,nº1 de 23.11.2021». Consulte o resultado da comunicação nas Opções Diversas deste documento."
b) Se a comunicação não foi efetuada com sucesso, então será apresentada a mensagem "Ocorreu um erro ao produzir e enviar o documento de faturação «XPTO,nº1 de 23.11.2021». Consulte o resultado da comunicação nas Opções Diversas deste documento."
- Ao clicar em executar para a opção "Produzir o documento eletrónico, enviá-lo via webservice à eSPap e guardá-lo como anexo" no final da comunicação, o documento XML será anexado ao documento de faturação.
Notas:
- é necessário configurar a série de faturação para ter anexos (menu Tabelas > Documentos > Tabelas que têm anexos);
- é necessário configurar a pasta para onde o anexo será guardado no PHC (menu Tabelas > Documentos > Pasta de anexos);
- na configuração da série deve ser definida a pasta para onde o anexo será guardado no PHC;
- no final da comunicação o ecrã "Documento Eletrónico" é fechado e voltamos para o ecrã de faturação.


4 - Estados dos documentos
1 - Comunicado > Documento comunicado à eSPap.
2 - Validado com sucesso > Validação com sucesso no controlo de qualidade.
3 - Validação com erros > Validação com erro no controlo de qualidade - Reenvie o documento corrigido.
4 - Rececionado > Documento foi rececionado com sucesso no portal FE-AP do cliente.
5 - Processado > Documento de faturação eletrónica processado.
6 - Aguarda Regularização > Solicitação de um documento de regularização - Envio de nota de débito ou crédito para regularizar.
7 - Aceitação de NC > Nota de crédito aceite pelo cliente. Constitui prova que o adquirente tomou conhecimento da retificação nos termos no n.º5.
8 - Emissão de pagamento > Documento de faturação eletrónica colocado a pagamento.
9 - Devolvido > Enviar novo documento em conformidade com o serviço/produto prestado.
10- Fechado manualmente > Documento finalizado manualmente.




5 - Alterações no ecrã "Emissão Automática de Documentos Eletrónicos"
Foram adicionadas as seguintes opções:
- Produzir e enviar os documentos eletrónicos via webservice à eSPap
- Produzir os documentos eletrónicos, enviá-los via webservice à eSPap e guardá-los como anexo

Notas:
- estas opções aparecem visíveis mas não selecionáveis se os requisitos se encontrarem válidos;
- ao selecionar uma série que cumpra os requisitos, referentes à série de documentos de faturação então as opções passam a estar selecionáveis;
- a opção "Produzir os documentos eletrónicos, enviá-los via webservice à eSPap e guardá-los como anexo" só aparece disponível com o módulo Documentos;
- se o processo for concluído com sucesso então é apresentada a mensagem "Os documentos eletrónicos foram enviados e produzidos corretamente."
- se existirem validações/erros ao produzir e enviar os documentos então é apresentada a informação sobre os motivos, como os seguintes exemplos:
a) Não foi produzido nem comunicado o documento eletrónico referente ao documento de faturação «XPTO, nº 1 de 23.11.2021» porque o cliente não é um cliente que comunica com a eSPap.
b) Não foi produzido nem comunicado o documento eletrónico referente ao documento de faturação «XPTO, nº 1 de 23.11.2021» porque o documento já foi comunicado à eSPap.
c) Ocorreu um erro ao produzir e enviar o documento de faturação «XPTO, nº 1 de 23.11.2021».
Código do Erro: XYZ
Descrição do erro: XPTO

- se o documento eletrónico foi produzido corretamente então é apresentada a mensagem "Foram produzidos X documentos eletrónicos corretamente."


6 - Funcionamento do Monitor de Comunicação de Documentos eSPap
(menu Supervisor)
No monitor é possível visualizar todos os documentos de faturação já comunicados ou ainda por comunicar.
- Permite efetuar diferentes tipos de filtros aos documentos de faturação apresentados;
- Permite só visualizar os documentos que não estejam num estado final;
- Permite imprimir ou pré-visualizar uma listagem de documentos de faturação;
- Permite a comunicação de vários documentos via webservice à eSPap;
- Permite atualizar o estado de vários documentos;
- Permite fechar manualmente um documento de faturação.

- Sempre que uma opção de filtro é alterada, é apresentada a pergunta "Tem a certeza que pretende atualizar a informação referente aos documentos de faturação?" com a nota "Vai atualizar a informação sem emitir e perder o que já está marcado!";

- Ao clicar em "Atualizar estado" sem ter nenhum documento selecionado é apresentada a mensagem "Desculpe, mas não existem Documentos de Faturação marcados para atualizar o estado do documento.";

- Ao clicar em "Atualizar estado" já com documentos selecionados é apresentada uma barra de carregamento até o processo terminar.
No fim do processo é apresentada uma lista (browlist) com o resultado da comunicação. As mensagens que podem ser apresentadas nessa lista são:
1- Não foi possível atualizar o estado do Documento de Faturação «XPTO, nº3 de 24.11.2021» porque ainda não foi comunicado à eSPap.
2- Não foi possível atualizar o estado do Documento de Faturação «XPTO, nº3 de 24.11.2021» porque já se encontra num estado final.
3- Ocorreu um erro ao atualizar o estado do documento de faturação «XPTO, nº3 de 23.11.2021».
Código do Erro: XYZ
Descrição do erro: XPTO

- Quando o estado do documento é atualizado com sucesso é apresentada a mensagem:
"Foi atualizado o estado do Documento de Faturação «XPTO, nº3 de 23.11.2021».
Estado atual: XYZ"

- Quando o estado é atualizado para "Validação com erros" é apresentada a mensagem:
"Foi atualizado o estado do Documento de Faturação «XPTO, nº3 de 23.11.2021».
Estado: XYZ
Descrição: XPTO"

- Ao clicar em "Enviar" sem ter nenhum documento selecionado é apresentada a mensagem "Desculpe, mas não existem Documentos de Faturação marcados para comunicar via webservice à eSPap.";

- Ao clicar em "Enviar" já com documentos selecionados é apresentada uma barra de carregamento até o processo terminar.
No fim do processo é apresentada uma lista (browlist) com o resultado da comunicação.

- Ao clicar no ícone eSPap, abre o ecrã de faturação e o resultado da comunicação do respetivo documento de faturação;
- Ao clicar no ícone do cadeado aberto, é apresentada a mensagem "Tem a certeza que pretende fechar manualmente o documento de faturação?" com a nota "Vai atualizar a informação referente ao estado do documento!":
a) Se sim, atualiza o estado do documento para "Fechado manualmente" e altera o ícone eSPap;
b) Se não, não faz nada.

- Com duplo-clique nos campos das colunas referentes ao documento de faturação é aberto o ecrã de faturação em modo de consulta do respetivo documentos;
- Com duplo-clique nos campos das colunas referentes ao cliente é aberto o ecrã de clientes em modo de consulta na respetiva ficha do cliente;
- Ao clicar no botão "i" junto à grelha é aberto um ecrã com informações sobre o monitor.

Notas:
- o botão do cadeado só é possível clicar quando o cadeado está aberto que é quando o documento já foi comunicado. Se o documento ainda não foi comunicado, o botão do cadeado não aparece visível. Também não é possível clicar no botão do cadeado quando o documento já está num estado final. (Emissão de pagamento, Devolvido ou Fechado manualmente).

7 - Função de Utilizador «u_comunica_espap()»
Passa a existir a função de utilizador «u_comunica_espap()» que permite validar a comunicação/atualização de estados dos documentos de faturação via alerta.
(Apenas disponível na gama Enterprise)

A função é composta pelos seguintes parâmetros:
- Opção »» É do tipo Caracter. Define a ação a executar. Aceita o valor "COMUNICAR" ou "ATUALIZAR".
- DataInicial »» É do tipo Data. Define a data inicial dos documentos de faturação.
- DataFinal »» É do tipo Data. Define a data final dos documentos de faturação.
- Silent »» É do tipo Lógico. Define se são apresentados os resultados das validações (Falso - .f.), ou não (Verdadeiro - .t.).

Validações para o implementador:
1. Validar o exe de Portugal.
Mensagem: "Desculpe, mas esta função apenas se encontra disponível em Portugal."

2. Validar a gama.
Mensagem: "Desculpe, mas esta função apenas se encontra disponível na gama Enterprise."

3. Validar se tem as configurações necessárias para utilizar a funcionalidade.
Mensagem: "Desculpe, mas não tem as configurações necessárias para utilizar esta funcionalidade."

4. Validar os parâmetros das datas como obrigatórios.
Mensagem: "Os parâmetros Data Inicial e Data Final são de preenchimento obrigatório. (2º e 3º parâmetros)"

5. Validar o tipo de dados do parâmetro Opção.
Mensagem: "O parâmetro Opção tem que ser do tipo Caracter. (1º parâmetro)"


Validações para o utilizador:
1. Caso não existam documentos de faturação para comunicar ou atualizar estado.
Mensagem: "Não foram encontrados documentos de faturação para comunicar ou atualizar estados."

2. Caso no parâmetro Opção seja passado o valor "COMUNICAR" mas dentro dos documentos existentes não existir nenhum documento por comunicar.
Mensagem: "Não foram encontrados documentos de faturação para comunicar."

3. Caso no parâmetro Opção seja passado o valor "ATUALIZAR" mas dentro dos documentos existentes não existir nenhum documento que já tenha sido comunicado (preparado para atualizar estado).
Mensagem: "Não foram encontrados documentos de faturação para atualizar estado."

4. Caso no parâmetro Opção seja passado um valor diferente de "COMUNICAR" ou "ATUALIZAR".
Mensagem: "O parâmetro Opção só aceita um dos seguintes valores: ´ATUALIZAR´ ou ´COMUNICAR´."

5. Caso não seja possível comunicar com o servidor da eSPap.
Mensagem: "Falha ao comunicar com o servidor eSPap. Por favor, volte a tentar mais tarde."

6. Case sejam encontrados documentos para comunicar ou atualizar estados é apresentada uma barra de carregamento (loading) que indica o tempo que demora o processo até terminar e os documentos que está a tratar em tempo real. O título dessa barra de loading é:
- Caso o parâmetro Opção esteja vazio: A enviar e atualizar estados dos Documentos de Faturação...
- Caso no parâmetro Opção estiver "COMUNICAR": A enviar os Documentos de Faturação...
- Caso no parâmetro Opção estiver "ATUALIZAR": Atualizar estados dos Documentos de Faturação...

7. No fim do processo é apresentada uma lista (browlist) com o resultado da comunicação. As mensagens que podem ser apresentadas nessa lista são:
a) Ocorreu um erro ao produzir e enviar o documento de faturação «XPTO, nº3 de 23.11.2021».
Código do Erro: XYZ
Descrição do erro: XPTO

b) Foi produzido e enviado o Documento de Faturação «XPTO, nº3 de 23.11.2021».

c) Ocorreu um erro ao atualizar o estado do documento de faturação «XPTO, nº3 de 23.11.2021».
Código do Erro: XYZ
Descrição do erro: XPTO

- Quando o estado do documento é atualizado com sucesso é apresentada a mensagem:
a) Foi atualizado o estado do Documento de Faturação «XPTO, nº3 de 23.11.2021».
Estado atual: XYZ

- Quando o estado é atualizado para "Validação com erros" é apresentada a mensagem:
Foi atualizado o estado do Documento de Faturação «XPTO, nº3 de 23.11.2021».
Estado: XYZ
Descrição: XPTO

Notas:
- se o parâmetro Opção for passado a vazio, então será executada a comunicação e atualização dos estados dos documentos (as duas ações);
- na lista (browlist) é possível navegar para o documento de faturação através do botão da coluna "Ver";

Exemplo de utilização:
Comunicar e atualizar os estados dos documentos de faturação dos últimos 3 dias:
«u_comunica_espap("",date()-3,date())»

 

Funcionalidade disponível a partir da versão 31 do PHC CS Desktop.