Documentação

Cobrança

Informações de assinatura, integração de checkout/portal Stripe, manutenção de avaliação e ingestão de webhook assinado.

Traduzido automaticamente do inglês. Ver o original em inglês

Área de testes

Envie essas solicitações para seu próprio sidecar em execução. Os valores permanecem neste navegador.

Não conectado

URL base Token do portador opcional Token de sessão opcional

Como isso funciona

O sidecar escuta em uma porta de loopback escolhida na inicialização e a imprime em seu ready linha; use esse URL e o CADCAMFUN_TOKEN foi iniciado. As solicitações vão direto desta página para esse endereço.

O sidecar envia cabeçalhos CORS apenas para as origens Tauri e para http://localhost ou http://127.0.0.1 em qualquer porto. Nos documentos hospedados, o navegador bloqueia a resposta, então execute os documentos localmente (bun run dev em packages/web) para usar o playground ou copie a solicitação como curl. Para experimentar sem tocar em dados reais, inicie o sidecar com CADCAMFUN_DATA_DIR apontado para um diretório descartável - veja o passo a passo da API.

Operações

15 endpoints no billing grupo, gerado a partir do próprio sidecar Documento OpenAPI. As operações protegidas levam Authorization: Bearer $CADCAMFUN_TOKEN; ver autenticação. Comportamento e limites estão em o guia do subsistema.

pegar	/api/subscription/info	billing.info
pegar	/api/subscriptions	billing.current
publicar	/api/subscriptions	billing.subscribe
publicar	/api/subscriptions/portal	billing.portal
pegar	/api/better-auth-stripe/subscription	billing.baGet
publicar	/api/better-auth-stripe/subscription	billing.baCheckout
colocar	/api/better-auth-stripe/subscription	billing.baUpdate
excluir	/api/better-auth-stripe/subscription	billing.baCancel
publicar	/api/better-auth-stripe/billing-portal	billing.baPortal
publicar	/api/better-auth-stripe/feature-access	billing.baFeature
publicar	/api/better-auth-stripe/sync	billing.baSync
pegar	/api/cron/update-expired-trials	billing.cronGet
publicar	/api/cron/update-expired-trials	billing.cronPost
pegar	/api/health/stripe	billing.stripeHealth
publicar	/api/webhooks/stripe	billing.stripeWebhook

Operações de faturamento em 3D Arraste para orbitar · role para ampliar · arraste com o botão direito para deslocar

Um bloco por operação (15), empilhado por seção de recursos desta página e colorido por método: verde GET, laranja POST, azul PUT, violeta PATCH, vermelho DELETE. Gerado a partir do documento OpenAPI em tempo de construção.

/api/subscription/info

pegar /api/subscription/info # billing.info

Requer Authorization: Bearer <token>.

Parâmetros

Nome	Em	Tipo	Obrigatório
userId	consulta	corda \| null	opcional

Respostas

200 objeto application/json

{
  id: string
  plan: string
  status: string
  currentPeriodEnd: string | null
  cancelAtPeriodEnd: boolean | null
  stripeCustomerId: string | null
  stripeSubscriptionId: string | null
}

400 BillingBadRequestEncoded application/json

BillingBadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

403 BillingForbiddenEncoded application/json

BillingForbiddenEncoded

404 BillingNotFoundEncoded application/json

BillingNotFoundEncoded

500 BillingFailureEncoded application/json

BillingFailureEncoded

Resposta de exemplo capturado · 400

GET /api/subscrição/info

{
  "_tag": "BillingBadRequest",
  "error": "User ID is required"
}

Exemplo de SDK

billing.info

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingInfoInput
const result = await client.billing.info({})

curl

GET /api/subscrição/info

curl --request GET "${CADCAMFUN_URL}/api/subscription/info" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Experimente

userId consulta

/api/subscriptions

pegar /api/subscriptions # billing.current

Requer Authorization: Bearer <token>.

Respostas

200 objeto application/json

{
  plan: string
  status: string
  periodEnd: string | null
  cancelAtPeriodEnd: boolean
  isOnTrial?: boolean | null
  trialEnd?: string | null
}

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

Resposta de exemplo capturado · 200

GET /api/subscrições

{
  "plan": "FREE",
  "status": "active",
  "periodEnd": null,
  "cancelAtPeriodEnd": false
}

Exemplo de SDK

billing.current

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// no input
const result = await client.billing.current()

curl

GET /api/subscrições

curl --request GET "${CADCAMFUN_URL}/api/subscriptions" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Experimente

publicar /api/subscriptions # billing.subscribe

Requer Authorization: Bearer <token>.

Corpo da solicitação · obrigatório · aplicação/json

{
  priceId?: string | null
  startTrial?: boolean | null
}

Respostas

200 objeto application/json

{
  url?: string | null
  success?: boolean | null
  message?: string | null
  redirectUrl?: string | null
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

Exemplo de SDK

billing.subscribe

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingSubscribeInput
const result = await client.billing.subscribe({
  priceId: "",
  startTrial: false
})

curl

POST /api/subscrições

curl --request POST "${CADCAMFUN_URL}/api/subscriptions" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Experimente

Solicitar corpo application/json

/api/subscriptions/portal

publicar /api/subscriptions/portal # billing.portal

Requer Authorization: Bearer <token>.

Corpo da solicitação · obrigatório · aplicação/json

{
  returnUrl?: string | null
}

Respostas

200 objeto application/json

{
  url: string
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

Exemplo de SDK

billing.portal

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingPortalInput
const result = await client.billing.portal({
  returnUrl: ""
})

curl

POST /api/subscrições/portal

curl --request POST "${CADCAMFUN_URL}/api/subscriptions/portal" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Experimente

Solicitar corpo application/json

/api/better-auth-stripe/subscription

pegar /api/better-auth-stripe/subscription # billing.baGet

Requer Authorization: Bearer <token>.

Respostas

200 objeto application/json

{
  id?: string | null
  plan: string
  status: string
  currentPeriodEnd: string | null
  cancelAtPeriodEnd: boolean
  stripeCustomerId?: string | null
  stripeSubscriptionId?: string | null
  source: "better-auth"
}

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 BillingFailureEncoded application/json

BillingFailureEncoded

Resposta de exemplo capturado · 200

GET /api/better-auth-stripe/subscrição

{
  "id": "c942817d-0162-4291-84ff-77321d387acc",
  "plan": "FREE",
  "status": "active",
  "currentPeriodEnd": null,
  "cancelAtPeriodEnd": false,
  "stripeCustomerId": null,
  "stripeSubscriptionId": null,
  "source": "better-auth"
}

Exemplo de SDK

billing.baGet

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// no input
const result = await client.billing.baGet()

curl

GET /api/better-auth-stripe/subscrição

curl --request GET "${CADCAMFUN_URL}/api/better-auth-stripe/subscription" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Experimente

publicar /api/better-auth-stripe/subscription # billing.baCheckout

Requer Authorization: Bearer <token>.

Corpo da solicitação · obrigatório · aplicação/json

{
  plan?: string | null
  successUrl?: string | null
  cancelUrl?: string | null
  trialDays?: number | "Infinity" | "-Infinity" | "NaN" | null
}

Respostas

200 objeto application/json

{
  url: string
  source: "better-auth"
}

400 BillingBadRequestEncoded application/json

BillingBadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 BillingFailureEncoded application/json

BillingFailureEncoded

Exemplo de SDK

billing.baCheckout

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingBaCheckoutInput
const result = await client.billing.baCheckout({
  plan: "",
  successUrl: "",
  cancelUrl: "",
  trialDays: 0
})

curl

POST /api/better-auth-stripe/subscrição

curl --request POST "${CADCAMFUN_URL}/api/better-auth-stripe/subscription" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Experimente

Solicitar corpo application/json

colocar /api/better-auth-stripe/subscription # billing.baUpdate

Requer Authorization: Bearer <token>.

Corpo da solicitação · obrigatório · aplicação/json

{
  newPlan?: string | null
}

Respostas

200 objeto application/json

{
  success: true
  message: string
  source: "better-auth"
}

400 BillingBadRequestEncoded application/json

BillingBadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 BillingFailureEncoded application/json

BillingFailureEncoded

Exemplo de SDK

billing.baUpdate

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingBaUpdateInput
const result = await client.billing.baUpdate({
  newPlan: ""
})

curl

PUT /api/better-auth-stripe/subscrição

curl --request PUT "${CADCAMFUN_URL}/api/better-auth-stripe/subscription" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Experimente

Solicitar corpo application/json

excluir /api/better-auth-stripe/subscription # billing.baCancel

Requer Authorization: Bearer <token>.

Respostas

200 objeto application/json

{
  success: true
  message: string
  source: "better-auth"
}

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 BillingFailureEncoded application/json

BillingFailureEncoded

Exemplo de SDK

billing.baCancel

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// no input
const result = await client.billing.baCancel()

curl

DELETE /api/better-auth-stripe/subscrição

curl --request DELETE "${CADCAMFUN_URL}/api/better-auth-stripe/subscription" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Experimente

/api/better-auth-stripe/billing-portal

publicar /api/better-auth-stripe/billing-portal # billing.baPortal

Requer Authorization: Bearer <token>.

Corpo da solicitação · obrigatório · aplicação/json

{
  returnUrl?: string | null
}

Respostas

200 objeto application/json

{
  url: string
  source: "better-auth"
}

400 BillingBadRequestEncoded application/json

BillingBadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 BillingFailureEncoded application/json

BillingFailureEncoded

Exemplo de SDK

billing.baPortal

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingBaPortalInput
const result = await client.billing.baPortal({
  returnUrl: ""
})

curl

POST /api/better-auth-stripe/portal de faturamento

curl --request POST "${CADCAMFUN_URL}/api/better-auth-stripe/billing-portal" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Experimente

Solicitar corpo application/json

/api/better-auth-stripe/feature-access

publicar /api/better-auth-stripe/feature-access # billing.baFeature

Requer Authorization: Bearer <token>.

Corpo da solicitação · obrigatório · aplicação/json

{
  feature?: string | null
  features?: unknown | null
}

Respostas

200 objeto application/json

{
  feature?: string | null
  hasAccess?: boolean | null
  source: "better-auth"
  features?: Array<{
    feature: string
    hasAccess: boolean
    error?: string | null
  }> | null
}

400 BillingBadRequestEncoded application/json

BillingBadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 BillingFailureEncoded application/json

BillingFailureEncoded

Exemplo de SDK

billing.baFeature

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingBaFeatureInput
const result = await client.billing.baFeature({
  feature: "",
  features: null
})

curl

POST /api/better-auth-stripe/feature-access

curl --request POST "${CADCAMFUN_URL}/api/better-auth-stripe/feature-access" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Experimente

Solicitar corpo application/json

/api/better-auth-stripe/sync

publicar /api/better-auth-stripe/sync # billing.baSync

Requer Authorization: Bearer <token>.

Respostas

200 objeto application/json

{
  success: true
  message: string
  subscription: {
    id?: string | null
    plan: string
    status: string
    currentPeriodEnd: string | null
    cancelAtPeriodEnd: boolean
    stripeCustomerId?: string | null
    stripeSubscriptionId?: string | null
    source: "better-auth"
  } | null
  source: "better-auth"
}

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 BillingFailureEncoded application/json

BillingFailureEncoded

Exemplo de SDK

billing.baSync

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// no input
const result = await client.billing.baSync()

curl

POST /api/better-auth-stripe/sync

curl --request POST "${CADCAMFUN_URL}/api/better-auth-stripe/sync" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Experimente

/api/cron/update-expired-trials

pegar /api/cron/update-expired-trials # billing.cronGet

Requer Authorization: Bearer <token>.

Parâmetros

Nome	Em	Tipo	Obrigatório
segredo	consulta	corda \| null	opcional

Respostas

200 objeto application/json

{
  success: true
  updatedCount: number | "Infinity" | "-Infinity" | "NaN"
  message: string
  timestamp: string
}

401 CronUnauthorizedEncoded | Não autorizadoEncoded application/json

CronUnauthorizedEncoded | UnauthorizedEncoded

500 CronFailureEncoded application/json

CronFailureEncoded

Resposta de exemplo capturado · 200

OBTER /api/cron/update-expired-trials

{
  "success": true,
  "updatedCount": 0,
  "message": "Successfully updated 0 expired trials",
  "timestamp": "2026-10-15T04:52:23.475Z"
}

Exemplo de SDK

billing.cronGet

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingCronGetInput
const result = await client.billing.cronGet({})

curl

OBTER /api/cron/update-expired-trials

curl --request GET "${CADCAMFUN_URL}/api/cron/update-expired-trials" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Experimente

segredo consulta

publicar /api/cron/update-expired-trials # billing.cronPost

Requer Authorization: Bearer <token>.

Parâmetros

Nome	Em	Tipo	Obrigatório
segredo	consulta	corda \| null	opcional

Respostas

200 objeto application/json

{
  success: true
  updatedCount: number | "Infinity" | "-Infinity" | "NaN"
  message: string
  timestamp: string
}

401 CronUnauthorizedEncoded | Não autorizadoEncoded application/json

CronUnauthorizedEncoded | UnauthorizedEncoded

500 CronFailureEncoded application/json

CronFailureEncoded

Exemplo de SDK

billing.cronPost

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// BillingCronPostInput
const result = await client.billing.cronPost({})

curl

POST /api/cron/update-expired-trials

curl --request POST "${CADCAMFUN_URL}/api/cron/update-expired-trials" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Experimente

segredo consulta

/api/health/stripe

pegar /api/health/stripe # billing.stripeHealth

Requer Authorization: Bearer <token>.

Respostas

200 objeto application/json

{
  status: "healthy"
  message: string
  timestamp: string
  service: "stripe"
}

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

503 StripeUnhealthyEncoded application/json

StripeUnhealthyEncoded

Resposta de exemplo capturado · 503

GET /api/health/stripe

{
  "_tag": "StripeUnhealthy",
  "status": "unhealthy",
  "message": "Stripe is not configured on this installation",
  "timestamp": "2026-10-15T04:52:23.476Z",
  "service": "stripe"
}

Exemplo de SDK

billing.stripeHealth

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

// no input
const result = await client.billing.stripeHealth()

curl

GET /api/health/stripe

curl --request GET "${CADCAMFUN_URL}/api/health/stripe" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Experimente

/api/webhooks/stripe

publicar /api/webhooks/stripe # billing.stripeWebhook

Requer Authorization: Bearer <token>.

Corpo da solicitação · obrigatório · aplicação/fluxo de octetos

string

Respostas

200 objeto application/json

{
  received: true
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

buscar exemplo

billing.stripeWebhook

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/webhooks/stripe`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

POST /api/webhooks/stripe

curl --request POST "${CADCAMFUN_URL}/api/webhooks/stripe" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/octet-stream" \
  --data-binary @request-body

Experimente

Esta operação leva application/octet-stream; use o exemplo curl ou fetch.

Esquemas

Esquemas nomeados acessíveis a partir dos parâmetros, corpos e respostas deste grupo. UM ? marca um campo opcional; | null marca um campo que pode estar presente com um valor nulo.

BadRequestEncoded

{
  _tag: "BadRequest"
  message: string
}

BillingBadRequestEncoded

{
  _tag: "BillingBadRequest"
  error: string
}

BillingFailureEncoded

{
  _tag: "BillingFailure"
  error: string
}

BillingForbiddenEncoded

{
  _tag: "BillingForbidden"
  error: string
}

BillingNotFoundEncoded

{
  _tag: "BillingNotFound"
  error: string
}

CronFailureEncoded

{
  _tag: "CronFailure"
  success: false
  error: string
  timestamp: string
}

CronUnauthorizedEncoded

{
  _tag: "CronUnauthorized"
  error: string
}

InternalErrorEncoded

{
  _tag: "InternalError"
  message: string
}

NotFoundEncoded

{
  _tag: "NotFound"
  message: string
}

StripeUnhealthyEncoded

{
  _tag: "StripeUnhealthy"
  status: "unhealthy"
  message: string
  timestamp: string
  service: "stripe"
}

UnauthorizedEncoded

{
  _tag: "Unauthorized"
  message: string
}

Chamando este grupo

Os IDs de operação têm o formato billing.<name>. O Promise SDK gerado (@cadcamfun/api/sdk) expõe a maioria deles como client.<namespace>.<method>(input), onde input é um objeto plano de parâmetros de caminho e campos de corpo; o exemplo do SDK de cada cartão mostra o acessador e o tipo de entrada exatos. Multipart uploads, respostas binárias ou JavaScript e webhooks brutos não são gerados; essas cartas mostram fetch em vez disso.

Erros do Promise SDK

import { CadCam, ClientError } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

try {
  await client.projects.list()
} catch (error) {
  if (error instanceof ClientError) {
    // Transport | UnexpectedStatus | UnsupportedContentType | MalformedResponse | SseEventTooLarge
  } else {
    // a declared error body: switch on error._tag
  }
}

Solução de problemas

Sintoma	Causa provável	Consertar
401 em cada chamada	Token de um lançamento anterior ou ausente `Bearer` prefixo	Enviar `Authorization: Bearer <token>` com o token com o qual o sidecar foi iniciado.
400 antes que algo aconteça	O corpo ou parâmetro não corresponde ao esquema	Compare a carga útil com o esquema de solicitação no cartão.
403 ou 404 em um registro que você vê em outro lugar	A conta atuante difere	Envie o certo `x-session-token`ou use o perfil local que possui o registro.
409	Estado conflitante, como um nome duplicado ou um cabeçalho de ramificação obsoleto	Leia novamente o recurso e tente novamente com os dados atuais.
Tente dizer "bloqueado pelo CORS"	Os documentos são veiculados a partir de uma origem sem loopback	Execute os documentos localmente ou copie a solicitação como curl.
Ligação recusada	O sidecar foi reiniciado em uma nova porta	Leia a porta do novo `ready` linha.