Enviar e receber faturas através da Peppol

A Peppol é a rede europeia para a troca de faturas eletrónicas estruturadas entre empresas e organismos públicos. Cada fatura circula desde o ponto de acesso do emissor até ao ponto de acesso do recetor. O Nordlet gera faturas e notas de crédito no formato Peppol BIS Billing 3.0, procedendo ao respetivo envio e receção através da conta do ponto de acesso da sua empresa.

A Peppol define as regras relativas à troca de documentos entre pontos de acesso, mas não o modo como o seu software comunica com o seu próprio ponto de acesso, uma vez que cada fornecedor possui a sua própria API. O Nordlet funciona com os seguintes fornecedores:

Fornecedor	Envia	Estado de entrega	Recebe
Recommand	sim	por webhook e a pedido	sim
Storecove	sim	apenas por webhook	sim
e-invoice.be	sim	por webhook e a pedido	sim

Sem um ponto de acesso, o Nordlet continua a gerar o ficheiro Peppol de cada fatura e nota de crédito emitida para que o possa descarregar e transmitir por outro meio; no entanto, não efetua o envio nem a receção de documentos.

O que é necessário

• Uma conta num dos fornecedores acima indicados, com a sua empresa registada na Peppol através do mesmo. Cada fornecedor cobra pelo respetivo serviço; consulte o respetivo preçário.
• No Nordlet, o número de IVA (NIF) ou número de registo da empresa, ou o respetivo ID Peppol (Conta → Empresas → ID Peppol). Cada cliente para o qual envie documentos também necessita de dispor de um destes elementos na respetiva ficha de parceiro.

Ligar o seu ponto de acesso

Aceda a Conta → Conformidade → UE → Ponto de acesso Peppol, selecione o seu fornecedor em Fornecedor, preencha os campos correspondentes conforme descrito abaixo e guarde. Deixe o campo URL base da API em vazio, a menos que o seu fornecedor lhe tenha fornecido um endereço diferente. Após guardar, a página apresenta o URL do webhook da sua empresa: https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}, em que {provider} é recommand, storecove ou e-invoice-be e {companyId} é o ID da sua empresa. Cada empresa no Nordlet possui o seu próprio URL de webhook.

O Nordlet apenas aceita uma chamada de webhook quando esta comprova que conhece o seu segredo de webhook, pelo que qualquer chamada proveniente de uma origem diferente da conta do seu ponto de acesso é recusada. O Nordlet apenas contacta endereços da internet pública quando acede ao seu ponto de acesso.

Recommand

1. No Recommand, abra a sua empresa e copie o respetivo ID de empresa para o campo ID da conta no ponto de acesso.
2. No Recommand, crie uma chave de API e copie a chave e respetivo segredo para os campos Chave de API e Segredo de API.
3. Crie um texto longo e aleatório que apenas conheça, juntamente com o Recommand, e introduza-o em Segredo do webhook. Guarde.
4. No Recommand, crie um webhook para a sua empresa utilizando o URL do webhook indicado pelo Nordlet e o mesmo segredo de webhook.

O Recommand assina todas as chamadas de webhook com esse segredo.

Storecove

1. No Storecove, crie uma entidade jurídica para a sua empresa, configurada para enviar e receber, e copie o respetivo ID para ID da conta no ponto de acesso.
2. No Storecove, em Chaves de API, crie uma chave de API e copie-a para Chave de API. Deixe o Segredo de API em vazio.
3. Crie um texto longo e aleatório e introduza-o em Segredo do webhook. Guarde.
4. No Storecove, configure um webhook do tipo push com o URL do webhook indicado pelo Nordlet, protegido com autenticação básica HTTP: qualquer nome de utilizador e o segredo do webhook como palavra-passe.

O Storecove não dispõe de um pedido para consultar o estado de um documento enviado, pelo que, com o Storecove, o estado de entrega provém exclusivamente do respetivo webhook e a página da fatura não apresenta o botão Verificar estado Peppol. Uma conta de testes (sandbox) do Storecove efetua envios na rede de testes da Peppol; as chaves de API de produção são obtidas através do suporte do Storecove.

e-invoice.be

1. Na aplicação e-invoice.be, em Definições da API, copie a chave de API da sua empresa para Chave de API. Deixe os campos ID da conta no ponto de acesso e Segredo de API em vazio. Guarde.
2. Crie um webhook através da API do e-invoice.be (POST https://api.e-invoice.be/api/webhooks/) utilizando o URL do webhook apresentado pelo Nordlet e os eventos document.received, document.sent e document.sent.failed.
3. Copie o secret devolvido pela API para o novo webhook para o campo Segredo do webhook no Nordlet e volte a guardar.

O e-invoice.be assina todas as chamadas de webhook com esse segredo. Uma empresa de testes no e-invoice.be envia por correio eletrónico os documentos que iria enviar, em vez de os transmitir através da Peppol.

Enviar uma fatura

1. Emita a fatura ou nota de crédito.
2. Certifique-se de que o cliente dispõe de um ID Peppol, número de IVA ou número de registo na respetiva ficha de parceiro.
3. Na página da fatura, na secção Entrega, clique em Enviar via Peppol e confirme. A secção de entrega é exibida em faturas emitidas que ainda não se encontram pagas, e o botão surge apenas quando o ponto de acesso está ligado.

O Nordlet gera o ficheiro Peppol e entrega-o ao seu ponto de acesso. A página da fatura passa então a exibir uma secção de Entrega Peppol:

Estado	Significado
pending	Entregue ao ponto de acesso; o ponto de acesso do cliente ainda não confirmou a receção
delivered	O ponto de acesso do cliente confirmou a receção da fatura
rejected	O cliente recusou a fatura; o motivo é apresentado abaixo do estado
failed	Não foi possível entregar a fatura; o motivo é apresentado abaixo do estado, caso o ponto de acesso o forneça

O estado atualiza-se automaticamente quando o ponto de acesso reporta uma alteração através do respetivo webhook. A opção Verificar estado Peppol solicita imediatamente o estado atual ao Recommand ou ao e-invoice.be; no caso do e-invoice.be, lê também a resposta do cliente à fatura, sendo uma recusa (código de resposta RE) apresentada como rejeitada. Uma fatura rejeitada ou com falha pode ser reenviada após corrigir a causa subjacente. Quando o ponto de acesso recusa diretamente uma fatura, por exemplo, porque o cliente não está registado na Peppol, o Nordlet apresenta o motivo e a fatura permanece por enviar.

O botão XML Peppol situado no topo da página da fatura permite descarregar o mesmo ficheiro Peppol sem proceder ao seu envio.

Uma transmissão intracomunitária indica a data de emissão como data de entrega e o país do cliente como país de entrega, conforme exigido pelas regras da Peppol.

Receber faturas

Quando o ponto de acesso reporta um documento recebido através do respetivo webhook, o Nordlet descarrega o ficheiro Peppol a partir do ponto de acesso. As faturas e notas de crédito recebidas pela sua empresa aparecem em Compras → Captura de documentos, identificadas como recebidas via Peppol a partir do ID Peppol do emitente. O Nordlet procede à leitura direta do ficheiro Peppol, pelo que a receção não consome créditos de reconhecimento de documentos.

1. Abra o documento recebido.
2. Verifique o fornecedor, as datas e as linhas; selecione o fornecedor a partir dos seus parceiros ou crie-o.
3. Clique em Guardar rascunho. O Nordlet cria um rascunho de fatura de compra, ou um rascunho de nota de crédito de compra no caso de uma nota de crédito recebida, com o ficheiro Peppol original anexo. Registe o documento tal como faria com qualquer outra fatura de compra.

As linhas de faturas de compra do Nordlet não podem apresentar valores negativos. Os descontos e encargos aplicáveis a todo o documento, bem como as linhas negativas, são distribuídos pelas linhas com a mesma taxa de IVA. Um montante que nenhuma linha com essa taxa de IVA possa suportar, tal como um artigo devolvido com uma taxa de IVA para a qual a fatura não tenha outra linha, é apresentado numa segunda tabela: Linhas de nota de crédito para uma fatura recebida, ou Linhas de fatura para uma nota de crédito recebida. Estas linhas são guardadas como um segundo documento para o mesmo fornecedor: uma nota de crédito de compra associada à nova fatura, numerada como "<número do documento>-CR", ou uma fatura de compra numerada como "<número do documento>-INV". Em conjunto, ambos os documentos totalizam os valores do documento recebido.

Verificar se um cliente está registado na Peppol

O pedido POST /v1/peppol/participants/lookup com um partnerId ou um participantId (":") consulta a rede Peppol para verificar se o recetor está registado e que documentos aceita. Esta operação funciona sem necessidade de um ponto de acesso.

Executar as mesmas operações através da API

Tarefa	Chamada
Ligar o ponto de acesso	POST /v1/declarations/configs/update com system: "peppol" e o parâmetro config contendo provider (recommand, storecove ou e-invoice-be), accountId, apiKey, apiSecret, webhookSecret e opcionalmente apiBaseUrl
Receber o webhook do ponto de acesso	POST /v1/peppol/webhooks/{provider}/{companyId}, invocado pelo ponto de acesso
Descarregar o ficheiro Peppol	POST /v1/sales/invoices/peppol-xml
Enviar	POST /v1/sales/invoices/peppol-send (retorna 422 na ausência de ponto de acesso)
Ler o estado de entrega	POST /v1/sales/invoices/peppol-status (retorna 422 com o Storecove); as faturas incluem peppolMessageId, peppolStatus, peppolDetail, peppolSentAt e peppolCheckedAt
Localizar documentos recebidos	POST /v1/capture/documents/list; os documentos recebidos apresentam provider: "peppol" e senderId
Converter um documento numa fatura de compra	POST /v1/capture/documents/confirm, utilizando oppositeLines para o segundo documento

Eventos de webhook: sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed e document_capture.peppol_received. Consulte as Convenções da API para obter informações sobre erros, idempotência e webhooks.