Integrar uma loja online com software de faturação exige mais do que transportar uma encomenda entre duas plataformas. É preciso definir que acontecimento inicia o processo, que dados seguem, como se tratam erros e quem acompanha as exceções.
Este guia centra-se no desenho técnico e operacional. O momento de emissão, os documentos aplicáveis e as regras fiscais devem ser confirmados com a contabilidade e com o fornecedor da solução, tendo em conta a operação concreta.
Começa por um mapa de estados
Na loja, uma encomenda pode estar criada, a aguardar pagamento, paga, em preparação, expedida ou cancelada. No sistema de faturação, os estados e documentos podem seguir outra lógica.
Não assumes que “encomenda criada” significa “venda concluída”. Uma pessoa pode abandonar o pagamento, repetir a tentativa ou escolher um método que demora a confirmar.
Reúne a equipa comercial, a operação e a contabilidade para definir o que cada estado significa. Guarda a decisão num documento acessível, com exemplos de encomendas normais e excecionais.
Define os dados e a respetiva origem
Lista os campos que a integração utiliza: identificador da encomenda, dados do cliente, linhas de produto, quantidades, portes, descontos, moeda e referências de pagamento.
Para cada campo, esclarece três coisas: quem o fornece, como é validado e se pode mudar depois. Se o cliente corrigir a morada, interessa saber se a alteração afeta apenas a entrega ou também os dados já enviados a outro sistema.
Produtos precisam de identificadores estáveis. Um nome comercial pode mudar; uma referência interna deve continuar a permitir relacionar os registos. Verifica também se variantes, conjuntos e portes têm representações compatíveis.
Evita duplicados com uma referência persistente
Imagina este caso fictício: a integração envia um pedido, o sistema de destino processa-o, mas a resposta perde-se. A loja vê um erro e tenta novamente. Sem controlo, a segunda tentativa pode repetir a operação.
O conector deve guardar a relação entre o identificador de origem e o de destino. Quando a API disponibiliza mecanismos de idempotência, usa-os de acordo com a documentação. Caso contrário, desenha uma verificação e um registo que permitam reconhecer operações já concluídas.
Não confies apenas em comparar nomes, valores ou datas. Duas encomendas legítimas podem partilhar esses dados.
Desenha cancelamentos e devoluções
Uma integração que só cobre o percurso feliz fica incompleta. Escreve o que deve acontecer quando:
- O pagamento é recusado ou permanece pendente.
- A encomenda é cancelada antes de ser preparada.
- Apenas parte dos produtos é devolvida.
- Os portes são alterados ou devolvidos.
- Há uma correção de dados depois do envio.
- O destino rejeita uma referência de produto.
Para cada caso, identifica a ação técnica e quem valida o efeito documental. Uma nota interna na loja não significa que o sistema externo tenha sido atualizado.
Mantém uma fila de exceções
Erros precisam de ser visíveis por encomenda, com mensagem compreensível e próxima ação. “Erro 500” pode ser útil para um programador, mas não diz à operação se deve aguardar ou corrigir informação.
Se houver novas tentativas automáticas, define um limite e um intervalo. Depois disso, o caso deve passar a uma pessoa. A equipa precisa de conseguir reprocessar uma operação sem reenviar indiscriminadamente todas as encomendas do dia.
Faz reconciliação, mesmo quando tudo parece funcionar
Compara periodicamente encomendas elegíveis com operações confirmadas no destino. Procura registos em falta, duplicados e diferenças de valores. O volume e o risco da operação determinam a frequência necessária.
Antes do lançamento, testa num ambiente separado uma encomenda normal, uma repetição, uma indisponibilidade e uma devolução parcial. Usa dados de teste e valida o resultado nas duas plataformas.
O conector mais barato só é uma boa escolha se cobrir o teu circuito real. Para avaliar essa ligação com o resto da operação, consulta o artigo sobre fragilidade nas lojas online ou apresenta o processo numa conversa técnica com a Letras Binárias.
Recursos gratuitos
Se este artigo te foi útil, começa também pelos recursos gratuitos
É a forma mais simples de passar da leitura à experimentação: descarregas um recurso, testas no teu contexto e decides depois se queres aprofundar com o ebook.