Receção de documentos

Âmbito

Esta funcionalidade permite a entrada automática de documentos de faturação no ERP do recetor, simplificando a integração nos sistemas contabilísticos. Também possibilita comunicar ao emissor os estados de aceitação e integração do documento (pago, aceite, recusado, etc.).

Neste fluxo de integração, devem ser implementados os seguintes pontos:

• Leitura e processamento de dados: Extrair a informação do XML ou de outros dados estruturados do documento para registar corretamente no ERP
• Comunicação do estado de integração: Informar o ilink sobre o resultado do processo de integração do documento
• Gestão do estado de aceitação: Comunicar o estado de aceitação do documento, incluindo mensagens detalhadas em caso de erro ou rejeição

Métodos de receção

Permite consultar e integrar documentos no sistema. A receção pode ser feita de duas formas: Consulta manual de documentos ou Webhook de receção.

Consulta manual de documentos

Neste modo, é necessário aceder ao endpoint GET /apps/documents. É possível indicar parâmetros de pesquisa para filtrar os resultados. A resposta inclui os dados principais dos documentos e informação de paginação através das propriedades rows (número de elementos por página) e page (número da página).

Para consultar os detalhes de um documento e aceder aos ficheiros XML e PDF, deve ser usado o método GET /apps/documents/{id}, recorrendo a um dos ids obtidos na listagem anterior.

O endpoint pode ser chamado periodicamente (processo em segundo plano) ou por ação de um utilizador no sistema (em tempo real).

Nota: A chave pública aqui usada corresponde à entidade recetora dos documentos. Deve ser utilizada a chave que identifica quem acede aos documentos recebidos.

Importante: O uso excessivo deste endpoint deve ser evitado. Chamadas em demasia podem originar timeouts ou restrições de acesso, de acordo com o acordo de interoperabilidade.

Webhook de receção (recomendado)

Neste modo, o ilink notifica o ERP sempre que chega um novo documento, dispensando consultas frequentes ao endpoint GET /apps/documents. Para mais informação, ver a secção Webhooks.

Nota: São enviados os dados dos documentos num formato estruturado, incluindo URLs públicos para acesso aos ficheiros XML e PDF.

Importação e aceitação

Após consultar o documento, o ERP deve comunicar ao ilink o estado de processamento, ou seja, se foi integrado com sucesso ou se necessita de correções. São necessários 2 passos:

• 1. Comunicar o estado do documento

  • Feito com POST /apps/documents/{id}/accepted, indicando se o documento foi aceite ou não e, em caso de rejeição, o motivo
  • É obrigatório indicar o motivo de rejeição se o documento não for aceite
  • Um documento rejeitado pode ser reenviado pelo emissor com os dados corrigidos

• 2. Comunicar a importação do documento (apenas se aceite)

  • Se o passo anterior indicar aceitação, deve ser chamado o método POST /apps/documents/{id}

Nota: Documentos rejeitados não devem ser importados.

A comunicação correta de documentos aceites/importados garante histórico de auditoria e facilita o consumo da API. Se estiver a ser usada a consulta manual, documentos já rejeitados ou importados não voltam a ser devolvidos em chamadas futuras. Ou seja, o endpoint GET /apps/documents não devolve documentos previamente rejeitados ou importados.

A imagem abaixo mostra como as operações feitas pelo ERP ficam registadas no portal do ilink:

O uso correto da importação de documentos gera também uma informação consultável para o fornecedor do documento, ficando confirmada a sua integração com o sistema do recetor.

Estados de Processo (opcional)

Nota: Funcionalidade opcional e apenas informativa. Não interfere com a receção de documentos.

O ilink permite criar estados de documento personalizados. Quando ativa, é possível consultar e modificar o estado de um documento via API. Esta capacidade permite que sistemas externos (ex.: gestão documental) alterem o estado processual de forma integrada, e é útil para sincronizar processos internos da organização entre sistemas. Todas as alterações de estado de processo ficam registadas no histórico do documento.

Importante: O estado de processo é independente do estado base (recebido, aceite, etc.). Serve apenas para organização interna e registo de operações.

Para consultar os estados disponíveis, use GET /apps/processstates, que devolve a lista completa com respetivo identification_code. Para alterar o estado de um documento, use PUT /apps/documents/{id}/processstates, indicando o novo identification_code.

A configuração dos estados de processo a usar é feita pela equipa de apoio do ilink.