API REST v1

Documentação da API Propulxia

Integre o poder da Propulxia diretamente ao seu CRM, às suas ferramentas internas ou aos seus aplicativos. Crie propostas, gerencie seus prospects e receba atualizações em tempo real por meio dos nossos webhooks.

Introdução

A API Propulxia é do tipo REST, baseada em respostas no formato JSON e protegida por chave de API.

URL base : https://app.propulxia.com/api/v1
Formato : JSON (Content-Type: application/json)
Autenticação : Clé API
Disponibilidade : Forfait Entreprise (pro)

1. Autenticação

Todas as requisições à API exigem uma chave de API enviada no cabeçalho de requisição HTTP Authorization:

Authorization: Bearer plx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Obter uma chave de API

As chaves são geradas no seu painel em Configurações → Acesso à API. Você pode nomear várias chaves para diferentes ambientes ou revogá-las a qualquer momento. A chave é exibida uma única vez, no momento da criação: guarde-a com segurança.

2. Convenções

Os identificadores (id) são cadeias de caracteres opacas.
Os valores são expressos na unidade monetária corrente (ex.: 1500.00 para R$ 1.500,00).
As datas (createdAt, etc.) são timestamps Unix em milissegundos.
Qualquer erro retorna um corpo no formato {"error": "message"} com o código HTTP correspondente.

3. Propostas

GET/proposals

Lista as propostas da sua conta.

curl https://app.propulxia.com/api/v1/proposals?status=sent&limit=10 \
  -H "Authorization: Bearer plx_live_..."

{
  "proposals": [
    {
      "id": "abc123",
      "title": "Refonte site web — Acme inc.",
      "status": "sent",
      "clientId": "cl_789",
      "companyId": "co_456",
      "totalAmount": 4500,
      "currency": "CAD",
      "shareUrl": "https://app.propulxia.com/share/a1b2c3...",
      "createdAt": 1737331200000
    }
  ]
}

POST/proposals

Cria uma nova proposta.

curl -X POST https://app.propulxia.com/api/v1/proposals \
  -H "Authorization: Bearer plx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refonte site web",
    "clientId": "cl_789",
    "companyId": "co_456",
    "totalAmount": 4500,
    "currency": "CAD"
  }'

POST/proposals/:id/send

Envia a proposta por e-mail e altera seu status para sent.

curl -X POST https://app.propulxia.com/api/v1/proposals/abc123/send \
  -H "Authorization: Bearer plx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "client@example.com"}'

4. Clientes

Gerencie seus clientes comerciais (contatos dentro das suas empresas-alvo) por meio destes endpoints:

Método	Rota	Descrição
GET	/clients	Lista todos os clientes.
GET	/clients/:id	Detalhes de um cliente.
POST	/clients	Criação de um prospect (firstName, lastName, email).
PATCH	/clients/:id	Atualização parcial das informações do cliente.
DELETE	/clients/:id	Exclusão de um cliente.

5. Tarefas

Gerencie as tarefas de follow-up e acompanhamento associadas às suas propostas e prospects:

Método	Rota	Descrição
GET	/tasks	Lista todas as tarefas da conta.
GET	/tasks/:id	Recupera os detalhes de uma tarefa.
POST	/tasks	Cria uma tarefa (title, dueDate obrigatórios).
PATCH	/tasks/:id	Modifica uma tarefa existente.
DELETE	/tasks/:id	Exclui uma tarefa.

Exemple de création de tâche :

curl -X POST https://app.propulxia.com/api/v1/tasks \
  -H "Authorization: Bearer plx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Relancer le client Acme",
    "dueDate": 1789958156580,
    "proposalId": "abc123",
    "status": "todo"
  }'

6. Modelos (Templates)

Recupere em modo somente leitura os modelos de propostas estruturados criados na sua conta:

Método	Rota	Descrição
GET	/templates	Lista todos os modelos.
GET	/templates/:id	Detalhes e seções de um modelo.

7. Catálogo de Produtos

Sincronize sua biblioteca de itens ou tabelas de preços com suas ferramentas de faturamento:

Método	Rota	Descrição
GET	/products	Lista os produtos.
GET	/products/:id	Detalhes de um produto.
POST	/products	Criação de um produto (name, price obrigatórios).
PATCH	/products/:id	Atualização de um produto.
DELETE	/products/:id	Exclusão de um produto.

8. Colaboradores (Equipe)

Gerencie as contas dos colaboradores da sua organização comercial:

Método	Rota	Descrição
GET	/employees	Lista a equipe.
GET	/employees/:id	Detalhes de um colaborador.
POST	/employees	Adição de um membro (firstName, lastName, email obrigatórios).
PATCH	/employees/:id	Atualização de um membro.
DELETE	/employees/:id	Remoção de um membro.

9. Relatórios

GET/reports/summary

Recupera KPIs sobre o seu desempenho comercial.

{
  "totalProposals": 42,
  "byStatus": { "backlog": 5, "in_progress": 3, "sent": 10, "won": 20, "lost": 4 },
  "totalValue": 187500,
  "wonValue": 92000,
  "winRate": 0.8333
}

10. Webhooks

Inscreva uma URL HTTPS para receber notificações em tempo real.

Eventos disponíveis:

proposal.created: Proposta criada via API.
proposal.sent: Proposta enviada.
proposal.paid: Pagamento de entrada ou saldo confirmado.
proposal.signed: Proposta assinada eletronicamente pelo cliente.

Inscrição:

curl -X POST https://app.propulxia.com/api/v1/webhooks \
  -H "Authorization: Bearer plx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-service.com/webhooks/propulxia",
    "events": ["proposal.sent", "proposal.paid"]
  }'

11. Integrações (Zapier)

Conecte a Propulxia a mais de 6.000 aplicativos via Zapier, sem escrever código. A integração oficial se apoia nesta API e em seus webhooks.

Gatilhos (quando um evento ocorre na Propulxia):

proposal.created
proposal.sent
proposal.signed
proposal.paid
new_client

Ações (o Zapier atua na Propulxia):

create_proposal
create_client
send_proposal

Busca:

find_client

Como conectar

No Zapier, procure por “Propulxia” e cole uma chave de API gerada em Configurações → Acesso à API. Cada Zap atua apenas na sua conta.

12. Códigos de erro

Código	Significado / Causa
400	Requisição malformada ou campos obrigatórios ausentes.
401	Autenticação ausente ou chave de API inválida.
403	O plano não inclui a API ou permissão insuficiente sobre o recurso.
404	Recurso não encontrado.

13. Limites

Não há limitação estrita de taxa nesta versão (Rate Limits), desde que o uso seja razoável. A paginação padrão limita as requisições de listas a 25 resultados (máx. 100).