> For the complete documentation index, see [llms.txt](https://anunzi-ai.gitbook.io/anunzi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://anunzi-ai.gitbook.io/anunzi-docs/api-widgets/consultar-contactos.md). # 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 ``` *** ## 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.` | 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.