API · Ordens

Consultar ordem

GET /api/crypto/v1/orders/{ref} — acompanhe uma cobrança.

GET /api/crypto/v1/orders/{ref}

ref é a referência pública retornada pela criação: 0x seguido de 64 dígitos hexadecimais. Quem possui a referência pode consultar a ordem e operar seu redirecionamento; trate-a como uma capability e não a publique desnecessariamente.

curl 'https://api.caedral.com/api/crypto/v1/orders/REF_DA_ORDEM'

Resposta 200

A resposta contém os campos públicos da ordem: ref, status, valores amountBRL, cryptoAmount, feeAmount, minFeeAmount e netAmount; token, tokenDecimals, tokenAddress, chain, chainId, chainParams, recipient, contractAddress, contractVersion e feeBps; URLs e URI de pagamento; expiresAt, payableUntil, createdAt, paidAt, txHash e description. Alguns campos podem ser nulos. expiresAt é o fim da cotação; payableUntil inclui a janela adicional aceita pelo contrato.

Status Significado
pending Aguardando pagamento.
paid Pagamento confirmado.
expired Expiração registrada; pagamentos dentro da janela adicional ainda podem ser reconciliados.
failed Falha no processamento.
redirected A ordem foi substituída; ainda pode ser monitorada para reconciliação.
duplicate_payment Pagamento duplicado identificado.

400: formato de referência inválido; 404: ordem não encontrada; 500: falha interna. Use webhook e consultas moderadas para reconciliação; não libere um pedido apenas porque a transação foi iniciada.

Exemplo de resposta 200

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"
}