3. Lista de Endpoints

A API ERP do Portal Retail fornece 9 endpoints principais para integração de dados. Cada endpoint suporta operações individuais e em lote.

3.1 Visão Geral de Todos os Endpoints

Recurso	Criação Individual	Criação Batch	Atualização Individual	Atualização Batch	Consulta Última Data
Produtos	`POST /product`	`POST /product/batch`	`PUT /product`	`PUT /product/batch`	`GET /product/get-latest-integration`
Estoque	`POST /stock`	`POST /stock/batch`	`PUT /stock`	`PUT /stock/batch`	`GET /stock/get-latest-integration`
Vendas Diárias	`POST /daily-sale`	`POST /daily-sale/batch`	`PUT /daily-sale`	`PUT /daily-sale/batch`	`GET /daily-sale/get-latest-integration`
Vendas Mensais	`POST /month-sale`	`POST /month-sale/batch`	`PUT /month-sale`	`PUT /month-sale/batch`	`GET /month-sale/get-latest-integration`
Lojas	`POST /store`	`POST /store/batch`	`PUT /store`	`PUT /store/batch`	`GET /store/get-latest-integration`
Fornecedores	`POST /supplier`	`POST /supplier/batch`	`PUT /supplier`	`PUT /supplier/batch`	`GET /supplier/get-latest-integration`
Medicamentos (Prescrição)	`POST /product-prescriber`	`POST /product-prescriber/batch`	`PUT /product-prescriber`	`PUT /product-prescriber/batch`	`GET /product-prescriber/get-latest-integration`
Grupos de Compra	`POST /purchase-group`	`POST /purchase-group/batch`	`PUT /purchase-group`	`PUT /purchase-group/batch`	`GET /purchase-group/get-latest-integration`
Documentos de Loja	`POST /store-document`	`POST /store-document/batch`	`PUT /store-document`	`PUT /store-document/batch`	`GET /store-document/get-latest-integration`

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.

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 no Hangfire 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": "hangfire-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": "hangfire-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)

Estrutura idêntica ao endpoint de Produtos.

Operação	URL
Criar	`POST /erp-data/stock`
Criar lote	`POST /erp-data/stock/batch`
Atualizar	`PUT /erp-data/stock`
Atualizar lote	`PUT /erp-data/stock/batch`
Última integração	`GET /erp-data/stock/get-latest-integration`

Campos principais do estoque: - company — Código da empresa - productDescription — Descrição do produto - currentStock — Quantidade em estoque atual - warehouseTransit — Quantidade em trânsito - distributionCenterStock — Estoque no centro de distribuição - currentAbcCurve — Classificação ABC (A, B, C)

3.4 Endpoint: VENDAS DIÁRIAS (ErpDailySales)

Operação	URL
Criar	`POST /erp-data/daily-sale`
Criar lote	`POST /erp-data/daily-sale/batch`
Atualizar	`PUT /erp-data/daily-sale`
Atualizar lote	`PUT /erp-data/daily-sale/batch`
Última integração	`GET /erp-data/daily-sale/get-latest-integration`

Campos principais: - erpProductId — Identificador do produto no ERP - erpStoreId — Identificador da loja no ERP - date — Data da venda (formato: YYYY-MM-DD) - quantity — Quantidade vendida - totalSellValue — Valor total da venda - origin — Origem da venda (exemplo: "Balcão", "Telefone")

3.5 Endpoint: VENDAS MENSAIS (ErpMonthlySales)

Operação	URL
Criar	`POST /erp-data/month-sale`
Criar lote	`POST /erp-data/month-sale/batch`
Atualizar	`PUT /erp-data/month-sale`
Atualizar lote	`PUT /erp-data/month-sale/batch`
Última integração	`GET /erp-data/month-sale/get-latest-integration`

3.6 Endpoint: LOJAS (ErpStore)

Operação	URL
Criar	`POST /erp-data/store`
Criar lote	`POST /erp-data/store/batch`
Atualizar	`PUT /erp-data/store`
Atualizar lote	`PUT /erp-data/store/batch`
Última integração	`GET /erp-data/store/get-latest-integration`

Campos principais: - erpId — Identificador da loja no ERP - title — Nome da loja - taxId — CNPJ - zipCode — CEP - address — Endereço completo - performsInjection — Boolean (realiza aplicações/injeções) - sellsControlled — Boolean (vende medicamentos controlados) - hasPopularFarmacy — Boolean (participa do programa Farmácia Popular)

3.7 Endpoint: FORNECEDORES (ErpSupplier)

Operação	URL
Criar	`POST /erp-data/supplier`
Criar lote	`POST /erp-data/supplier/batch`
Atualizar	`PUT /erp-data/supplier`
Atualizar lote	`PUT /erp-data/supplier/batch`
Última integração	`GET /erp-data/supplier/get-latest-integration`

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

Operação	URL
Criar	`POST /erp-data/product-prescriber`
Criar lote	`POST /erp-data/product-prescriber/batch`
Atualizar	`PUT /erp-data/product-prescriber`
Atualizar lote	`PUT /erp-data/product-prescriber/batch`
Última integração	`GET /erp-data/product-prescriber/get-latest-integration`

Uso: Registrar medicamentos que requerem prescrição médica.

3.9 Endpoint: GRUPOS DE COMPRA (ErpPurchaseGroup)

Operação	URL
Criar	`POST /erp-data/purchase-group`
Criar lote	`POST /erp-data/purchase-group/batch`
Atualizar	`PUT /erp-data/purchase-group`
Atualizar lote	`PUT /erp-data/purchase-group/batch`
Última integração	`GET /erp-data/purchase-group/get-latest-integration`

3.10 Endpoint: DOCUMENTOS DE LOJA (ErpStoreDocument)

Operação	URL
Criar	`POST /erp-data/store-document`
Criar lote	`POST /erp-data/store-document/batch`
Atualizar	`PUT /erp-data/store-document`
Atualizar lote	`PUT /erp-data/store-document/batch`
Última integração	`GET /erp-data/store-document/get-latest-integration`

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/hangfire-job-1234567890 HTTP/1.1
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

Resposta (200 OK) — Em Processamento:

{
  "jobId": "hangfire-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": "hangfire-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": "hangfire-invalid-job-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

4. Modelo de Dados - Entrada