API · Ordens

Criar ordem

POST /api/crypto/v1/orders — crie uma cobrança ou intenção de pagamento.

POST /api/crypto/v1/orders

Cria uma ordem sem chave de API: o endereço EVM informado determina o destino do lojista. Envie Content-Type: application/json. A operação pode gerar uma ordem diretamente ou uma intenção de seleção.

Corpo

Campo Obrigatório Regras
amountBRL Sim Número de 1 a 50000; arredondado a centavos. Sujeito ao mínimo da rede.
wallet.address Sim Endereço EVM de 40 dígitos hexadecimais.
wallet.affiliates Não Até 10 objetos com address e bps; cada bps entre 1 e 10000, soma até 10000.
token Não USDT, USDC, BRZ, EURC ou auto, sujeitos à disponibilidade.
chain Não Identificador retornado por /chains ou auto.
acceptedTokens Não Lista de 1 a 6 símbolos conhecidos que podem ser escolhidos na troca de ativo.
description Não Texto, limitado a 200 caracteres.
cartId Não Identificador do lojista; letras, números, _ e -, até 64 caracteres.
webhookUrl Não URL HTTPS para notificações da ordem.

Exemplo

Substitua os endereços de exemplo pelos das suas carteiras. Não envie chaves privadas.

curl -X POST https://api.caedral.com/api/crypto/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{"amountBRL":149.90,"cartId":"PED-1042","wallet":{"address":"0x1111111111111111111111111111111111111111","affiliates":[{"address":"0x2222222222222222222222222222222222222222","bps":500}]},"token":"USDC","chain":"base","webhookUrl":"https://loja.example/webhooks/caedral"}'

Resposta 201

Uma ordem direta retorna ref, status, amountBRL, cryptoAmount, feeAmount, netAmount, token, tokenDecimals, chain, chainId, recipient, contractAddress, feeBps, paymentUrl, paymentUri, qrCodeUrl, statusUrl, expiresAt, payableUntil, createdAt, paidAt, txHash e outros detalhes. Campos podem ser nulos antes da confirmação. ref é um identificador hexadecimal de 32 bytes, com prefixo 0x; guarde-a para acompanhar a cobrança.

Se webhookUrl foi enviada, webhook.secret aparece apenas na criação. Guarde-o em segredo para validar a assinatura. Veja Webhooks.

Se tanto token quanto chain forem omitidos, a resposta contém selectionRequired: true, intentId, expiresAt e options; confirme a escolha em Confirmar intenção. O código atual não preserva o webhook nesse fluxo: para receber notificações por pedido, informe token ou rede na criação.

Erros e limites

400 indica dados inválidos ou falha ao criar a ordem; 429 indica limite de 30 criações/confirmações por IP em cinco minutos, compartilhado entre as rotas. Respeite Retry-After. O limite é em memória por processo; não dependa dele como garantia de capacidade.

Exemplo de resposta 201

Os valores são ilustrativos e variam conforme o ambiente e a ordem.

{
  "ref": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "amountBRL": 149.9,
  "cryptoAmount": "28.000000",
  "feeAmount": "0.280000",
  "minFeeAmount": "0.10",
  "feeModel": null,
  "netAmount": "27.720000",
  "token": "USDC",
  "tokenLabel": "USD Coin",
  "tokenDecimals": 6,
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chain": "base",
  "chainId": 8453,
  "chainParams": {
    "chainIdHex": "0x2105",
    "chainName": "Base",
    "rpcUrls": [
      "https://mainnet.base.org"
    ],
    "nativeSymbol": "ETH",
    "blockExplorerUrls": [
      "https://basescan.org"
    ]
  },
  "recipient": "0x1111111111111111111111111111111111111111",
  "contractAddress": "0x3333333333333333333333333333333333333333",
  "contractVersion": "v4",
  "feeBps": 100,
  "paymentUrl": "https://pay.example/pay/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "paymentUri": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x3333333333333333333333333333333333333333&uint256=28000000",
  "qrCodeUrl": "https://api.caedral.com/api/crypto/v1/orders/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/qr",
  "statusUrl": "https://api.caedral.com/api/crypto/v1/orders/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "expiresAt": "2026-11-08T18:15:00.000Z",
  "payableUntil": "2026-11-08T19:00:00.000Z",
  "createdAt": "2026-11-08T18:00:00.000Z",
  "paidAt": null,
  "txHash": null,
  "description": "Pedido PED-1042",
  "webhook": {
    "url": "https://loja.example/webhooks/caedral",
    "secret": "whsec_EXEMPLO_GUARDE_EM_SEGURANCA",
    "note": "Recebe payment.confirmed assinado (HMAC-SHA256). Guarde o secret."
  }
}

Exemplo de resposta 201 com seleção pendente

Quando token e chain são omitidos, o resultado é uma intenção, ainda sem ordem ou QR.

{
  "selectionRequired": true,
  "intentId": "EXEMPLO_ID_DA_INTENCAO",
  "expiresAt": "2026-11-08T18:15:00.000Z",
  "options": [
    { "chain": "base", "label": "Base", "tokens": ["USDC"], "tokenInfo": { "USDC": { "decimals": 6 } } }
  ]
}

As opções acima são ilustrativas e reduzidas; consulte os dados retornados no seu ambiente.