Integração API de Guias de Remessa Eletrónicas: Ligar o Seu ERP/DMS ao Portal
Guia técnico para integrar o seu ERP ou DMS com o portal de guias de remessa eletrónicas via API. Autenticação, endpoints, formatos e problemas comuns.
Porque a Integração API e Essencial
O portal tem uma interface web para introdução manual, mas para empresas que enviam mais de 5-10 guias de remessa diariamente, a introdução manual e insustentável. A integração API permite a criação automática, confirmação de receção e sincronização de estados.
Arquitetura do Sistema
- Protocolo: HTTPS (TLS 1.2+)
- Formato: JSON
- Autenticação: Certificado eletrónico qualificado (TLS mutuo) + chave API
- Documentação: Disponível no portal apos o registo
Endpoints API Principais
| Endpoint | Método | Descrição |
|---|---|---|
| /api/v1/delivery-notes | POST | Criar nova guia de remessa eletrónica |
| /api/v1/delivery-notes/{id} | GET | Ver uma guia de remessa individual |
| /api/v1/delivery-notes | GET | Listar guias de remessa (com filtros) |
| /api/v1/receipt-notes | POST | Criar guia de receção (confirmar receção) |
| /api/v1/delivery-notes/{id}/status | GET | Estado da guia de remessa |
| /api/v1/delivery-notes/{id}/pdf | GET | Versão PDF para impressão |
Integração com Sistemas ERP Populares
SAP
Utilize SAP PI/PO ou SAP Integration Suite. Mapeie a partir do modulo SD (Documento de Envio/Entrega) para o formato API.
Microsoft Dynamics
Utilize Power Automate ou conectores personalizados. Mapeie a partir de Ordens de Venda/Transferencia.
Sistemas ERP Locais
A maioria das soluções ERP locais (Pantheon, Lidder, Bild, 4D) estão a desenvolver ou já tem módulos de guias de remessa eletrónicas.
Problemas Comuns de Integração
- Certificado não configurado corretamente: deve estar no servidor, não apenas na estação de trabalho
- Formato de data errado: a API espera ISO 8601 (AAAA-MM-DDTHH:mm:ss)
- Campos obrigatórios em falta: a API retorna 400 com lista de campos
- Destinatário não registado: o destinatário deve existir no sistema
- Timeout com envios grandes: divida mais de 100 itens em varias guias
Notificações Webhook
O portal suporta webhooks para atualizações de estado em tempo real: confirmação de receção, aceitacao/rejeicao, avisos de prazo.
Conclusão
A integração API e a única abordagem sustentável para operações de grande volume.
O Docavelo tem uma integração pronta com o portal: ligue o seu ERP ao Docavelo e ele comunica com o portal por si.
