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:

# 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://api.corpxapi.com"
export AUTH_URL="https://auth.corpxapi.com"

1. Autenticação

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

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:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Armazene o token para uso nas chamadas subsequentes:

export JWT="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

2. Consultar Saldo

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

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

Resposta:

{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "total": 15000.00,
  "locked": 500.00,
  "available": 14500.00,
  "currency": "BRL",
  "updatedAt": "2024-01-15T10:30:00Z",
  "locks": [
    {
      "lockId": "lock-abc123",
      "amount": 500.00,
      "currency": "BRL",
      "reason": "MED investigation",
      "medId": "med-12345",
      "status": "active",
      "createdAt": "2024-01-10T14:00:00Z"
    }
  ]
}

3. Gerar QR Code Dinâmico (Recebimento)

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

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.

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.

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code?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 para detalhes.

6.1 PIX para CPF

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

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

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)

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:

{
  "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:

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

Resposta:

{
  "transactionId": "txn-abc123-def456",
  "endToEndId": "E12345678202401151234abcdefghijkl",
  "status": "COMPLETED",
  "type": "CASH_OUT",
  "amount": -150.00,
  "currency": "BRL",
  "description": "PIX - MARIA DA SILVA",
  "transactionDate": "2024-01-15T12:34:00Z",
  "counterparty": {
    "name": "MARIA DA SILVA",
    "document": "123***01",
    "bankCode": "001"
  },
  "balance": 14350.00
}

Parâmetros de consulta:

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

Nota: Pelo menos um dos parâmetros endToEndId ou identifier é obrigatório.

7. Pagar QR Code (PIX Out via EMV)

Pague um QR Code PIX utilizando a string EMV (copia e cola).

7.1 Pagar QR Code Dinâmico (valor pré-definido)

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",
       "description": "Pagamento de compra online"
     }'

7.2 Pagar QR Code Estático (especificando valor)

Para QR Codes estáticos sem valor definido, o campo amount é obrigatório:

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-426614174000520400005303986540010.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304EFGH",
       "amount": 150.00,
       "description": "Service payment"
     }'

Resposta de sucesso:

{
  "transactionId": "txn-qr-abc123",
  "status": "APPROVED",
  "endToEndId": "E12345678202401151234mnopqrstuvwx",
  "amount": 150.00,
  "currency": "BRL"
}

8. Solicitar Devolução

Devolva um PIX recebido anteriormente (total ou parcialmente).

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:

{
  "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.

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	Tamanho da página (máx. 500)
`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

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

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": "email",
       "pixKey": "financeiro@minhaempresa.com.br"
     }'

Valores para keyType no cadastro:

Valor	Descrição
`cpf`	CPF do titular da conta
`cnpj`	CNPJ do titular da conta
`phone`	Número de telefone (+5511999999999)
`email`	Endereço de email
`random`	Chave aleatória (EVP) - gerada automaticamente pelo sistema

10.3 Registrar uma Chave Aleatória (EVP)

Para chaves aleatórias, omita o campo pixKey:

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

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)

Consulte infrações e disputas abertas via MED.

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

Parâmetros de filtro:

Parâmetro	Valores	Descrição
`status`	`OPEN`, `IN_PROGRESS`, `CLOSED`, `CANCELED`	Status do MED
`responseStatus`	`PENDING`, `AGREED`, `DISAGREED`	Status da resposta
`minAmount`	number	Valor mínimo
`maxAmount`	number	Valor máximo
`from`	datetime	Data inicial
`to`	datetime	Data final
`limit`	integer	Limite de resultados
`cursor`	string	Cursor de paginação

11.1 Responder a um MED

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/med-12345/response" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{
       "answer": "DISCORDO",
       "message": "Legitimate transaction as per attached receipts",
       "evidences": [
         {
           "order": 1,
           "description": "Comprovante de entrega",
           "url": "https://storage.exemplo.com/evidencia1.pdf"
         }
       ]
     }'

Valores para answer:

Valor	Descrição
`CONCORDO`	Aceita a devolução solicitada
`DISCORDO`	Contesta a solicitação de devolução

12. Transferência Interna

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

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

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

Chave PIX Inválida

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

Conflito de Idempotência

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

Boas Práticas

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

Para mais detalhes sobre cada endpoint, consulte a Referência da API ou o Guia de Integração.

Variáveis de Ambiente​

1. Autenticação​

2. Consultar Saldo​

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

4. Gerar QR Code Estático​

5. Consultar Status do QR Code​

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

6.1 PIX para CPF​

6.2 PIX para Email​

6.3 PIX para Telefone​

6.4 PIX para Chave Aleatória (EVP)​

6.5 Consultar Status da Transferência​

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

7.1 Pagar QR Code Dinâmico (valor pré-definido)​

7.2 Pagar QR Code Estático (especificando valor)​

8. Solicitar Devolução​

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

10. Gerenciar Chaves PIX​

10.1 Listar Chaves PIX​

10.2 Registrar uma Nova Chave PIX​

10.3 Registrar uma Chave Aleatória (EVP)​

10.4 Excluir uma Chave PIX​

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

11.1 Responder a um MED​

12. Transferência Interna​

Tratamento de Erros Comuns​

Saldo Insuficiente​

Chave PIX Inválida​

Conflito de Idempotência​

Boas Práticas​

Variáveis de Ambiente

1. Autenticação

2. Consultar Saldo

3. Gerar QR Code Dinâmico (Recebimento)

4. Gerar QR Code Estático

5. Consultar Status do QR Code

6. PIX Out (Transferência via Chave)

6.1 PIX para CPF

6.2 PIX para Email

6.3 PIX para Telefone

6.4 PIX para Chave Aleatória (EVP)

6.5 Consultar Status da Transferência

7. Pagar QR Code (PIX Out via EMV)

7.1 Pagar QR Code Dinâmico (valor pré-definido)

7.2 Pagar QR Code Estático (especificando valor)

8. Solicitar Devolução

9. Listar Transações Recentes (Extrato)

10. Gerenciar Chaves PIX

10.1 Listar Chaves PIX

10.2 Registrar uma Nova Chave PIX

10.3 Registrar uma Chave Aleatória (EVP)

10.4 Excluir uma Chave PIX

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

11.1 Responder a um MED

12. Transferência Interna

Tratamento de Erros Comuns

Saldo Insuficiente

Chave PIX Inválida

Conflito de Idempotência

Boas Práticas