# Zapini API — Contactos y Mensajes Programados

**Versión:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticación

Todos los endpoints requieren un Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Genera tokens de API en el panel admin en **API Docs → Gestionar Tokens**.

---

## Contactos

### GET /contacts

Listar contactos.

**Parámetros de Consulta:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| instance_id | string | UUID de instancia |
| search | string | Buscar por nombre, número, email o empresa |
| is_group | boolean | Filtrar grupos |
| sort | string | Campo de ordenación |
| dir | string | Dirección (asc, desc) |
| per_page | integer | Elementos por página |

---

### POST /contacts

Crear un nuevo contacto.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| instance_id | string | Sí | UUID de instancia |
| phone_number | string | Sí | Número de teléfono |
| first_name | string | No | Nombre |
| last_name | string | No | Apellido |
| display_name | string | No | Nombre de visualización |
| email | string | No | Email |
| company | string | No | Empresa |
| job_title | string | No | Cargo |
| notes | string | No | Notas |
| custom_fields | object | No | Campos personalizados |

---

### POST /contacts/import

Importar contactos en masa.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| instance_id | string | Sí | UUID de instancia |
| contacts | array | Sí | Lista de contactos (máx. 1000) |

**Ejemplo:**

```bash
curl -X POST https://zapini.app/api/v1/contacts/import \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "contacts": [
      {
        "phone_number": "+15551234567",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com"
      },
      {
        "phone_number": "+15559876543",
        "first_name": "Jane",
        "company": "XYZ Corp"
      }
    ]
  }'
```

---

### GET /contacts/{uuid}

Retorna detalles del contacto.

---

### PATCH /contacts/{uuid}

Actualizar un contacto.

---

### DELETE /contacts/{uuid}

Eliminar un contacto.

---

### GET /contacts/{uuid}/messages

Listar mensajes intercambiados con un contacto.

---

## Mensajes Programados

### GET /scheduled

Listar mensajes programados.

**Parámetros de Consulta:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| instance_id | string | UUID de instancia |
| from | datetime | Fecha de inicio |
| to | datetime | Fecha de fin |
| per_page | integer | Elementos por página |

---

### POST /scheduled

Programar un nuevo mensaje.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| instance_id | string | Sí | UUID de instancia |
| recipient | string | Sí* | Número del destinatario |
| contact_id | string | Sí* | UUID del contacto (alternativo a recipient) |
| message | string | Sí | Contenido del mensaje |
| scheduled_at | datetime | Sí | Fecha/hora de envío |
| media_url | string | No | URL de medios |
| media_type | string | No | Tipo de medios |

*Se requiere uno de los dos: recipient o contact_id

---

### GET /scheduled/{uuid}

Retorna detalles del mensaje programado.

---

### PATCH /scheduled/{uuid}

Actualizar un mensaje programado pendiente.

---

### DELETE /scheduled/{uuid}

Cancelar un mensaje programado.

---

### POST /scheduled/{uuid}/send-now

Enviar el mensaje programado inmediatamente.

---

*Generado por Zapini — https://zapini.app*