> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alterar Status da Transação

> Atualiza o status da transação e executa regras de atualização automaticamente — no produto de monitoramento de transações gu1 para fraude e AML.

## 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`:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Cabeçalhos Obrigatórios

```bash theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

## Parâmetros de Rota

<ParamField path="id" type="string" required>
  O UUID da transação a ser atualizada

  **Tipo**: `string` (uuid)
</ParamField>

## Corpo da Requisição

<ParamField body="status" type="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)

  **Tipo**: `enum` - `'CREATED' | 'PROCESSING' | 'SUSPENDED' | 'SENT' | 'EXPIRED' | 'DECLINED' | 'REFUNDED' | 'SUCCESSFUL'`
</ParamField>

## 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**:

1. ✅ **Aberto → Aberto**: Permitido (ex: CREATED → PROCESSING)
2. ✅ **Aberto → Fechado**: Permitido (ex: PROCESSING → SUCCESSFUL)
3. ❌ **Fechado → Aberto**: **NÃO** Permitido (ex: SUCCESSFUL → PROCESSING)
4. ❌ **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:

1. **Valida a transição** - Garante que o novo status é válido e a transição é permitida
2. **Atualiza o status** - Altera o status da transação no banco de dados
3. **Executa regras de atualização** - Executa todas as regras com `trigger: 'updated'` em seu escopo
4. **Atualiza pontuação de risco** - Recalcula o risco com base nos resultados das regras
5. **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**:

```json theme={null}
{
  "scope": {
    "triggers": ["updated"],
    "targetEntityTypes": ["transaction"]
  }
}
```

## Exemplos Completos de Requisição

### Aprovar uma Transação Suspensa

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const transactionId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(`http://api.gu1.ai/transactions/${transactionId}/changeStatus`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: 'SUCCESSFUL'
    })
  });

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  transaction_id = "550e8400-e29b-41d4-a716-446655440000"
  url = f"http://api.gu1.ai/transactions/{transaction_id}/changeStatus"

  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  payload = {
      "status": "SUCCESSFUL"
  }

  response = requests.patch(url, json=payload, headers=headers)
  result = response.json()

  print(f"Status da Transação: {result['transaction']['status']}")
  summary = result.get("rulesExecutionSummary") or {}
  print(f"Regras com match: {summary.get('matchedRulesCount', 0)}")
  ```
</CodeGroup>

### Recusar uma Transação em Revisão

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const transactionId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(`http://api.gu1.ai/transactions/${transactionId}/changeStatus`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: 'DECLINED'
    })
  });

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  transaction_id = "550e8400-e29b-41d4-a716-446655440000"
  url = f"http://api.gu1.ai/transactions/{transaction_id}/changeStatus"

  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  payload = {
      "status": "DECLINED"
  }

  response = requests.patch(url, json=payload, headers=headers)
  result = response.json()

  print(f"Status mudou de {result['statusChanged']['from']} para {result['statusChanged']['to']}")
  ```
</CodeGroup>

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

```bash theme={null}
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)

```json theme={null}
{
  "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

<ResponseField name="success" type="boolean">
  Se a mudança de status foi bem-sucedida
</ResponseField>

<ResponseField name="transaction" type="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
</ResponseField>

<ResponseField name="statusChanged" type="object">
  Informação sobre a transição de estado:

  * **from** (string) - Status anterior
  * **to** (string) - Novo status
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="object">
  **Na raiz da resposta** (alinhado a [Criar transação](/pt/api-reference/transactions/create)). **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).
</ResponseField>

## Respostas de Erro

### 400 Bad Request - Status Inválido

```json theme={null}
{
  "error": "Invalid status",
  "validStatuses": [
    "CREATED",
    "PROCESSING",
    "SUSPENDED",
    "SENT",
    "EXPIRED",
    "DECLINED",
    "REFUNDED",
    "SUCCESSFUL"
  ]
}
```

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

```json theme={null}
{
  "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

```json theme={null}
{
  "error": "Transaction not found"
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": "Failed to change transaction status",
  "details": "Internal server error message"
}
```

## Casos de Uso

### 1. Fluxo de Revisão Manual

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

1. **Validar antes de alterar** - Sempre verificar o status atual antes de tentar uma mudança de status para evitar chamadas API desnecessárias

2. **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

3. **Usar status apropriados** - Escolher o status correto que reflita o estado de negócio real da transação

4. **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

5. **Implementar registro de auditoria** - Rastrear todas as mudanças de status no seu sistema para conformidade e depuração

6. **Atualizações em massa** - Ao atualizar múltiplas transações, usar Promise.allSettled() para continuar processando mesmo se algumas atualizações falharem

7. **Integração de webhooks** - Considerar configurar webhooks para receber notificações quando mudanças de status acionarem regras importantes

8. **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

<CardGroup cols={2}>
  <Card title="Criar Transação" icon="plus" href="/pt/use-cases/transaction-monitoring/api-reference">
    Criar novas transações
  </Card>

  <Card title="Obter Transação" icon="eye" href="/pt/api-reference/transactions/get">
    Recuperar detalhes da transação
  </Card>

  <Card title="Configuração de Regras" icon="sliders" href="/pt/use-cases/transaction-monitoring/rules-configuration">
    Configurar regras de atualização
  </Card>

  <Card title="Resumo" icon="book" href="/pt/use-cases/transaction-monitoring/overview">
    Voltar ao resumo
  </Card>
</CardGroup>