Alterar Status da Transação

curl --request PATCH \
  --url http://api.gu1.ai/transactions/:id/changeStatus \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "<string>"
}
'

{
  "success": true,
  "transaction": {},
  "statusChanged": {},
  "rulesExecutionSummary": {}
}

PATCH

transactions

:id

changeStatus

Alterar Status da Transação

curl --request PATCH \
  --url http://api.gu1.ai/transactions/:id/changeStatus \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "<string>"
}
'

{
  "success": true,
  "transaction": {},
  "statusChanged": {},
  "rulesExecutionSummary": {}
}

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/matrizes com trigger transaction_status_changed (não 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_status_changed, que executa regras com action: "status_changed" ou matrizes com eventType: "transaction_status_changed". O trigger updated fica para PATCH /transactions/{id} (metadata, deviceDetails, channel, reason). 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"
  },
  "rulesExecutionSummary": {
    "rulesHit": [
      {
        "name": "Verificação de Transações de Alto Valor",
        "score": 5,
        "status": "active"
      }
    ],
    "rulesNoHit": [],
    "totalScore": 22.5,
    "matchedRulesCount": 3,
    "executionTimeMs": 245,
    "trigger": "status_change"
  }
}

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

rulesExecutionSummary

object

Na raiz da resposta (alinhado a Criar transação). 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 a rulesExecutionSummary 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

Endpoint Criar Transação para Monitoramento Visão Geral de Webhooks

⌘I

​Endpoint

​Alterar Status da Transação

​Autenticação

​Cabeçalhos Obrigatórios

​Parâmetros de Rota

​Corpo da Requisição

​Regras de Transição de Estados

​Estados Abertos

​Estados Fechados

​Matriz de Transições

​Execução de Regras de Atualização

​Trigger de Regras

​Exemplos Completos de Requisição

​Aprovar uma Transação Suspensa

​Recusar uma Transação em Revisão

​Suspender uma Transação para Revisão Manual

​Resposta

​Resposta de Sucesso (200 OK)

​Campos de Resposta

​Respostas de Erro

​400 Bad Request - Status Inválido

​400 Bad Request - Transição Inválida

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​1. Fluxo de Revisão Manual

​2. Verificação Automática de Conformidade

​3. Resposta à Detecção de Fraude

​4. Atualizações em Massa de Status

​Melhores Práticas

​Endpoints Relacionados

Criar Transação

Obter Transação

Configuração de Regras

Resumo

Endpoint

Alterar Status da Transação

Autenticação

Cabeçalhos Obrigatórios

Parâmetros de Rota

Corpo da Requisição

Regras de Transição de Estados

Estados Abertos

Estados Fechados

Matriz de Transições

Execução de Regras de Atualização

Trigger de Regras

Exemplos Completos de Requisição

Aprovar uma Transação Suspensa

Recusar uma Transação em Revisão

Suspender uma Transação para Revisão Manual

Resposta

Resposta de Sucesso (200 OK)

Campos de Resposta

Respostas de Erro

400 Bad Request - Status Inválido

400 Bad Request - Transição Inválida

404 Not Found

401 Unauthorized

500 Internal Server Error

Casos de Uso

1. Fluxo de Revisão Manual

2. Verificação Automática de Conformidade

3. Resposta à Detecção de Fraude

4. Atualizações em Massa de Status

Melhores Práticas

Endpoints Relacionados