10. Consultas e Envio de Dados ao ERP¶

Este capítulo detalha as interfaces desenvolvidas para que o Portal Retail realize consultas em tempo real de validação na base de dados do ERP e exporte cadastros prontos para o ERP integrado. Diferente do recebimento em lote (Batch), aqui o Portal é quem faz as requisições ao serviço web disponibilizado pelo parceiro ERP.

10.1 Diretrizes de Integração e Protocolos¶

As integrações descritas nesta seção (consultas externas e envio de dados) possuem as seguintes premissas de flexibilidade:

1. Protocolos Suportados: A comunicação pode ser realizada via API REST (JSON) ou WebServices SOAP (XML).
2. Responsabilidade do Parceiro ERP: O parceiro responsável pela manutenção do ERP deverá fornecer ao Portal Retail:
   • Credenciais de acesso (Tokens, API Keys, ou Basic Auth).
   • URLs de homologação e produção.
   • Endpoints específicos para cada operação.
   • Documentação técnica com exemplos de retorno de sucesso e erro.
   • Limitações de volume ou frequência (Rate Limit), caso existam.
3. Modelos de Dados: O Portal Retail propõe modelos de payload (descritos abaixo). Caso o parceiro ERP possua uma estrutura própria inflexível, ele deverá enviar a sugestão de payload para que o Portal adapte a integração.
4. Estratégia de Integração (Push vs Event): A forma como novos itens são enviados ao ERP deve ser acordada entre o parceiro e o Portal Retail. As opções incluem:
   • Envio Direto (Push): O Portal faz um POST imediato com os dados completos (REST ou SOAP).
   • Notificação (Event): O Portal envia um Webhook leve e o ERP faz o resgate dos dados (modelo Fetch).
5. Configuração Modular: Todas as integrações de saída são opcionais. O administrador do sistema Portal Retail poderá habilitar ou desabilitar cada consulta ou fluxo de envio de forma independente através da interface de administração.

10.2 Consultas ao ERP (Validações)¶

Nesta seção, o Portal Retail atua como cliente, realizando consultas pontuais para validar informações antes de prosseguir com processos internos.

10.2.1 Consulta e Validação de EAN¶

O EAN (European Article Number) é validado no ERP para evitar duplicidades no catálogo varejista.

Proposta de Payload (REST):

{
  "ean": "7896045000001"
}

Regras de Negócio: - Se o EAN já existir na base e estiver ativo: O Portal bloqueia o novo cadastro e informa duplicidade. - Se o EAN existir e estiver inativo: O Portal oferece a opção de reativação do registro existente e bloqueia a criação de um novo.

10.2.2 Consulta e Classificação Fiscal (NCM)¶

O NCM é consultado no ERP para garantir a conformidade tributária e a classificação correta do produto (Medicamento vs. Não Medicamento).

Proposta de Payload (REST):

{
  "ncm": "84733090"
}

Regras de Negócio: - Classificação Determinística: A definição se o produto é Medicamento ou não deve vir exclusivamente do ERP. O usuário não possui permissão para editar este campo manualmente no Portal. - Conflito de Classificação: Se o NCM retornar múltiplas classificações possíveis, o Portal exibe um alerta solicitando que o usuário confirme a classificação desejada antes de prosseguir.

10.3 Envio de Dados ao ERP (Exportação)¶

Esta área destina-se ao envio de cadastros consolidados e aprovados dentro do Portal Retail para o banco de dados do ERP. O envio depende de uma ação explícita ou fluxo de aprovação final.

10.3.1 Envio de Cadastro de Produto¶

Dados consolidados após a aprovação da "Ficha Completa".

Exemplo de Payload:

{
  "operation": "CREATE",
  "product": {
    "basic": {
      "ean": "7896045000001",
      "description": "Dipirona 500mg Cápsulas",
      "internalDescription": "Analgésico Genérico",
      "dosage": "500mg",
      "unit": "CX"
    },
    "commercial": {
      "brand": "Laboratório Exemplo",
      "activeIngredient": "Dipirona Monoidratada",
      "continuousUse": false,
      "priceGroup": "Analgésicos"
    },
    "fiscal": {
      "ncmCode": "30049062",
      "cest": "1300300",
      "itemOrigin": 0,
      "stBaseMargin": 45.0
    },
    "marketing": {
      "webName": "Dipirona 500mg Genérico",
      "images": [
        { "fileName": "foto_frontal.jpg", "contentBase64": "..." }
      ]
    }
  }
}

10.3.2 Envio de Cadastro de Fornecedor¶

Dados coletados durante o fluxo de homologação, incluindo documentos em Base64.

Exemplo de Payload:

{
  "operation": "CREATE",
  "supplier": {
    "taxId": "12345678000190",
    "name": "FORNECEDOR DE EXEMPLO LTDA",
    "address": {
      "zipCode": "20000-000",
      "city": "Rio de Janeiro",
      "state": "RJ"
    },
    "documents": [
      { "type": "ALVARA_SANITARIO", "fileName": "alvara.pdf", "contentBase64": "..." }
    ]
  }
}

10.3.3 Envio de Grupos de Compra¶

Exportação de agrupamentos comerciais definidos no Portal para sincronização de categorias no ERP.

Exemplo de Payload:

{
  "operation": "CREATE",
  "purchaseGroup": {
    "name": "Analgésicos e Antitérmicos",
    "description": "Categoria principal de medicamentos isentos",
    "isActive": true
  }
}

10.4 Rastreabilidade e Retorno¶

Para cada envio, o sistema registra: - Timestamp: Data e hora do envio. - Responsável: ID do usuário que disparou a exportação. - Payload Enviado: Cópia do JSON/XML enviado ao ERP. - Resposta do ERP: O Portal espera um retorno claro. Caso o ERP falhe, o Portal exibe a mensagem de erro retornada pelo parceiro no painel de controle.