# API de Nemphi

> Documentación del API REST de Nemphi: autenticación con OAuth 2.1 o llaves de API, alcances, endpoints, ejemplos de peticiones, errores y la especificación OpenAPI.

Todo lo que haces en la app es una herramienta que tu código también puede llamar, con las mismas reglas, aprobaciones y bitácora.

## Qué es

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](https://www.nemphi.com/openapi.json) (OpenAPI 3.1).

## Autenticación y alcances

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`.

## Endpoints

| 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](https://www.nemphi.com/desarrolladores/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).

## Ejemplos

Lista las herramientas que alcanza tu llave:

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

Ejecuta una:

```sh
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:

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

Desde TypeScript, el SDK [`@nemphi/sdk`](https://www.npmjs.com/package/@nemphi/sdk) hace lo mismo con `nemphi.invoke("invoices.list", { status: "draft" })`.

## Respuestas y errores

- **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.

```json
{
  "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. |

## Recursos para máquinas

- [Especificación OpenAPI](https://www.nemphi.com/openapi.json): cada herramienta como operación, con su esquema y su alcance.
- [Metadatos del servidor de autorización](https://api.nemphi.com/.well-known/oauth-authorization-server) (RFC 8414) y [del recurso protegido](https://api.nemphi.com/.well-known/oauth-protected-resource) (RFC 9728), con `scopes_supported`.
- [Catálogo de APIs](https://www.nemphi.com/.well-known/api-catalog) (RFC 9727).
- [llms.txt](https://www.nemphi.com/llms.txt): el mapa del sitio para modelos de lenguaje, con la guía para que un agente abra una cuenta.
- [Servidor MCP](https://www.nemphi.com/desarrolladores/mcp): la misma tubería para asistentes de IA.

¿Dudas? Escribe a [hola@nemphi.com](mailto:hola@nemphi.com).