# NDX One · API v1

> La API de NDX One: lee y crea datos de la operación de una organización desde sus propios sistemas, con una llave por sistema. Cada guía y cada operación tiene su versión Markdown en la misma dirección terminada en `.md`.

Contrato OpenAPI: https://plataforma.ndx-one.com/api/v1/openapi.json

## Fundamentos

- [Crear la llave](https://developers.ndx-one.com/guias/crear-la-llave.md): La credencial con la que tu sistema entra en la API.
- [La primera petición](https://developers.ndx-one.com/guias/primera-peticion.md): Comprueba que la llave entra y qué puede hacer.
- [Paginar los resultados](https://developers.ndx-one.com/guias/paginacion.md): Recorrer una lista entera, página a página.
- [Idempotency-Key y reintentos](https://developers.ndx-one.com/guias/idempotencia-y-reintentos.md): Repetir una petición sin hacerla dos veces.
- [Errores y límites](https://developers.ndx-one.com/guias/errores-y-limites.md): Qué significa cada error y cuánto aguanta la API.

## Recursos

- [Contactos](https://developers.ndx-one.com/guias/contactos.md): Buscar, leer la ficha y dar de alta.
- [Actividades](https://developers.ndx-one.com/guias/actividades.md): Lo que pasa con un contacto, en su histórico.
- [Tareas](https://developers.ndx-one.com/guias/tareas.md): Dejar a alguien del equipo algo por hacer sobre un contacto.

## Casos de uso

- [Integrar una centralita o un asistente de voz](https://developers.ndx-one.com/guias/centralita-o-asistente-de-voz.md): Reconocer a quien llama, darle contexto y dejar la llamada en su ficha.

## Referencia

- [Visión general](https://developers.ndx-one.com/referencia.md): URL base, autenticación, repetir sin duplicar y errores.
- [Qué llave soy](https://developers.ndx-one.com/referencia/me.md): `GET /api/v1/me` — La llave, su empresa y lo que puede hacer: para configurar la integración sin preguntar.
- [Buscar contactos](https://developers.ndx-one.com/referencia/searchContacts.md): `GET /api/v1/crm/contacts` — Por teléfono (E.164), correo o nombre, en la empresa de la llave y lo compartido. Sin ficha con ese teléfono, devuelve los contactos de la cuenta cuyo teléfono general es ese número (matchedBy company_phone).
- [Dar de alta un contacto](https://developers.ndx-one.com/referencia/createContact.md): `POST /api/v1/crm/contacts` — En la empresa de la llave, sin responsable. Si ya hay una ficha con ese correo, 409 duplicate (con su id si la llave puede ver). El teléfono no cuenta como duplicado: busca antes.
- [El contacto](https://developers.ndx-one.com/referencia/getContact.md): `GET /api/v1/crm/contacts/{id}` — La ficha, con su ETag. Con If-None-Match igual al ETag, 304 sin cuerpo. Fuera del alcance de la llave, 404.
- [Resumen del contacto](https://developers.ndx-one.com/referencia/getCallContext.md): `GET /api/v1/crm/contacts/{id}/context` — La ficha, sus oportunidades abiertas, las cinco últimas interacciones y sus tareas abiertas. Fuera del alcance de la llave, 404.
- [Registrar una llamada](https://developers.ndx-one.com/referencia/logCall.md): `POST /api/v1/crm/contacts/{id}/calls` — Una actividad de tipo llamada en el histórico del contacto, firmada por la llave. Pide ver el contacto. La transcripción y los números se guardan en crudo aparte. Con el mismo externalCallId otra vez, 409 duplicate con la que ya está.
- [Crear una tarea](https://developers.ndx-one.com/referencia/createTask.md): `POST /api/v1/crm/contacts/{id}/tasks` — Al responsable del contacto o, si no tiene o no lo ve, al de la llave. Si ninguno puede verlo, 422.
- [Los tipos de actividad](https://developers.ndx-one.com/referencia/listActivityTypes.md): `GET /api/v1/crm/activity-types` — El vocabulario de la organización para tipificar una actividad.