4. Modelo de Dados — Entrada¶

Este capítulo detalha a estrutura esperada dos dados que você deve enviar para cada endpoint.

O Que Atualizou¶

16/09/2026 — Venda Diária (ErpDailySales)¶

Endpoints: POST /erp-data/daily-sale, PUT /erp-data/daily-sale e suas versões em lote (/batch).

Orientações de envio:

• sellDateTimeUtc: o momento em que a venda ocorreu, com hora, minuto e segundo, em UTC. O envio apenas da data, com o horário fixo em 00:00:00, deixa de ser o formato esperado.
• Converter do horário de Brasília (UTC−3) somando 3 horas. Quando a soma passa da meia-noite, a data em UTC é a do dia seguinte — e esse é o comportamento correto. Venda às 22:30 de 11/09 em Brasília vai como "2026-09-12T01:30:00Z".
• Todas as linhas da mesma compra trazem o mesmo sellDateTimeUtc, invoiceNumber e transactionCode.
• erpId: informado em todos os registros de venda diária, com um valor próprio por linha de venda.
• invoiceNumber e transactionCode: informados sempre que a venda possuir esses dados.

Regras de preenchimento em 4.3 Estrutura de Venda Diária.

4.1 Estrutura de Produto (ErpProduct)¶

Campos Obrigatórios¶

Campos Opcionais (Altamente Recomendados)¶

Campos Opcionais (Complementares)¶

Exemplo Válido — Mínimo¶

{
  "erpId": 12345,
  "ncmCode": "84733090",
  "status": "Active",
  "description": "Dipirona 500mg Cápsulas"
}

Exemplo Válido — Completo¶

{
  "erpId": 12345,
  "ncmCode": "84733090",
  "status": "Active",
  "ean": "7896045000001",
  "description": "Dipirona 500mg Cápsulas",
  "internalDescription": "Genérico - Analgésico",
  "webName": "Dipirona 500mg",
  "specification": "Cápsulas de 500mg, frasco com 20",
  "metaDescription": "Compre Dipirona 500mg online",
  "brand": "Genérico",
  "sku": "SKU-DIPO-500-001",
  "healthRegistration": "61541",
  "manufacturer": "Laboratório Exemplo",
  "manufacturerCnpj": "12.345.678/0001-90",
  "weightGr": 25.5,
  "lengthCm": 10.0,
  "widthCm": 5.0,
  "heightCm": 15.0,
  "ipi": false,
  "purchaseGroup": "Analgésicos",
  "purchaseStatus": "Available",
  "activePrinciple": "Dipirona Monoidratada",
  "indication": "Dor leve a moderada, febre",
  "contraindication": "Alergia à dipirona",
  "medicalPrescriptionType": "None",
  "continuousUse": false,
  "controlledSale": false,
  "minimumPurchaseMultiple": 1
}

Exemplos Inválidos¶

❌ Exemplo 1: Campo Obrigatório Ausente¶

{
  "erpId": 12345,
  "ncmCode": "84733090",
  "status": "Active"
  // Faltando: description
}

Erro esperado:

Field 'description' is required

❌ Exemplo 2: Tipo de Dado Incorreto¶

{
  "erpId": "não é um número",
  "ncmCode": "84733090",
  "status": "Active",
  "description": "Dipirona 500mg"
}

Erro esperado:

Field 'erpId' must be a number

❌ Exemplo 3: Campo Vazio¶

{
  "erpId": 12345,
  "ncmCode": "",
  "status": "Active",
  "description": "Dipirona 500mg"
}

Erro esperado:

Field 'ncmCode' must not be empty

❌ Exemplo 4: Tamanho Máximo Excedido¶

{
  "erpId": 12345,
  "ncmCode": "84733090123456789", // Máximo 8 caracteres
  "status": "Active",
  "description": "Dipirona 500mg"
}

Erro esperado:

Field 'ncmCode' must not exceed 8 characters

4.2 Estrutura de Estoque (ErpStock)¶

Campos Obrigatórios¶

Campos Recomendados¶

Exemplo Válido¶

{
  "company": 1,
  "companyName": "Loja Centro",
  "address": "Rua Principal, 100",
  "productDescription": "Dipirona 500mg",
  "currentStock": 500.0,
  "warehouseTransit": 100.0,
  "distributionCenterStock": 2000.0,
  "brand": "Genérico",
  "currentAbcCurve": "A",
  "cnpj": "12.345.678/0001-90"
}

4.3 Estrutura de Venda Diária (ErpDailySales)¶

Campos Obrigatórios¶

Campos Opcionais¶

O campo erpId¶

Identificador da linha de venda no ERP (o item do cupom ou da transação). Obrigatório em todos os registros de venda diária.

• Use o identificador da linha que o próprio ERP já gera. Não gere o valor a partir de outros campos do payload (por exemplo, um hash de produto + loja + data).
• Cada linha de venda tem seu próprio erpId. Uma compra com três produtos gera três registros, com três erpId diferentes.
• O valor deve ser estável: a mesma linha de venda tem sempre o mesmo erpId, em qualquer envio.
• Correções: para corrigir uma venda já enviada, reenvie o registro com o mesmo erpId e os valores corretos. O registro anterior é substituído.

Os campos invoiceNumber e transactionCode¶

Identificam a compra à qual a linha de venda pertence. Opcionais.

• Todas as linhas da mesma compra devem trazer o mesmo invoiceNumber e/ou transactionCode.
• Envie os dois quando a venda tiver os dois. Se tiver só um, envie só esse.
• Envie o valor exatamente como está no ERP. Máscara, série, zeros à esquerda e a chave de acesso de 44 dígitos são aceitos, desde que caibam em 64 caracteres.
• Não gere esses valores a partir de outros campos do payload.
• Esses campos não substituem o erpId: erpId identifica a linha e invoiceNumber / transactionCode identificam a compra.

Importante: Tratamento de Data¶

Mudança de 16/09/2026. O campo date passou a se chamar sellDateTimeUtc e o nome antigo deixou de ser aceito — payload com date recebe HTTP 400 com a mensagem O campo 'date' foi substituído por 'sellDateTimeUtc'. Mudou também o conteúdo: espera-se o instante real da venda (hora, minuto e segundo), e não mais o dia com 00:00:00Z.

⚠️ CRÍTICO PARA POSTGRESQL

A data DEVE estar em formato ISO 8601 com timezone UTC:

✅ Formatos Válidos:

2026-09-11T17:32:10Z
2026-09-11T17:32:10.250Z

❌ Formatos Inválidos:

2026-09-11                 // Sem hora
17:32:10                   // Sem data
2026-09-11T17:32:10        // Sem Z (timezone)
2026-09-11T14:32:10-03:00  // Fuso local; converter para UTC
11/09/2026 14:32:10        // Fora do padrão ISO 8601

Conversão do horário de Brasília (UTC−3): somar 3 horas. Venda às 22:30 de 11/09 em Brasília vai como "2026-09-12T01:30:00Z" — dia seguinte em UTC, e isso está correto.

Exemplo Válido¶

{
  "erpId": "CUPOM-100234-LINHA-1",
  "erpProductId": "12345",
  "erpStoreId": "1001",
  "sellDateTimeUtc": "2026-09-11T17:32:10Z",
  "quantity": 15.0,
  "totalSellValue": 125.5,
  "invoiceNumber": "000123456",
  "transactionCode": "CUPOM-100234",
  "origin": "Balcão",
  "deliveryMethod": "Retirada"
}

Exemplo Inválido — Data Sem Timezone¶

{
  "erpId": "CUPOM-100234-LINHA-1",
  "erpProductId": "12345",
  "erpStoreId": "1001",
  "sellDateTimeUtc": "2026-09-11T17:32:10", // ❌ Faltando Z
  "quantity": 15.0,
  "totalSellValue": 125.5
}

Erro esperado:

Invalid DateTime format. Must be UTC with Z suffix: YYYY-MM-DDTHH:mm:ssZ

4.4 Estrutura de Loja (ErpStore)¶

Campos Obrigatórios¶

Campos Recomendados¶

Campos de Características¶

Campos de Funcionamento¶

Exemplo Válido¶

{
  "erpId": "1001",
  "title": "Farmácia Centro",
  "taxId": "12.345.678/0001-90",
  "stateRegistration": "123.456.789.012",
  "zipCode": "01234-567",
  "address": "Rua Principal",
  "number": "100",
  "complement": "Próximo à estação",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "performsInjection": true,
  "sellsControlled": false,
  "hasPopularFarmacy": true,
  "storeType": "Popular",
  "storeSize": "M",
  "weekdayHours": "09:00-20:00",
  "saturdayHours": "09:00-18:00",
  "sundayHours": "10:00-16:00",
  "openingDate": "2020-01-15T00:00:00Z",
  "isActive": true
}

4.5 Estrutura de Fornecedor (ErpSupplier)¶

Campos Típicos¶

4.6 Estrutura de Venda Mensal (ErpMonthlySales)¶

Similar à Venda Diária, mas com data agregada:

4.7 Validações Gerais Aplicadas¶

Validações de Tipo¶

✓ String → Texto
✓ Decimal → Números com vírgula (0.00)
✓ Boolean → true ou false
✓ DateTime → ISO 8601 com Z
✗ Qualquer outro tipo → Erro 400

Validações de Tamanho¶

✓ Campo com até 50 caracteres → Aceita de 0-50
✗ Campo com até 50 caracteres → Rejeita > 50
✓ Campo obrigatório → Não pode ser vazio
✗ Campo obrigatório → Se vazio, erro

Validações de Formato¶

✓ NCM: 8 caracteres numéricos
✓ EAN: 13 caracteres (com ou sem dígito verificador)
✓ CNPJ: 14 caracteres (com ou sem formatação)
✓ CEP: 8 caracteres (com ou sem hífen)
✓ Data: ISO 8601 UTC com Z

Checklist de Dados — Antes de Enviar¶

• [ ] Todos os campos obrigatórios estão preenchidos?
• [ ] Nenhum campo obrigatório está vazio ou null?
• [ ] Números estão em formato decimal (ex: 123.45)?
• [ ] Datas estão no formato UTC ISO 8601 com Z?
• [ ] Strings não excedem o tamanho máximo?
• [ ] Booleanos estão como true/false (não "1"/"0")?
• [ ] Códigos (NCM, EAN, CNPJ) têm o tamanho correto?
• [ ] Nenhum caractere especial indevido nas strings?

Próxima Seção¶

5. Modelo de Dados — Saída (Sucesso)