> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Exemplos de Uso

Esta página apresenta exemplos práticos de como interagir com a API CorpX usando cURL, na ordem lógica de uma integração típica.

## Variáveis de Ambiente

Configure estas variáveis antes de executar os exemplos:

```bash
# OAuth Credentials (provided during onboarding)
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

# Account identifiers
export TENANT_ID="your-tenant-uuid"
export ACCOUNT_ID="your-account-uuid"

# Environment URLs
export API_URL="https://tenant.api.corpx.com"
export AUTH_URL="https://auth.api.corpx.com"
```

---

## 1. Autenticação

O primeiro passo é obter um access token OAuth2 utilizando suas credenciais de cliente.

```bash
curl -X POST "${AUTH_URL}/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=${CLIENT_ID}" \
     -d "client_secret=${CLIENT_SECRET}"
```

**Resposta de sucesso:**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300
}
```

Armazene o token para uso nas chamadas subsequentes:

```bash
export JWT="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

---

## 2. Consultar Saldo

Consulte o saldo disponível e bloqueado da sua conta em tempo real.

```bash
curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/balance" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"
```

**Resposta:**

```json
{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "total": 15000.00,
  "locked": 500.00,
  "available": 14500.00,
  "currency": "BRL",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

> **Info**
>
> O saldo é lido em tempo real do parceiro. `locked` é apenas o valor bloqueado
> informado pela liquidante (não há detalhamento `locks[]` nem endpoint de
> lock/unlock nesta API).

---

## 3. Gerar QR Code Dinâmico (Recebimento)

Gere um QR Code dinâmico para receber um pagamento PIX de um valor específico.

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/dynamic" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "pixKey": "contact@mycompany.com",
       "value": 150.00,
       "expirationDate": "2024-12-31T23:59:59Z",
       "allowChangeValue": false,
       "message": "Payment for order #12345",
       "identifier": "order-12345",
     }'
```

| Valor   | Descrição                            |
| ------- | ------------------------------------ |
| `IMAGE` | Retorna uma imagem Base64 do QR Code |
| `EMV`   | Retorna apenas a string copia e cola |

---

## 4. Gerar QR Code Estático

QR Codes estáticos não expiram e são ideais para exibição permanente.

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/static" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "pixKey": "contact@mycompany.com",
       "value": 50.00,
       "message": "Donation to project XYZ",
       "identifier": "doacao-xyz-001",
     }'
```

---

## 5. Consultar Status do QR Code

Verifique se o QR Code gerado anteriormente foi pago ou ainda está pendente.

```bash
curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/lookup?identifier=order-12345" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"
```

---

## 6. PIX Out (Transferência via Chave)

Envie um PIX para uma chave de terceiros (transferência de saída).

> **Precisa enviar PIX sem chave PIX?** Se você possui apenas os dados bancários do destinatário (ISPB, agência e conta), utilize o endpoint específico `POST /v1/accounts/{accountId}/pix/out/bank-account`. Veja o [changelog v1.27.0](/baas/changelog#v1270-2026-04-14---pix-out-por-dados-bancários) para detalhes.

### 6.1 PIX para CPF

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 150.00,
       "currency": "BRL",
       "keyType": "CPF",
       "key": "12345678900",
       "description": "Service payment",
       "identifier": "order-456"
     }'
```

### 6.2 PIX para Email

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 75.50,
       "currency": "BRL",
       "keyType": "EMAIL",
       "key": "supplier@company.com",
       "description": "Pagamento NF 789"
     }'
```

### 6.3 PIX para Telefone

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 200.00,
       "currency": "BRL",
       "keyType": "PHONE",
       "key": "+5511999999999",
       "description": "Transfer"
     }'
```

### 6.4 PIX para Chave Aleatória (EVP)

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 500.00,
       "currency": "BRL",
       "keyType": "EVP",
       "key": "123e4567-e89b-12d3-a456-426614174000",
       "description": "Pagamento de fornecedor"
     }'
```

**Valores para `keyType`:**

| Valor   | Descrição                | Formato                      |
| ------- | ------------------------ | ---------------------------- |
| `CPF`   | CPF do destinatário      | 11 dígitos (somente números) |
| `CNPJ`  | CNPJ do destinatário     | 14 dígitos (somente números) |
| `EMAIL` | Email do destinatário    | Email válido                 |
| `PHONE` | Telefone do destinatário | +55 + DDD + número           |
| `EVP`   | Chave aleatória          | UUID v4                      |

**Resposta de sucesso:**

```json
{
  "transactionId": "txn-abc123-def456",
  "status": "APPROVED",
  "endToEndId": "E12345678202401151234abcdefghijkl",
  "amount": 150.00,
  "currency": "BRL"
}
```

**Valores para `status`:**

| Valor        | Descrição                                |
| ------------ | ---------------------------------------- |
| `APPROVED`   | Transferência aprovada e concluída       |
| `PENDING`    | Aguardando confirmação do banco          |
| `PROCESSING` | Em processamento                         |
| `REJECTED`   | Rejeitada (verifique a mensagem de erro) |

### 6.5 Consultar Status da Transferência

Consulte o status de uma transferência usando o E2E ID:

```bash
curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/transactions?endToEndId=E12345678202401151234abcdefghijkl" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"
```

**Resposta:** o mesmo envelope do extrato (`items[]`), com 0 ou 1 item.
`direction` é `OUT` (enviado) ou `IN` (recebido) e `amount` é negativo na
saída. Transação inexistente não é `404`: vem `200` com `items: []`.

```json
{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "source": "live",
  "page": 0,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1,
  "hasNext": false,
  "items": [
    {
      "endToEndId": "E12345678202401151234abcdefghijkl",
      "direction": "OUT",
      "transactionType": "D",
      "operation": "PIX",
      "status": "COMPLETED",
      "amount": -150.00,
      "currency": "BRL",
      "description": "Pedido 12345",
      "identifier": "order-12345",
      "timestamp": "2024-01-15T12:34:00-03:00",
      "counterParty": {
        "name": "MARIA DA SILVA",
        "document": "12345678900",
        "bankCode": "001"
      }
    }
  ],
  "fetchedAt": "2024-01-15T15:34:05Z"
}
```

**Parâmetros de consulta:**

| Parâmetro    | Descrição                               |
| ------------ | --------------------------------------- |
| `accountId`  | ID da conta (obrigatório, no path)      |
| `endToEndId` | ID E2E da transação                     |
| `identifier` | Identificador da cobrança ou referência |

> **Nota**: informe `endToEndId` ou `identifier`. Sem nenhum dos dois, a rota
> devolve o extrato paginado, como `GET /statement`.

---

## 7. Pagar QR Code (PIX Out via EMV)

Pague um QR Code PIX utilizando a string EMV (copia e cola). Preferir o
fluxo **assíncrono** (`/pix/out/qr-code/async`). O sync
(`/pix/out/qr-code`) está **deprecated** (Sunset 2026-11-21).

### 7.1 Pagar QR Code assíncrono (recomendado, 202 imediato)

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/qr-code/async" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540010.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304EFGH",
       "amount": 150.00,
       "description": "Service payment",
       "identifier": "pay-qr-async-001"
     }'
```

Resposta `202` com `status: "ACCEPTED"`. O resultado final chega por webhook
(`pix.out.completed` / `failed` / `timeout`) ou via lookup por `identifier`.

### 7.2 \[DEPRECATED] Pagar QR Code síncrono

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/qr-code" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540510.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304ABCD",
       "amount": 150.00,
       "description": "Pagamento de compra online"
     }'
```

Retorna headers `Deprecation` / `Sunset` / `Link`. Migre para `/qr-code/async`.

---

## 8. Solicitar Devolução

Devolva um PIX recebido anteriormente (**estorno total** — `amount` deve ser igual ao valor original).

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/refund" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "originalEndToEnd": "E12345678202401101234abcdefghijkl",
       "amount": 150.00,
       "currency": "BRL",
       "reason": "Product not available in stock"
     }'
```

**Resposta:**

```json
{
  "refundId": "ref-abc123-def456",
  "status": "PROCESSING",
  "amount": 150.00,
  "currency": "BRL"
}
```

**Valores para `status` da devolução:**

| Valor        | Descrição                       |
| ------------ | ------------------------------- |
| `PROCESSING` | Devolução em processamento      |
| `COMPLETED`  | Devolução concluída com sucesso |
| `REJECTED`   | Devolução rejeitada             |

---

## 9. Listar Transações Recentes (Extrato)

Recupere o histórico recente de transações da conta.

```bash
curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/statement?limit=10&order=desc" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"
```

**Parâmetros de consulta:**

| Parâmetro   | Tipo     | Descrição                                                                        |
| ----------- | -------- | -------------------------------------------------------------------------------- |
| `page`      | integer  | Índice da página (base 0)                                                        |
| `size`      | integer  | Teto da página (máx. 100). `items` pode ter menos entradas; avance com `hasNext` |
| `startDate` | datetime | Filtro de data inicial (ISO 8601)                                                |
| `endDate`   | datetime | Filtro de data final (ISO 8601)                                                  |
| `limit`     | integer  | Limite total de registros (máx. 1000)                                            |
| `order`     | string   | Ordem de classificação: `asc` ou `desc`                                          |

---

## 10. Gerenciar Chaves PIX

### 10.1 Listar Chaves PIX

```bash
curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"
```

### 10.2 Registrar uma Nova Chave PIX

> **E-mail e telefone exigem OTP**
>
> `POST /v1/accounts/{accountId}/pix/keys` com `email` ou `phone` responde **202** e a facade envia o código. Confirme em `POST .../pix/keys/verify`. Falha de envio é **503** `otp_send_failed`.

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "cpf",
       "pixKey": "12345678900"
     }'
```

**Valores para `keyType` no cadastro:**

| Valor    | Descrição                                                   |
| -------- | ----------------------------------------------------------- |
| `cpf`    | CPF do titular da conta                                     |
| `cnpj`   | CNPJ do titular da conta                                    |
| `random` | Chave aleatória (EVP) - gerada automaticamente pelo sistema |
| `phone`  | Telefone E.164 — 202 + OTP (Twilio)                         |
| `email`  | E-mail — 202 + OTP (SES)                                    |

### 10.3 Registrar uma Chave Aleatória (EVP)

Para chaves aleatórias, omita o campo `pixKey`:

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "random"
     }'
```

### 10.4 Excluir uma Chave PIX

```bash
curl -X DELETE "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys/contact%40mycompany.com" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"
```

---

## 11. Consultar MEDs (Mecanismo Especial de Devolução)

Liste as disputas abertas contra a conta. A lista é montada a partir dos
webhooks `pix.med.opened` / `pix.med.updated` — sem assiná-los ela fica vazia.
Ver [Disputas (MED)](/baas/guias/pagar/med).

```bash
curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med?limit=20" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"
```

**Parâmetros:**

| Parâmetro | Valores | Descrição                             |
| --------- | ------- | ------------------------------------- |
| `limit`   | integer | Máximo de itens (padrão 50, teto 200) |
| `offset`  | integer | Deslocamento para paginar             |

Não há filtro por status: a API não expõe status de disputa. O liquidante não
tem consulta de relato, então o estado atual não é verificável — o que a API
mostra é `answered` (se você respondeu) e o prazo.

### 11.1 Anexar evidência

Três passos, e todos antes de responder — anexo depois da resposta não entra na
defesa (`409 conflict`).

```bash
# 1. URL de upload
PRESIGN=$(curl -sS -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/${MED_ID}/evidence/upload-url" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{"filename":"comprovante.pdf","contentType":"application/pdf","sizeBytes":184320}')

UPLOAD_URL=$(echo "$PRESIGN" | jq -r .uploadUrl)
KEY=$(echo "$PRESIGN" | jq -r .key)

# 2. PUT direto no armazenamento (sem header de auth nosso)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @comprovante.pdf

# 3. Registrar o anexo na disputa
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/${MED_ID}/evidence/add" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d "{\"key\":\"${KEY}\",\"filename\":\"comprovante.pdf\",\"contentType\":\"application/pdf\",\"sizeBytes\":184320}"
```

Limites: 5 MB por arquivo, 6 MB e 10 arquivos por disputa, e só
PDF/JPEG/PNG/WebP/TXT/CSV. Cada arquivo passa por antivírus e sanitização
antes de valer como evidência (`scanStatus`).

### 11.2 Responder a um MED

O titular tem **48h** desde a abertura (`clientAnswerDeadline`) para se
defender. A resposta é enviada **uma vez**: a segunda chamada recebe
`409 conflict`.

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/204cc938-da3d-4f04-baf3-0b2e6a2f1283/answer" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{
       "result": "DISAGREE",
       "reason": "Venda legítima: cliente cadastrado há 14 meses, entrega com rastreio confirmado."
     }'
```

**Valores para `result`:**

| Valor      | Descrição                                                         |
| ---------- | ----------------------------------------------------------------- |
| `AGREE`    | Reconhece a fraude relatada                                       |
| `DISAGREE` | Contesta o relato. Exige `reason` (`422 invalid_payload` sem ele) |

A resposta é `202`. Ela registra a sua defesa e a encaminha, com os anexos, ao
time que conduz a disputa — nada é enviado ao liquidante por esta chamada e
nenhum status muda. Não existe rota de decisão: devolver ou recusar o PIX
disputado não é feito por esta API.

---

## 12. Transferência Interna

Transfira fundos entre contas do mesmo banco (sem custo, instantânea).

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/transfers/internal" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "branch": "0001",
       "account": "123456-7",
       "taxNumber": "12345678900",
       "value": 500.00,
       "message": "Transfer between accounts",
       "identifier": "transf-int-12345"
     }'
```

---

## Tratamento de Erros Comuns

### Saldo Insuficiente

```json
{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}
```

### Chave PIX Inválida

```json
{
  "errorCode": "invalid_payload",
  "message": "keyType must be one of: CPF, CNPJ, EMAIL, PHONE, EVP"
}
```

### Conflito de Idempotência

```json
{
  "errorCode": "idempotency_conflict",
  "message": "Request with same Idempotency-Key but different payload"
}
```

---

## Boas Práticas

1. **Sempre use Idempotency-Key** em operações POST/PUT/PATCH para evitar duplicidades
2. **Armazene o `endToEndId`** das transações para rastreamento e devoluções
3. **Implemente retry com backoff exponencial** para erros 5xx
4. **Valide o saldo** antes de operações de saída para melhor experiência do usuário
5. **Configure webhooks** para receber notificações em tempo real

---

Para mais detalhes sobre cada endpoint, consulte a [Referência da API](/baas/referencia) ou o [Guia de Integração](/baas/guias/comece-aqui/guia-do-integrador).