API de entrada em lote (Bulk Input API)

A API de Entrada em Lote permite enviar múltiplas solicitações simultâneas para execução de workflows na plataforma Sinky, otimizando o processamento de grandes volumes de dados. Ideal para análises de crédito em massa, verificações KYC em lote, ou qualquer automação que envolva múltiplos registros, essa API fornece controle detalhado por item e por lote, com rastreabilidade completa e notificações assíncronas via webhook.

Essa API é útil para empresas que precisam escalar seus processos de decisão com eficiência e controle, mantendo a rastreabilidade individual de cada requisição mesmo dentro de um processamento em massa. O envio é feito de forma assíncrona, permitindo que o cliente continue o fluxo enquanto os dados são processados em segundo plano. Uma vez concluído, a resposta de cada item pode ser recebida via webhook ou consultada por meio de relatórios agregados.

Você pode utilizar essa API para:

• Enviar múltiplos CPFs ou CNPJs para análise de crédito ou verificação
• Iniciar fluxos de risco ou compliance para grandes bases de dados
• Automatizar ciclos periódicos de revalidação cadastral
• Executar testes A/B em workflows com múltiplos datasets

Para saber como enviar os dados, interpretar as respostas e acompanhar os resultados de cada execução, consulte os exemplos e as boas práticas neste documento.

Consulte também o endpoint oficial de envio em lote.

Envio de Dados em Lote

Corpo da Requisição:

{
  "workflowId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "items": [
    {
      "inputData": {
        "document": "12.345.678/0001-90",
        "requestType": "credit_analysis",
        "requestedAmount": 50000
      },
      "metadata": {
        "internalId": "req_001"
      }
    },
    {
      "inputData": {
        "document": "98.765.432/0001-10",
        "requestType": "credit_analysis",
        "requestedAmount": 75000
      },
      "metadata": {
        "internalId": "req_002"
      }
    }
  ],
  "batchMetadata": {
    "source": "credit-platform",
    "priority": "high",
    "batchId": "batch_20240115_001"
  }
}

Resposta da API

Exemplo de Resposta para processamento em lote

{
  "batchId": "batch_20240115_001",
  "workflowId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "status": "queued",
  "totalItems": 2,
  "message": "Processamento em lote iniciado com sucesso",
  "estimatedCompletionTime": "2024-01-15T15:30:00.000Z",
  "items": [
    {
      "itemId": 0,
      "jobId": "exec_credit_analysis_001",
      "status": "queued",
      "metadata": {
        "internalId": "req_001"
      }
    },
    {
      "itemId": 1,
      "jobId": "exec_credit_analysis_002",
      "status": "queued",
      "metadata": {
        "internalId": "req_002"
      }
    }
  ]
}

Resposta em Webhook

A execução do workflow em lote é assíncrona e as respostas serão recebidas via webhook configurado em seu workflow. Cada item do lote gerará uma notificação individual quando for concluído.

Adicionalmente, uma notificação final será enviada quando todo o lote for processado:

{
  "batchId": "batch_20240115_001",
  "workflowId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "status": "completed",
  "startTime": "2024-01-15T15:00:00.000Z",
  "endTime": "2024-01-15T15:25:30.850Z",
  "executionTime": 1530850,
  "totalItems": 2,
  "successfulItems": 2,
  "failedItems": 0,
  "batchMetadata": {
    "source": "credit-platform",
    "priority": "high",
    "batchId": "batch_20240115_001"
  },
  "summary": {
    "approvedCount": 1,
    "rejectedCount": 1,
    "totalAmount": 125000,
    "approvedAmount": 50000
  },
  "items": [
    {
      "itemId": 0,
      "jobId": "exec_credit_analysis_001",
      "status": "completed",
      "result": {
        "approved": true,
        "reason": "Score Serasa acima do limite mínimo",
        "creditLimit": 50000
      }
    },
    {
      "itemId": 1,
      "jobId": "exec_credit_analysis_002",
      "status": "completed",
      "result": {
        "approved": false,
        "reason": "Score Serasa abaixo do limite mínimo",
        "creditLimit": 0
      }
    }
  ]
}

Considerações Importantes

1. Limites de Processamento:

   • Máximo de 1000 itens por lote
   • Tamanho máximo da requisição JSON: 5MB

2. Prioridade de Processamento:

   • Processamentos em lote têm prioridade menor que execuções individuais
   • Use o campo batchMetadata.priority para ajustar a prioridade relativa entre lotes

3. Monitoramento:

   • O status do lote pode ser consultado através do endpoint GET /workflow/batch/{batchId}/status
   • Relatórios detalhados estão disponíveis em GET /workflow/batch/{batchId}/report

4. Tratamento de Falhas:

   • Falhas em itens individuais não interrompem o processamento do lote
   • Cada item tem seu próprio status e mensagens de erro, seguindo as convenções dispostas em API de Input.
   • O webhook final inclui informações sobre todos os itens, incluindo os que falharam