3. Recebimento de Informações vindas do ERP¶

A API ERP do Portal Retail fornece 9 endpoints principais, com grande foco no recebimento de dados em lote (Batch). Essa estruta assíncrona garante alta performance ao receber informações e atualizações massivas diretamente do seu sistema ERP.

3.1 Visão Geral de Todos os Endpoints¶

3.2 Endpoint: PRODUTOS (ErpProduct)¶

3.2.1 Criar Produto (Individual)¶

Endpoint: POST /erp-data/product

Status HTTP:

• Sucesso: 201 Created
• Erro de validação: 400 Bad Request
• Não autorizado: 401 Unauthorized
• Erro interno: 500 Internal Server Error

Descrição: Cria um novo produto individual. Use este endpoint para produtos isolados ou testes.

3.2.1.1 Campos disponíveis (Product)¶

Os endpoints POST /erp-data/product e PUT /erp-data/product usam os mesmos campos, com exceção de id que é obrigatório no PUT.

Nos endpoints em lote (POST /erp-data/product/batch e PUT /erp-data/product/batch), cada item do array products segue exatamente a mesma estrutura abaixo.

Campos obrigatórios¶

Campos opcionais¶

Requisição:

POST https://api.retailportal.com/erp-data/product HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpId": "12345",
  "ncmCode": "84733090",
  "status": "Active",
  "ean": "7896045000001",
  "description": "Dipirona 500mg Cápsulas",
  "internalDescription": "Genérico - Analgésico",
  "brand": "Genérico",
  "sku": "SKU-DIPO-500-001",
  "healthRegistration": "61541"
}

Resposta de Sucesso (201 Created):

{
  "success": true,
  "id": 98765,
  "message": "Produto criado com sucesso",
  "description": "Dipirona 500mg Cápsulas"
}

Resposta de Erro (400 Bad Request):

{
  "success": false,
  "errors": [
    "Field 'ncmCode' is required",
    "Field 'description' must not be empty"
  ],
  "message": "Validation failed"
}

3.2.2 Criar Produtos em Lote¶

Endpoint: POST /erp-data/product/batch

Status HTTP:

• Sucesso (enfileirado): 202 Accepted
• Erro de validação: 400 Bad Request
• Não autorizado: 401 Unauthorized
• Erro interno: 500 Internal Server Error

Descrição: Enfileira múltiplos produtos para processamento assíncrono. Use para sincronizações periódicas com muitos itens.

Fluxo:

1. Validação imediata (< 1 segundo)
2. Enfileiramento para processamento assíncrono
3. Resposta com jobId
4. Processamento em background (até 5 minutos)
5. Consulte status com GET /batch-job-report/{jobId}

Requisição:

POST https://api.retailportal.com/erp-data/product/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "products": [
    {
      "erpId": "12345",
      "ncmCode": "84733090",
      "status": "Active",
      "ean": "7896045000001",
      "description": "Dipirona 500mg"
    },
    {
      "erpId": "12346",
      "ncmCode": "84733091",
      "status": "Active",
      "ean": "7896045000002",
      "description": "Ibuprofeno 600mg"
    }
  ]
}

Resposta de Sucesso (202 Accepted):

{
  "message": "Batch received and will be processed asynchronously",
  "jobId": "batch-job-1234567890",
  "totalItems": 2
}

Resposta de Erro (400 Bad Request):

{
  "message": "Validation failed at item 1",
  "totalItems": 2,
  "invalidItems": 1,
  "itemErrors": [
    {
      "index": 1,
      "errors": ["Field 'ncmCode' is required"]
    }
  ]
}

3.2.3 Atualizar Produto (Individual)¶

Endpoint: PUT /erp-data/product

Status HTTP:

• Sucesso: 200 OK
• Erro de validação: 400 Bad Request
• Produto não encontrado: 404 Not Found
• Não autorizado: 401 Unauthorized

Descrição: Atualiza um produto existente. Requer envio do ErpId.

Requisição:

PUT https://api.retailportal.com/erp-data/product HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpId": "12345",
  "description": "Dipirona 500mg - Atualizado",
  "status": "Inactive",
  "brand": "Genérico Premium"
}

Resposta de Sucesso (200 OK):

{
  "success": true,
  "id": 98765,
  "message": "Produto atualizado com sucesso",
  "description": "Dipirona 500mg - Atualizado"
}

3.2.4 Atualizar Produtos em Lote¶

Endpoint: PUT /erp-data/product/batch

Status HTTP:

• Sucesso (enfileirado): 202 Accepted
• Erro de validação: 400 Bad Request

Requisição:

PUT https://api.retailportal.com/erp-data/product/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "products": [
    {
      "erpId": "12345",
      "status": "Inactive"
    },
    {
      "erpId": "12346",
      "brand": "Novo Fabricante"
    }
  ]
}

Resposta (202 Accepted):

{
  "message": "Batch received and will be processed asynchronously",
  "jobId": "batch-job-1234567891",
  "totalItems": 2
}

3.2.5 Obter Última Data de Integração¶

Endpoint: GET /erp-data/product/get-latest-integration

Status HTTP:

• Sucesso: 200 OK
• Não autorizado: 401 Unauthorized

Descrição: Retorna a data e hora da última sincronização de produtos bem-sucedida. Use para sincronizar apenas produtos modificados desde a última integração.

Requisição:

GET https://api.retailportal.com/erp-data/product/get-latest-integration HTTP/1.1
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

Resposta (200 OK):

{
  "classType": "ErpProduct",
  "id": 1,
  "erpId": 0,
  "lastOperation": "Create",
  "lastDateTime": "2024-12-06T15:30:45.123Z"
}

Interpretação:

• lastOperation — Última operação realizada (Create, Update)
• lastDateTime — Data/hora UTC da última integração bem-sucedida
• Use para sincronizações incrementais: busque no ERP todos os produtos modificados APÓS este timestamp

3.3 Endpoint: ESTOQUE (ErpStock)¶

3.3.1 Campos disponíveis (Stock)¶

Os endpoints POST /erp-data/stock e PUT /erp-data/stock usam os mesmos campos, com exceção de id, obrigatório apenas no PUT (identifica o registro interno para atualização).

Nos endpoints em lote (POST /erp-data/stock/batch e PUT /erp-data/stock/batch), cada item do array stocks segue a mesma estrutura abaixo.

Campos obrigatórios¶

Campos opcionais¶

Exemplo (POST):

POST https://api.retailportal.com/erp-data/stock HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpStoreId": "LOJA-01",
  "erpProductId": "SKU-001",
  "currentStock": 120,
  "warehouseTransit": 15,
  "distributionCenterStock": 40,
  "minimumStock": 20,
  "safetyStock": 30,
  "maximumStock": 200
}

3.3.2 Batch (stock) (POST /erp-data/stock/batch)¶

Formato do corpo (JSON): um único objeto raiz com a propriedade **stocks (array). Cada elemento do array é um objeto com a mesma estrutura do POST único descrito em 3.3.1**.

• Nomes em camelCase (stocks, erpStoreId, currentStock, etc.).
• O array **stocks não pode ser null nem vazio; caso contrário a API retorna 400**.
• Tamanho máximo do lote: 1000 itens por requisição.

Status HTTP (referência):

• Sucesso (enfileirado): 202 Accepted
• Erro de validação / corpo inválido: 400 Bad Request
• Não autorizado: 401 Unauthorized

Requisição (exemplo):

POST https://api.retailportal.com/erp-data/stock/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "stocks": [
    {
      "erpStoreId": "LOJA-01",
      "erpProductId": "SKU-001",
      "currentStock": 120,
      "warehouseTransit": 15,
      "distributionCenterStock": 40
    },
    {
      "erpStoreId": "LOJA-01",
      "erpProductId": "SKU-002",
      "currentStock": 85,
      "minimumStock": 20,
      "safetyStock": 25,
      "maximumStock": 180
    }
  ]
}

3.4 Endpoint: VENDAS DIÁRIAS (ErpDailySales)¶

3.4.1 Campos disponíveis (Daily sales)¶

Os endpoints POST /erp-data/daily-sale e PUT /erp-data/daily-sale usam os mesmos campos, com exceção de id, obrigatório apenas no PUT (identifica o registro interno para atualização).

Nos endpoints em lote (POST /erp-data/daily-sale/batch e PUT /erp-data/daily-sale/batch), cada item do array dailySales segue a mesma estrutura abaixo.

Campos obrigatórios¶

Formato de date (obrigatório ler)¶

A API valida que o valor recebido represente um instante em UTC explícito (data/hora com fuso indicado como UTC no payload).

• Não use apenas a data civil no formato YYYY-MM-DD (ex.: "2026-04-01"). Muitos clientes JSON interpretam isso como instante sem fuso definido (não UTC), e a validação rejeita com a mensagem: Date deve ser uma data válida em UTC (Kind=Utc) e não pode ser MinValue ou MaxValue.
• Use data/hora em ISO 8601 com fuso UTC indicado no texto, por exemplo:
• Meia-noite UTC do dia da venda: "2026-04-01T00:00:00Z" (o sufixo **Z** é obrigatório neste padrão para marcar UTC).
• Ou equivalente com offset zero: "2026-04-01T00:00:00+00:00".

Para um “dia de venda” sem hora de negócio específica, o padrão recomendado é **YYYY-MM-DDTHH:mm:ssZ** com 00:00:00Z no dia desejado.

Campos opcionais¶

Exemplo (POST):

POST https://api.retailportal.com/erp-data/daily-sale HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpProductId": "SKU-001",
  "erpStoreId": "LOJA-01",
  "quantity": 12.5,
  "totalSellValue": 199.9,
  "date": "2025-06-15T12:00:00Z",
  "origin": "Balcão",
  "deliveryMethod": "Retira"
}

3.4.2 Criar vendas diárias em lote (POST /erp-data/daily-sale/batch)¶

Formato do corpo (JSON): um único objeto raiz com a propriedade **dailySales (array). Cada elemento do array é um objeto com a mesma estrutura do POST único descrito em 3.4.1 (campos obrigatórios e opcionais, inclusive regras de date em UTC — ver Formato de date**).

• Nomes em camelCase (dailySales, erpProductId, totalSellValue, etc.), como no restante da API ERP.
• O array **dailySales não pode ser null nem vazio; caso contrário a API retorna 400**.
• Tamanho máximo do lote: 1000 itens por requisição. Ultrapassar o limite gera erro de validação.

Status HTTP (referência):

• Sucesso (enfileirado): 202 Accepted
• Erro de validação / corpo inválido: 400 Bad Request
• Não autorizado: 401 Unauthorized

Requisição (exemplo):

POST https://api.retailportal.com/erp-data/daily-sale/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "dailySales": [
    {
      "erpProductId": "12345",
      "erpStoreId": "123456",
      "quantity": 5,
      "totalSellValue": 1500,
      "date": "2026-04-01T00:00:00Z"
    },
    {
      "erpProductId": "12346",
      "erpStoreId": "123456",
      "quantity": 2,
      "totalSellValue": 80.5,
      "date": "2026-04-01T00:00:00Z",
      "origin": "Balcão",
      "deliveryMethod": "Retira"
    }
  ]
}

O fluxo assíncrono (validação rápida, job em background, consulta por jobId) segue o mesmo padrão dos outros endpoints em lote ERP (ex.: produtos em 3.2.2).

3.5 Endpoint: VENDAS MENSAIS (ErpMonthlySales)¶

3.5.1 Campos disponíveis (Month sales)¶

Os endpoints POST /erp-data/month-sale e PUT /erp-data/month-sale usam os mesmos campos, com exceção de id, obrigatório apenas no PUT (identifica o registro interno para atualização).

Nos endpoints em lote (POST /erp-data/month-sale/batch e PUT /erp-data/month-sale/batch), cada item do array monthSales no JSON segue a mesma estrutura abaixo.

Nota: diferente das vendas diárias (3.4), vendas mensais usam **month e **year** (inteiros); não** existe campo date.

Campos obrigatórios¶

Campos opcionais¶

Exemplo (POST):

POST https://api.retailportal.com/erp-data/month-sale HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpProductId": "SKU-001",
  "erpStoreId": "LOJA-01",
  "quantity": 120,
  "totalSellValue": 4500.5,
  "month": 4,
  "year": 2026,
  "origin": "Balcão",
  "deliveryMethod": "Retira"
}

3.5.2 Criar vendas mensais em lote (POST /erp-data/month-sale/batch)¶

Formato do corpo (JSON): um único objeto raiz com a propriedade **monthSales (array). Cada elemento segue a mesma estrutura do POST único em 3.5.1**.

• Nomes em camelCase (monthSales, erpProductId, totalSellValue, month, year, etc.).
• O array **monthSales não pode ser null nem vazio; caso contrário a API retorna 400**.
• Tamanho máximo do lote: 1000 itens por requisição.

Status HTTP (referência):

• Sucesso (enfileirado): 202 Accepted
• Erro de validação / corpo inválido: 400 Bad Request
• Não autorizado: 401 Unauthorized

Requisição (exemplo):

POST https://api.retailportal.com/erp-data/month-sale/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "monthSales": [
    {
      "erpProductId": "12345",
      "erpStoreId": "123456",
      "quantity": 5,
      "totalSellValue": 1500,
      "month": 4,
      "year": 2026
    },
    {
      "erpProductId": "12346",
      "erpStoreId": "123456",
      "quantity": 2,
      "totalSellValue": 800,
      "month": 4,
      "year": 2026,
      "origin": "E-commerce",
      "deliveryMethod": "Entrega"
    }
  ]
}

O fluxo assíncrono (validação rápida, job em background, consulta por jobId) segue o mesmo padrão dos outros endpoints em lote ERP (ex.: 3.4.2).

3.6 Endpoint: LOJAS (ErpStore)¶

3.6.1 Campos disponíveis (Store)¶

Os endpoints POST /erp-data/store e PUT /erp-data/store usam os mesmos campos, com exceção de id que é obrigatório no PUT.

Nos endpoints em lote (POST /erp-data/store/batch e PUT /erp-data/store/batch), cada item do array stores segue a mesma estrutura abaixo.

Campos obrigatórios¶

Campos opcionais¶

3.7 Endpoint: FORNECEDORES (ErpSupplier)¶

3.7.1 Campos disponíveis (Supplier)¶

Os endpoints POST /erp-data/supplier e PUT /erp-data/supplier usam os mesmos campos, com exceção de id, obrigatório apenas no PUT (identifica o registro interno para atualização).

Nos endpoints em lote (POST /erp-data/supplier/batch e PUT /erp-data/supplier/batch), cada item do array suppliers no JSON segue a mesma estrutura abaixo.

Campos obrigatórios¶

Campos opcionais¶

Exemplo (POST mínimo):

POST https://api.retailportal.com/erp-data/supplier HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpSupplierId": "FORN-001",
  "name": "Distribuidora Exemplo Ltda"
}

3.7.2 Fornecedores em lote (POST /erp-data/supplier/batch / PUT /erp-data/supplier/batch)¶

Formato do corpo (JSON): objeto raiz com a propriedade **suppliers (array de itens no mesmo formato de 3.7.1**).

• O array **suppliers não pode ser null nem vazio em operações de lote válidas; caso contrário, 400**.
• Tamanho máximo do lote: 1000 itens por requisição.

Status HTTP (referência):

• Sucesso (enfileirado): 202 Accepted
• Erro de validação / corpo inválido: 400 Bad Request
• Não autorizado: 401 Unauthorized

Requisição (exemplo — POST batch):

POST https://api.retailportal.com/erp-data/supplier/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "suppliers": [
    {
      "erpSupplierId": "FORN-001",
      "name": "Distribuidora Exemplo Ltda",
      "taxId": "12345678000199",
      "zipCode": "01310100",
      "address": "Av. Paulista",
      "number": 1000,
      "city": "São Paulo",
      "state": "SP"
    }
  ]
}

O fluxo assíncrono (validação rápida, job em background, consulta por jobId) segue o mesmo padrão dos outros endpoints em lote ERP (ex.: 3.4.2).

3.8 Endpoint: MEDICAMENTOS COM PRESCRIÇÃO (ErpProductPrescriber)¶

3.8.1 Campos disponíveis (Product Prescriber)¶

Os endpoints POST /erp-data/product-prescriber e PUT /erp-data/product-prescriber usam os mesmos campos, com exceção de id, obrigatório apenas no PUT (identifica o registro interno para atualização).

Nos endpoints em lote (POST /erp-data/product-prescriber/batch e PUT /erp-data/product-prescriber/batch), cada item do array productPrescribers segue a mesma estrutura abaixo.

Campos obrigatórios¶

Campos opcionais¶

Formato de checkoutDateTime¶

A API valida que checkoutDateTime seja DateTime com Kind = Utc.

• Use ISO 8601 com UTC explícito, por exemplo:
• "2026-04-01T00:00:00Z"
• "2026-04-01T00:00:00+00:00"
• O valor também precisa cair em uma faixa temporal razoável validada pela API.

Exemplo (POST):

POST https://api.retailportal.com/erp-data/product-prescriber HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpProductId": "12345",
  "quantity": 2,
  "checkoutDateTime": "2026-04-01T12:00:00Z",
  "prescriberMedicalLicense": "CRM123456",
  "erpStoreId": "LOJA-001",
  "prescriberName": "Dra. Maria",
  "state": "SP"
}

3.8.2 Batch (product prescriber) (POST /erp-data/product-prescriber/batch)¶

Formato do corpo (JSON): um único objeto raiz com a propriedade productPrescribers (array). Cada elemento do array é um objeto com a mesma estrutura do POST único descrito em 3.8.1.

• Nomes em camelCase (productPrescribers, erpProductId, checkoutDateTime, etc.).
• O array productPrescribers não pode ser null nem vazio; caso contrário a API retorna 400.
• Tamanho máximo do lote: 1000 itens por requisição.

Status HTTP (referência):

• Sucesso (enfileirado): 202 Accepted
• Erro de validação / corpo inválido: 400 Bad Request
• Não autorizado: 401 Unauthorized

Requisição (exemplo):

POST https://api.retailportal.com/erp-data/product-prescriber/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "productPrescribers": [
    {
      "erpProductId": "12345",
      "quantity": 2,
      "checkoutDateTime": "2026-04-01T12:00:00Z",
      "prescriberMedicalLicense": "CRM123456",
      "erpStoreId": "LOJA-001",
      "prescriberName": "Dra. Maria",
      "state": "SP"
    },
    {
      "erpProductId": "12346",
      "quantity": 1,
      "checkoutDateTime": "2026-04-01T13:00:00Z",
      "prescriberMedicalLicense": "CRM654321",
      "erpStoreId": "LOJA-002"
    }
  ]
}

3.9 Endpoint: GRUPOS DE COMPRA (ErpPurchaseGroup)¶

3.9.1 Campos disponíveis (Purchase Group)¶

Os endpoints POST /erp-data/purchase-group e PUT /erp-data/purchase-group usam os mesmos campos, com exceção de id, obrigatório apenas no PUT (identifica o registro interno para atualização).

Nos endpoints em lote (POST /erp-data/purchase-group/batch e PUT /erp-data/purchase-group/batch), cada item do array purchaseGroups segue a mesma estrutura abaixo.

Campos obrigatórios¶

Campos opcionais¶

Exemplo (POST):

POST https://api.retailportal.com/erp-data/purchase-group HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpId": "PG-001",
  "name": "Grupo de Higiene",
  "description": "Grupo para itens de higiene pessoal",
  "erpSupplierId": "SUP-0001"
}

3.9.2 Batch (purchase group) (POST /erp-data/purchase-group/batch)¶

Formato do corpo (JSON): um único objeto raiz com a propriedade **purchaseGroups (array). Cada elemento do array é um objeto com a mesma estrutura do POST único descrito em 3.9.1**.

• Nomes em camelCase (purchaseGroups, erpId, erpSupplierId, etc.).
• O array **purchaseGroups não pode ser null nem vazio; caso contrário a API retorna 400**.
• Tamanho máximo do lote: 1000 itens por requisição.

Status HTTP (referência):

• Sucesso (enfileirado): 202 Accepted
• Erro de validação / corpo inválido: 400 Bad Request
• Não autorizado: 401 Unauthorized

Requisição (exemplo):

POST https://api.retailportal.com/erp-data/purchase-group/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "purchaseGroups": [
    {
      "erpId": "PG-001",
      "name": "Grupo de Higiene",
      "description": "Itens de higiene pessoal",
      "erpSupplierId": "SUP-0001"
    },
    {
      "erpId": "PG-002",
      "name": "Grupo Dermocosméticos",
      "erpSupplierId": "SUP-0002"
    }
  ]
}

3.10 Endpoint: DOCUMENTOS DE LOJA (ErpStoreDocument)¶

3.10.1 Campos disponíveis (Store Document)¶

Os endpoints POST /erp-data/store-document e PUT /erp-data/store-document usam os mesmos campos, com exceção de id, obrigatório apenas no PUT (identifica o registro interno para atualização).

Nos endpoints em lote (POST /erp-data/store-document/batch e PUT /erp-data/store-document/batch), cada item do array storeDocuments segue a mesma estrutura abaixo.

Campos obrigatórios¶

Campos opcionais¶

Formato de issueDate e expirationDate¶

A API valida que ambas as datas sejam DateTime com Kind = Utc.

• Não use apenas data civil (YYYY-MM-DD), pois tende a desserializar como Kind=Unspecified e pode ser rejeitada.
• Use ISO 8601 com UTC explícito, por exemplo:
• "2026-04-01T00:00:00Z"
• "2026-04-01T00:00:00+00:00"

Além disso:

• expirationDate deve ser estritamente maior que issueDate quando ambas as datas forem informadas.
• As datas devem estar dentro da faixa temporal validada pela API.

Exemplo (POST):

POST https://api.retailportal.com/erp-data/store-document HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpStoreId": "LOJA-01",
  "fileUrl": "https://erp.exemplo.com/documentos/alvara-loja-01.pdf",
  "documentType": "ALVARA_FUNCIONAMENTO",
  "issueDate": "2026-01-01T00:00:00Z",
  "expirationDate": "2027-01-01T00:00:00Z"
}

3.10.2 Batch (store document) (POST /erp-data/store-document/batch)¶

Formato do corpo (JSON): um único objeto raiz com a propriedade storeDocuments (array). Cada elemento do array é um objeto com a mesma estrutura do POST único descrito em 3.10.1.

• Nomes em camelCase (storeDocuments, erpStoreId, fileUrl, etc.).
• O array storeDocuments não pode ser null nem vazio; caso contrário a API retorna 400.
• Tamanho máximo do lote: 1000 itens por requisição.

Status HTTP (referência):

• Sucesso (enfileirado): 202 Accepted
• Erro de validação / corpo inválido: 400 Bad Request
• Não autorizado: 401 Unauthorized

Requisição (exemplo):

POST https://api.retailportal.com/erp-data/store-document/batch HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "storeDocuments": [
    {
      "erpStoreId": "LOJA-01",
      "fileUrl": "https://erp.exemplo.com/documentos/alvara-loja-01.pdf",
      "documentType": "ALVARA_FUNCIONAMENTO",
      "issueDate": "2026-01-01T00:00:00Z",
      "expirationDate": "2027-01-01T00:00:00Z"
    },
    {
      "erpStoreId": "LOJA-02",
      "fileUrl": "https://erp.exemplo.com/documentos/licenca-loja-02.pdf",
      "documentType": "LICENCA_SANITARIA",
      "issueDate": "2026-02-01T00:00:00Z",
      "expirationDate": "2027-02-01T00:00:00Z"
    }
  ]
}

3.11 Endpoint: RELATÓRIO DE BATCH¶

Endpoint: GET /erp-data/batch-job-report/{jobId}

Status HTTP:

• Sucesso: 200 OK
• Job não encontrado: 404 Not Found
• Não autorizado: 401 Unauthorized

Descrição: Consulta o progresso e status de um trabalho enfileirado. Use após receber HTTP 202 Accepted.

Requisição:

GET https://api.retailportal.com/erp-data/batch-job-report/batch-job-1234567890 HTTP/1.1
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

Resposta (200 OK) — Em Processamento:

{
  "jobId": "batch-job-1234567890",
  "entityType": "ErpProduct",
  "state": "Processing",
  "isComplete": false,
  "createdAt": "2024-12-06T10:30:00Z",
  "startedAt": "2024-12-06T10:30:02Z",
  "completedAt": null,
  "duration": null,
  "totalItems": 100,
  "successCount": 45,
  "failureCount": 0,
  "retryAttempt": 0,
  "hasPartialData": false,
  "errorMessage": null
}

Resposta (200 OK) — Concluído com Sucesso:

{
  "jobId": "batch-job-1234567890",
  "entityType": "ErpProduct",
  "state": "Finished",
  "isComplete": true,
  "createdAt": "2024-12-06T10:30:00Z",
  "startedAt": "2024-12-06T10:30:02Z",
  "completedAt": "2024-12-06T10:35:15Z",
  "duration": "00:05:13",
  "totalItems": 100,
  "successCount": 100,
  "failureCount": 0,
  "retryAttempt": 0,
  "hasPartialData": false,
  "errorMessage": null,
  "exceptionDetails": null
}

Resposta (404 Not Found):

{
  "message": "Batch job not found",
  "jobId": "batch-job-invalid-id"
}

Fluxo Típico de Integração¶

1. POST /product/batch com 100 produtos
   ↓
2. Recebe 202 Accepted + jobId
   ↓
3. GET /batch-job-report/{jobId} a cada 10 segundos
   ↓
4. Estado: Enqueued → Processing → Finished
   ↓
5. Verifica: successCount, failureCount, errorMessage
   ↓
6. Se sucesso: Próxima sincronização
   Se parcial: Analisa erros e reenvia com dados corrigidos
   Se falha: Aguarda 5 min e reenviar

Próxima Seção¶

1. Modelo de Dados - Entrada