Integração para construtoras e incorporadoras

A API REST v1 da Conecta Lar é a vantagem exclusiva de integração da nossa PropTech: conecte seu ERP, CRM ou portal de vendas ao Fundo Mutualista Imobiliário em poucas chamadas HTTP — com OAuth 2.0, webhooks assinados e ambiente de sandbox.

Visão geral

• Base URL: https://api.conectalar.tech/v1
• Sandbox: https://sandbox.api.conectalar.tech/v1
• Formato: JSON (UTF-8), datas em ISO 8601, valores em BRL (centavos quando sufixados por _centavos).
• Versionamento: via prefixo de path (/v1, /v2). Mudanças incompatíveis não entram em v1.

Autenticação — OAuth 2.0 (client credentials)

Cada construtora recebe um par client_id / client_secret no painel do plano SaaS. Troque por um access_token de curta duração (1h) e use no header Authorization: Bearer.

curl -X POST https://api.conectalar.tech/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_01H...",
    "client_secret": "sk_live_...",
    "scope": "grupos:write cotas:write pagamentos:read"
  }'

Escopos disponíveis

• grupos:read / grupos:write
• cotas:read / cotas:write
• pagamentos:read / pagamentos:write
• entregas:read / entregas:write
• webhooks:manage

Limites e idempotência

• Rate limit: 600 req/min por plano Growth, 2.000 req/min no Scale, sob acordo no Enterprise.
• Idempotência: envie Idempotency-Key em todo POST — chaves duplicadas retornam a mesma resposta por 24h.
• Paginação: ?cursor=...&limit=50 (máx. 200).

curl -X POST https://api.conectalar.tech/v1/grupos \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "empreendimento_id": "emp_01H...",
    "nome": "Residencial Aurora",
    "cotas_totais": 120,
    "valor_unidade_brl": 320000,
    "prazo_meses": 96
  }'

curl -X POST https://api.conectalar.tech/v1/cotas \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grupo_id": "grp_01H...",
    "associado": {
      "nome": "Maria Silva",
      "cpf": "000.000.000-00",
      "email": "maria@exemplo.com.br"
    },
    "valor_mensal_brl": 1490
  }'

Webhooks

Configure uma URL HTTPS no painel para receber eventos. Cada requisição traz o header X-ConectaLar-Signature com HMAC-SHA256 do corpo cru, assinado pelo seu webhook_secret. Verifique sempre com comparação timing-safe antes de processar.

Códigos de erro

• 400 — payload inválido (detalhes em error.fields).
• 401 — token ausente, expirado ou escopo insuficiente.
• 404 — recurso não existe ou não pertence à sua construtora.
• 409 — conflito de idempotência ou regra de negócio.
• 422 — violação de regra mutualista (ex.: grupo com cotas esgotadas).
• 429 — rate limit atingido.
• 5xx — incidente do nosso lado; consulte status.conectalar.tech.

Conformidade

Toda chamada à API é registrada em trilha de auditoria imutável, atendendo LGPD (Lei 13.709/18), MP 2.200-2/2001 (assinaturas eletrônicas) e às regras de PLD/FT aplicáveis à Asaas como instituição de pagamento autorizada pelo Banco Central.