API de Quipu · conector open source
La API de Quipu, explicada por quien la usa en producción
Qué permite, qué no, y dónde están las trampas que no vienen en la documentación. Con un conector MCP open source para conectarla a Claude o a la IA que uses.
La API en seis datos
- Especificación
- OpenAPI 3.1
- Operaciones
- 49 en 27 rutas
- Autenticación
- OAuth2 client credentials
- Formato
- JSON:API
- Base URL
- getquipu.com
- Licencia del conector
- MIT
Los límites que nadie te cuenta
No hay endpoints de modelos fiscales
Es lo primero que busca todo el mundo y no existe. La API v1 no expone el 303, ni el 130, ni el 111, ni tampoco OCR de tickets. Los recursos son facturas, facturas simplificadas, ingresos y gastos adicionales, contactos, nóminas, series de numeración, categorías contables, adjuntos y asientos. Para saber el IVA de un trimestre hay que recorrer las facturas y los gastos del periodo y sumarlos.
Los importes no se llaman como esperas
No existen total ni subtotal. El importe base es
total_amount_without_taxes, el impuesto es vat_amount y la
retención es retention_amount. Si asumes los nombres obvios, tu integración
compila, no da error y devuelve importes vacíos, que es la peor forma de fallar.
Los números llegan como texto
Todos los importes son cadenas, no números. Convertirlos sin comprobar produce un
NaN silencioso que se propaga hasta el total. En una cifra de IVA, eso no es
un bug menor.
El token caduca y todo cuelga del slug
La autenticación es OAuth2 client credentials, no una API key estática: hay que cachear el token, renovarlo antes de que expire y reintentar cuando la API responde 401. Y todos los endpoints de negocio van prefijados por el slug de tu cuenta, el primer segmento de tus URLs de Quipu.
El conector: 18 herramientas
Open source bajo licencia MIT. Puedes revisar el código antes de darle acceso a tu facturación, que es exactamente lo que deberías hacer con cualquier herramienta que toque tus datos fiscales.
Listar, consultar, crear, actualizar y eliminar clientes y proveedores.
CRUD completo más enlace temporal de descarga del PDF.
Facturas de proveedor y costes deducibles, con categoría contable.
IVA repercutido, soportado, saldo y retenciones de un trimestre o rango.
La pieza que hace el trabajo de verdad es get_tax_summary: recorre todas las
páginas de facturas y gastos de un periodo y calcula IVA repercutido, soportado, saldo y
retenciones en código, con redondeo a céntimos. Pedirle a un modelo que
sume cien importes leyéndolos uno a uno es una forma fiable de equivocar una cifra fiscal.
Instalación
Necesitas credenciales de API de Quipu (Configuración → API) y el slug de tu cuenta. Añade esto a la configuración de tu cliente MCP:
{
"mcpServers": {
"quipu": {
"command": "npx",
"args": ["-y", "@nubiia/mcp-quipu"],
"env": {
"QUIPU_CLIENT_ID": "tu_client_id",
"QUIPU_CLIENT_SECRET": "tu_client_secret",
"QUIPU_OWNER_SLUG": "tu_slug"
}
}
}
}
El código está en GitHub,
el paquete en npm
y el servidor está publicado en el registro oficial de MCP como io.github.nubiia-dev/mcp-quipu,
así que los clientes que lo consultan lo encuentran sin configurar nada a mano.
Si prefieres no montarlo tú, lo implantamos y lo mantenemos:
mira conectar Quipu con la IA.
Preguntas frecuentes
- ¿Qué autenticación usa la API de Quipu?
-
OAuth2 con flujo client credentials. Se pide un token a
POST /oauth/tokenenviandoclient_idyclient_secretcomo Basic Auth, y ese token caduca. A diferencia de una API key estática, hay que cachearlo y renovarlo. Además, todos los endpoints salvo el de token exigen la cabeceraAccept: application/vnd.quipu.v1+json. - ¿La API de Quipu devuelve los modelos de IVA (303, 130, 111)?
-
No. La API v1 no expone ningún endpoint de modelos fiscales ni de OCR. Para saber el IVA
de un trimestre hay que recorrer las facturas y los gastos del periodo y sumar el campo
vat_amount. - ¿Por qué mis importes llegan vacíos al leer una factura?
-
Porque los campos no se llaman como uno espera. No existen
totalnisubtotal: el importe base estotal_amount_without_taxes, el impuesto esvat_amounty la retención esretention_amount. Además llegan como texto y envueltos en JSON:API dentro dedata.attributes. - ¿Cuántos endpoints tiene la API de Quipu?
- La especificación OpenAPI 3.1 oficial declara 49 operaciones en 27 rutas, sobre once recursos. Todos los endpoints de negocio cuelgan del slug de la cuenta.
¿Lo montamos nosotros?
El conector es gratis y open source. Si prefieres que lo implantemos, lo configuremos a tus casos reales y nos ocupemos del mantenimiento, cuéntanos tu caso en 20 minutos.
Sin tarjeta. Sin compromiso.