Tenho dados estruturados da fatura
Crie o cabeçalho, adicione cada linha, anexe opcionalmente o PDF e gere o documento UBL Peppol.
Ver este fluxo →
Peppox Developer Platform
Envie a sua primeira fatura pela Peppol, passo a passo.
Escolha o percurso adequado ao seu sistema, desde a primeira chamada API ao acompanhamento da entrega.
PEPPOX / INTEGRATION FLOW
- 01Painel
- 02Chave API
- 03Fatura
- 04Validar
- 05Peppol
READY TO BUILD
01 · Antes da primeira chamada
Quatro elementos preparados uma única vez
Configure primeiro a conta e o perfil do fornecedor. A aplicação reutiliza depois as mesmas credenciais em cada documento.
- 01
Crie a conta Peppox
Registe a empresa legal que enviará os documentos.
- 02
Complete o perfil do fornecedor
Dados da empresa, IVA, banco e routing Peppol vêm da conta.
- 03
Abra o ambiente de integração
Teste com segurança nas ferramentas do painel antes da produção.
- 04
Copie a chave API
Guarde-a apenas no servidor; nunca no browser ou numa aplicação móvel.
02 · Escolha o percurso mais curto
Comece com os dados que já possui
Já produzo um PDF
Carregue o PDF, deixe a Peppox extrair os dados, verifique, confirme e envie pela Peppol.
Ver este fluxo →03 · PDF2Peppol
Um envio completo em quatro chamadas API
O percurso documentado mais direto quando o sistema já produz faturas em PDF.
- 01
Carregue o PDF
Envie ficheiro, Base64 ou URL e guarde queue_guid.
POST/pdf2peppol/add - 02
Verifique os dados extraídos
Consulte até terminar e confirme comprador, totais, IVA e linhas.
GET/pdf2peppol/check - 03
Confirme o documento
Confirme apenas quando todos os dados extraídos estiverem corretos.
POST/pdf2peppol/confirm - 04
Envie para a Peppol
Envie o documento confirmado e guarde o GUID do documento.
POST/pdf2peppol/send - 05
Acompanhe a entrega
Use a lista de enviados ou o painel para acompanhar o estado final.
GET/doc-sent/header/list
Exemplo mínimo
Upload → check → confirm → send
Substitua os valores de exemplo pela sua identificação e pelos IDs da chamada anterior.
pdf2peppol.sh
curl -X POST "https://api.peppox.com/pdf2peppol/add/" \
-F "supplier_id=YOUR_SUPPLIER_ID" \
-F "pdf=@invoice.pdf" \
-F "network=integration"
# Save queue_guid, then check it
curl "https://api.peppox.com/pdf2peppol/check/?supplier_id=YOUR_SUPPLIER_ID&queue_guid=QUEUE_GUID"
curl -X POST "https://api.peppox.com/pdf2peppol/confirm/" \
-H "Content-Type: application/json" \
-d '{"supplier_id":"YOUR_SUPPLIER_ID","queue_guid":"QUEUE_GUID","confirmed":1}'
curl -X POST "https://api.peppox.com/pdf2peppol/send/" \
-H "Content-Type: application/json" \
-d '{"supplier_id":"YOUR_SUPPLIER_ID","queue_guid":"QUEUE_GUID"}'04 · API de fatura estruturada
Crie uma fatura pronta para Peppol a partir dos seus dados
Ideal quando o ERP já guarda todos os campos e linhas de forma estruturada.
- 01
Crie o cabeçalho
Envie cliente, datas, moeda, pagamento e entrega; guarde invoice_guid.
POST/invoice/add - 02
Adicione as linhas
Repita para cada produto ou serviço.
POST/invoice_line/add - 03
Anexe o PDF (opcional)
Adicione a fatura legível por ficheiro, Base64 ou URL.
POST/invoice_attach_pdf/add - 04
Gere o XML UBL
A Peppox combina cabeçalho, linhas e anexo; o sucesso devolve XML_BUILT.
POST/xml/generate - 05
Acompanhe e gira
Consulte documento e estado no painel ou APIs de enviados.
GET/doc-sent/header/list
API NOTE
Importante: a referência publicada para faturas estruturadas documenta a geração XML, mas atualmente não um endpoint /send final separado. Para uma chamada final explícita use PDF2Peppol ou conclua o envio pelo fluxo ou painel Peppox configurado.
05 · Mapa de endpoints
Todos os endpoints explicados de forma simples
01Faturas
POST/invoice/addCria o cabeçalho e devolve invoice_guid.
POST/invoice_line/addAdiciona uma linha à fatura.
POST/invoice_attach_pdf/addAnexa ou substitui o PDF da fatura.
02Geração UBL
POST/xml/generateGera XML UBL compatível com Peppol.
03Notas de crédito
POST/creditnote/addCria o cabeçalho da nota de crédito.
POST/creditnote_line/addAdiciona uma linha à nota de crédito.
POST/creditnote_attach_pdf/addAnexa ou substitui o respetivo PDF.
04Documentos enviados
GET/doc-sent/header/listLista cabeçalhos enviados com filtros e páginas.
GET/doc-sent/lines/listObtém linhas de um documento enviado.
05Documentos recebidos
GET/doc-received/header/listLista cabeçalhos recebidos com filtros e páginas.
GET/doc-received/lines/listObtém linhas de um documento recebido.
06PDF2Peppol
POST/pdf2peppol/addCarrega um PDF e inicia a extração.
GET/pdf2peppol/checkVerifica estado e campos extraídos.
POST/pdf2peppol/confirmConfirma os dados verificados.
POST/pdf2peppol/sendEnvia o documento confirmado pela Peppol.
06 · Testes sem código
Compreenda cada pedido no painel antes de programar
Os formulários guiados do painel Peppox chamam as APIs por si. Teste documentos reais, descubra parâmetros obrigatórios e compreenda o JSON antes de ligar o ERP.
- 01Escolha um endpoint e preencha os campos
- 02Execute sem criar um cliente de teste
- 03Veja GUID, JSON e erros
- 04Valide no ambiente de integração
- 05Reutilize o pedido funcional no backend
- 06Acompanhe enviados e recebidos
Guarde estes identificadores
O estado da integração é simples
invoice_guidLiga cabeçalho, linhas, PDF e XML gerado.
queue_guidLiga as quatro chamadas PDF2Peppol durante a extração.
GUID do documentoLiga o documento final à entrega e reconciliação.
Se um pedido falhar
400Verifique campos ausentes ou inválidos.401Verifique chave API e ambiente.404Verifique o GUID da chamada anterior.429Abrande e tente de novo com espera progressiva.500Registe o pedido, repita com segurança e contacte a Peppox se persistir.