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"
  }
}

Campos	Descrição
`workflowId`	Obrigatório. O ID do workflow a ser executado para todos os itens do lote.
`items`	Obrigatório. Array de objetos contendo os dados de entrada para cada execução.
`items[].inputData`	Obrigatório. Objeto JSON que deve corresponder ao esquema do tipo de entrada do workflow.
`items[].metadata`	Objeto JSON que poderá conter parâmetros internos para controle individual de cada item.
`batchMetadata`	Objeto JSON que poderá conter parâmetros para controle do lote como um todo.

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"
      }
    }
  ]
}

Campos	Descrição
`batchId`	Identificador único do lote de processamento.
`workflowId`	ID do workflow que está sendo executado.
`status`	Status atual do lote: `queued`, `processing`, `completed` ou `failed`.
`totalItems`	Número total de itens no lote.
`message`	Mensagem informativa sobre o status do lote.
`estimatedCompletionTime`	Estimativa de quando o processamento do lote será concluído.
`items`	Array com informações sobre cada item do lote.
`items[].itemId`	Índice do item no array original.
`items[].jobId`	ID único da execução do workflow para este item.
`items[].status`	Status individual deste item.
`items[].metadata`	Metadados fornecidos para este item específico.

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
      }
    }
  ]
}

Campos	Descrição
`batchId`	Identificador único do lote de processamento.
`workflowId`	ID do workflow que foi executado.
`status`	Status final do lote.
`startTime`	Data e hora de início do processamento do lote.
`endTime`	Data e hora de conclusão do processamento do lote.
`executionTime`	Tempo total de execução em milissegundos.
`totalItems`	Número total de itens no lote.
`successfulItems`	Número de itens processados com sucesso.
`failedItems`	Número de itens que falharam durante o processamento.
`batchMetadata`	Metadados fornecidos para o lote como um todo.
`summary`	Resumo agregado dos resultados do lote (específico para cada tipo de workflow).
`items`	Array com resultados resumidos de cada item do lote.
`items[].itemId`	Índice do item no array original.
`items[].jobId`	ID único da execução do workflow para este item.
`items[].status`	Status final deste item.
`items[].result`	Resumo do resultado da execução (campos principais do outputData).

Considerações Importantes

Limites de Processamento:
- Máximo de 1000 itens por lote
- Tamanho máximo da requisição JSON: 5MB
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
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
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