API de Entrada (Input API)

A API de Entrada é o principal mecanismo para envio de dados que disparam a execução de fluxos de decisão no Sinky Studio.

Para mais detalhes técnicos e testes, acesse nossa Referência de API - Enviar Entrada.

Exemplo de Requisição

{
  "workflowId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "inputData": {
    "first_name": "Joao",
    "last_name": "Silva",
    "email_address": "[email protected]",
    "telephone": "5511987669766",
    "date_of_birth": "10/03/1978",
    "address_line": "Avenida Brigadeiro Faria Lima",
    "address_line2": "",
    "city": "Sao Paulo",
    "state": "SP",
    "country": "BR",
    "zip": "01415000",
    "ssn_last_4digits": "1234",
    "serasa_credit_score": 520,
    "credit_requested": 30000,
    "debt_to_income_ratio": 80,
  },
  "metadata": {
      "internalId": : "Seu_id_de_controle_interno"
    }
}

Campos	Descrição
`workflowId`	Obrigatório. O ID do workflow ao qual você irá chamar.
`inputData`	Obrigatório. Um objeto JSON que deve corresponder ao esquema do tipo de entrada. Ele contém todas as características de entrada para as regras.
`metadata`	Um objeto JSON que poderá conter parametros internos para o seu controle interno

Exemplo de Resposta em Webhook

A execução do workflow é assíncrona e resposta será recebida via webhook configurado em seu workflow.

{
  "jobId": "exec_credit_analysis_789abc",
  "workflowId": "wf_credit_analysis_v1",
  "status": "completed",
  "startTime": "2024-01-15T14:20:00.000Z",
  "endTime": "2024-01-15T14:22:15.850Z",
  "executionTime": 135850,
  "metadata": {
    "source": "credit-platform",
    "requestId": "req_credit_123456",
    "clientId": "client_789"
  },
  "inputData": {
    "document": "12.345.678/0001-90",
    "requestType": "credit_analysis",
    "requestedAmount": 50000.00
  },
  "outputData": {
    "approved": true,
    "reason": "Score Serasa acima do limite mínimo",
    "serasaScore": 750,
    "creditLimit": 50000.00,
    "decidedAt": "2024-01-15T14:21:45.200Z",
    "decidedBy": "system",
    "callbackSent": true,
    "processedAt": "2024-01-15T14:22:15.850Z"
  },
  "errors": [],
  "nodeExecutions": [
    {
      "nodeId": "input_001",
      "nodeName": "Document Input",
      "nodeType": "input",
      "status": "completed",
      "startTime": "2024-01-15T14:20:00.100Z",
      "endTime": "2024-01-15T14:20:00.250Z",
      "executionTime": 150,
      "inputData": {
        "document": "12.345.678/0001-90",
        "requestType": "credit_analysis",
        "requestedAmount": 50000.00
      },
      "outputData": {
        "document": "12.345.678/0001-90",
        "cnpj": "12.345.678/0001-90",
        "requestType": "credit_analysis",
        "requestedAmount": 50000.00,
        "validatedAt": "2024-01-15T14:20:00.250Z"
      },
      "errors": []
    },
    {
      "nodeId": "integration_002",
      "nodeName": "Serasa Integration",
      "nodeType": "integration",
      "status": "completed",
      "startTime": "2024-01-15T14:20:00.300Z",
      "endTime": "2024-01-15T14:21:30.500Z",
      "executionTime": 90200,
      "inputData": {
        "document": "12.345.678/0001-90",
        "selectedSubProduct": "Serasa Report PJ Avançado"
      },
      "outputData": {
        "cnpj": "12.345.678/0001-90",
        "companyName": "Empresa Exemplo LTDA",
        "serasaScore": 750,
        "riskLevel": "low",
        "foundationDate": "2010-05-15",
        "legalStatus": "active",
        "mainActivity": "Desenvolvimento de software",
        "employees": 25,
        "revenue": 2500000.00,
        "creditHistory": {
          "totalDebts": 0,
          "pendingPayments": 0,
          "protestsCount": 0,
          "lastUpdate": "2024-01-15T14:21:30.500Z"
        },
        "enrichedAt": "2024-01-15T14:21:30.500Z"
      },
      "errors": []
    },
    {
      "nodeId": "ruleset_003",
      "nodeName": "Credit Score Validation",
      "nodeType": "ruleSet",
      "status": "completed",
      "startTime": "2024-01-15T14:21:30.550Z",
      "endTime": "2024-01-15T14:21:30.650Z",
      "executionTime": 100,
      "inputData": {
        "serasaScore": 750,
        "minimumScore": 700,
        "requestedAmount": 50000.00,
        "riskLevel": "low"
      },
      "outputData": {
        "matchedRule": "Score Above Minimum Threshold",
        "ruleIndex": 0,
        "selectedHandle": "approve",
        "action": "approve_credit",
        "scoreValid": true,
        "approvalRecommendation": "approve"
      },
      "errors": []
    },
    {
      "nodeId": "decision_004",
      "nodeName": "Credit Decision",
      "nodeType": "decision",
      "status": "completed",
      "startTime": "2024-01-15T14:21:30.700Z",
      "endTime": "2024-01-15T14:21:45.200Z",
      "executionTime": 14500,
      "inputData": {
        "approvalRecommendation": "approve",
        "serasaScore": 750,
        "requestedAmount": 50000.00,
        "companyName": "Empresa Exemplo LTDA"
      },
      "outputData": {
        "approved": true,
        "reason": "Score Serasa acima do limite mínimo",
        "creditLimit": 50000.00,
        "interestRate": 2.5,
        "paymentTerms": "12x",
        "decidedAt": "2024-01-15T14:21:45.200Z",
        "decidedBy": "system",
        "validUntil": "2024-02-15T14:21:45.200Z"
      },
      "errors": []
    },
    {
      "nodeId": "apicall_005",
      "nodeName": "Approval Callback",
      "nodeType": "apiCall",
      "status": "completed",
      "startTime": "2024-01-15T14:21:45.250Z",
      "endTime": "2024-01-15T14:22:15.850Z",
      "executionTime": 30600,
      "inputData": {
        "url": "https://client-system.com/api/credit-callback",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer client_callback_token",
          "Content-Type": "application/json"
        },
        "body": {
          "requestId": "req_credit_123456",
          "cnpj": "12.345.678/0001-90",
          "approved": true,
          "creditLimit": 50000.00,
          "interestRate": 2.5,
          "paymentTerms": "12x",
          "serasaScore": 750,
          "decidedAt": "2024-01-15T14:21:45.200Z"
        }
      },
      "outputData": {
        "callbackSent": true,
        "responseStatus": 200,
        "responseBody": {
          "status": "received",
          "message": "Credit approval notification received successfully",
          "clientReference": "client_ref_789"
        },
        "sentAt": "2024-01-15T14:22:15.850Z"
      },
      "errors": []
    }
  ]
}

Interpretar e Consumir a resposta da API de Entrada e da API de Resultado

Campo	Descrição	Informações Adicionais
`jobId`	Identificador único da execução do workflow	Identificador único do Job.
`workflowId`	Identificador único do workflow executado	Formato: `wf_`seguido de nome do workflow e versão
`status`	Status final da execução do workflow	Valores possíveis: `completed`, `failed`, `timeout`, `canceled`
`startTime`	Data e hora de início da execução	Formato ISO 8601 (UTC)
`endTime`	Data e hora de término da execução	Formato ISO 8601 (UTC)
`executionTime`	Tempo total de execução em milissegundos	Diferença entre `endTime` e `startTime`
`metadata`	Metadados adicionais sobre a execução	Objeto contendo informações contextuais
`inputData`	Dados de entrada fornecidos para o workflow	Varia conforme o tipo de workflow
`outputData`	Dados de saída produzidos pelo workflow	Resultado final da execução do workflow
`errors`	Lista de erros ocorridos durante a execução	Array vazio quando não há erros
`nodeExecutions`	Lista de execuções de cada nó do workflow	Array de objetos detalhando a execução de cada nó

Campos do Objeto `metadata`

Campo	Descrição	Informações Adicionais
`source`	Origem da solicitação de execução	Exemplo: `credit-platform`
`requestId`	Identificador da requisição original	Usado para rastreabilidade
`clientId`	Identificador do cliente	Referência ao cliente que solicitou a execução

Campos do Objeto `nodeExecutions`

Campo	Descrição	Informações Adicionais
`nodeId`	Identificador único do nó	Formato: tipo de nó seguido de número sequencial
`nodeName`	Nome descritivo do nó	Nome amigável configurado no designer do workflow
`nodeType`	Tipo do nó	Valores possíveis: `input`, `integration`, `ruleSet`, `decision`, `apiCall`, etc.
`status`	Status da execução do nó	Valores possíveis: `completed`, `failed`, `skipped`
`startTime`	Data e hora de início da execução do nó	Formato ISO 8601 (UTC)
`endTime`	Data e hora de término da execução do nó	Formato ISO 8601 (UTC)
`executionTime`	Tempo de execução do nó em milissegundos	Diferença entre `endTime` e `startTime` do nó
`inputData`	Dados de entrada recebidos pelo nó	Varia conforme o tipo de nó
`outputData`	Dados de saída produzidos pelo nó	Resultado do processamento do nó
`errors`	Lista de erros ocorridos durante a execução do nó	Array vazio quando não há erros

A seguir, passaremos por um caminho feliz (happy path) e forneceremos detalhes sobre o tratamento de erros.

Passo 1: Verifique o código de resposta http

Primeiro, verifique se o código de resposta http é 200.

Passo 2: Verifique a seção de erros

Em seguida, verifique se a seção de erros (errors) está vazia.

"errors":[]

Se a lista de erros não estiver vazia, consulte a seção de tratamento de erros no final deste documento.

Passo 3: Revise a seção de saídas (outputs / outputData)

A seção outputData contém os resultados da execução do fluxo de trabalho.

O parametro outputData na raiz do objeto inclui o nome de cada decisão, status e motivo (juntamente com quaisquer outros argumentos de decisão). Pode haver múltiplas decisões.

  "outputData": {
    "approved": true,
    "reason": "Score Serasa acima do limite mínimo",
    "serasaScore": 750,
    "creditLimit": 50000.00,
    "decidedAt": "2024-01-15T14:21:45.200Z",
    "decidedBy": "system",
    "callbackSent": true,
    "processedAt": "2024-01-15T14:22:15.850Z"
  }

Passo Opcional: Revise a seção de outputData para cada etapa

A seção outputData dentro de nodeExecutions irá ter o resultado de cada etapa que foi chamada dentro do fluxo de um determinado Job.

O exemplo abaixo é uma resposta simulada de uma etapa de Integração com um provedor que foi ativado no Sinky Data Marketplace.

{
      "nodeId": "integration_002",
      "nodeName": "Serasa Integration",
      "nodeType": "integration",
      "status": "completed",
      "startTime": "2024-01-15T14:20:00.300Z",
      "endTime": "2024-01-15T14:21:30.500Z",
      "executionTime": 90200,
      "inputData": {
        "document": "12.345.678/0001-90",
        "selectedSubProduct": "Serasa Report PJ Avançado"
      },
      "outputData": {
        "cnpj": "12.345.678/0001-90",
        "companyName": "Empresa Exemplo LTDA",
        "serasaScore": 750,
        "riskLevel": "low",
        "foundationDate": "2010-05-15",
        "legalStatus": "active",
        "mainActivity": "Desenvolvimento de software",
        "employees": 25,
        "revenue": 2500000.00,
        "creditHistory": {
          "totalDebts": 0,
          "pendingPayments": 0,
          "protestsCount": 0,
          "lastUpdate": "2024-01-15T14:21:30.500Z"
        },
        "enrichedAt": "2024-01-15T14:21:30.500Z"
      },
      "errors": []
    },

Tratamento de Erros

Erros na execução do fluxo de trabalho

A seção errors lista todos os erros que ocorreram durante a execução do fluxo de trabalho (se aplicável). Por exemplo, um erro http ocorreu durante uma chamada de integração de terceiros.

Erros podem haver na seção principal da raiz do resultado ou dentro das etapas (nodeExecutions).

"errors":[
  {
    "message":"Third party internal error",
    "code":90004,
    "context":"{http_code=404, method=POST, request_body={\"phoneNumber\":\"2001001687\",],\"ssn\":\"xx\"}, response_body={\"status\":1012,\"description\":\"No CRM data available\",\"additionalInfo\":\"full ssn mismatch\"}}"
  }
]

Erros Fatais

No evento improvável de um erro fatal, o código de resposta http não será 2xx. O código de erro seguirá as convenções http e mais detalhes serão fornecidos no corpo da resposta de erro.

Formato do Erro

Todos os erros retornarão com o mesmo formato base.

{
  "requestId": "420f0910-a664-4671-8d16-29f05e28530a",
  "message": "Event type not found, please check event type name in the input",
  "type": "enrichment",
  "code": 4001,
  "context": "{\"missing_event_type\": \"get_eligibility_v2\"}",
}

Atributo	Descrição
`Request`	UUID, identificador da requisição.
`Message`	Descrição detalhada do erro.
`Type`	Classificação de alto nível do erro.
`Code`	Código de erro indicando o tipo exato do erro. Cada tipo de erro tratado no sistema Sinky recebe um código de erro único. Veja abaixo a lista de possíveis códigos de erro secundários.
`Context`	Uma string JSON contendo pares de chave/valor como informações de contexto do erro.

Códigos de erro secundários

Código HTTP	Código Secundário	Descrição
400	4000	Requisição inválida (Bad request)
	4001	Tipo de evento não encontrado
	4002	Falha na validação do corpo da requisição
	4003	Falha na análise do JSON do corpo da requisição
	4004	Regra ou fluxo de trabalho não especificado
409	4091	Enriquecimento assíncrono não é suportado pela execução síncrona
401	4011	Autenticação, geral
	4012	Autenticação, token inválido
404		Não encontrado (Not found)
415		Formato de arquivo não suportado
500	5000	Erro de servidor não tratado
	5001	Erro de acesso à entidade
	5002	Erro de conversão de esquema
	5003	Erro de enriquecimento de característica
	5004	Erro na execução da decisão
	5005	Erro de validação
	5006	Timeout na execução
	90002	Atributo ausente durante a execução
	90003	Busca de terceiros resultou em um erro "400 (bad request)"
	90004	Terceiro retornou um erro interno
	90005	Busca de terceiros retornou um erro de "resposta não disponível"
	90006	Busca de terceiros retornou um erro de autorização
	90007	Erro no armazenamento de entrada
	90008	Conflito no armazenamento de entrada
	90010	Erro na busca da lista de documentos
	90011	Timeout na espera do webhook de integração assíncrona
503		Serviço indisponível (Service Unavailable)