Skip to main content
POST
/
api
/
sales
curl -X POST https://api.imperiumpay.com.br/api/sales \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "paymentMethod": "PIX",
    "customer": {
      "name": "João Silva Santos",
      "email": "joao.silva@exemplo.com.br",
      "document": {
        "type": "cpf",
        "number": "12345678900"
      },
      "phone": "11999999999"
    },
    "items": [
      {
        "title": "Assinatura Premium Mensal",
        "unitPrice": 5000,
        "quantity": 1,
        "tangible": false
      }
    ],
    "subscription": {
      "enabled": true,
      "billingCycle": "MONTHLY",
      "trialDays": 0
    },
    "postbackUrl": "https://seusite.com.br/webhook/assinatura"
  }'

{
  "message": "Venda criada com sucesso",
  "sale": {
    "id": 4607,
    "amount": "5000",
    "status": "PENDENTE",
    "paymentMethod": "PIX",
    "customer": {
      "name": "João Silva Santos",
      "email": "joao.santos@example.com",
      "document": "12345678900",
      "phone": "5511999999999"
    },
    "payment": {
      "method": "PIX",
      "installments": null,
      "pix": {
        "key": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix...",
        "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOQ...",
        "expiresAt": null
      }
    },
    "shipping": null,
    "createdAt": "2026-02-24T15:30:00.000Z",
    "subscription": {
      "id": 123,
      "status": "PENDING",
      "billingCycle": "MONTHLY",
      "amount": 5000,
      "nextBillingDate": "2026-03-24T15:30:00.000Z",
      "trialEndsAt": null,
      "customerEmail": "joao.santos@example.com",
      "customerName": "João Silva Santos"
    }
  }
}
Crie uma nova assinatura recorrente adicionando o bloco subscription na criação de uma transação. A assinatura será criada automaticamente após o processamento da venda.

​
Autenticação

Este endpoint requer autenticação via API Keys:
​
X-Api-Public-Key
string
required
Sua chave pública da API
​
X-Api-Private-Key
string
required
Sua chave privada da API

​
Parâmetros do Body

Além dos parâmetros padrão de criação de transação, inclua o bloco subscription:

​
Parâmetros de Assinatura

​
subscription
object
required
Configuração da assinatura recorrente
​
subscription.enabled
boolean
required
Define se a venda deve criar uma assinatura. Use true para criar assinatura.
​
subscription.billingCycle
string
required
Ciclo de cobrança. Valores possíveis: WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, YEARLY
​
subscription.trialDays
integer
Número de dias de período de teste gratuito (0-90). Padrão: 0

​
Parâmetros Padrão da Transação

​
amount
integer
required
Valor da assinatura em centavos (ex: 5000 = R$ 50,00)
​
paymentMethod
string
required
Método de pagamento. Valores possíveis: CREDIT_CARD, PIX
​
customer
object
required
Dados do cliente assinante
​
customer.name
string
required
Nome completo do cliente
​
customer.email
string
required
Email do cliente
​
customer.document
object
Documento do cliente (CPF ou CNPJ)
​
customer.document.type
string
Tipo do documento: cpf ou cnpj
​
customer.document.number
string
Número do documento
​
customer.phone
string
Telefone do cliente no formato 11999999999 (sem caracteres especiais)
​
items
array
required
Lista de itens da assinatura
​
items[].title
string
required
Nome do produto/plano
​
items[].unitPrice
integer
required
Preço unitário em centavos
​
items[].quantity
integer
required
Quantidade do item
​
items[].tangible
boolean
required
Se o item é físico (true) ou digital (false)
​
card
object
Informações do cartão (obrigatório para CREDIT_CARD)
​
postbackUrl
string
URL para receber notificações de mudança de status
{
  "message": "Venda criada com sucesso",
  "sale": {
    "id": 4607,
    "amount": "5000",
    "status": "PENDENTE",
    "paymentMethod": "PIX",
    "customer": {
      "name": "João Silva Santos",
      "email": "joao.santos@example.com",
      "document": "12345678900",
      "phone": "5511999999999"
    },
    "payment": {
      "method": "PIX",
      "installments": null,
      "pix": {
        "key": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix...",
        "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOQ...",
        "expiresAt": null
      }
    },
    "shipping": null,
    "createdAt": "2026-02-24T15:30:00.000Z",
    "subscription": {
      "id": 123,
      "status": "PENDING",
      "billingCycle": "MONTHLY",
      "amount": 5000,
      "nextBillingDate": "2026-03-24T15:30:00.000Z",
      "trialEndsAt": null,
      "customerEmail": "joao.santos@example.com",
      "customerName": "João Silva Santos"
    }
  }
}

curl -X POST https://api.imperiumpay.com.br/api/sales \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "paymentMethod": "PIX",
    "customer": {
      "name": "João Silva Santos",
      "email": "joao.silva@exemplo.com.br",
      "document": {
        "type": "cpf",
        "number": "12345678900"
      },
      "phone": "11999999999"
    },
    "items": [
      {
        "title": "Assinatura Premium Mensal",
        "unitPrice": 5000,
        "quantity": 1,
        "tangible": false
      }
    ],
    "subscription": {
      "enabled": true,
      "billingCycle": "MONTHLY",
      "trialDays": 0
    },
    "postbackUrl": "https://seusite.com.br/webhook/assinatura"
  }'

​
Fluxo de Status da Assinatura

Após criar uma transação com assinatura:
  1. Assinatura criada com status PENDING - Aguardando primeiro pagamento
  2. Pagamento confirmado - Status muda para:
    • ACTIVE se não houver período de trial
    • TRIALING se houver período de trial configurado
  3. Cobranças recorrentes - Processadas automaticamente no ciclo definido
Nota: A assinatura só é ativada após a confirmação do primeiro pagamento. Para PIX, isso ocorre quando o cliente efetua o pagamento. Para cartão de crédito, ocorre imediatamente se aprovado.

​
Códigos de Erro

{
  "message": "Campos obrigatórios faltando",
  "error": "Dados inválidos",
  "details": {
    "missingFields": ["subscription.billingCycle"]
  }
}

{
  "message": "Erro de validação",
  "error": "Dados inválidos",
  "details": {
    "field": "subscription.billingCycle",
    "message": "Ciclo de cobrança inválido. Use: WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY"
  }
}

{
  "message": "Erro de validação",
  "error": "Dados inválidos",
  "details": {
    "field": "subscription.trialDays",
    "message": "Período de trial deve ser entre 0 e 90 dias"
  }
}

​
Status HTTP

CódigoDescrição
201Venda e assinatura criadas com sucesso
400Dados inválidos ou campos obrigatórios faltando
401Não autorizado - Chaves de API inválidas
422Erro de validação
500Erro interno do servidor

​
Diferença entre Venda Normal e Assinatura

A única diferença entre criar uma venda normal e uma assinatura é a inclusão do bloco subscription:
AspectoVenda NormalAssinatura
Bloco subscriptionNão incluirIncluir com enabled: true
CobrançaÚnicaRecorrente automática
Status inicialPENDENTEPENDING (assinatura)
Próximas cobrançasManualAutomática