Creating Properties

Learn how to create new property listings in the Sistema de Gestión de Propiedades API using the POST /api/propiedades endpoint.

This endpoint requires authentication. See the Authentication guide for setup instructions.

Endpoint

POST https://idforideas-1.jamrdev.com.ar/api/propiedades

Required Fields

When creating a property, you must provide:

pais (string) - Country
ciudad (string) - City
direccion (string) - Street address
ambientes (number) - Number of rooms
metros_cuadrados (number) - Square meters
precio (number) - Price
tipo_contratacion (enum) - “Alquiler” or “Venta”
estado (enum) - “Disponible”, “Reservado”, “Alquilado”, or “Vendido”

Optional Fields

codigo_id (string, 6 characters) - Custom property ID. If not provided, one will be auto-generated
descripcion (string) - Property description

Property ID Generation

The API handles property IDs intelligently:

Auto-generated
Custom ID

If you don’t provide a codigo_id, the API automatically generates a unique 6-character alphanumeric ID:

{
  "ciudad": "Buenos Aires",
  // ... other fields ...
  // No codigo_id provided
}

The API will:

Generate a random 6-character ID (e.g., “A7K92M”)
Check for uniqueness in the database
Retry up to 5 times if there’s a collision
Return the generated ID in the response

If you provide a codigo_id, the API validates it:

{
  "codigo_id": "ZN1001",
  "ciudad": "Buenos Aires",
  // ... other fields ...
}

The API will:

Validate it’s exactly 6 characters
Check it doesn’t already exist
Return a 409 Conflict error if it’s a duplicate

ID generation uses alphanumeric characters excluding O (letter O) to avoid confusion with 0 (zero).Character set: ABCDEFGHIJKLMNPQRSTUVWXYZ123456789Source: Backend/src/controllers/propiedades.controller.ts:24-30

Basic Example

curl -X POST https://idforideas-1.jamrdev.com.ar/api/propiedades \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "pais": "Argentina",
    "ciudad": "Buenos Aires",
    "direccion": "Av. Corrientes 1234",
    "ambientes": 2,
    "metros_cuadrados": 65,
    "precio": 95000,
    "tipo_contratacion": "Alquiler",
    "estado": "Disponible",
    "descripcion": "Departamento luminoso en el centro"
  }'

Success Response

Status Code: 201 Created

{
  "success": true,
  "message": "Propiedad creada correctamente",
  "id": "A7K92M"
}

The id field contains the property’s codigo_id (either the one you provided or the auto-generated one).

Complete Examples

Rental Property (Auto-generated ID)

curl -X POST https://idforideas-1.jamrdev.com.ar/api/propiedades \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "pais": "Argentina",
    "ciudad": "Tigre",
    "direccion": "Av. Cazón 456",
    "ambientes": 3,
    "metros_cuadrados": 85.5,
    "precio": 150000,
    "tipo_contratacion": "Alquiler",
    "estado": "Disponible",
    "descripcion": "Casa con vista al río"
  }'

Sale Property (Custom ID)

curl -X POST https://idforideas-1.jamrdev.com.ar/api/propiedades \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "codigo_id": "VT2024",
    "pais": "Argentina",
    "ciudad": "La Plata",
    "direccion": "Calle 50 N° 123",
    "ambientes": 4,
    "metros_cuadrados": 120,
    "precio": 2500000,
    "tipo_contratacion": "Venta",
    "estado": "Disponible",
    "descripcion": "Casa familiar con jardín"
  }'

Minimal Property (Required Fields Only)

curl -X POST https://idforideas-1.jamrdev.com.ar/api/propiedades \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "pais": "Argentina",
    "ciudad": "Rosario",
    "direccion": "Av. Pellegrini 789",
    "ambientes": 1,
    "metros_cuadrados": 35,
    "precio": 65000,
    "tipo_contratacion": "Alquiler",
    "estado": "Disponible"
  }'

Error Responses

400 Bad Request - Validation Error

Returned when the request data doesn’t match the schema:

{
  "success": false,
  "error": "Invalid input: ..."
}

Common validation errors:

codigo_id must be exactly 6 characters

# Wrong: 4 characters
{ "codigo_id": "AB12" }

# Wrong: 8 characters  
{ "codigo_id": "AB123456" }

# Correct: exactly 6
{ "codigo_id": "AB1234" }

Invalid tipo_contratacion

Must be exactly “Alquiler” or “Venta” (case-sensitive):

# Wrong
{ "tipo_contratacion": "alquiler" }  # lowercase
{ "tipo_contratacion": "Rent" }      # English

# Correct
{ "tipo_contratacion": "Alquiler" }
{ "tipo_contratacion": "Venta" }

Invalid estado

Must be one of: “Disponible”, “Reservado”, “Alquilado”, “Vendido”

# Wrong
{ "estado": "disponible" }  # lowercase
{ "estado": "Available" }   # English

# Correct
{ "estado": "Disponible" }
{ "estado": "Reservado" }
{ "estado": "Alquilado" }
{ "estado": "Vendido" }

Missing required fields

{
  "success": false,
  "error": "Required field missing: ciudad"
}

All of these are required:

pais, ciudad, direccion
ambientes, metros_cuadrados, precio
tipo_contratacion, estado

Invalid data types

# Wrong: price as string
{ "precio": "100000" }

# Wrong: rooms as string
{ "ambientes": "3" }

# Correct: numbers as numbers
{ "precio": 100000, "ambientes": 3 }

401 Unauthorized

Returned when authentication is missing or invalid:

{
  "error": "Unauthorized"
}

Verify your credentials using the /api/auth/verify endpoint before attempting to create properties.

409 Conflict - Duplicate ID

Returned when you provide a codigo_id that already exists:

{
  "success": false,
  "error": "El código ZN1001 ya existe."
}

Solution: Either:

Use a different codigo_id
Omit codigo_id to let the API auto-generate one

Field Validation Rules

Field	Type	Constraints
codigo_id	string	Exactly 6 characters (optional)
pais	string	Required
ciudad	string	Required
direccion	string	Required
ambientes	number	Required, integer
metros_cuadrados	number	Required, can be decimal
precio	number	Required, can be decimal
tipo_contratacion	enum	”Alquiler” or “Venta”
estado	enum	”Disponible”, “Reservado”, “Alquilado”, “Vendido”
descripcion	string	Optional

For complete validation details, see Validation Rules.

Best Practices

Validate locally first

Check your data matches the schema before sending the request to avoid unnecessary API calls.

Let the API generate IDs

Unless you have a specific naming convention, let the API auto-generate unique IDs.

Use descriptive descriptions

The descripcion field helps users understand property features at a glance.

Set appropriate status

New properties should typically have estado: "Disponible" unless they’re pre-reserved.

Handle errors gracefully

Always check the response status and handle validation errors appropriately.

Implementation Details

The creation logic (from Backend/src/controllers/propiedades.controller.ts:32-96):

Parse the request body
Determine ID (provided or generate)
Check for uniqueness (retry up to 5 times for auto-generated IDs)
Validate against Zod schema
Insert into database
Return success with the property ID

// Simplified from source
export const createPropiedad = async (c: Context) => {
  const body = await c.req.json();
  
  // Auto-generate ID if not provided
  let uniqueId = body.codigo_id || generarCodigoId();
  
  // Check uniqueness
  const existing = await c.env.DB.prepare(
    'SELECT codigo_id FROM propiedades WHERE codigo_id = ?'
  ).bind(uniqueId).first();
  
  if (existing && body.codigo_id) {
    return c.json({ 
      success: false, 
      error: `El código ${body.codigo_id} ya existe.` 
    }, 409);
  }
  
  // Validate with Zod
  const validated = PropiedadSchema.parse(body);
  
  // Insert into database
  await c.env.DB.prepare(`INSERT INTO propiedades (...) VALUES (...)`)
    .bind(...values)
    .run();
  
  return c.json({ 
    success: true, 
    message: 'Propiedad creada correctamente',
    id: validated.codigo_id 
  }, 201);
};

Next Steps

Update Properties

Learn how to update existing properties

Query Properties

Retrieve and filter property listings

Error Handling

Handle API errors gracefully

API Reference

Complete API reference for this endpoint

Get Started

Authentication

Guides

Deployment

Creating properties

Creating Properties

Endpoint

Required Fields

Optional Fields

Property ID Generation

Basic Example

Success Response

Complete Examples

Rental Property (Auto-generated ID)

Sale Property (Custom ID)

Minimal Property (Required Fields Only)

Error Responses

400 Bad Request - Validation Error

401 Unauthorized

409 Conflict - Duplicate ID

Field Validation Rules

Best Practices

Implementation Details

Next Steps

Update Properties

Query Properties

Error Handling

API Reference

Build docs developers (and LLMs) love

Get Started

Authentication

Guides

Deployment

​Creating Properties

​Endpoint

​Required Fields

​Optional Fields

​Property ID Generation

​Basic Example

​Success Response

​Complete Examples

​Rental Property (Auto-generated ID)

​Sale Property (Custom ID)

​Minimal Property (Required Fields Only)

​Error Responses

​400 Bad Request - Validation Error

​401 Unauthorized

​409 Conflict - Duplicate ID

​Field Validation Rules

​Best Practices

​Implementation Details

​Next Steps

Update Properties

Query Properties

Error Handling

API Reference

Build docs developers (and LLMs) love

Creating Properties

Endpoint

Required Fields

Optional Fields

Property ID Generation

Basic Example

Success Response

Complete Examples

Rental Property (Auto-generated ID)

Sale Property (Custom ID)

Minimal Property (Required Fields Only)

Error Responses

400 Bad Request - Validation Error

401 Unauthorized

409 Conflict - Duplicate ID

Field Validation Rules

Best Practices

Implementation Details

Next Steps