properfy-sdk

A TypeScript SDK for Properfy API - the Brazilian ERP system for real estate agencies.

Features

• Full TypeScript support with auto-generated types from OpenAPI spec
• Automatic authentication and token refresh
• Support for both Node.js and browser environments
• Modular API design for easy maintenance
• Comprehensive error handling
• Built with axios for reliable HTTP requests

Installation

npm install properfy-sdk

Quick Start

import { ProperfyClient } from 'properfy-sdk';

const client = new ProperfyClient({
  baseUrl: 'https://sistema.yourcompany.com.br/api',
  email: '[email protected]',
  password: 'your-password',
});

const properties = await client.properties.list();
console.log(properties);

Configuration

The SDK requires a configuration object with the following properties:

interface ProperfyConfig {
  baseUrl: string;
  email: string;
  password: string;
  token?: string;
}

• baseUrl: Your Properfy instance URL (e.g., https://sistema.yourcompany.com.br/api)
• email: Your user email
• password: Your user password
• token: (Optional) Existing token to reuse

Sandbox Environment

For testing, use the sandbox environment:

const client = new ProperfyClient({
  baseUrl: 'https://sandbox.properfy.com.br/api',
  email: '[email protected]',
  password: 'POMRDSCW',
});

API Modules

The SDK is organized into the following modules:

Authentication

const authInfo = await client.authenticate();
console.log(authInfo.token, authInfo.company, authInfo.name);

Properties

const properties = await client.properties.list({ page: 1, chrStatus: 'ACTIVE' });
const property = await client.properties.get(1894);
const newProperty = await client.properties.create({ /* property data */ });
await client.properties.update(1894, { /* updated data */ });
await client.properties.delete(1894);

const shared = await client.properties.getShared();
const documents = await client.properties.listDocuments(1894);
await client.properties.addNote(1894, { chrNote: 'Important note' });
const report = await client.properties.getReport({
  dateStart: '2024-01-01',
  dateEnd: '2024-12-31'
});

Contracts

const contracts = await client.contracts.list({ page: 1 });
const contract = await client.contracts.get(2149);
const newContract = await client.contracts.create({ /* contract data */ });
await client.contracts.update(2149, { /* updated data */ });
await client.contracts.delete(2149);

const documents = await client.contracts.listDocuments(2149);
await client.contracts.addNote(2149, { chrNote: 'Contract note' });
const readjustments = await client.contracts.getReadjustmentList(630);

Partners

const owners = await client.partners.listOwners({ page: 1 });
const renters = await client.partners.listRenters({ chrStatus: 'ACTIVE' });
const bondsmen = await client.partners.listBondsmen();
const providers = await client.partners.listProviders();
const agents = await client.partners.listAgents();

await client.partners.create('owner', { /* owner data */ });
await client.partners.update('renter', 123, { /* updated data */ });
await client.partners.delete('bondsman', 456);

Maintenance

const maintenances = await client.maintenance.list({ page: 1 });
const maintenance = await client.maintenance.get(57);
await client.maintenance.create({ /* maintenance data */ });
await client.maintenance.update(57, { /* updated data */ });

const documents = await client.maintenance.listDocuments(57);
await client.maintenance.addNote(57, { chrNote: 'Maintenance update' });

Financial

const revenues = await client.financial.listRevenues({
  dateStart: '2024-01-01',
  dateEnd: '2024-12-31'
});
await client.financial.createRevenue({ /* revenue data */ });
await client.financial.updateRevenue(123, { /* updated data */ });
await client.financial.deleteRevenue(123);

const outlays = await client.financial.listOutlays({
  dateStart: '2024-01-01',
  dateEnd: '2024-12-31'
});
await client.financial.createOutlay({ /* outlay data */ });
await client.financial.updateOutlay(456, { /* updated data */ });
await client.financial.deleteOutlay(456);

const statement = await client.financial.getFinancialStatement({
  dateStart: '2024-01-01',
  dateEnd: '2024-12-31'
});

Users

const users = await client.users.list({ page: 1 });
await client.users.create({
  chrName: 'John Doe',
  chrEmail: '[email protected]',
  chrPass: 'password123',
  fkCompany: 1,
  fkAccessProfile: 1,
});
await client.users.update(52, { chrName: 'Jane Doe' });

Access Profiles

const profiles = await client.accessProfiles.list();
await client.accessProfiles.create({
  chrAlias: 'Manager',
  rules: [
    { endpoint: 'property/property', rule: 1 },
    { endpoint: 'rental/contract', rule: 1 },
  ],
});
await client.accessProfiles.update(7, { chrAlias: 'Senior Manager' });

Company

const companyInfo = await client.company.get();
await client.company.update({ /* company data */ });

CRM

const leads = await client.crm.listLeads({ page: 1, chrStatus: 'OPEN' });
const lead = await client.crm.getLead(123);
await client.crm.createLead({ /* lead data */ });
await client.crm.updateLead(123, { /* updated data */ });

Date Format

All date fields should be in YYYY-MM-DD format:

const properties = await client.properties.getReport({
  dateStart: '2024-01-01',
  dateEnd: '2024-12-31',
});

Error Handling

The SDK automatically handles authentication errors and retries with a fresh token. For other errors, use try-catch:

try {
  const property = await client.properties.get(123);
} catch (error) {
  console.error('Failed to fetch property:', error);
}

Development

Building the SDK

npm run build

Running Tests

npm test
npm run test:watch

Regenerating Types

If the Postman collection is updated, regenerate types:

npm run generate

This will:

1. Convert the Postman collection to OpenAPI spec
2. Generate TypeScript types from the OpenAPI spec

Project Structure

properfy-sdk/
├── src/
│   ├── api/           # API modules (properties, contracts, etc.)
│   ├── auth/          # Authentication management
│   ├── types/         # TypeScript type definitions
│   ├── utils/         # HTTP client and utilities
│   ├── client.ts      # Main SDK client
│   └── index.ts       # Public exports
├── schemas/           # Postman collection and OpenAPI spec
├── scripts/           # Build scripts
└── dist/              # Compiled JavaScript output

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT

Support

For issues or questions about the Properfy API, contact [email protected] or your account manager.