Atualizar um cadastro

Use o método PUT para atualizar o status de um cadastro — tanto o client_status (situação na sua plataforma) quanto o analysis_status (decisão manual de análise).

Retroalimentação importa

Informar o desfecho real via PUT é o que mantém a qualidade das recomendações. Sem esse retorno, os modelos não aprendem com os casos da sua carteira.

O endpoint aceita os dois tipos de cadastro:

/onboarding/natural_person/{external_id}
/onboarding/legal_person/{external_id}

O {external_id} é o id que você enviou no POST.

---

PUT — atualizar status

ENDPOINT

/onboarding/natural_person/EXTERNAL_ID

MÉTODO

PUT

O corpo aceita duas formas mutuamente exclusivas: uma para client_status, outra para analysis_status.

client_status

Atualiza a situação do cliente na sua plataforma.

client_statusenumobrigatórioEm Natural Person aceita approved, reproved, fraud_blocked, default_blocked ou cancelled. Em Legal Person, apenas fraud_blocked, default_blocked ou cancelled.event_datedatetimeobrigatórioData e hora do evento, com fuso horário. Offset terminado em :00/:30 ou sufixo Z.

Bloqueio por fraude

{
  "client_status": "fraud_blocked",
  "event_date": "2026-08-07T13:34:12-03:00"
}

Bloqueio por inadimplência

{
  "client_status": "default_blocked",
  "event_date": "2026-08-07T13:34:12-03:00"
}

Cancelamento pelo cliente

{
  "client_status": "cancelled",
  "event_date": "2026-08-07T13:34:12-03:00"
}

analysis_status

Registra uma decisão manual de análise.

analysis_statusenumobrigatórioAceita manually_approved, manually_reproved, manually_challenged, manually_cancelled ou on_hold.risk_levelenumopcionallow, medium, high ou critical.observationstringopcionalJustificativa da decisão. Até 3.000 caracteres.user_namestringopcionalNome do analista responsável. Até 50 caracteres.user_emailstringopcionalE-mail do analista responsável.

Aprovação manual

{
  "analysis_status": "manually_approved",
  "risk_level": "low",
  "observation": "Documentação conferida e validada.",
  "user_name": "Ana Analista",
  "user_email": "ana@exemplo.com.br"
}

Exemplos de requisição

Python

import requests

BASE_URL = "https://api.sandbox.caas.qitech.app"
API_KEY = "YOUR_API_KEY"
EXTERNAL_ID = "12345678"

response = requests.put(
    f"{BASE_URL}/onboarding/natural_person/{EXTERNAL_ID}",
    json={
        "client_status": "approved",
        "event_date": "2026-08-07T13:34:12-03:00",
    },
    headers={"Authorization": API_KEY},
    timeout=30,
)

response.raise_for_status()

PHP

<?php

$baseUrl    = 'https://api.sandbox.caas.qitech.app';
$apiKey     = 'YOUR_API_KEY';
$externalId = '12345678';

$payload = [
    'client_status' => 'approved',
    'event_date'    => '2026-08-07T13:34:12-03:00',
];

$ch = curl_init("{$baseUrl}/onboarding/natural_person/{$externalId}");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Falha ao atualizar: HTTP {$status} — {$body}");
}

Node.js

const BASE_URL = "https://api.sandbox.caas.qitech.app";
const API_KEY = "YOUR_API_KEY";
const EXTERNAL_ID = "12345678";

async function updateStatus() {
  const response = await fetch(
    `${BASE_URL}/onboarding/natural_person/${EXTERNAL_ID}`,
    {
      method: "PUT",
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY,
      },
      body: JSON.stringify({
        client_status: "approved",
        event_date: "2026-08-07T13:34:12-03:00",
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Falha ao atualizar: HTTP ${response.status}`);
  }
}

updateStatus();

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class UpdateClientStatus {

    private static final String BASE_URL = "https://api.sandbox.caas.qitech.app";
    private static final String API_KEY = "YOUR_API_KEY";
    private static final String EXTERNAL_ID = "12345678";

    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "client_status": "approved",
              "event_date": "2026-08-07T13:34:12-03:00"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/onboarding/natural_person/" + EXTERNAL_ID))
                .header("Content-Type", "application/json")
                .header("Authorization", API_KEY)
                .timeout(Duration.ofSeconds(30))
                .PUT(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new IllegalStateException(
                    "Falha ao atualizar: HTTP " + response.statusCode());
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class UpdateClientStatus
{
    private const string BaseUrl = "https://api.sandbox.caas.qitech.app";
    private const string ApiKey = "YOUR_API_KEY";
    private const string ExternalId = "12345678";

    public static async Task Main()
    {
        var payload = new
        {
            client_status = "approved",
            event_date = "2026-08-07T13:34:12-03:00"
        };

        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
        client.DefaultRequestHeaders.Add("Authorization", ApiKey);

        var content = new StringContent(
            JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        var response = await client.PutAsync(
            $"{BaseUrl}/onboarding/natural_person/{ExternalId}", content);

        if (!response.IsSuccessStatusCode)
        {
            throw new InvalidOperationException(
                $"Falha ao atualizar: HTTP {(int)response.StatusCode}");
        }
    }
}

curl

curl -X PUT \
  'https://api.sandbox.caas.qitech.app/onboarding/natural_person/12345678' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{
    "client_status": "approved",
    "event_date": "2026-08-07T13:34:12-03:00"
  }'

Erros

Status	Situação	Como resolver
400	Enum fora da lista aceita.	Confira os valores aceitos para client_status e analysis_status.
400	client_status sem event_date.	Envie os dois juntos.
400	Campo não previsto no schema.	O schema usa additionalProperties: false.
404	Cadastro não encontrado para a sua API Key.	Verifique o external_id do path.

Lista completa em Status HTTP.