API · Assinaturas

Criar assinatura

POST /api/crypto/v1/subscriptions — configure cobrança recorrente.

POST /api/crypto/v1/subscriptions

Cria uma assinatura. No modo padrão invoice, cria imediatamente o primeiro ciclo como ordem na Base. No modo authorization, quando habilitado no ambiente, prepara uma autorização on-chain e retorna o endereço para o cliente autorizar.

Corpo JSON

Campo Obrigatório Descrição
amountBRL Sim Número entre 1 e 50000, arredondado a centavos.
customerRef Sim Identificador do cliente, até 64 caracteres alfanuméricos, _ ou -.
wallet.address Sim Endereço EVM do lojista.
wallet.affiliates Não Objetos address e bps; soma até 10000. A implementação considera os primeiros 10.
intervalDays Sim, salvo monthly Número de dias de 1 a 365.
monthly Alternativo true define intervalo de 30 dias, não um mês de calendário.
customerEmail Não Endereço de email válido.
description Não Descrição de até 200 caracteres.
webhookUrl Não URL HTTPS para eventos da assinatura.
token Não USDC ou USDT; o código normaliza qualquer outro valor para USDT.
mode Não invoice (padrão) ou authorization, se habilitado.
customerAddress Condicional Carteira do cliente para o modo de autorização.

A rota atual não encaminha um campo chain do corpo ao serviço: as assinaturas são configuradas para Base.

curl -X POST https://api.caedral.com/api/crypto/v1/subscriptions \
  -H 'Content-Type: application/json' \
  -d '{"amountBRL":49.90,"customerRef":"cliente_1042","monthly":true,"wallet":{"address":"0x1111111111111111111111111111111111111111"},"token":"USDC"}'

Resposta 201

Retorna subscription e manageToken. No modo invoice, a assinatura inclui subscriptionId, status, customerRef, amountBRL, intervalDays, cycle, currentCharge, chain, token e recipient. currentCharge contém a referência, valores, URLs e expiração do primeiro ciclo. No modo authorization, inclui onchainSubId, chargerAddress, authorizeUrl e registrationTxHash.

Guarde manageToken em um cofre: ele é retornado apenas na criação e autoriza consulta, pausa e cancelamento. Envie no cabeçalho X-Manage-Token. A URL de webhook de assinatura não recebe secret gerado por esta rota; a implementação atual envia esses eventos sem assinatura HMAC. Não trate esses eventos isoladamente como prova de pagamento: consulte o estado da ordem.

400: validação ou modo indisponível; 500: erro de criação ou infraestrutura. Criação envolve efeitos persistentes: reconcilie antes de repetir após timeout.

Exemplo de resposta 201

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

{
  "subscription": {
    "subscriptionId": "674000000000000000000001",
    "status": "active",
    "customerRef": "cliente_1042",
    "amountBRL": 49.9,
    "intervalDays": 30,
    "cycle": 1,
    "currentCharge": {
      "ref": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "status": "pending",
      "cryptoAmount": "9.330000",
      "feeAmount": "0.100000",
      "netAmount": "9.230000",
      "chain": "base",
      "token": "USDC",
      "tokenLabel": "USD Coin",
      "recipient": "0x1111111111111111111111111111111111111111",
      "paymentUrl": "https://pay.example/pay/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "paymentUri": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x3333333333333333333333333333333333333333&uint256=9330000",
      "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"
    },
    "chain": "base",
    "token": "USDC",
    "recipient": "0x1111111111111111111111111111111111111111",
    "manageTokenUsage": "Envie o manageToken no header X-Manage-Token para consultar, pausar ou cancelar. Ele não é exibido novamente."
  },
  "manageToken": "EXEMPLO_GUARDE_EM_SEGURANCA"
}