Skip to main content
Este guia acompanha você por todo o ciclo de vida de faturamento: escolher um plano, criar uma assinatura, adicionar um método de pagamento e pagar faturas. Ao final, você terá uma integração de faturamento totalmente operacional.

​
O que você vai construir

Listar planos → Criar assinatura → Adicionar método de pagamento → Ver próxima fatura → Pagar fatura → Verificar status

​
Pré-requisitos

Antes de começar, certifique-se de ter:
  • Uma conta de usuário verificada (veja Autenticação)
  • Uma organização ativa com seu organizationId
  • Um access token válido com permissões plan:read, subscription:write, payment_method:write e invoice:pay
Modo teste vs. produção: Durante o desenvolvimento, todas as chamadas à API usam os mesmos endpoints. Métodos de pagamento criados com tokens de cartão de teste (ex: tokens de teste do Stripe) não cobram dinheiro real. Use o número de cartão de teste 4242 4242 4242 4242 com qualquer data de validade futura.

​
Configuração passo a passo

1

Listar planos disponíveis

Busque todos os planos ativos para exibir opções de preço ao usuário.
curl https://api.awsales.io/studio/plans?status=ACTIVE \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
Exemplo de response (resumida):
{
  "data": [
    {
      "planId": "019525fd-6b2c-7a1e-9d4f-3c5e7a9b1d3f",
      "name": "Starter",
      "description": "Perfect for small teams getting started.",
      "intervals": [
        {
          "id": "019525fd-7e40-7c5a-b2d8-4e6f8a0c2e4a",
          "interval": "MONTHLY",
          "amount": 4900,
          "currency": "BRL"
        },
        {
          "id": "019525fd-8f54-7d6b-c3e9-5f7a9b1c3d5f",
          "interval": "YEARLY",
          "amount": 47040,
          "currency": "BRL"
        }
      ],
      "status": "ACTIVE"
    }
  ]
}
Todos os valores monetários estão em centavos. 4900 significa R$49,00. Sempre divida por 100 antes de exibir para os usuários.
2

Adicionar um método de pagamento

Antes de criar uma assinatura, a organização precisa de pelo menos um método de pagamento. A AWSales suporta cartões de crédito/débito e boleto.
curl -X POST https://api.awsales.io/studio/organizations/019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2/payment-methods \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CARD",
    "cardToken": "tok_visa_4242",
    "isDefault": true,
    "billingDetails": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+5511999999999",
      "address": {
        "line1": "Av Paulista 1000",
        "city": "Sao Paulo",
        "state": "SP",
        "postalCode": "01310-100",
        "country": "BR"
      }
    }
  }'
Response:
{
  "paymentMethodId": "pm_abc123",
  "organizationId": "019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2",
  "type": "CARD",
  "brand": "visa",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2027,
  "isDefault": true,
  "billingDetails": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  }
}
Organizações podem ter até 3 métodos de pagamento por cartão e 1 método de pagamento por boleto. Tentar exceder esses limites retorna um erro 409.
3

Criar uma assinatura

Inscreva a organização em um plano usando o planId, planIntervalId e paymentMethodId dos passos anteriores.
curl -X POST https://api.awsales.io/studio/organizations/019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2/subscriptions \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "019525fd-6b2c-7a1e-9d4f-3c5e7a9b1d3f",
    "planIntervalId": "019525fd-7e40-7c5a-b2d8-4e6f8a0c2e4a",
    "paymentMethodId": "pm_abc123"
  }'
Response:
{
  "subscriptionId": "019525fd-b17c-7f8d-e5a1-7b9c1d3f5a7d",
  "organizationId": "019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2",
  "planId": "019525fd-6b2c-7a1e-9d4f-3c5e7a9b1d3f",
  "currency": "BRL",
  "status": "ACTIVE",
  "coupons": [],
  "createdAt": "2026-03-25T14:00:00.000Z"
}
Para aplicar um cupom na criação da assinatura, adicione um objeto coupon com o campo code:
{
  "planId": "...",
  "planIntervalId": "...",
  "paymentMethodId": "...",
  "coupon": { "code": "WELCOME10" }
}
Verifique a disponibilidade do cupom antes via Verificar Disponibilidade.
4

Ver a próxima fatura

Visualize como será a próxima fatura, incluindo itens, descontos e o valor total.
curl https://api.awsales.io/studio/organizations/019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2/subscriptions/upcoming-invoice \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
Response:
{
  "invoiceId": "019525fd-c290-7a9e-f6b2-8c0d2e4a6b8e",
  "currency": "BRL",
  "totalAmount": 5900,
  "discountAmount": 500,
  "payableAmount": 5400,
  "lines": [
    { "name": "Starter Plan - Monthly", "unitPrice": 4900, "quantity": 1, "amount": 4900 },
    { "name": "API Calls", "unitPrice": 10, "quantity": 100, "amount": 1000 }
  ],
  "discounts": [
    { "type": "COUPON", "code": "WELCOME10", "amount": 500 }
  ],
  "status": "OPEN",
  "dueDate": "2026-04-01T00:00:00.000Z"
}
5

Pagar uma fatura

Quando uma fatura estiver vencida, pague usando o método de pagamento padrão ou especifique um diferente.
curl -X POST https://api.awsales.io/studio/organizations/019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2/invoices/019525fd-c290-7a9e-f6b2-8c0d2e4a6b8e/pay \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{}'
O endpoint de pagamento não é idempotente. Não retente uma request de pagamento sem antes verificar o status da fatura. Uma chamada duplicada pode resultar em cobrança dupla.
6

Verificar status da assinatura

Verifique se a assinatura está ativa e revise seu estado atual.
curl https://api.awsales.io/studio/organizations/019525fd-4c38-7e30-a5c1-b6e3f4d8a9c2/subscriptions \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
Status da assinatura:
StatusSignificado
ACTIVEAssinatura em dia e faturando normalmente
PAST_DUEPagamento falhou. Verifique pastDueReason para detalhes.
PAUSEDPausada manualmente por um usuário ou administrador
CANCELLEDAssinatura foi cancelada

​
Modelo de faturamento

A AWSales usa um modelo de faturamento híbrido: uma taxa fixa de assinatura do plano mais custos variáveis de uso (consumo de tokens, taxas de mensagens, chamadas à API). A prévia da próxima fatura mostra ambos os componentes. 
Total = Taxa do plano + Cobranças de uso - Descontos
Thresholds de faturamento: Organizações podem configurar um threshold de faturamento. Quando as cobranças de uso acumuladas excedem o valor do threshold, uma fatura é gerada automaticamente no meio do ciclo. Verifique o campo billingThreshold nas responses de fatura.

​
Tratamento de moeda

Todos os valores monetários na API estão em centavos (unidades menores). Para BRL: 4900 = R49,00,‘100‘=R49,00, `100` = R1,00, 10 = R$0,10.Sempre divida por 100 ao exibir para os usuários e multiplique por 100 ao enviar valores para a API.
// Display: cents → human-readable
const displayPrice = (cents, currency = "BRL") => {
  return new Intl.NumberFormat("pt-BR", {
    style: "currency",
    currency,
  }).format(cents / 100);
};

displayPrice(4900);  // "R$ 49,00"
displayPrice(47040); // "R$ 470,40"

​
Webhooks para eventos de pagamento

Em vez de fazer polling para mudanças de status de fatura, integre com webhooks da AWSales para receber notificações em tempo real quando pagamentos são aprovados, falham ou quando assinaturas mudam de estado. Entre em contato com seu gerente de conta para configurar endpoints de webhook.

​
Próximos passos

Planos

Referência completa da API para listar e inspecionar planos.

Assinaturas

Criar, visualizar e gerenciar assinaturas.

Faturas

Listar, visualizar e pagar faturas.

Métodos de Pagamento

Gerenciar cartões e métodos de pagamento por boleto.

Cupons

Verificar disponibilidade de cupons antes de aplicar.

Vouchers

Visualizar vouchers de crédito aplicados à organização.