Alterar Status da Transação

Endpoint

Alterar Status da Transação

PATCH http://api.gu1.ai/transactions/:id/changeStatus

Atualiza o status de uma transação existente com validação automática de transições de estado e execução opcional de regras para reavaliação de risco em tempo real. Recursos:

Validação automática de transições de estado (previne mudanças de estado inválidas)
Aplicação de máquina de estados (regras de estados abertos ↔ fechados)
Execução automática de regras de atualização com trigger trigger_transaction_updated
Proteção de integridade de transações
Rastro de auditoria completo

Autenticação

Todas as requisições devem incluir uma chave API no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Cabeçalhos Obrigatórios

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Parâmetros de Rota

string

required

O UUID da transação a ser atualizadaTipo: string (uuid)

Corpo da Requisição

status

string

required

Novo status da transação. Deve ser um valor válido do enum de status.Status Válidos:

CREATED - Transação criada (estado aberto)
PROCESSING - Transação em processamento (estado aberto)
SUSPENDED - Transação temporariamente suspensa (estado aberto)
SENT - Transação enviada/transmitida (estado fechado)
EXPIRED - Transação expirada (estado fechado)
DECLINED - Transação recusada/declinada (estado fechado)
REFUNDED - Transação reembolsada/revertida (estado fechado)
SUCCESSFUL - Transação concluída com sucesso (estado fechado)

Regras de Transição de Estados

O endpoint aplica regras estritas de transição de estados para manter a integridade das transações:

Estados Abertos

Estados que permitem transições adicionais:

CREATED
PROCESSING
SUSPENDED
SENT

Estados Fechados

Estados finais que não podem transitar para outros estados:

EXPIRED
DECLINED
REFUNDED
SUCCESSFUL

Matriz de Transições

Estado Origem	Estado Destino	Permitido?	Nota
CREATED	PROCESSING	✅ Sim	Fluxo normal
CREATED	SUSPENDED	✅ Sim	Suspender para revisão
CREATED	SUCCESSFUL	✅ Sim	Aprovação rápida
PROCESSING	SUSPENDED	✅ Sim	Suspender durante processamento
PROCESSING	SUCCESSFUL	✅ Sim	Conclusão normal
PROCESSING	DECLINED	✅ Sim	Recusar durante processamento
SUSPENDED	PROCESSING	✅ Sim	Retomar processamento
SUSPENDED	SUCCESSFUL	✅ Sim	Aprovar transação suspensa
SUSPENDED	DECLINED	✅ Sim	Recusar transação suspensa
SUCCESSFUL	PROCESSING	❌ Não	Não é possível reabrir transação fechada
DECLINED	PROCESSING	❌ Não	Não é possível reabrir transação fechada
EXPIRED	PROCESSING	❌ Não	Não é possível reabrir transação fechada
REFUNDED	any	❌ Não	Não é possível alterar transação reembolsada
SUCCESSFUL	DECLINED	❌ Não	Não é possível mudar entre estados fechados

Regras Principais:

✅ Aberto → Aberto: Permitido (ex: CREATED → PROCESSING)
✅ Aberto → Fechado: Permitido (ex: PROCESSING → SUCCESSFUL)
❌ Fechado → Aberto: NÃO Permitido (ex: SUCCESSFUL → PROCESSING)
❌ Fechado → Fechado: NÃO Permitido (ex: DECLINED → REFUNDED)

Execução de Regras de Atualização

Quando o status de uma transação é alterado, o endpoint automaticamente:

Valida a transição - Garante que o novo status é válido e a transição é permitida
Atualiza o status - Altera o status da transação no banco de dados
Executa regras de atualização - Executa todas as regras com trigger: 'updated' em seu escopo
Atualiza pontuação de risco - Recalcula o risco com base nos resultados das regras
Retorna transação atualizada - Retorna a transação completa com a nova avaliação de risco

Trigger de Regras

O endpoint usa o modo trigger_transaction_updated, que executa todas as regras configuradas com o trigger updated. Exemplo de configuração de escopo de regra:

{
  "scope": {
    "triggers": ["updated"],
    "targetEntityTypes": ["transaction"]
  }
}

Exemplos Completos de Requisição

Aprovar uma Transação Suspensa

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "SUCCESSFUL"
  }'

Recusar uma Transação em Revisão

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "DECLINED"
  }'

Suspender uma Transação para Revisão Manual

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "SUSPENDED"
  }'

Resposta

Resposta de Sucesso (200 OK)

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_12345",
    "type": "PAYMENT",
    "status": "SUCCESSFUL",
    "amount": 1500.00,
    "currency": "USD",
    "amountInUsd": 1500.00,
    "origin": {
      "entityId": "customer_001",
      "externalId": "EXT-001",
      "name": "João Silva",
      "country": "US",
      "details": {},
      "type": "person",
      "riskScore": 15.50
    },
    "destination": {
      "entityId": "merchant_002",
      "externalId": "MER-002",
      "name": "Loja de Eletrônicos",
      "country": "US",
      "details": {},
      "type": "company",
      "riskScore": 8.20
    },
    "riskScore": 22.50,
    "riskFactors": [
      {
        "factor": "status_change",
        "score": 5,
        "description": "Status da transação mudou para SUCCESSFUL"
      }
    ],
    "flagged": false,
    "description": "Compra de laptop",
    "category": "electronics",
    "metadata": {},
    "transactedAt": "2024-12-23T14:30:00.000Z",
    "createdAt": "2024-12-23T14:30:00.000Z",
    "updatedAt": "2024-12-23T15:45:00.000Z"
  },
  "statusChanged": {
    "from": "SUSPENDED",
    "to": "SUCCESSFUL"
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 3,
    "executionTimeMs": 245,
    "result": {
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityType": "transaction",
      "rulesExecuted": [
        {
          "ruleId": "rule_001",
          "ruleName": "Verificação de Transações de Alto Valor",
          "passed": true,
          "score": 5
        }
      ],
      "totalRules": 3,
      "successfulRules": 3,
      "failedRules": 0,
      "overallConfidence": 0.95,
      "riskScore": 22.50,
      "flags": []
    },
    "auditId": "audit_12345",
    "isNewAudit": false
  }
}

Campos de Resposta

success

boolean

Se a mudança de status foi bem-sucedida

transaction

object

A transação atualizada com todos os seus dados, incluindo:

id (string) - UUID da transação
status (string) - Novo status da transação
origin (object) - Informação da parte origem (estrutura aninhada)
- entityId (string) - UUID da entidade origem
- name (string) - Nome da parte origem
- country (string) - País de origem
- details (object) - Detalhes adicionais de origem
- type (string) - Tipo de entidade origem
- riskScore (number) - Pontuação de risco da entidade origem
destination (object) - Informação da parte destino (estrutura aninhada)
- entityId (string) - UUID da entidade destino
- name (string) - Nome da parte destino
- country (string) - País de destino
- details (object) - Detalhes adicionais de destino
- type (string) - Tipo de entidade destino
- riskScore (number) - Pontuação de risco da entidade destino
riskScore (number) - Pontuação de risco atualizada após reavaliação
riskFactors (array) - Fatores de risco atualizados
flagged (boolean) - Status de sinalização atualizado
updatedAt (string) - Timestamp da atualização

statusChanged

object

Informação sobre a transição de estado:

from (string) - Status anterior
to (string) - Novo status

rulesResult

object

Resultado completo da execução de regras de atualização (RulesExecutionResult):

success (boolean) - Se as regras foram executadas com sucesso
executed (boolean) - Se alguma regra foi executada
result (object | undefined) - Resultado da análise de entidade com detalhes de execução de regras
rulesTriggered (number | undefined) - Número de regras que foram executadas
executionTimeMs (number | undefined) - Tempo de execução em milissegundos
error (string | undefined) - Mensagem de erro se a execução falhou
auditId (string | undefined) - ID do registro de auditoria
isNewAudit (boolean | undefined) - Se uma nova auditoria foi criada
warnings (array | undefined) - Array de mensagens de aviso
metadata (object | undefined) - Metadata adicional incluindo resumo de cobertura, campos faltantes e recomendações
rulesExecutionSummary (object | undefined) - Quando as regras foram executadas, resumo detalhado; ver abaixo

rulesExecutionSummary

object

Na raiz da resposta (igual à API de transações). Mesmo valor que rulesResult.rulesExecutionSummary. Apenas presente quando as regras foram executadas. Resumo de quais regras deram match (hit) vs não deram (no hit), ações executadas e pontuação total.

rulesHit (array) - Regras cujas condições foram atendidas. Cada item: name, description, score, priority, category, status, conditions, actions.
rulesNoHit (array) - Regras avaliadas mas condições não atendidas. Mesma estrutura que rulesHit.
actionsExecuted (object) - Ações executadas agregadas: alerts, suggestion, status, assignedUser, customKeys (array de strings, opcional) — chaves de ações personalizadas das regras que deram match; para integrações/workflows.
totalScore (number) - Soma da pontuação de todas as regras que deram hit (excluindo shadow).

Respostas de Erro

400 Bad Request - Status Inválido

{
  "error": "Invalid status",
  "validStatuses": [
    "CREATED",
    "PROCESSING",
    "SUSPENDED",
    "SENT",
    "EXPIRED",
    "DECLINED",
    "REFUNDED",
    "SUCCESSFUL"
  ]
}

400 Bad Request - Transição Inválida

{
  "error": "Cannot transition from closed status to open status",
  "currentStatus": "SUCCESSFUL",
  "requestedStatus": "PROCESSING",
  "message": "Transaction is in a closed state (SUCCESSFUL) and cannot be reopened"
}

404 Not Found

{
  "error": "Transaction not found"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to change transaction status",
  "details": "Internal server error message"
}

Casos de Uso

1. Fluxo de Revisão Manual

// Passo 1: Suspender transação suspeita
await changeStatus(transactionId, 'SUSPENDED');

// Passo 2: Analista revisa a transação
// ... processo de revisão manual ...

// Passo 3: Aprovar ou recusar conforme a revisão
if (approved) {
  await changeStatus(transactionId, 'SUCCESSFUL');
} else {
  await changeStatus(transactionId, 'DECLINED');
}

2. Verificação Automática de Conformidade

// Transação criada com status CREATED
const transaction = await createTransaction({...});

// Executar verificações de conformidade adicionais
const complianceResult = await runComplianceChecks(transaction.id);

if (complianceResult.passed) {
  // Mover para processamento
  await changeStatus(transaction.id, 'PROCESSING');

  // Completar transação
  await changeStatus(transaction.id, 'SUCCESSFUL');
} else {
  // Recusar por problemas de conformidade
  await changeStatus(transaction.id, 'DECLINED');
}

3. Resposta à Detecção de Fraude

// Monitorar atualizações de transações
if (fraudDetected) {
  // Suspender transação imediatamente
  await changeStatus(transactionId, 'SUSPENDED');

  // Criar alerta para investigação
  await createAlert({
    transactionId,
    type: 'fraud_suspected',
    severity: 'high'
  });

  // Após a investigação, tomar ação
  if (confirmed) {
    await changeStatus(transactionId, 'DECLINED');
  } else {
    await changeStatus(transactionId, 'SUCCESSFUL');
  }
}

4. Atualizações em Massa de Status

// Atualizar múltiplas transações em paralelo
const suspendedTransactions = await getTransactionsByStatus('SUSPENDED');

const results = await Promise.allSettled(
  suspendedTransactions.map(async (txn) => {
    if (shouldApprove(txn)) {
      return await changeStatus(txn.id, 'SUCCESSFUL');
    } else if (shouldDecline(txn)) {
      return await changeStatus(txn.id, 'DECLINED');
    }
  })
);

console.log(`Atualizadas ${results.filter(r => r.status === 'fulfilled').length} transações`);

Melhores Práticas

Validar antes de alterar - Sempre verificar o status atual antes de tentar uma mudança de status para evitar chamadas API desnecessárias
Tratar erros de transição - Implementar tratamento de erros apropriado para transições inválidas, já que transações fechadas não podem ser reabertas
Usar status apropriados - Escolher o status correto que reflita o estado de negócio real da transação
Monitorar execução de regras - Prestar atenção ao objeto rulesResult para garantir que as regras de atualização sejam executadas conforme esperado e verificar detalhes de execução, avisos e metadata
Implementar registro de auditoria - Rastrear todas as mudanças de status no seu sistema para conformidade e depuração
Atualizações em massa - Ao atualizar múltiplas transações, usar Promise.allSettled() para continuar processando mesmo se algumas atualizações falharem
Integração de webhooks - Considerar configurar webhooks para receber notificações quando mudanças de status acionarem regras importantes
Testar transições de estado - Testar todas as possíveis transições de estado no seu ambiente de desenvolvimento antes de implantar em produção

Endpoints Relacionados

Criar Transação

Criar novas transações

Obter Transação

Recuperar detalhes da transação

Configuração de Regras

Configurar regras de atualização

Resumo

Voltar ao resumo

Começando

Casos de Uso

Webhooks

Pessoa

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Enriquecimento

Integrações

Tutoriais Interativos

​Endpoint