8. Integración con su CRM¶

NAP Manager Pro tiene una API para que el sistema comercial de su empresa (CRM, facturación, portal de ventas) consulte la red y asigne puertos automáticamente.

Qué puede hacer su CRM¶

Caso de uso	Operación
¿Hay cobertura en este domicilio?	Factibilidad por coordenadas: cajas NAP cercanas con puertos libres
¿Dónde está conectado este cliente?	Conexión del cliente: puerto, caja, ONT y potencia estimada
Instalar a un cliente	Asignar un puerto a un cliente y su ONT
Dar de baja o mover a un cliente	Liberar el puerto
Consultar sucursales, sectores y proyectos	Lecturas de organización
Ver qué clientes cuelgan de un puerto PON	Trazabilidad hacia el cliente

La referencia técnica completa, con todos los campos y ejemplos, está en /docs/api de su servidor (por ejemplo https://api.su-dominio.com/docs/api).

1. Crear una llave¶

Necesita el rol Propietario o Administrador y que su plan incluya API. 1. Entre a Integraciones (API) → Nueva llave. 2. Escriba un nombre que identifique al sistema que la usará (por ejemplo «CRM de ventas»). Ese nombre aparece en la Bitácora junto a cada operación. 3. Elija los permisos (solo los que necesita):

Permiso	Permite
Consultar la red	Factibilidad, cajas NAP y puertos, trazabilidad
Asignar puertos	Ocupar, reservar y liberar puertos de cajas NAP. No permite modificar cables, mangas ni cajas
Consultar organización	Sucursales, sectores y proyectos

(Recomendado) ponga una fecha de vencimiento (por ejemplo 365 días).
Pulse Crear llave y cópiela en ese momento: es la única vez que se muestra. Si la pierde, revóquela y cree otra.

Cuide su llave como una contraseña. Úsela solo desde su servidor, nunca en una página web, una app móvil ni un repositorio público. Si sospecha que se filtró, revóquela en la lista: deja de funcionar de inmediato.

2. Usarla¶

Envíe la llave en la cabecera X-Api-Key de cada solicitud.

Ejemplo: factibilidad¶

curl -H "X-Api-Key: nap_xxxxxxxx_..." \
  "https://api.su-dominio.com/api/v1/integration/feasibility?lat=-12.0464&lon=-77.0428&radiusM=300&limit=5"

Respuesta:

{
  "latitude": -12.0464, "longitude": -77.0428, "radiusM": 300, "serviceable": true,
  "items": [
    { "napBoxId": "…", "code": "NAP-0042", "name": null, "latitude": -12.0465, "longitude": -77.0429,
      "distanceM": 18.4, "capacity": 16, "freePorts": 5, "sectorId": "…" }
  ]
}

serviceable es true si hay al menos una caja dentro del radio con un puerto libre.

Ejemplo: asignar un puerto al instalar¶

curl -X PUT -H "X-Api-Key: nap_xxxxxxxx_..." -H "Content-Type: application/json" \
  -d '{"status":"Occupied","customerRef":"CRM-5001","ontSerial":"HWTC12345678"}' \
  "https://api.su-dominio.com/api/v1/nap-boxes/ports/ID_DEL_PUERTO"

customerRef es el identificador del cliente en su CRM; luego sirve para consultarlo. Para liberar: {"status":"Available"}.

Ejemplo: dónde está conectado un cliente¶

curl -H "X-Api-Key: nap_xxxxxxxx_..." \
  "https://api.su-dominio.com/api/v1/integration/customers/CRM-5001/connection"

Devuelve el puerto, la caja, el serial de la ONT y, si la red está completa hasta la OLT, la potencia estimada (valueKind: "Estimado", un cálculo teórico, no una lectura de la ONT).

Ejemplo en C¶

using var http = new HttpClient { BaseAddress = new Uri("https://api.su-dominio.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("NAP_API_KEY"));
var json = await http.GetStringAsync("/api/v1/integration/feasibility?lat=-12.0464&lon=-77.0428&radiusM=300");

Ejemplo en Python¶

import os, requests
r = requests.get("https://api.su-dominio.com/api/v1/integration/feasibility",
                 params={"lat": -12.0464, "lon": -77.0428, "radiusM": 300},
                 headers={"X-Api-Key": os.environ["NAP_API_KEY"]}, timeout=15)
r.raise_for_status()
print(r.json())

3. Buenas prácticas¶

Guarde la llave en una variable de entorno o gestor de secretos, no en el código.
Cree una llave por sistema (CRM, portal de ventas…), con los permisos mínimos. Así puede revocar una sin afectar a las demás.
Maneje los errores: ante un 409 (por ejemplo, el puerto ya fue tomado por otro) vuelva a consultar la factibilidad y elija otro puerto.
Respete el límite de 300 solicitudes por minuto por llave: ante un 429, espere unos segundos y reintente (con espera creciente).
No dependa de que un puerto siga libre entre «consultar» y «asignar»: asignar siempre puede fallar si otro lo tomó antes; es una operación segura frente a la concurrencia (solo una gana).

4. Errores frecuentes¶

Código	Causa
`401`	Llave inexistente, mal copiada, revocada o vencida; o el plan ya no incluye la API
`403`	La llave no tiene el permiso para esa operación
`404`	El puerto, la caja o el cliente no existe (o es de otra empresa)
`409`	Conflicto: puerto ya ocupado, ONT ya asignada a otro puerto…
`400`	Datos inválidos (el mensaje indica cuáles)
`429`	Demasiadas solicitudes

Todas las respuestas de error usan el formato estándar application/problem+json con los campos title, status, code y, si aplica, errors.

5. Control y auditoría¶

Cada operación de escritura de una llave queda en la Bitácora con el nombre api:NombreDeLaLlave. La lista de llaves muestra su último uso: si una llave que nadie usa aparece en uso, revóquela.

Próximamente¶

Webhooks (avisos a su CRM cuando cambie un puerto o haya una falla), módulo de clientes con sincronización bidireccional, y conectores listos para los CRM más usados.