Porque a Integracao API e Essencial
O portal tem uma interface web para introducao manual, mas para empresas que enviam mais de 5-10 guias de remessa diariamente, a introducao manual e insustentavel. A integracao API permite a criacao automatica, confirmacao de rececao e sincronizacao de estados.
Arquitetura do Sistema
- Protocolo: HTTPS (TLS 1.2+)
- Formato: JSON
- Autenticacao: Certificado eletronico qualificado (TLS mutuo) + chave API
- Documentacao: Disponivel no portal apos o registo
Endpoints API Principais
| Endpoint | Metodo | Descricao |
|---|---|---|
| /api/v1/delivery-notes | POST | Criar nova guia de remessa eletronica |
| /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 rececao (confirmar rececao) |
| /api/v1/delivery-notes/{id}/status | GET | Estado da guia de remessa |
| /api/v1/delivery-notes/{id}/pdf | GET | Versao PDF para impressao |
Integracao 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 solucoes ERP locais (Pantheon, Lidder, Bild, 4D) estao a desenvolver ou ja tem modulos de guias de remessa eletronicas.
Problemas Comuns de Integracao
- Certificado nao configurado corretamente -- deve estar no servidor, nao apenas na estacao de trabalho
- Formato de data errado -- a API espera ISO 8601 (AAAA-MM-DDTHH:mm:ss)
- Campos obrigatorios em falta -- a API retorna 400 com lista de campos
- Destinatario nao registado -- o destinatario deve existir no sistema
- Timeout com envios grandes -- divida mais de 100 itens em varias guias
Notificacoes Webhook
O portal suporta webhooks para atualizacoes de estado em tempo real -- confirmacao de rececao, aceitacao/rejeicao, avisos de prazo.
Conclusao
A integracao API e a unica abordagem sustentavel para operacoes de grande volume.
O Arhivix tem uma integracao pronta com o portal -- ligue o seu ERP ao Arhivix e ele comunica com o portal por si.
