請求API

認証

キーは「請求 → APIとWebhook」で作成します（口座で2段階認証が有効になっている必要があります）。Authorizationヘッダーで送信し、サーバー上にのみ保管してください。アクセス権を選択します：「請求の読み取りと作成」（ストア）または「読み取りのみ」（照合、レポート）。読み取り専用キーで作成しようとすると403が返ります。

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

請求の作成

token：USDCまたはSOL。valor：小数点はピリオド。金額自由の場合は省略します。validade_horas：1、24、72、168、720（デフォルト24）。externo_id：ストアの注文番号で、口座ごとに一意です。ネットワークが切断されても安全に再試行できるよう、Idempotency-Key（UUID）を送信してください。

curl -X POST https://ducripto.com/api/v1/cobrancas \
  -H "Authorization: Bearer ib_XXXXXXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a8e-4b1d-4c55-9a3e-0d2b7f9e1c11" \
  -d '{"token":"USDC","valor":"25.90","descricao":"Pedido 1042","externo_id":"1042","validade_horas":24}'

{
  "id": "9b2f…", "estado": "pendente", "externo_id": "1042",
  "token": "USDC", "decimais": 6, "valor_unidades": "25900000", "valor": "25.9",
  "url_pagamento": "https://ducripto.com/pagar/9b2f…",
  "solana_pay": "solana:<carteira>?amount=25.9&spl-token=EPjF…&reference=…",
  "expira_em": "…", "pagamento": null
}

照会

金額は常に、精度を失わないようトークンの整数単位の文字列（valor_unidades）で返されます。estado：pendente、paga、expirada、cancelada。一覧はページ単位で返されます。limite（1〜100、デフォルト50）を使い、次のページを読むにはproximoの値をdepoisに渡してください。proximoがnullなら終端です。サーバーで取引を組み立てるウォレット（Solana Pay "transaction request"）にはsolana_pay_transacaoを使用します。金額自由の請求では、エンコード前にURLに?quantidade=を追加してください。

curl https://ducripto.com/api/v1/cobrancas/9b2f… -H "Authorization: Bearer ib_…"
curl "https://ducripto.com/api/v1/cobrancas?externo_id=1042" -H "Authorization: Bearer ib_…"
curl "https://ducripto.com/api/v1/cobrancas?limite=50&depois=<proximo>" -H "Authorization: Bearer ib_…"

Webhook：請求の支払い完了

type cobranca.pagaのJSON POSTを受信します。署名を確認してください：あなたのシークレットで"timestamp.corpo"のHMAC-SHA256を16進数で計算し、timestampが5分より古い場合は拒否します。2xxで応答してください。そうでない場合は間隔を延ばしながら再送します。重複を無視するにはevento_idを使ってください。

import { createHmac, timingSafeEqual } from 'node:crypto';

// corpo = texto CRU da requisição (antes de JSON.parse)
// x-interbank-assinatura-anterior só vem durante uma troca de chaves da plataforma: aceite qualquer uma
export function webhookValido(corpo, cab, segredo) {
  const ts = cab['x-interbank-timestamp'];
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const esperado = createHmac('sha256', segredo).update(`${ts}.${corpo}`).digest();
  return ['x-interbank-assinatura', 'x-interbank-assinatura-anterior'].some((h) => {
    const veio = Buffer.from(cab[h] ?? '', 'hex');
    return veio.length === esperado.length && timingSafeEqual(veio, esperado);
  });
}

サイト用の決済ボタン（SDK）

スクリプト1行で、あなたのブランドのボタンを表示し、新しいタブでチェックアウトを開きます。支払いが確定すると、サイトはcheckout:pagaイベントを受け取ります。このイベントは画面表示用です。注文の引き渡しは、サーバーで確認した後（署名付きWebhookまたは請求のGET）に行ってください。

<!-- data-cobranca: id devolvido por POST /api/v1/cobrancas · data-voltar: opcional, só do seu site -->
<script src="https://ducripto.com/sdk/v1/checkout.js" data-cobranca="9b2f…" data-voltar="/obrigado" async></script>
<script>
  addEventListener('checkout:paga', (e) => mostrarObrigado(e.detail.cobranca));
</script>

任意のトークンからUSDCで受け取る

金額指定のUSDC請求を作成する際に"aceita_conversao": trueを送信します。支払いページで支払者はSOL、USDT、JUP、BONKを選び、支払額を確認でき、同じ取引内で換算されて正確な金額のUSDCがあなたのウォレットに届きます。Webhookと照会は同じで、基準は届いたUSDCです。テストモードでは使えません。

curl -X POST https://ducripto.com/api/v1/cobrancas -H "Authorization: Bearer ib_…" -H "Content-Type: application/json" \
  -d '{"token":"USDC","valor":"49.90","externo_id":"1043","aceita_conversao":true}'
# → { "aceita_conversao": true, "url_pagamento": "https://ducripto.com/pagar/…", … }
# quem paga escolhe SOL, USDT, JUP ou BONK na página; você recebe 49.90 USDC exatos

テスト環境（サンドボックス）

テストモードでキーを作成します（ib_test_で始まります）。同じAPIを使いますが、テスト用の請求のみを参照・作成でき、それらはテストネットワーク上にあり（応答とWebhookでmodo: "teste"）、売上には一切計上されません。ウォレットなしでテストするには支払いをシミュレートします：POST /api/v1/cobrancas/{id}/simular-pagamento（金額自由の場合は{"valor": "…"}を送信）。Webhook cobranca.pagaは本番と同じく署名付きで届きます。本番キーではシミュレートできず、キー同士は互いの請求を参照できません。

# chave de teste (ib_test_…): mesma API, só cobranças de teste, rede de testes
curl -X POST https://ducripto.com/api/v1/cobrancas -H "Authorization: Bearer ib_test_XXXXXXXXXXXX_…" \
  -H "Content-Type: application/json" -d '{"token":"USDC","valor":"25.90","externo_id":"teste-1"}'
# → { "id": "9b2f…", "modo": "teste", "rede": "devnet", "estado": "pendente", … }

curl -X POST https://ducripto.com/api/v1/cobrancas/9b2f…/simular-pagamento -H "Authorization: Bearer ib_test_XXXXXXXXXXXX_…"
# → { "estado": "paga", "pagamento": { "assinatura": "simulado_…", … } } e o webhook cobranca.paga com "modo": "teste"

エラーと制限

エラーは{ erro: { codigo, mensagem } }の形式で返されます。401 無効または失効したキー · 403 キーにその操作のスコープがない · 404 他の口座の請求または存在しない請求 · 409 externo_idの重複、またはIdempotency-Keyを別の本文で再利用 · 422 無効なデータ · 429 キーごとに毎分120回を超過。

仕様（OpenAPI）

完全なOpenAPI 3.1仕様（請求、エラー、Webhook）は/api/v1/openapi.jsonにあります。Postman、Insomnia、またはクライアントジェネレーターにインポートしてください。テストで実際の応答と照合しているのと同じスキーマから生成されています。

curl https://ducripto.com/api/v1/openapi.json