# Consultar contactos y notas

Anunzi ofrece un endpoint para consultar fichas de contacto y sus notas directamente desde tu sistema, sin necesidad de acceder al panel web.

***

## ¿Para qué sirve?

Este endpoint es útil cuando quieres:

* Verificar si existe un contacto en Anunzi y ver su estado antes de iniciar una llamada.
* Leer las notas de gestión de un contacto desde tu CRM o herramienta externa.
* Auditar el historial de notas de los últimos días de forma programática.
* Integrar la información de contactos con flujos de Make, Zapier o scripts propios.

***

## Obtener el token del agente

Cada agente tiene su propio **API Token**, que autoriza el acceso a los datos de tu cuenta. Para obtenerlo:

1. Ve a **Agentes de Llamada** en el menú lateral.
2. Selecciona el agente que quieres usar.
3. En la sección **Resumen**, encontrarás el **API Token** del agente.
4. Cópialo para usarlo en tus solicitudes.

> 🔒 Trata el token como una contraseña. No lo compartas públicamente ni lo incluyas en código que suba a repositorios públicos.

***

## Endpoint

```
GET https://panel.anunzi.net/api/contacts.php
```

### Encabezados requeridos

```
Authorization: Bearer TU_TOKEN_DE_AGENTE
```

> También podés autenticarte con tu **API Key de cuenta** (`anz_live_…`), que cubre toda tu cuenta con una sola credencial — ver [API Keys de cuenta](api-keys.md).


***

## Parámetros de consulta

Debes indicar al menos uno de los siguientes criterios de búsqueda:

| Parámetro | Tipo | Descripción |
|---|---|---|
| `phone` | texto (solo dígitos) | Número de teléfono del contacto. El sistema prueba automáticamente variantes con y sin prefijo de país. |
| `search_field` | texto | Campo por el que buscar (ver tabla de campos disponibles abajo). Requerido si no se usa `phone`. |
| `search_value` | texto | Valor exacto a buscar. Requerido cuando se usa `search_field`. |
| `days` | número | Ventana de días para filtrar las notas. Por defecto: `30`. Máximo: `365`. |
| `limit` | número | Cantidad máxima de contactos a devolver. Por defecto: `10`. Máximo: `50`. |

### Campos disponibles para `search_field`

| Valor | Descripción |
|---|---|
| `name` | Nombre del contacto. |
| `email` | Correo electrónico. |
| `phone_e164` | Teléfono en formato E.164 (ej. `+5491123456789`). |
| `phone_norm` | Teléfono normalizado (solo dígitos). |
| `status` | Estado del contacto en el CRM (ej. `Contactado`, `Ganado`). |
| `meta_json.<clave>` | Cualquier campo personalizado del contacto. Ej: `meta_json.cuil`. |

***

## Ejemplos de solicitud

### Buscar por número de teléfono

```bash
curl "https://panel.anunzi.net/api/contacts.php?phone=5491123456789&days=7" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ"
```

### Buscar por nombre

```bash
curl "https://panel.anunzi.net/api/contacts.php?search_field=name&search_value=Juan+P%C3%A9rez&days=30" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ"
```

### Buscar por campo personalizado (ej. CUIL)

```bash
curl "https://panel.anunzi.net/api/contacts.php?search_field=meta_json.cuil&search_value=20123456789&days=14" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ"
```

***

## Respuesta — 200 OK

```json
{
  "assistant_id": "agent_abc123",
  "assistant_label": "Agente de Ventas",
  "phone_queried": "5491123456789",
  "days": 7,
  "since": "2026-05-19T00:00:00Z",
  "count": 1,
  "results": [
    {
      "contact": {
        "id": 42,
        "name": "Juan Pérez",
        "phone_e164": "+5491123456789",
        "email": "juan@ejemplo.com",
        "status": "Contactado",
        "score": 80,
        "last_touch_at": "2026-05-25T14:30:00Z",
        "created_at": "2026-03-10T09:00:00Z",
        "meta_json": {
          "cuil": "20123456789",
          "zona": "Palermo"
        }
      },
      "notes_count": 2,
      "notes": [
        {
          "body": "Prometió pagar el viernes. Buen tono en la conversación.",
          "author_name": "Sofía IA",
          "source": "manual",
          "created_at": "2026-05-25T14:30:00Z"
        },
        {
          "body": "Segundo intento. Atendió pero pidió llamar más tarde.",
          "author_name": "Marcos IA",
          "source": "manual",
          "created_at": "2026-05-23T11:15:00Z"
        }
      ]
    }
  ]
}
```

### Descripción de los campos de respuesta

| Campo | Descripción |
|---|---|
| `count` | Cantidad de contactos encontrados. |
| `since` | Fecha desde la que se filtran las notas (calculada a partir de `days`). |
| `contact.id` | ID interno del contacto en Anunzi. |
| `contact.name` | Nombre del contacto. |
| `contact.phone_e164` | Teléfono en formato E.164. |
| `contact.email` | Correo electrónico. |
| `contact.status` | Estado del contacto en el CRM. |
| `contact.score` | Puntuación de calidad del lead (0–100). |
| `contact.last_touch_at` | Fecha y hora del último contacto registrado. |
| `contact.meta_json` | Campos personalizados del contacto (objeto). `null` si no tiene. |
| `notes_count` | Cantidad de notas dentro del período consultado. |
| `notes[].body` | Texto de la nota. |
| `notes[].author_name` | Nombre de quien generó la nota (puede ser un agente de IA o un usuario). |
| `notes[].source` | Origen de la nota: `manual` (creada en el panel) u otro valor según la fuente. |
| `notes[].created_at` | Fecha y hora de creación de la nota (ISO 8601, UTC). |

***

## Códigos de estado

| Código | Descripción |
|---|---|
| `200` | Consulta exitosa. El array `results` puede estar vacío si no se encontraron contactos. |
| `400` | Parámetros inválidos o faltantes. El campo `error` indica el motivo. |
| `401` | Token ausente o inválido. |
| `403` | El agente no tiene un usuario asociado. Contacta a soporte. |
| `500` | Error interno del servidor. |

***

> 💡 Si usas Make o Zapier, puedes usar este endpoint como módulo HTTP dentro de un flujo para enriquecer datos antes de una llamada o registrar notas en tu CRM automáticamente después de una gestión.