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