Emissão de documentos

Âmbito

A plataforma ilink permite aos sistemas integradores emitir documentos que são automaticamente enviados aos respetivos destinatários. O ilink gere todo o processo de envio para os ERPs e EDIs configurados para cada cliente, tornando este processo transparente para o API. Estas configurações são realizadas pela equipa de apoio do ilink antes da entrada em produção.

A plataforma ilink suporta o envio de faturas eletrónicas em 2 cenários distintos:

• Envio de PDF assinado via e-mail para consumidores finais ou empresas privadas
  • Neste cenário, não é necessário criar ligações com outros EDIs. Basta indicar no endpoint de criação de documento o(s) endereço(s) de e-mail de destino. Para mais informações, consulte a secção Métodos de envio.
• Envio de XML CIUS-PT para entidades públicas (obrigatório nos contratos públicos)
  • Neste cenário, é necessário configurar previamente as ligações entre NIFs e, possivelmente, entre outros brokers EDI externos.

Como são enviados os documentos para outros brokers EDI? Durante a fase de passagem a produção, deve ser feito um levantamento de todas as entidades que irão receber documentos via EDI, bem como os respetivos brokers EDI. Posteriormente, a equipa de apoio (apoio@ilink.pt) configurará as ligações necessárias para que os documentos sejam automaticamente integrados no sistema de cada recetor. Antes de enviar documentos para a solução FE-AP da eSPap, é também necessário que cada emissor complete o processo de adesão de fornecedores FE-AP.

Todos os documentos emitidos ficam disponíveis no portal do ilink, tanto para a entidade emissora como para a entidade recetora.

Nota: No ambiente de testes, deve emitir documentos apenas entre as 2 entidades que receberam acessos. Caso pretenda verificar o funcionamento do envio de documentos para um consumidor final (NIF arbitrário), deve sempre emitir o documento através de uma das entidades que receberam acessos.

IMPORTANTE: Para o envio de documentos a entidades públicas, recomendamos vivamente a implementação dos seguintes aspetos, sob pena de não conseguir integrar os documentos com determinados sistemas:

• Número de compromisso
• Ficheiro PDF original da fatura
• Número de encomenda ou requisição (se aplicável)
• Capital Social do fornecedor
• Endereço de e-mail do cliente (apenas para as secretarias do Governo Regional da Madeira)
• Todos os dados da morada do fornecedor (rua, código postal, cidade, etc.)
• GLN do cliente (se aplicável)
• Possibilidade de reenvio do documento mediante o estado obtido (útil para corrigir e reenviar um documento previamente rejeitado)

Assinatura digital

O ilink permite assinar automaticamente os anexos dos documentos emitidos (XML e PDF), desde que a entidade emissora tenha adquirido e configurado um selo de um dos provedores de assinaturas digitais qualificadas. Atualmente, apenas o GTS - Global Trusted Sign é suportado, mas existem planos para suportar os restantes provedores em Portugal.

Isto significa que o ERP não é obrigado a integrar com um provedor de assinaturas, podendo delegar (opcionalmente) o processo de certificação ao ilink. A alternativa será o próprio ERP efetuar o processo de certificação e enviar os documentos já assinados para o ilink.

Nota: No cenário de assinatura via ilink, por defeito, todos os ficheiros resultantes são assinados no momento de entrada (xml e pdf), sendo posteriormente enviados ao cliente. Este comportamento pode ser alterado, permitindo definir que ficheiros são assinados. Para mais informações, consulte a seção sobre o consumo de assinaturas.

No caso de assinatura via ERP, a assinatura digital do documento é sempre validada criptograficamente para todos os documentos que entram no sistema. Um documento com assinatura inválida, tanto no XML como no PDF, não integrará e retornará sempre um erro via API como o seguinte:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "document": {
      "code": "e217",
      "msg": "A assinatura do documento não é válida."
    }
  }
}

O erro anterior indica que o documento sofreu alterações desde o momento da assinatura, ou que a assinatura foi gerada incorretamente. O seguinte validador pode ser utilizado para verificar a validade da assinatura dos documentos. Os formatos de assinatura reconhecidos pelo ilink são PADES e PKCS7-B (PDF), ou XMLDSig e XADES-BES (XML).

Nota: Os requisitos legais de assinatura das faturas eletrónicas estão disponíveis no Decreto-Lei 28/2019, secção II, artigo 12º.

Nota: O ilink assina os documentos PDF em PADES e os documentos XML em XADES-BES enveloped.

Métodos de envio

Após efetuada a autenticação com sucesso, estamos em condições de começar a enviar documentos. O API do ilink disponibiliza duas abordagens para o envio de documentos:

Envio do XML em formato UBL 2.1 CIUS-PT (ou UBL 2.1 PEPPOLBIS3 - Encomendas)

Neste método, o sistema integrador deve gerar corretamente o ficheiro XML antes de enviá-lo para o ilink. A eSPap disponibiliza a especificação técnica do formato CIUS-PT aqui.

Todos os ficheiros XML enviados por este método são validados de acordo com o validador oficial da eSPap, versão 2.1.2, e o API retornará um erro caso se verifiquem inconsistências sintáticas. A eSPap disponibiliza um validador Schematron que implementa todas as validações da Norma Europeia EN16931 CIUS e as validações adicionais do CIUS-PT, estando disponível online neste link. Se os ficheiros validam sintaticamente no validador online, então deverão validar no ilink, com exceção das validações adicionais definidas pelo destinatário do documento.

Nota: Para incluir um ficheiro PDF na fatura eletrónica e consultar outros casos de uso, consulte a secção casos de uso.

Nota: A eSPap também disponibiliza vários exemplos do CIUS-PT.

Alguns exemplos de erros no processo de validação XML:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "document": {
      "code": "e217",
      "msg": "[BR-CO-25]-Caso o valor a pagar (BT-115) seja positivo, deve indicar a data de vencimento (BT-9) ou a nota da condição de pagamento (BT-20)."
    }
  }
}

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "document": {
      "code": "e217",
      "msg": "[DT-CIUS-PT-166]-Amount due for payment (BT-115) = Invoice total amount with VAT (BT-112) -Paid amount (BT-113) +Rounding amount (BT-114), with an acceptance range of 1.00 € (it does not mean that this tolerance is accepted by the customer)."
    }
  }
}

O método a utilizar para envio do XML é o POST /apps/documentsUBL. Neste contexto, a chave pública identifica o emissor do documento e deve corresponder à chave associada ao NIF do emissor especificado no XML (AccountingSupplierParty>Party>PartyTaxScheme>CompanyID para faturas/notas de crédito, ou AccountingCustomerParty>Party>PartyTaxScheme>CompanyID para encomendas). Caso isto não se verifique, o API retornará o seguinte erro:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "supplier": {
      "code": "e199",
      "msg": "A entidade criadora do documento deve ser cliente ou fornecedor do novo documento."
    }
  }
}

Se o XML for válido e respeitar todas as validações da norma, bem como todas as regras de negócio adicionais do recetor, o API retorna uma resposta de sucesso, juntamente com os dados principais do documento criado:

HTTP status: 201 Created

{
  "success": true,
  "message": {
    "code": "s011",
    "msg": "Documento criado com sucesso"
  },
  "response": {
    "data": {
      "id": "60796c3c2a6fa2.53909016",
      "number": "7411111",
      "emission_date": "2021-04-15",
      "type_document_fact": {
        "id": "5c9cb870a5ef57.36583702",
        "code": "380",
        "alias": "invoice",
        "type": "FT",
        "description": "Fatura"
      },
      "type_document": {
        "alias": "issued",
        "description": "Emitido"
      },
      "state_document": {
        "id": "5c9cb878745b16.4225687",
        "alias": "sent",
        "description": "Enviado ao cliente."
      }
    }
  }
}

Nota: Um documento é enviado com sucesso ao destinatário via EDI quando o campo state_document.alias tem o valor sent ou accepted. Caso pretenda apenas que o documento seja enviado via e-mail, o estado do documento deve ser ignorado, devendo consultar alternativamente o registo dos e-mails enviados através da consulta de estado.

Envio dos dados estruturados do documento

Ao adotar esta opção, o ERP dispensa a geração completa do XML, ficando o ilink responsável por gerar o XML final. Assim, o ERP necessita apenas de enviar ao ilink todos os dados referentes ao documento. O endpoint a adotar aqui é o POST /apps/documents

A especificação deste método é extensa, pois abrange todos os campos possíveis de uma fatura/encomenda, que estão devidamente documentados na especificação. Todos os documentos criados por este endpoint estão sujeitos às mesmas validações que os documentos enviados pelo método POST /apps/documentsUBL, ou seja, o XML resultante dos dados inseridos será validado de acordo com o validador oficial da eSPap, que pode ser consultado online neste link, e segundo as regras de negócio adicionais do recetor do documento, caso existam.

Nota: Para incluir um ficheiro PDF na fatura eletrónica e outras situações habituais, consulte a secção casos de uso.

Nota: É possível enviar vários anexos num documento através do campo files[] (ver especificação acima). Contudo, a representação visual do documento (i.e. PDF original da fatura usado na impressão) deve ser enviada sempre no campo file, sendo o campo files[] reservado para ficheiros adicionais (notas de encomenda, avisos de despacho, guias de transporte, etc.). Se o emissor do documento tem uma assinatura digital ativa no ilink, todos os anexos serão assinados por defeito, e o consumo de transações terá em conta a soma do tamanho ocupado por todos os anexos enviados (é debitada 1 transação por cada 1MB de anexos enviados).

Envio do documento

Envio via EDI

Um documento, após criação com sucesso por qualquer um dos métodos descritos (envio de XML ou envio de dados), será enviado automaticamente ao destinatário por EDI. Contudo, em casos pontuais, este poderá não ser entregue imediatamente via EDI devido a configurações em falta e/ou outras anomalias na plataforma ilink ou no sistema do recetor. Caso isto se verifique, será devolvido um campo to_send_status na resposta do documento para detalhar a situação:

HTTP status: 201 OK

{
  "success": true,
  "message": {
    "code": "s011",
    "msg": "Documento criado com sucesso"
  },
  "response": {
    "data": {
      "id":"60796c3c2a6fa2.53909016",
      "state_document": {
        "id": "5c9cb870f34b16.42025494",
        "alias": "tosend",
        "description": "Por enviar ao cliente."
      },
      "to_send_status": {
        "code": "sent_connection",
        "title": "Aguardar a aceitação de ligação com o destinatário do documento."
      }
    }
  }
}

Nota: Pode verificar que o documento NÃO foi entregue via EDI pois o campo state_document.alias assume o valor tosend e o motivo de erro encontra-se descrito no campo to_send_status. Nesta situação, é necessário primeiro concluir a ligação EDI com o destinatário e depois proceder ao reenvio.

Os motivos possíveis (code) para um documento não ser entregue são:

• sent_connection, no_connection: Ligação com o destinatário em falta
• registered_entity: O destinatário não está registado no ilink
• received_pay_transactions: O destinatário suporta os custos dos documentos recebidos mas não dispõe de transações suficientes para o envio do documento

Após regularizar a situação de erro, será possível enviar o documento novamente (ver secção de reenvio de documentos).

Nota: O estado do documento (state_document) é apenas aplicável a envios EDI. Caso o documento seja apenas enviado para um cliente arbitrário via e-mail (PDF), o estado de envio não reflete o envio do e-mail. Consulte a seguinte secção para mais informações.

Envio via e-mail

Um documento, após criação com sucesso (HTTP status 201) por qualquer um dos métodos descritos (envio de XML ou envio de dados), será remetido via e-mail ao destinatário caso seja especificado o campo send_by_email com o valor 1. O(s) endereço(s) do(s) recetor(es) do documento pode(m) ser especificado(s) de 3 formas:

• no campo additional_emails[] (em ambos os métodos de envio)
• no campo customer[email] (apenas no método de envio de dados)
• no elemento cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail do XML (apenas no método de envio de XML).

Para consultar o envio dos e-mails e leitura dos mesmos pelo cliente, ver secção de consulta de estado de documentos emitidos.

Criação de documentos e consumo de assinaturas digitais qualificadas

Nota: Esta secção é apenas relevante para clientes que utilizam o ilink para assinar digitalmente os documentos emitidos. Ver detalhes.

Caso esteja configurada uma assinatura digital qualificada no ilink, todos os documentos serão assinados no momento da sua criação, incluindo todos os ficheiros resultantes da fatura eletrónica (xml e pdf). Dado que a assinatura dos documentos não é obrigatória por lei em todos os cenários de utilização, é possível controlar individualmente a assinatura dos ficheiros xml e pdf no momento da criação do documento através dos campos disable_xml_sign e disable_pdf_sign, disponíveis em ambos os métodos de criação de documento (XML ou dados). Isto permite reduzir o consumo de assinaturas digitais, bem como otimizar o processo de criação de documentos.

Ou seja:

• No envio de fatura digital via PDF assinado para um consumidor final ou cliente privado, não será obrigatório assinar o ficheiro XML resultante, pelo que recomendamos a utilização do campo disable_xml_sign: 1.
• No envio de fatura eletrónica para a Administração Pública via EDI (exemplo eSPap), não é obrigatório assinar o documento, no entanto é sempre possível assinar ambos os ficheiros por motivos de segurança adicional e integridade. Se pretende, por exemplo, desativar a assinatura digital do anexo PDF, basta usar a opção disable_pdf_sign: 1.
• Os campos acima descritos apenas têm efeito quando o emissor do documento usa uma assinatura digital qualificada no ilink.

Validações adicionais

O recetor da fatura pode configurar no ilink requisitos adicionais para determinados campos (regras de negócio), mesmo quando estes não são obrigatórios na especificação CIUS-PT. Por exemplo, um cliente pode definir que apenas aceita faturas com o ficheiro PDF em anexo ou com o número de compromisso especificado. É fundamental que estes requisitos sejam acordados previamente com o cliente/destinatário antes da entrada em produção, de forma a evitar erros de integração.

Caso o recetor do documento obrigue à presença de algum campo não especificado no XML, o API retornará um erro como abaixo e o documento não será gerado:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "commitment_number": {
      "code": "e048",
      "msg": "O número de compromisso é obrigatório."
    }
  }
}

Note-se que apenas são retornados erros neste formato quando o receptor do documento é cliente ilink e tem as devidas regras de negócio configuradas na plataforma. Quando um documento é enviado a um sistema EDI externo, qualquer falha no processo de validação é normalmente comunicada num momento futuro via alteração de estado para Rejeitado, com a devida mensagem de erro. É importante notar que nem todos os sistemas EDI suportam envio de mensagens de estado.

Criar/editar documento

Um documento pode ser editado e reenviado ao destinatário:

• se ainda não foi enviado ao cliente final
• ou se já foi enviado ao cliente e o cliente pediu uma regularização

Em termos práticos, a possibilidade de reenvio pode ser consultada através do seguinte campo de resposta do documento:

"state_edi_document": {
  "alias": <estado> // estados possíveis de reenvio: 'regularization' ou 'reception' ou 'error'
}

Para consultar o estado de um documento, ver secção de consulta de estado de documentos emitidos.

Para editar um documento existente, basta repetir o pedido POST /apps/documentsUBL ou POST /apps/documents com os dados corrigidos, mantendo o número, tipo e data de emissão do documento anterior:

HTTP status: 200 OK

{
  "success": true,
  "message": {
    "code": "s012",
    "msg": "Documento editado com sucesso"
  },
  "response": {
    "data": {
      "id": "60796c3c2a6fa2.53909016",
      "number": "7411111",
      "emission_date": "2021-04-16",
      "type_document_fact": {
        "id": "5c9cb870a5ef57.36583702",
        "code": "380",
        "alias": "invoice",
        "type": "FT",
        "description": "Fatura"
      },
      "type_document": {
        "alias": "issued",
        "description": "Emitido"
      },
      "state_document": {
        "id": "5c9cb870f34b16.42025494",
        "alias": "tosend",
        "description": "Por enviar ao cliente."
      }
    }
  }
}

Caso o documento não seja elegível para edição (i.e. já foi enviado ou foi aceite pelo cliente final), será apresentado um erro ao tentar reenviar:

HTTP status: 400 Bad request

{
  "success": false,
  "errors": {
    "number": {
      "code": "e200",
      "msg": "Documento já existe."
    }
  }
}

Acesso a documentos emitidos

Quando um documento é registado com sucesso, será sempre devolvido um id nas respostas, que o identifica perante o ilink. É útil guardar este identificador para consultas futuras ao documento.

HTTP status: 201 Created

{
  "success": true,
  "message": {
    "code": "s011",
    "msg": "Documento criado com sucesso"
  },
  "response": {
    "data": {
      "id": "60796c3c2a6fa2.53909016"
    }
  }
}

O API permite também aceder a todos os dados (inclusive ao XML e PDF gerados) de todos os documentos previamente emitidos. Para tal, deve usar o método GET /apps/documents/{id}. O id recebido na criação do documento deve ser usado como parâmetro aqui para aceder ao documento em questão.

Todos os dados retornados por este método estão disponíveis na especificação.

Nota: Caso a entidade emissora do documento tenha configurado a assinatura automática de documentos no ilink, os URLs de acesso ao XML e ao PDF já retornam os ficheiros assinados.

Consulta de documentos emitidos no portal (opcional)

Os documentos podem também ser consultados no portal de testes do ilink usando as credenciais das entidades que foram fornecidas. Aqui pode validar visualmente se a informação apresentada está coerente com os dados enviados via API:

Para aceder aos anexos de um documento, deve aceder ao documento da tabela e clicar no ícone da lupa:

Nota: Os documentos deverão estar presentes tanto na entidade emissora (secção de documentos emitidos), como na entidade recetora (secção de documentos recebidos).

Consulta de estado de documentos emitidos

É também possível aceder ao estado atual dos documentos previamente emitidos. Esta operação permite ao emissor do documento consultar se o documento foi aceite pelo cliente, ou se está pendente de reenvio/regularização, bem como os motivos que levaram a tal.

Consulta de estado de documento enviado via EDI

O ilink contempla 4 estados simplificados de documento na propriedade state_document:

Estado	alias	Descrição
Por enviar	tosend	O documento não foi enviado ao cliente. Provavelmente significa que falta alguma configuração no ilink, emissor/recetor não autorizam ligação entre eles, ou que alguma das entidades presentes no documento não tem transações suficientes para proceder ao envio. Se apenas se pretende que o documento seja remetido via email, este estado deve ser ignorado.
Enviado	sent	O documento não foi enviado ao cliente. Provavelmente significa que falta alguma configuração no ilink, emissor/recetor não autorizam ligação entre eles, ou que alguma das entidades presentes no documento não tem transações suficientes para proceder ao envio. Se apenas se pretende que o documento seja remetido via email, este estado deve ser ignorado.
Aceite	accepted	O documento foi enviado e o cliente aprovou o documento. Estado final.
Recusado	rejected	O documento foi enviado e o cliente rejeitou o mesmo devido a uma incoerência. O motivo de recusa é disponibilizado na resposta no campo reasons. O documento poderá ser enviado novamente caso seja solicitada uma regularização.

Nota: O ilink devolve também o estado de processamento EDI do documento (state_edi_document), que é independente dos estados acima. Para mais informação, consulte o Guia de Transmissão de Documentos FE-AP, página 7. Contudo, a leitura do estado EDI nem sempre é relevante para os softwares de faturação.

Existem 3 abordagens para aceder ao estado de um documento previamente emitido: Consulta individual, Webhook de mudança de estado e Reporte de estados.

• Na Consulta individual de estado, basta efetuar a chamada GET /apps/documents/{id}. O id recebido na criação do documento deve ser usado como parâmetro para aceder ao documento em questão. O estado é devolvido no campo state_document (ver especificação). Este método apenas permite consultar o estado de um documento de cada vez, e como tal não é recomendado para clientes que processam um volume elevado de documentos.

• No Webhook de mudança de estado, o ilink tem a iniciativa de informar o emissor do documento sempre que o mesmo muda de estado. Esta é a opção recomendada em termos de desempenho e rapidez, mas pode não ser viável caso o sistema a integrar pertença a uma rede não exposta publicamente ao ilink. Para mais informação, consulte a secção Webhooks.

• No Reporte de estados, a aplicação integradora tem a iniciativa de consultar os diversos eventos que levaram às alterações de estado dos documentos emitidos. Para tal, basta efetuar a chamada GET /apps/states-report/documents. Cada evento identifica o documento e o estado alterados. É possível filtrar os eventos retornados por id de documento, número de documento, intervalos de datas, entre outros (ver especificação). Este método permite à aplicação consultar o estado de vários documentos em simultâneo.

  De modo a facilitar a utilização do reporte de estados, é adicionalmente disponibilizado o endpoint de leitura de eventos POST /apps/states-report/documents/read, que permite marcar um ou mais ids de evento obtidos anteriormente como lidos. Os eventos marcados como lidos não são retornados novamente no endpoint de reporte de estados, facilitando a consulta futura do método anterior. Esta opção é uma alternativa escalável para os sistemas que não podem implementar Webhooks.

Consulta de estado de documento enviado via e-mail

No cenário de envio de documentos por e-mail, é possível consultar o registo de envio e de leitura dos e-mails remetidos ao cliente. Note-se que o estado do documento retornado (state_document) não é aplicável neste cenário, pois estes documentos por norma não são enviados via EDI, e como tal, o seu estado de envio será habitualmente to_send. Este estado deve ser ignorado a favor das abordagens abaixo descritas:

• Na Consulta individual, basta efetuar a chamada GET /apps/documents/{id}. O id recebido na criação do documento deve ser usado como parâmetro para aceder ao documento em questão. Na resposta, deve aceder à propriedade emails, que retorna uma lista das mensagens enviadas e o seu estado de receção e leitura. Este método apenas permite consultar o estado de um documento de cada vez e tem as mesmas limitações que a consulta individual de documentos da secção anterior:

HTTP status: 200 OK

{
  "success": true,
  "response": {
    "data": {
      "id": "60796c3c2a6fa2.53909016",
      ...
      "emails": [
        {
          "id": "634672bab0f3b8.40302642",
          "b_open": true, // true caso o email tenha sido lido pelo recetor
          "b_sent": true, // true caso o email tenha sido enviado com sucesso
          "created_at": "2022-10-12 08:54:34", // data e hora de envio do email
          "opened_at": "2022-10-12 09:14:16", // data e hora de leitura do email
          "address": {
            "emails": ["joao.freitas@email.com"], // endereço de envio
          }
        }
      ]
    }
  }
}

Nota: Alguns clientes de e-mail (Outlook, etc.) podem bloquear o registo de leitura dos e-mails, ficando o b_open a false mesmo que o e-mail tenha sido aberto em algumas situações. O ilink tem também a capacidade de detetar se um email foi devolvido pelo servidor de email, ficando responsável por tentativas sucessivas de reenvio ao longo do tempo.

• Na Consulta de histórico de documento é possível consultar todas as alterações processuais de um determinado documento. Este histórico irá listar todas as alterações de estado que ocorreram no documento por ordem cronológica, bem como os registos dos envios de e-mail para o destinatário, o que permite um rastreio completo de auditoria. Pode ser acedido através de GET /apps/documents/{id}/history.