Início rápido

Você não precisa de conta, cartão nem CLI pra começar. Uma chamada HTTP cria um tenant de sandbox e devolve as chaves de teste. Você assume a conta depois, dentro do prazo retornado em expiresAt. Integrando com IA? Comece pelo cadastro pelo agente. Ele pergunta email, nome do app e forma de cobrança, prepara o ambiente e entrega o link para você finalizar na Infi.

1. Pegue uma chave

curl -X POST https://api-sandbox.beinfi.com/public/v1/claimables \
  -H 'Content-Type: application/json' \
  -d '{"email":"founder@example.com","accountName":"Acme"}'

Resposta (201):

{
  "id": "d4147638-938e-4854-a6f7-3addaac7909a",
  "status": "UNCLAIMED",
  "tenantSlug": "app-ec62ff27",
  "accountName": "Acme",
  "productId": "95165eab-a189-43eb-b2b9-83c714cb204e",
  "apiKeySecret": "sk_test_09eed9fc…",
  "publishableKey": "pk_test_…",
  "claimUrl": "https://app-sandbox.beinfi.com/claim/d4147638-938e-4854-a6f7-3addaac7909a",
  "expiresAt": "2026-10-04T19:49:46Z"
}

apiKeySecret — sua sk_test_. Vem uma única vez, não tem como reemitir.
publishableKey — sua pk_test_ da Infi, para APIs de cliente que a exigem. A chave secreta continua no servidor.
tenantSlug — o slug que entra na URL pública de cobrança (/pay/{slug}/…).
claimUrl — abra pra assumir a conta. O prazo padrão é de 30 dias; vale a data de expiresAt.
productId — o produto seed. Ele não serve pra vender nem pra medir ainda: vem sem key, sem meter e com a versão 1 em draft. O seu produto de verdade você cria em catálogo.

email e accountName são opcionais. O corpo também aceita ref ({"ref":"cli"}) pra marcar a origem. Com a atualização de email de claim, informar o endereço enfileira um aviso com link e prazo, limitado a um por endereço a cada 24 horas. Guarde e entregue a claimUrl mesmo assim: 201 não confirma entrega do email. O endereço só vira contato; assumir a conta exige login.

Não mande intent nesse endpoint. {"intent":"one-time"} responde 422 unrecognized field. Intent é conceito da CLI, não do endpoint público.

O atalho: uma linha e você já tem o que vender

O curl acima te dá a chave e um produto que não serve pra vender. A CLI faz a corrente inteira:

npx -y @beinfi/cli bootstrap --intent one-time --ref cli --json

Medido, numa pasta vazia: além do tenant e da chave, ela deixa um produto item + one_time com a versão publicada a R$ 29,90 — e “publicar” é o passo que ninguém adivinha e que faz a diferença entre um produto cobrável e um 422. Dá pra faturar nele imediatamente, sem mais nenhuma chamada:

await infi.invoices.createForProduct(productId, { customer: {…} });
// -> { status: "open", total: "29.90" }

Ela também escreve infi.company.ts + .env.local, sincroniza e roda doctor. Se você fizer à mão, são cinco chamadas — criar produto, listar versões, publicar, inscrever cliente, faturar — e todas estão em catálogo. Vale ler de qualquer jeito pra saber o que a CLI fez por você; só não precisa digitar.

Só a chave, sem escrever arquivo. npx -y @beinfi/cli claim create --json. E desde a 0.2.0 a CLI deduz o host a partir do prefixo da chave — em versões anteriores as duas falhavam sem INFI_API_URL, então se você tiver uma presa em lockfile, atualize.

2. Hosts

Nada disso precisa ir pro env do seu app — o SDK resolve host a partir do prefixo da chave. Escreva aqui pra quem usa curl, libera egress ou debuga DNS:

	sandbox (`sk_test_`)	produção (`sk_live_`)
API	`api-sandbox.beinfi.com`	`api.beinfi.com`
Checkout / links	`app-sandbox.beinfi.com`	`app.beinfi.com`

curl: Idempotency-Key. Todo POST/PUT/DELETE autenticado exige o header Idempotency-Key — sem ele volta 400 idempotency_key_required. O SDK gera um por chamada. (O /public/v1/claimables do passo 1 é exceção: é público e não pede.)

3. Variáveis de ambiente

INFI_SECRET_KEY=sk_test_...   # obrigatória (servidor)
INFI_PUBLISHABLE_KEY=pk_test_... # APIs de cliente que exigem a chave pública Infi
INFI_TENANT_SLUG=seu-tenant   # slug do checkout hospedado /pay/{slug}
APP_URL=https://seu-app.com   # origens / redirects (recomendado)

Não use URLs legacy. INFI_AUTH_BASE_URL e INFI_PAY_BASE_URL são legado — o SDK nem lê essas variáveis, e infi doctor pede pra remover. O host de API e o de checkout saem do prefixo da chave: sk_test_ → api-sandbox + app-sandbox, sk_live_ → api + app. Pra apontar pra outro lugar (local, self-host), use apiUrl / appUrl no construtor.

4. Instale o SDK

npm
pnpm
bun

npm install @beinfi/sdk

pnpm add @beinfi/sdk

bun add @beinfi/sdk

import { Infi } from "@beinfi/sdk";

export const infi = new Infi({ secretKey: process.env.INFI_SECRET_KEY! });

await infi.products.list(); // sanity check: a chave responde

5. Medir uso

Medição precisa de um produto seu, com meter e versão publicada — três chamadas em catálogo. Com isso pronto, inscreva o seu usuário no produto e registre uso:

// seuUserId vem do SEU auth — a Infi não faz login de usuário final
const enrollment = await infi.products.enroll(productId, {
  externalId: seuUserId,
  email: "cliente@empresa.com",
});

await infi.track({
  customerId: enrollment.id,   // id da inscrição, não o seu id de usuário
  productId,                   // obrigatório quando o tenant tem >1 produto
  meter: "tokens",
  value: "1200",
});

enroll não abre período — e sem período não há crédito. products.enroll cria a inscrição e para aí. O grant on: "cycle" só é creditado quando um período abre, e quem abre período é a assinatura:

await infi.products.subscribe(productId, { enrollmentId: enrollment.id });

Sem isso a carteira fica em zero e toda chamada com gate pré-pago cai em 402, com o catálogo perfeitamente configurado.

Dois 422 comuns em track. productId: is required — o tenant já tem o produto seed, então basicamente sempre há mais de um produto: mande productId sempre. E meter: unknown meter — o meter tem que existir no produto antes (veja catálogo).

Próximos passos

Catálogo

Produto → versão publicada → preço. É o que falta antes de cobrar.

Saber que pagou

Webhooks em produção, polling em sandbox.

Sua primeira venda

Do zero à fatura paga: qual caminho escolher e o que guardar.

Company as code

Catálogo declarado em git.

Começar

Integração

Início rápido

1. Pegue uma chave

O atalho: uma linha e você já tem o que vender

2. Hosts

3. Variáveis de ambiente

4. Instale o SDK

5. Medir uso

Próximos passos

Catálogo

Saber que pagou

Sua primeira venda

Company as code

​1. Pegue uma chave

​O atalho: uma linha e você já tem o que vender

​2. Hosts

​3. Variáveis de ambiente

​4. Instale o SDK

​5. Medir uso

​Próximos passos

Catálogo

Saber que pagou

Sua primeira venda

Company as code

1. Pegue uma chave

O atalho: uma linha e você já tem o que vender

2. Hosts

3. Variáveis de ambiente

4. Instale o SDK

5. Medir uso

Próximos passos