# Transferências PIX

## Ciclo de Vida

### Fluxo Padrão

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /external/v1/pix/transfers
    B-->>P: 201 Created (status: PENDING)
    Note over B: Valida chave PIX e cria a transação
    P->>B: POST /external/v1/pix/transfers/{id}/approve
    B-->>P: 200 OK (status: PROCESSING)
    Note over B: Processamento assíncrono
    B-->>P: Webhook cash_out.update (SUCCESS)
```

### Fluxo com Falha na Aprovação

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /external/v1/pix/transfers
    B-->>P: 201 Created (status: PENDING)
    P->>B: POST /external/v1/pix/transfers/{id}/approve
    B-->>P: 200 OK (status: PROCESSING)
    Note over B: Processamento assíncrono
    B-->>P: Webhook cash_out.update (FAILED)
```

### Fluxo com Falha na Criação

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /external/v1/pix/transfers
    B-->>P: 201 Created (status: FAILED)
    Note over B: Falha ao criar transação pix
```

### Status

| Status       | Descrição                                  |
| ------------ | ------------------------------------------ |
| `PENDING`    | Transferência criada, aguardando aprovação |
| `PROCESSING` | Transferência aprovada, em processamento   |
| `SUCCESS`    | Transferência concluída com sucesso        |
| `FAILED`     | Transferência falhou                       |
| `RETURNED`   | Transferência estornada                    |

***

## POST /external/v1/pix/transfers

Cria uma nova transferência PIX. A transferência é criada com status `PENDING` e precisa ser aprovada via `POST /external/v1/pix/transfers/{id}/approve` para iniciar o processamento assíncrono.

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/service/banking/external/v1/pix/transfers' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "pixKey": "12345678900",
    "pixKeyType": "CPF",
    "amount": 100.00,
    "description": "Pagamento de serviço",
    "idempotencyKey": "unique-key-123"
  }'
```

### Campos — Request

| Campo            | Tipo       | Obrigatório | Validação                                                               |
| ---------------- | ---------- | ----------- | ----------------------------------------------------------------------- |
| `accountId`      | UUID       | Sim         | UUID v4 da conta bancária                                               |
| `pixKey`         | String     | Sim         | Chave PIX do destinatário. Validada conforme o tipo (ver tabela abaixo) |
| `pixKeyType`     | String     | Sim         | Enum: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`                            |
| `amount`         | BigDecimal | Sim         | Valor em reais. Mínimo: `0.01`. Ex: `100.00`                            |
| `description`    | String     | Não         | Descrição da transferência                                              |
| `idempotencyKey` | String     | Sim         | Chave única para deduplicação. Não pode estar vazio                     |

### Tipos de Chave PIX

| Tipo    | Descrição                | Formato esperado                                  |
| ------- | ------------------------ | ------------------------------------------------- |
| `CPF`   | CPF do destinatário      | 11 dígitos numéricos (ex: `12345678900`)          |
| `CNPJ`  | CNPJ do destinatário     | 14 dígitos numéricos (ex: `12345678000190`)       |
| `EMAIL` | Email do destinatário    | Formato de email válido (ex: `user@example.com`)  |
| `PHONE` | Telefone do destinatário | `+55` + DDD + número (ex: `+5511999998888`)       |
| `EVP`   | Chave aleatória          | UUID (ex: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`) |

Se o formato da chave não corresponder ao tipo informado, a API retorna **400 Bad Request** com o erro `BNK-0501`.

### Idempotência

O campo `idempotencyKey` garante a deduplicação de requisições. Se uma requisição com a mesma chave já existir, a API retorna **409 Conflict** com o erro `BNK-0316`.

**Response — 201 Created:**

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "PENDING",
  "amount": 100.00,
  "pixKey": "12345678900",
  "pixKeyType": "CPF",
  "recipientName": "João da Silva",
  "recipientDocument": "12345678900",
  "endToEndId": null,
  "description": "Pagamento de serviço",
  "idempotencyKey": "unique-key-123"
}
```

### Campos — Response

| Campo               | Tipo       | Descrição                                                                         |
| ------------------- | ---------- | --------------------------------------------------------------------------------- |
| `id`                | String     | Identificador único da transferência (UUID)                                       |
| `status`            | String     | Status da transferência: `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`, `RETURNED` |
| `amount`            | BigDecimal | Valor em reais. Ex: `100.00`                                                      |
| `pixKey`            | String     | Chave PIX utilizada                                                               |
| `pixKeyType`        | String     | Tipo da chave PIX: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`                         |
| `recipientName`     | String     | Nome do destinatário                                                              |
| `recipientDocument` | String     | Documento do destinatário (CPF/CNPJ)                                              |
| `endToEndId`        | String     | Identificador end-to-end do PIX (pode ser `null` durante processamento)           |
| `description`       | String     | Descrição da transferência (pode ser `null`)                                      |
| `idempotencyKey`    | String     | Chave de idempotência                                                             |

**Response — 400 Bad Request (campo obrigatório ausente):**

```json
{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Invalid request params",
      "description": "Error in request amount - Amount must be greater than 0"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 400 Bad Request (JSON inválido):**

```json
{
  "errors": [
    {
      "code": "BAR-0501",
      "title": "INVALID_REQUEST_PARAM",
      "description": "JSON parse error: ..."
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 403 Forbidden (sem acesso a conta):**

```json
{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 404 Not Found (conta não encontrada):**

```json
{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Business account with id f47ac10b-58cc-4372-a567-0e02b2c3d479 not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 400 Bad Request (formato de chave PIX inválido):**

```json
{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Error in request",
      "description": "Invalid PIX key format for type CPF: abc123"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 409 Conflict (idempotency key duplicada):**

```json
{
  "errors": [
    {
      "code": "BNK-0316",
      "title": "Payment flow error",
      "description": "Payment already exists for idempotency key: unique-key-123"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                                               |
| ------------------ | ------------------------------------------------------- |
| `201 Created`      | Transferência criada, aguardando aprovação              |
| `400 Bad Request`  | Dados inválidos ou campos obrigatórios ausentes         |
| `401 Unauthorized` | Token inválido ou expirado                              |
| `403 Forbidden`    | Sem acesso a conta                                      |
| `404 Not Found`    | Conta bancária não encontrada                           |
| `409 Conflict`     | Já existe uma transferência com a mesma idempotency key |

***

## GET /external/v1/pix/transfers/{id}

Consulta os detalhes de uma transferência PIX.

**Path Parameters:**

| Parâmetro | Tipo   | Descrição                             |
| --------- | ------ | ------------------------------------- |
| `id`      | String | Identificador da transferência (UUID) |

**Request:**

```bash
curl --request GET \
  --url 'https://api-banking.barte.com/service/banking/external/v1/pix/transfers/a1b2c3d4-5678-90ab-cdef-1234567890ab' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "amount": 100.00,
  "pixKey": "12345678900",
  "pixKeyType": "CPF",
  "description": "Pagamento de serviço",
  "status": "SUCCESS",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "recipient": {
    "name": "João da Silva",
    "document": "12345678900",
    "ispb": "31680151"
  },
  "failReason": null,
  "createdAt": "2026-01-30T15:30:00",
  "completedAt": "2026-01-30T15:30:05"
}
```

### Campos — Response

| Campo                | Tipo       | Descrição                                                                         |
| -------------------- | ---------- | --------------------------------------------------------------------------------- |
| `id`                 | String     | Identificador único da transferência (UUID)                                       |
| `accountId`          | String     | UUID da conta bancária                                                            |
| `amount`             | BigDecimal | Valor em reais. Ex: `100.00`                                                      |
| `pixKey`             | String     | Chave PIX utilizada                                                               |
| `pixKeyType`         | String     | Tipo da chave PIX: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`                         |
| `description`        | String     | Descrição da transferência (pode ser `null`)                                      |
| `status`             | String     | Status da transferência: `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`, `RETURNED` |
| `endToEndId`         | String     | Identificador end-to-end do PIX (pode ser `null`)                                 |
| `recipient`          | Object     | Dados do destinatário                                                             |
| `recipient.name`     | String     | Nome do destinatário                                                              |
| `recipient.document` | String     | Documento do destinatário (CPF/CNPJ)                                              |
| `recipient.ispb`     | String     | Código ISPB do banco do destinatário (pode ser `null`)                            |
| `failReason`         | String     | Motivo da falha (pode ser `null`)                                                 |
| `createdAt`          | String     | Data/hora de criação (ISO 8601)                                                   |
| `completedAt`        | String     | Data/hora de conclusão (pode ser `null`)                                          |

**Response — 403 Forbidden (sem acesso a conta):**

```json
{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 404 Not Found (transferência não encontrada):**

```json
{
  "errors": [
    {
      "code": "BNK-0301",
      "title": "Payment flow error",
      "description": "Payment not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                    |
| ------------------ | ---------------------------- |
| `200 OK`           | Detalhes da transferência    |
| `401 Unauthorized` | Token inválido ou expirado   |
| `403 Forbidden`    | Sem acesso a conta           |
| `404 Not Found`    | Transferência não encontrada |

***

## POST /external/v1/pix/transfers/{id}/approve

Aprova uma transferência PIX previamente criada.

**Path Parameters:**

| Parâmetro | Tipo   | Descrição                             |
| --------- | ------ | ------------------------------------- |
| `id`      | String | Identificador da transferência (UUID) |

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/service/banking/external/v1/pix/transfers/a1b2c3d4-5678-90ab-cdef-1234567890ab/approve' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "PROCESSING",
  "amount": 100.00,
  "pixKey": "12345678900",
  "pixKeyType": "CPF",
  "recipientName": "João da Silva",
  "recipientDocument": "12345678900",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "description": "Pagamento de serviço",
  "idempotencyKey": "unique-key-123"
}
```

**Response — 404 Not Found (transferência não encontrada):**

```json
{
  "errors": [
    {
      "code": "BNK-0301",
      "title": "Payment flow error",
      "description": "Payment not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 400 Bad Request (transferência já aprovada ou não está em CREATED):**

```json
{
  "errors": [
    {
      "code": "BNK-0302",
      "title": "Payment flow error",
      "description": "Payment already submitted"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 400 Bad Request (erro no provider):**

```json
{
  "errors": [
    {
      "code": "BNK-0313",
      "title": "Transfer domain flow error",
      "description": "Seller payment failed"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 403 Forbidden (sem acesso a conta):**

```json
{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                                                      |
| ------------------ | -------------------------------------------------------------- |
| `200 OK`           | Transferência aprovada e em processamento                      |
| `400 Bad Request`  | Transferência não está em status `CREATED` ou erro no provider |
| `401 Unauthorized` | Token inválido ou expirado                                     |
| `403 Forbidden`    | Sem acesso a conta                                             |
| `404 Not Found`    | Transferência não encontrada                                   |