Bem-vindo à documentação da API LinkPix. Integre gestão completa de faturas, orçamentos, clientes e pagamentos em sua aplicação.

Documentação da API LinkPix

Integre o sistema completo de faturamento e gestão financeira da LinkPix diretamente em sua aplicação. Crie faturas, orçamentos, gerencie clientes e automatize cobranças recorrentes com nossa API RESTful.

Sistema Completo de Faturamento

A API LinkPix oferece acesso completo para gerenciar faturas, orçamentos, clientes e assinaturas. Ideal para freelancers, agências e empresas que precisam automatizar processos de cobrança.

O que a API oferece

┌─────────────────────────────────────────────────────────────┐
│                     Sua Aplicação                          │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    API LinkPix v1                           │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  • Autenticação por API Key (Produção)                │ │
│  │  • Gestão completa de clientes (PF/PJ)                │ │
│  │  • Criação e gerenciamento de faturas                 │ │
│  │  • Orçamentos profissionais                           │ │
│  │  • Faturas recorrentes (assinaturas)                  │ │
│  │  • Paginação e filtros avançados                      │ │
│  │  • Cálculo automático de impostos e descontos         │ │
│  └───────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              Banco de Dados (Supabase)                      │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  • Dados seguros isolados por equipe                  │ │
│  │  • RLS policies para segurança                        │ │
│  │  • Logs de auditoria completos                        │ │
│  │  • Backup automático e redundância                    │ │
│  └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Por que usar a API LinkPix?

Benefício	Descrição
Gestão Completa	Clientes, faturas, orçamentos e assinaturas em um só lugar
Automatização	Faturas recorrentes geradas automaticamente
Segurança	Dados isolados por equipe com RLS policies
Integração Fácil	API RESTful com autenticação simples via Bearer Token
Auditoria	Logs completos de todas as operações

Primeiros Passos

Obtenha suas credenciais

Acesse o painel de configurações e gere suas chaves de API.

Cada chave está vinculada ao seu time e herda automaticamente suas configurações.

⚠️ Importante: Como não há separação de ambiente, todas as chaves são de produção. Use com cuidado!

Configure a autenticação

Todas as requisições devem incluir o header Authorization com sua chave de API.

Authorization: Bearer mbx_live_sua_chave_aqui

Faça sua primeira requisição

Teste a conexão criando um cliente:

curl -X POST https://app.linkpix.co/api/v1/clients \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "client_type": "individual",
    "full_name": "João da Silva",
    "email": "joao@example.com",
    "phone": "(11) 98765-4321"
  }'

const response = await fetch('https://app.linkpix.co/api/v1/clients', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_type: 'individual',
    full_name: 'João da Silva',
    email: 'joao@example.com',
    phone: '(11) 98765-4321'
  })
});

const { data } = await response.json();
console.log(`Cliente criado: ${data.full_name}`);

import requests

response = requests.post(
    'https://app.linkpix.co/api/v1/clients',
    headers={
        'Authorization': 'Bearer mbx_live_sua_chave_aqui',
        'Content-Type': 'application/json'
    },
    json={
        'client_type': 'individual',
        'full_name': 'João da Silva',
        'email': 'joao@example.com',
        'phone': '(11) 98765-4321'
    }
)

data = response.json()['data']
print(f"Cliente criado: {data['full_name']}")

Base URL

Todas as requisições devem ser feitas para:

https://app.linkpix.co/api/v1

Fluxo Típico de Integração

1. Criar Cliente         →  POST /api/v1/clients
                              ↓
2. Criar Orçamento       →  POST /api/v1/quotes
                              ↓
3. Criar Fatura          →  POST /api/v1/invoices
                              ↓
4. Gerar Link Pagamento  →  GET /api/v1/invoices/:id
                              ↓
5. Enviar para Cliente   →  Use invoice.share_token ou email

Pessoa Física: nome, email, CPF (opcional)
Pessoa Jurídica: razão social, email, CNPJ (opcional)

Faturas (Invoices)

Uma fatura é um documento de cobrança com:

Cliente vinculado
Itens/serviços com quantidade e preço
Cálculo automático de subtotal, impostos e descontos
Número sequencial automático
Status: draft, sent, cancelled
Status de pagamento: pending, partial, paid, overdue

Orçamentos (Quotes)

Um orçamento é uma proposta comercial:

Estrutura similar à fatura
Data de validade
Pode ser convertido em fatura
Status: draft, sent, accepted, declined, cancelled

Faturas Recorrentes (Recurring Invoices)

Assinaturas que geram faturas automaticamente:

Frequência: mensal, bimestral, trimestral, semestral, anual
Dia de vencimento configurável
Geração automática X dias antes do vencimento
Status: active, paused, cancelled, expired

Paginação

Todos os endpoints de listagem suportam paginação:

GET /api/v1/clients?page=1&limit=50

Parâmetro	Padrão	Máximo	Descrição
`page`	1	-	Número da página
`limit`	50	100	Itens por página

Resposta:

{
  "data": {
    "clients": [...],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 150,
      "totalPages": 3
    }
  }
}

Filtros

A maioria dos endpoints suporta filtros:

# Filtrar faturas por status
GET /api/v1/invoices?status=sent&payment_status=pending

# Filtrar clientes por tipo
GET /api/v1/clients?client_type=company&is_active=true

# Buscar cliente por nome/email
GET /api/v1/clients?search=João

Rate Limits

Endpoint	Limite
`/clients/*`	100 req/min
`/invoices/*`	100 req/min
`/quotes/*`	100 req/min
`/recurring-invoices/*`	50 req/min
Health check	Ilimitado

Exceder os limites resultará em resposta 429 Too Many Requests.

Segurança

✅ Boas Práticas

Use variáveis de ambiente para armazenar API keys
Nunca exponha chaves em código front-end ou repositórios públicos
Rotacione chaves periodicamente
Monitore o uso via painel de desenvolvedor
Use HTTPS em todas as requisições

🔒 Proteções Implementadas

Hash SHA-256 das API keys
RLS policies no banco (isolamento por equipe)
Service Role authentication
Logs de auditoria completos
Rate limiting automático

Suporte

Precisa de ajuda com sua integração? Nossa equipe está disponível:

Email: suporte@moblix.com.br
Documentação: Você está aqui! 📚
Painel: app.linkpix.co## Próximos Passos1. Configure a autenticação

Introdução

Documentação da API LinkPix

O que a API oferece

Por que usar a API LinkPix?

Primeiros Passos

Obtenha suas credenciais

Configure a autenticação

Faça sua primeira requisição

Base URL

Fluxo Típico de Integração

Recursos Disponíveis

🔐 Autenticação

👥 Clientes

📄 Faturas

💰 Orçamentos

🔄 Faturas Recorrentes

Conceitos Importantes

Clientes (Clients)