contacts

Ver en Git

---

Contacts API Documentation

Base URL

/api/sales/contacts

Authentication

All endpoints require JWT authentication. Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

All endpoints are limited to 10 requests per second.

---

Endpoints

1. Get All Contacts

Retrieve all contacts for the authenticated user with filters and pagination.

Endpoint: POST /api/sales/contacts/

Request (Full):

• Method: POST
• Headers: Authorization required
• Body:

{
  "filters": {
    "contacts": ["123e4567-e89b-12d3-a456-426614174000"],
    "search": "John",
    "page": "MTIz",
    "page_size": 10
  }
}

Request (Lite - for selects):

{
  "action": "lite"
}

Request Fields (all optional):

• action: Set to "lite" for minimal response (uuid, first_name, last_name only, no pagination)
• filters: Object containing filter criteria
  • contacts: Array of contact UUIDs to filter by (array of strings, UUID format)
  • accounts: Array of account UUIDs to filter contacts related to those accounts (array of strings, UUID format)
  • search: Search term for contact names (string, case-insensitive, searches first_name and last_name)
  • page: Pagination cursor from previous response (string)
  • page_size: Number of contacts per page (integer, default: 10, max: 1000)

Response (Full):

{
  "code": 0,
  "data": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "associated_accounts": [
        {
          "uuid": "987e6543-e21b-12d3-a456-426614174999",
          "name": "Acme Corp"
        },
        {
          "uuid": "456e7890-e89b-12d3-a456-426614174888",
          "name": "Tech Solutions"
        }
      ]
    }
  ],
  "next_page": "MTIz"
}

Response (Lite):

{
  "code": 0,
  "data": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "first_name": "John",
      "last_name": "Doe"
    },
    {
      "uuid": "456e7890-e89b-12d3-a456-426614174001",
      "first_name": "Jane",
      "last_name": "Smith"
    }
  ]
}

Response Fields (Full):

• uuid: Unique identifier (string, UUID format)
• first_name: First name (string)
• last_name: Last name (string)
• email: Email address (string, nullable)
• phone: Phone number (string, nullable)
• associated_accounts: Array of accounts associated to this contact
  • uuid: Account UUID (string, UUID format)
  • name: Account name (string)
• next_page: Cursor for next page (string, nullable)

Response Fields (Lite):

• uuid: Unique identifier (string, UUID format)
• first_name: First name (string)
• last_name: Last name (string)

Filter Examples:

1. Get all contacts (no filters):

{}

2. Filter by specific contact UUIDs:

{
  "filters": {
    "contacts": [
      "123e4567-e89b-12d3-a456-426614174000",
      "456e7890-e89b-12d3-a456-426614174001"
    ]
  }
}

3. Filter by accounts:

{
  "filters": {
    "accounts": [
      "987e6543-e21b-12d3-a456-426614174999"
    ]
  }
}

4. Search by name:

{
  "filters": {
    "search": "Doe"
  }
}

5. Combined filters with pagination:

{
  "filters": {
    "accounts": ["987e6543-e21b-12d3-a456-426614174999"],
    "search": "John",
    "page_size": 20
  }
}

6. Lite mode for select dropdowns:

{
  "action": "lite"
}

---

2. Get Contact by UUID

Retrieve a specific contact by its UUID.

Endpoint: GET /api/sales/contacts/contact

Request:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Request Fields:

• uuid: Contact UUID (string, required, UUID format)

Response:

{
  "code": 0,
  "data": {
    "id": 1,
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "associated_accounts": [
      {
        "uuid": "987e6543-e21b-12d3-a456-426614174999",
        "name": "Acme Corp"
      }
    ]
  }
}

Response Fields:

• id: Internal database ID (integer)
• uuid: Unique identifier (string, UUID format)
• first_name: First name (string)
• last_name: Last name (string)
• email: Email address (string, nullable)
• phone: Phone number (string, nullable)
• associated_accounts: Array of accounts associated to this contact
  • uuid: Account UUID (string, UUID format)
  • name: Account name (string)

Error Codes:

• Code 4: "Contact not found" - The specified contact UUID doesn't exist or doesn't belong to the user

---

3. Create Contact

Create a new contact.

Endpoint: POST /api/sales/contacts/contact

Request:

{
  "action": "create",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890"
}

Request Fields:

• action: Must be "create" (string, required)
• first_name: First name (string, required, 1-50 characters)
• last_name: Last name (string, required, 1-50 characters)
• email: Email address (string, optional, max 50 characters)
• phone: Phone number (string, optional, max 50 characters)

Response:

{
  "code": 0,
  "message": "Contact created successfully",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890"
  }
}

Error Codes:

• No specific error codes for creation

---

4. Update Contact

Update an existing contact.

Endpoint: POST /api/sales/contacts/contact

Request:

{
  "action": "update",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "phone": "+1234567890"
}

Request Fields:

• action: Must be "update" (string, required)
• uuid: Contact UUID (string, required, UUID format)
• first_name: First name (string, required, 1-50 characters)
• last_name: Last name (string, required, 1-50 characters)
• email: Email address (string, optional, max 50 characters)
• phone: Phone number (string, optional, max 50 characters)

Response:

{
  "code": 0,
  "message": "Contact updated successfully",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "phone": "+1234567890"
  }
}

Error Codes:

• Code 4: "Contact not found" - The specified contact UUID doesn't exist or doesn't belong to the user

---

5. Delete Contact

Delete an existing contact (soft delete).

Endpoint: POST /api/sales/contacts/contact

Request:

{
  "action": "delete",
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Request Fields:

• action: Must be "delete" (string, required)
• uuid: Contact UUID (string, required, UUID format)

Response:

{
  "code": 0,
  "message": "Contact deleted successfully",
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Error Codes:

• Code 4: "Contact not found" - The specified contact UUID doesn't exist or doesn't belong to the user

---

6. Inactivate Contact

Inactivate a contact. Only the owner can inactivate their contacts.

Endpoint: POST /api/sales/contacts/contact

Request:

{
  "action": "inactivate",
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Request Fields:

• action: Must be "inactivate" (string, required)
• uuid: Contact UUID (string, required, UUID format)

Response:

{
  "code": 0,
  "message": "Contact inactivated successfully",
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Notes:

• Only the owner (creator) of the contact can inactivate it
• Sets fecha_inactivacion to current timestamp
• Returns error if contact is already inactive

Error Codes:

• Code 4: "Contact not found or already inactive" - Cannot inactivate (not found or already inactive)

---

7. Activate Contact

Activate an inactive contact. Only the owner can activate their contacts.

Endpoint: POST /api/sales/contacts/contact

Request:

{
  "action": "activate",
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Request Fields:

• action: Must be "activate" (string, required)
• uuid: Contact UUID (string, required, UUID format)

Response:

{
  "code": 0,
  "message": "Contact activated successfully",
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Notes:

• Only the owner (creator) of the contact can activate it
• Sets fecha_inactivacion to NULL
• Returns error if contact is already active

Error Codes:

• Code 4: "Contact not found or already active" - Cannot activate (not found or already active)

---

8. Associate Contact to Account

Associate a contact with an account and assign a role.

Endpoint: POST /api/sales/contacts/associate-account

Request:

{
  "contact_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "account_uuid": "987e6543-e21b-12d3-a456-426614174999",
  "rol_id": 1
}

Request Fields:

• contact_uuid: Contact UUID (string, required, UUID format)
• account_uuid: Account UUID (string, required, UUID format)
• rol_id: Role ID (integer, required, minimum 1)

Response:

{
  "code": 0,
  "message": "Contact associated to account successfully"
}

Notes:

• Both contact and account must belong to the authenticated user's workspace
• The account must be active (not inactivated)

Error Codes:

• Code 6: "Failed to create association" - General association error
• Code 7: "Cannot associate contact to inactive account" - The account is inactive and cannot have new contacts associated
• Code 8: "Association already exists" - The contact is already associated to the account
• Code 9: "Contact or account not found" - Either the contact or account doesn't exist or doesn't belong to the user's workspace

---

Error Response Format

All error responses follow this format:

{
  "res": "error",
  "code": <error_code>,
  "info": "<error_description>"
}

HTTP Status Codes:

• 200: Success
• 400: Bad Request (validation errors)
• 401: Unauthorized (missing or invalid JWT token)
• 429: Too Many Requests (rate limit exceeded)
• 500: Internal Server Error

---

Field Mapping

The API uses English field names in requests/responses, but the database uses Spanish names:

API Field	Database Field	Description
first_name	nombre	First name
last_name	apellido	Last name
email	email	Email address
phone	telefono	Phone number

---

Usage Examples

JavaScript/Fetch Example:

// Get all contacts
const response = await fetch('/api/sales/contacts/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
});

// Get contacts with filters
const filteredResponse = await fetch('/api/sales/contacts/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filters: {
      search: 'John',
      page_size: 20
    }
  })
});

// Create contact
const createResponse = await fetch('/api/sales/contacts/contact', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'create',
    first_name: 'John',
    last_name: 'Doe',
    email: 'john@example.com'
  })
});