Manual de Integração ERP — Portal Retail API¶

🎯 Objetivos Principais da Integração¶

O objetivo fundamental desta documentação é orientar a comunicação direta entre o ERP e o Portal Retail. A integração tem dois papéis principais e muito bem definidos:

1. Recebimento de Dados em Lote (ERP → Portal Retail): Possibilitar que o sistema do ERP envie informações operacionais (produtos, estoque, vendas, etc.) ao nosso sistema, garantindo alta performance por meio de rotinas de carga em lote, conforme especificado nos Endpoints (Item 3).
2. Consultas em Tempo Real e Exportação (Portal Retail → ERP): Capacitar nossa aplicação a realizar chamadas (queries) sob demanda para o banco de dados do ERP, essenciais para validações (ex: validação de EAN) e envios de cadastros, conforme detalhado no item de Consultas ao ERP (Item 10).

📚 Índice Completo¶

Este manual técnico foi desenvolvido para guiar empresas na integração de seus sistemas ERP com a API Portal Retail. Oferece instruções detalhadas, exemplos práticos e boas práticas comprovadas.

📖 Capítulos do Manual¶

1️⃣ Visão Geral¶

O que você precisa entender primeiro

• Objetivo do módulo ERP
• Como funciona o fluxo de integração
• Operações síncronas vs assíncronas
• Entendendo HTTP 202 Accepted
• Estados de processamento de batch

Tempo de leitura: ~15 minutos

2️⃣ Autenticação e Segurança¶

Como se conectar à API com segurança

• Tipo de autenticação (API Key)
• Exemplos práticos com cURL e Bash
• Cabeçalhos obrigatórios
• Rate limiting e proteção
• Boas práticas de segurança

Tempo de leitura: ~20 minutos

Essencial antes de: Primeira integração

3️⃣ Recebimento de Informações vindas do ERP¶

Todos os endpoints para o seu ERP enviar dados ao Portal

• Visão geral de 9 endpoints principais
• Envio em lote (Batch) para alta volumetria
• Produtos (ErpProduct)
• Estoque (ErpStock)
• Vendas diárias e mensais
• Lojas, fornecedores, medicamentos, grupos de compra
• Relatório de batch jobs

Tempo de leitura: ~25 minutos

Referência: Consulte sempre que precisar criar/atualizar dados

4️⃣ Modelo de Dados — Entrada¶

Estrutura esperada dos dados que você envia

• Campos obrigatórios vs opcionais
• Tipos de dados corretos
• Regras de validação
• Exemplos válidos e inválidos
• Tratamento especial de datas

Tempo de leitura: ~20 minutos

Crítico para: Preparar dados corretos

5️⃣ Modelo de Dados — Saída (Sucesso)¶

O que você receberá em caso de sucesso

• HTTP 200 OK — Atualização bem-sucedida
• HTTP 201 Created — Criação bem-sucedida
• HTTP 202 Accepted — Batch enfileirado
• HTTP 200 OK — Consulta de status
• Progressão de estados
• Estrutura completa de resposta

Tempo de leitura: ~20 minutos

6️⃣ Modelo de Dados — Saída (Erro)¶

Como diagnosticar e resolver problemas

• HTTP 400 — Erros de validação
• HTTP 401 — Autenticação falhou
• HTTP 404 — Recurso não encontrado
• HTTP 409 — Conflito/duplicidade
• HTTP 500 — Erro do servidor
• HTTP 429 — Rate limit
• Exemplos de cada erro
• Como corrigir

Tempo de leitura: ~25 minutos

Consulte quando: Receber mensagem de erro

7️⃣ Relatório de Execução do Batch¶

Monitorar progresso de operações em lote

• Endpoint GET /batch-job-report/{jobId}
• Estados: Enqueued, Processing, Finished, Failed
• Campos e interpretação
• Polling recomendado
• Implementação em Python/Bash
• Fluxo completo de exemplo

Tempo de leitura: ~20 minutos

Essencial para: Operações em batch

8️⃣ Fluxo de Reenvio em Caso de Erro¶

Identificar, diagnosticar e corrigir erros

• Árvore de decisão
• Tipos de erro e como resolvê-los
• Erros em batch
• Retry automático com backoff exponencial
• Reenvio inteligente
• Código completo de exemplo

Tempo de leitura: ~25 minutos

Leia quando: Primeira falha ocorrer

9️⃣ Boas Práticas¶

Implementar integração robusta e eficiente

• Tamanho ideal das cargas
• Frequência recomendada
• Idempotência e segurança contra duplicatas
• Strategies para evitar duplicidades
• Connection pooling
• Processamento paralelo
• Monitoramento e logging
• Alertas e notificações
• Checklist de implementação
• SLA recomendado

Tempo de leitura: ~30 minutos

Leia antes de: Colocar em produção

🔟 Consultas e Envio de Dados ao ERP¶

Validações e exportação de cadastros para o ERP

• Consulta e validação de EAN e NCM
• Envio de cadastros aprovados (Produtos, Fornecedores e Grupos)
• Modelos de payloads e regras de negócio
• Rastreabilidade de envios e tratamento de erros

Tempo de leitura: ~10 minutos

Essencial para: Rotinas de validação e envio de cadastros

1️⃣1️⃣ Glossário de Integração¶

Dicionário de termos técnica e de negócio

• Mapeamento EN/PT-BR
• Descrição detalhada dos campos dos payloads
• Referência para desenvolvedores ERP

1️⃣2️⃣ Webhooks (Eventos e Notificações)¶

Aviso em tempo real sobre novos cadastros

• O que são e como funcionam
• Payload padronizado do disparo
• Eventos de Produto e Fornecedor
• Resgate de dados completos (Fetch)
• Segurança e retentativas

🎯 Guias Rápidos por Caso de Uso¶

Caso 1: Primeira Integração (Novo)¶

Ordem de leitura: 1. Visão Geral — Entender conceitos 2. Autenticação — Obter chave, entender segurança 3. Endpoints — Escolher endpoint correto 4. Dados Entrada — Formatar dados 5. Exemplo Prático — Testar primeira requisição

Tempo total: ~2 horas

Caso 2: Integrando Batch em Produção¶

Ordem de leitura: 1. Endpoints — /product/batch 2. Dados Entrada — Formatar 1000 itens 3. Dados Saída Sucesso — Entender 202 4. Relatório Batch — Polling de status 5. Boas Práticas — Otimizar integração

Tempo total: ~90 minutos

Caso 3: Debugar Erro Atual¶

Ordem rápida: 1. Dados Saída Erro — Identificar tipo 2. Fluxo Reenvio — Corrigir

Tempo total: ~20 minutos

Caso 4: Sincronização Automática Diária¶

Ordem de leitura: 1. Boas Práticas — Estratégias 2. Endpoints — /get-latest-integration 3. Relatório Batch — Monitoramento

Tempo total: ~45 minutos

📋 Exemplo Completo — Passo a Passo¶

Objetivo: Criar 100 produtos¶

# PASSO 1: Preparar dados (JSON válido)
# Ver: [Dados Entrada](./04-DADOS-ENTRADA.md)

curl --request POST \
  --url https://api.retailportal.com/erp-data/product/batch \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: SUA-CHAVE-AQUI' \
  --data '{
    "products": [
      {
        "erpId": 12345,
        "ncmCode": "84733090",
        "status": "Active",
        "description": "Dipirona 500mg",
        ...
      },
      ...
    ]
  }'

# PASSO 2: Receber 202 + jobId
# Resposta: { "jobId": "hangfire-123...", ... }
# Ver: [Dados Saída Sucesso](./05-DADOS-SAIDA-SUCESSO.md)

# PASSO 3: Consultar status
curl --request GET \
  --url https://api.retailportal.com/erp-data/batch-job-report/hangfire-123... \
  --header 'X-API-Key: SUA-CHAVE-AQUI'

# PASSO 4: Aguardar até "Finished"
# Ver: [Relatório Batch](./07-BATCH-RELATORIO.md)

# PASSO 5: Analisar resultado
# successCount = 100, failureCount = 0
# ✓ Sucesso total!

🔑 Conceitos-Chave¶

HTTP 202 Accepted¶

Significa que sua requisição foi ACEITA, mas ainda NÃO foi processada. É normal em operações em batch. Você deve consultar o status depois.

Saiba mais: Visão Geral 1.4

Idempotência¶

A API garante que reenviar a mesma requisição não criará duplicatas. Você pode reenviar com segurança se perder conexão.

Saiba mais: Boas Práticas 9.3

Batch vs Individual¶

• Individual (POST/PUT): Resposta imediata (1-5s), até 1 item
• Batch: Resposta 202 + polling, até 1.000 itens, mais rápido no total

Compare: Visão Geral 1.3

Rate Limiting¶

Se fizer mais de 100 tentativas de autenticação em 5 minutos, será bloqueado por 15 minutos.

Saiba mais: Autenticação 2.4

🆘 Troubleshooting Rápido¶

📞 Suporte¶

• Email: suporte@evot.com.br
• Portal: https://www.evot.com.br
• SLA: Resposta em até 8 horas

Inclua ao contactar: - JobId (se aplicável) - Timestamp do erro - JSON enviado - Mensagem de erro exata

📄 Estrutura de Diretórios¶

integracao-erp/
├── README.md (você está aqui)
├── 01-VISAO-GERAL.md
├── 02-AUTENTICACAO-SEGURANCA.md
├── 03-ENDPOINTS.md
├── 04-DADOS-ENTRADA.md
├── 05-DADOS-SAIDA-SUCESSO.md
├── 06-DADOS-SAIDA-ERRO.md
├── 07-BATCH-RELATORIO.md
├── 08-REENVIO-ERROS.md
├── 09-BOAS-PRATICAS.md
├── 10-CONSULTAS-E-ENVIO.md
├── 11-GLOSSARIO.md
├── 12-WEBHOOKS.md
└── exemplos/ (em breve)
    ├── exemplo_produto_individual.json
    ├── exemplo_batch_1000_items.json
    ├── exemplo_python_completo.py
    ├── exemplo_bash_curl.sh
    └── exemplo_nodejs.js

✅ Checklist Pré-Produção¶

Antes de colocar a integração em produção:

• [ ] Leu o manual completo
• [ ] Testou autenticação com API Key
• [ ] Formatou dados corretamente
• [ ] Testou criação individual
• [ ] Testou batch pequeno (10 itens)
• [ ] Testou batch grande (1.000 itens)
• [ ] Implementou polling de batch
• [ ] Implementou retry automático
• [ ] Adicionou logging
• [ ] Testou tratamento de erros
• [ ] Documentou procedimentos
• [ ] Testou sincronização incremental
• [ ] Tem contato de suporte identificado

📈 Versão e Histórico¶

📝 Licença e Uso¶

Este manual é fornecido pela Portal Retail para integração de sistemas ERP. Uso restrito a parceiros autorizados. Não reproduzir ou distribuir sem autorização.

🚀 Próximas Etapas¶

1. Escolha seu caso de uso (novo, debugging, produção, etc.)
2. Siga o guia rápido correspondente
3. Implemente a integração
4. Teste antes de produção
5. Contacte suporte se tiver dúvidas

Última atualização: Abril 2026

Manual versão: 1.1

API versão: v1 (ErpData)

🎓 Recursos Adicionais¶

• Documentação de API Completa
• Código de Exemplo em Múltiplas Linguagens

Dúvidas? Contacte: suporte@evot.com.br