API de Nemphi

El API de Nemphi es un API REST con JSON en https://api.nemphi.com. Cada capacidad del producto (clientes, facturación electrónica, cobros, contabilidad, marketing, proyectos y los agentes) es una herramienta con un nombre, como invoices.list, y un esquema JSON de entrada.

GET /v1/tools lista las herramientas que tu credencial alcanza y POST /v1/tools/{nombre}:invoke ejecuta una. No hay rutas aparte: cada llamada pasa por la misma tubería que la app, con el permiso de tu rol, las políticas de autonomía de la empresa, las aprobaciones y la bitácora de acciones.

La descripción completa, una operación por herramienta con su esquema, está en https://www.nemphi.com/openapi.json (OpenAPI 3.1).

Envía la credencial en la cabecera Authorization: Bearer …. Hay dos clases.

OAuth 2.1. Para aplicaciones que actúan en nombre de una persona: código de autorización con PKCE (S256), registro dinámico de clientes en https://api.nemphi.com/oauth/register o Client ID Metadata Documents. El token de acceso dura 1 hora y el de actualización 30 días. Los metadatos están en https://api.nemphi.com/.well-known/oauth-authorization-server (RFC 8414) y https://api.nemphi.com/.well-known/oauth-protected-resource (RFC 9728).

Alcance	Qué permite
tools:read	Solo herramientas de lectura. Nada cambia en la empresa.
tools	Todas las herramientas que alcanza el rol de quien autorizó, de lectura y escritura. Lo que la empresa retiene para aprobación sigue esperando a una persona.
sites.login	Iniciar sesión de un visitante en un sitio alojado en Nemphi. Solo identidad, sin herramientas.
sites.edit	Editar los sitios de la empresa con las herramientas del Studio (sites.*).

Pide el alcance más pequeño que te sirva. La especificación OpenAPI declara en cada operación qué alcance la alcanza.

Llave de API. Para tus propios programas: crea una en Nemphi, en Desarrolladores › Llaves API. Empieza por nk_, hereda el rol que le asignes y se puede limitar a patrones de herramientas como invoices.% o %:read.

Método y ruta	Qué hace	Autenticación
GET /v1/tools	Lista las herramientas que alcanza la credencial, con su clase de riesgo y su esquema de entrada.	tools:read, tools o llave
POST /v1/tools/{nombre}:invoke	Ejecuta una herramienta. El cuerpo es su entrada en JSON.	tools:read para lecturas, tools para el resto, o llave
POST /v1/auth/agent-signup	Un agente de IA abre una cuenta y una empresa para la persona con la que trabaja.	Ninguna
POST /mcp	El servidor MCP.	tools:read, tools o llave
GET /healthz	Si el API está en servicio.	Ninguna

Cabeceras opcionales: Idempotency-Key repite la primera respuesta cuando reenvías la misma llamada, y X-Tenant-Id nombra la empresa (una llave o un token ya pertenece a una sola).

Lista las herramientas que alcanza tu llave:

curl https://api.nemphi.com/v1/tools \
  -H "Authorization: Bearer $NEMPHI_API_KEY"

Ejecuta una:

curl -X POST https://api.nemphi.com/v1/tools/invoices.list:invoke \
  -H "Authorization: Bearer $NEMPHI_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-invoices-list" \
  -d '{"status": "draft"}'

La respuesta trae el nombre de la herramienta y su resultado:

{
  "tool": "invoices.list",
  "output": { "invoices": [ … ] }
}

Desde TypeScript, el SDK @nemphi/sdk hace lo mismo con nemphi.invoke("invoices.list", { status: "draft" }).

• 200: la herramienta se ejecutó; output es su resultado.
• 202 pending_approval: en una empresa que abrió un agente, la llamada espera al dueño. Trae el id de la aprobación; transmite la respuesta de tu usuario con la herramienta approvals.decide.
• 4xx: un rechazo con cuerpo {"error", "code"}. code es estable y error es una frase para una persona.

{
  "error": "invoices.list: invalid input: status must be one of draft, posted, void",
  "code": "invalid_input",
  "field": "status"
}

Código	Estado	Qué significa
unauthenticated	401	Falta la credencial, venció o se revocó.
insufficient_scope	403	Los alcances de la credencial no llegan a ese endpoint.
approval_required	403	La llamada espera la aprobación de una persona en la Bandeja de Nemphi.
policy_denied	403	Los alcances de la credencial, el rol o las políticas de la empresa no permiten esa herramienta.
unknown_tool	404	No hay ninguna herramienta con ese nombre.
idempotency_conflict	409	Esa Idempotency-Key ya se usó con otra entrada.
body_too_large	413	La entrada supera el límite de la herramienta.
invalid_input	422	Un argumento no cumple el esquema; field dice cuál.
rate_limited	429	Demasiadas peticiones; espera y reintenta.

• Especificación OpenAPI: cada herramienta como operación, con su esquema y su alcance.
• Metadatos del servidor de autorización (RFC 8414) y del recurso protegido (RFC 9728), con scopes_supported.
• Catálogo de APIs (RFC 9727).
• llms.txt: el mapa del sitio para modelos de lenguaje, con la guía para que un agente abra una cuenta.
• Servidor MCP: la misma tubería para asistentes de IA.

¿Dudas? Escribe a [email protected].