Início

📚 Í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️⃣ Lista de Endpoints

Todos os endpoints disponíveis

  • Visão geral de 9 endpoints principais
  • 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

🎯 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

Problema Solução Ref
"Unauthorized" Verifique API Key 2.3
"Field required" Adicione campo obrigatório 4.1
"Invalid DateTime" Use formato ISO 8601 com Z 4.3
Job ainda "Processing" Continue consultando 7.2.2
"Already exists" Use PUT em vez de POST 6.5
Error 500 servidor Aguarde 5 min e reenvie 6.6

📞 Suporte

  • Email: suporte@retailportal.com
  • Portal: https://support.retailportal.com
  • SLA: Resposta em até 4 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
└── 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

Versão Data Alterações
1.0 Dez 2024 Versão inicial completa

📝 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: Dezembro 2024

Manual versão: 1.0

API versão: v1 (ErpData)

🎓 Recursos Adicionais

  • Documentação de API Completa
  • Código de Exemplo em Múltiplas Linguagens
  • Vídeos Tutoriais (em breve)
  • Webinar Mensal (agendado)
  • FAQ (em construção)

Dúvidas? Contacte: suporte@retailportal.com