Faturas Internas

Criar Fatura Interna

POST/v1/internal-invoice

Cria uma nova fatura interna para cobrança entre contas. Retorna o QR Code e a URL de acesso à fatura.

Rate limit: 20 requisições por 60 segundos

Definição do Body

Interface TypeScripttypescript

interface CreateInternalInvoiceRequest {
  amount: number;          // Obrigatório — mín. 0.01, máx. 2 casas decimais
  description?: string;    // Opcional — máx. 500 caracteres
  due_date?: string;       // Opcional — ISO 8601, deve ser data futura
  webhook_url?: string;    // Opcional — URL válida, máx. 500 caracteres
  receiver_name?: string;  // Opcional — nome exibido no lado do pagador
}

Parâmetros

Campo	Tipo	Descrição
`amount`obrigatório	`number`	Valor da cobrança em BRL. Mínimo: 0.01, máximo 2 casas decimais.
`description`	`string`	Descrição da fatura exibida ao pagador. Máximo: 500 caracteres.
`due_date`	`string (ISO 8601)`	Data de vencimento. Deve ser uma data futura.
`webhook_url`	`string`	URL para receber notificações quando a fatura for paga ou expirar.
`receiver_name`	`string`	Nome fictício do beneficiário exibido no lado do pagador.

Campos da Resposta

Campo	Tipo	Descrição
`id`	`string (UUID)`	ID único da fatura
`code`	`string`	Código de 8 caracteres para identificar a fatura no painel
`invoice_url`	`string`	URL de acesso à fatura no dashboard
`invoice_qrcode_base64`	`string`	QR Code da fatura em formato base64
`guide`	`string`	Instruções de pagamento para o pagador
`amount`	`number`	Valor bruto da cobrança
`fee`	`number`	Taxa calculada automaticamente
`net_amount`	`number`	Valor líquido (amount - fee)
`status`	`string`	Status da fatura: PENDING, PAID, CANCELLED, EXPIRED
`created_at`	`string (ISO 8601)`	Data e hora de criação

Regras de Negócio

Valor mínimo: R$ 0,01
Taxa calculada automaticamente com base na configuração do usuário recebedor
Transferências internas devem estar habilitadas na conta
Saque automático deve estar habilitado para o usuário
due_date deve ser uma data futura (se informada)

Erros Possíveis

400

Dados inválidos

"O valor da cobrança deve ser maior que zero"
"A data de vencimento deve ser uma data futura"

401

Não autenticado

"API Secret não fornecida"

403

Acesso negado

"Transferências internas estão desabilitadas"
"Saque automático não está habilitado para este usuário"
"Não é possível criar cobranças. Seu acesso está bloqueado"

404

Não encontrado

"Usuário não encontrado"

POSThttps://api.connectpay.vc/v1/internal-invoice

Headers

api-secret: sua-api-secret-aqui
Content-Type: application/json

Request Body (JSON)

{
  "amount": 100.50,
  "description": "Pagamento de serviços mensais",
  "due_date": "2026-02-15T10:00:00Z",
  "webhook_url": "https://exemplo.com/webhook",
  "receiver_name": "Nome do Beneficiário"
}

cURL

curl -X POST "https://api.connectpay.vc/v1/internal-invoice" \
  -H "api-secret: sua-api-secret-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "description": "Pagamento de serviços mensais",
    "due_date": "2026-02-15T10:00:00Z",
    "webhook_url": "https://exemplo.com/webhook",
    "receiver_name": "Nome do Beneficiário"
  }'

Response 200

{
  "hasError": false,
  "message": "Cobrança criada com sucesso",
  "data": {
    "id": "uuid-da-cobranca",
    "code": "ABC12345",
    "invoice_url": "https://dashboard.url/finance?invoice_code=ABC12345",
    "invoice_qrcode_base64": "iVBORw0KG...",
    "amount": 100.50,
    "fee": 2.50,
    "net_amount": 98.00,
    "status": "PENDING",
    "created_at": "2026-01-28T10:00:00Z"
  }
}