Empresas y empleados

Todos los endpoints de esta página requieren la cabecera X-API-Key (ver Integraciones). Las empresas se identifican por su slug, que eliges tú al crearlas y sirve de clave de correspondencia con tu CRM.

Empresas

Crear una empresa

POST /api/v1/integrations/companies/
X-API-Key: fc_xxxxx
Content-Type: application/json

{
  "slug": "mi-negocio",
  "name": "Mi Negocio SL",
  "tax_id": "B12345678",
  "email": "contacto@minegocio.com",
  "subscription_plan": "bikecrm",
  "admin_email": "admin@minegocio.com",
  "admin_first_name": "Ana",
  "admin_last_name": "García"
}

Respuesta 201 Created:

{
  "id": "uuid",
  "slug": "mi-negocio",
  "name": "Mi Negocio SL",
  "tax_id": "B12345678",
  "email": "contacto@minegocio.com",
  "subscription_plan": "bikecrm",
  "max_employees": 10,
  "is_active": true,
  "created_at": "2026-01-01T00:00:00Z"
}

• subscription_plan debe estar entre los planes permitidos de tu clave.
• Los campos admin_* crean el usuario responsable de la empresa.
• El slug es además el subdominio del portal de empleados (mi-negocio.web.fichachat.com).

Consultar una empresa

GET /api/v1/integrations/companies/{slug}/
X-API-Key: fc_xxxxx

Actualizar una empresa

PATCH para cambios parciales (solo se modifican los campos enviados); PUT exige el cuerpo completo.

PATCH /api/v1/integrations/companies/{slug}/
X-API-Key: fc_xxxxx
Content-Type: application/json

{ "name": "Mi Negocio, S.L.", "email": "nuevo@minegocio.com" }

Empleados

Listar empleados

GET /api/v1/integrations/companies/{slug}/employees/
X-API-Key: fc_xxxxx

Respuesta 200 OK (paginada, 20 por página):

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "uuid",
      "email": "empleada@minegocio.com",
      "first_name": "Laura",
      "last_name": "Pérez",
      "full_name": "Laura Pérez",
      "employee_code": "crm-123",
      "department": "Ventas",
      "position": "Responsable",
      "is_active": true,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Crear un empleado

POST /api/v1/integrations/companies/{slug}/employees/
X-API-Key: fc_xxxxx
Content-Type: application/json

{
  "email": "empleada@minegocio.com",
  "first_name": "Laura",
  "last_name": "Pérez",
  "employee_code": "crm-123",
  "department": "Ventas",
  "position": "Responsable"
}

Respuesta 201 Created con el objeto del empleado. El alta respeta el límite de empleados del plan de la empresa.

Actualizar un empleado

PUT /api/v1/integrations/companies/{slug}/employees/{id}/
X-API-Key: fc_xxxxx
Content-Type: application/json

{ "department": "Marketing", "position": "Directora" }

Eliminar un empleado

DELETE /api/v1/integrations/companies/{slug}/employees/{id}/
X-API-Key: fc_xxxxx

Respuesta 204 No Content. Es una eliminación lógica: el empleado deja de estar activo pero sus registros se conservan los 4 años que exige la ley.

Sincronización masiva (upsert)

Crea o actualiza varios empleados en una sola llamada. La correspondencia se hace por employee_code o, en su defecto, por email.

POST /api/v1/integrations/companies/{slug}/employees/sync/
X-API-Key: fc_xxxxx
Content-Type: application/json

{
  "employees": [
    { "email": "laura@minegocio.com", "first_name": "Laura", "last_name": "Pérez", "employee_code": "crm-123" },
    { "email": "marc@minegocio.com",  "first_name": "Marc",  "last_name": "Soler", "employee_code": "crm-456" }
  ]
}

Respuesta 200 OK:

{ "created": ["uuid1", "uuid2"], "updated": [], "errors": [] }

Revisa siempre errors: la sincronización continúa con el resto de empleados aunque alguno falle.

Ejemplo de cliente en Python

import httpx

class FichaChatClient:
    def __init__(self, api_key: str, base_url: str = "https://api.fichachat.com"):
        self.client = httpx.Client(
            base_url=base_url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            timeout=15,
        )

    def create_company(self, slug: str, name: str, tax_id: str, email: str,
                       subscription_plan: str = "bikecrm", **kwargs) -> dict:
        r = self.client.post("/api/v1/integrations/companies/", json={
            "slug": slug, "name": name, "tax_id": tax_id,
            "email": email, "subscription_plan": subscription_plan, **kwargs,
        })
        r.raise_for_status()
        return r.json()

    def sync_employees(self, company_slug: str, employees: list[dict]) -> dict:
        r = self.client.post(
            f"/api/v1/integrations/companies/{company_slug}/employees/sync/",
            json={"employees": employees},
        )
        r.raise_for_status()
        return r.json()


client = FichaChatClient("fc_xxxxx")
client.create_company("mi-negocio", "Mi Negocio SL", "B12345678", "contacto@minegocio.com")
client.sync_employees("mi-negocio", [
    {"email": "laura@minegocio.com", "first_name": "Laura", "employee_code": "001"},
    {"email": "marc@minegocio.com", "first_name": "Marc", "employee_code": "002"},
])