Especificação de integração de API
Integração: Encomendas da loja para a contabilidade
Versão: 1.0
Escrito por: Hamza Idrissi
Data: 5 de abril de 2029
1. Objetivo
Enviar cada encomenda paga da loja online para o sistema de contabilidade como fatura de venda, para que as finanças não a tenham de reintroduzir.
2. Sistemas
- Envia dados: Loja online (API v2)
- Recebe dados: Sistema de contabilidade (API REST)
3. Fluxo de dados
1. O cliente paga uma encomenda.
2. A loja envia um webhook para o serviço de integração.
3. O serviço transforma a encomenda numa fatura e chama a API de contabilidade.
4. O sistema de contabilidade devolve o número da fatura, que o serviço guarda na encomenda.
4. Endpoints e mensagens
| Método e caminho | O que faz | Campos principais | O que devolve |
|---|---|---|---|
| POST /invoices | Criar uma fatura | Corpo: cliente, linhas, imposto, total | Devolve: id e número da fatura |
| GET /customers?email= | Encontrar um cliente | Devolve: id do cliente ou vazio | |
| POST /customers | Criar um cliente | Corpo: nome, email, morada |
5. Mapeamento de campos
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. Autenticação e segurança
OAuth 2.0 client credentials. Os tokens duram uma hora. Os segredos ficam no cofre, nunca no código. Todas as chamadas usam HTTPS. Os webhooks são assinados e a assinatura é verificada.
Os dados pessoais só são enviados quando necessário, não são registados nos logs e estão abrangidos pelos termos de privacidade de ambos os sistemas.
7. Erros e novas tentativas
Repetir em caso de 429 e 5xx até 5 vezes, com atrasos crescentes. Não repetir erros 4xx; registá-los e alertar as finanças. Cada fatura tem uma chave única, para que uma nova tentativa não crie um duplicado.
8. Limites e volumes
A API de contabilidade permite 60 chamadas por minuto. Prevêem-se 400 encomendas por dia, até 2 000 em dias de saldos.
9. Testes
Utilize o ambiente de testes da contabilidade. Teste uma encomenda normal, uma encomenda com desconto, um reembolso, um cliente que já existe e uma falha da API.
10. Responsáveis e suporte
Responsável: equipa de e-commerce. Suporte: Hamza Idrissi. Escalamento: o apoio ao cliente do fornecedor de contabilidade.
11. Alterações e versionamento
Qualquer das partes avisa com 30 dias de antecedência sobre uma alteração incompatível.