DEV Community: Victor Cavero Gracia

La IA es el nuevo usuario de tu web: 4 cosas que cambian en tu API cuando el cliente es un agente

Victor Cavero Gracia — Thu, 06 Aug 2026 19:55:21 +0000

Estuve probando Holded durante unas semanas y no me gustó nada. No porque esté mal hecho, que no lo está. Es que está construido para otra época: una UI bonita donde tú entras, haces clic, subes la factura a mano y revisas el cuadro de mandos.

El problema es que yo ya casi no entro a las webs. Le pregunto a un agente. Y el agente no puede usar una UI bonita.

Esa frase suena a eslogan, así que voy a bajarla a decisiones técnicas concretas. Si aceptas que el agente es el nuevo usuario, hay cuatro cosas de tu producto que cambian, y ninguna es "añadir un chatbot en la esquina".

1. Tu OpenAPI deja de ser documentación y pasa a ser la interfaz

Cuando el usuario es humano, la API es un extra para integradores. Cuando el usuario es un agente, la API es el producto y la UI es el extra.

Eso tiene una consecuencia incómoda: la spec tiene que ser pública y completa, sin login previo. Un agente no puede descubrir lo que sabes hacer si le pides que se registre antes de leer el índice.

curl -s https://api.aikount.com/openapi.json | jq '.paths | keys | length'
# 345

345 endpoints, OpenAPI 3.1, accesible sin autenticar. Si tu spec vive detrás de un portal de desarrolladores con registro, para un agente no existe.

2. Los endpoints tienen que hablar el idioma del dominio, no el de tu base de datos

Este es el error que más he visto, y lo cometí yo primero.

Un CRUD honesto expone PATCH /documents/{id} y deja que el cliente descubra qué combinación de campos significa "concilia esto". Un humano con la documentación delante lo resuelve. Un agente se inventa la combinación, y en contabilidad inventarse una combinación significa un asiento mal hecho.

La alternativa es exponer la intención, no la mutación:

POST /api/v1/reconciliations/auto
POST /api/v1/purchases/autogen-from-movements
GET  /api/v1/contacts/{contact_id}/tax-suggestion

Estos tres no son azúcar sintáctico sobre un CRUD. Cada uno encapsula una decisión de negocio que antes vivía en la cabeza del contable, y al exponerla como endpoint propio consigues dos cosas: el agente no tiene que reconstruirla, y tú puedes cambiarla sin romper a nadie.

Regla práctica: si para hacer algo el agente necesita encadenar cuatro llamadas en un orden concreto, ese orden es un endpoint que te falta.

3. Hay acciones que el agente puede hacer, y otras que no debe poder

La parte que nadie cuenta de "dale herramientas a tu agente" es que algunas herramientas no deberían existir.

En contabilidad la línea es bastante nítida: proponer es reversible, presentar no lo es. Un agente puede leer un extracto, casar un cobro con su factura y proponer el apunte. Lo que no puede es cerrar un periodo o mandar algo a la AEAT sin que un humano lo mire.

Eso se modela con estado, no con buenas intenciones en el prompt:

POST /api/v1/journal/{entry_id}/lock

Un asiento bloqueado ya no lo toca el agente. Y el registro Veri*Factu, que va encadenado por hash y no admite "perdón, me equivoqué", vive en su propio recurso con su propio reintento:

GET  /api/v1/verifactu/records
POST /api/v1/verifactu/records/{record_id}/retry

Fíjate en retry como endpoint explícito. Cuando el cliente es un agente que reintenta solo, el reintento tiene que ser una operación que tú controlas y registras, no un bucle que el modelo improvisa. Si tu API no define qué significa reintentar, el agente lo definirá por ti, normalmente duplicando.

4. El onboarding del agente es un producto en sí mismo

Tenemos un botón que se llama "Conectar tu agente de IA". Lo que hace es generar una API key con scopes y darte el comando ya montado para pegárselo a Claude, ChatGPT o Gemini. Cero configuración manual, cero copiar la URL base de un PDF.

La autenticación es Bearer, y admite tanto el JWT de sesión como una key larga con prefijo agl_:

Authorization: Bearer agl_...

El prefijo no es decorativo. Cuando una credencial se te escapa en un log o en un repo, un prefijo reconocible es lo que permite detectarla y revocarla automáticamente. Si tus keys son un UUID pelado, no hay nada que buscar.

Lo que aprendí

Construimos Aikount para resolver nuestro propio problema: saber el estado real de mi SL con un mensaje de WhatsApp, en vez de abrir un panel y navegar seis pantallas. Es contabilidad española de verdad, con PGC, Modelo 303, Veri*Factu y conexión PSD2 a los bancos.

Pero lo que me llevo como aprendizaje técnico va más allá del nicho:

Publica la spec sin login o para un agente no existes.
Expón intenciones, no mutaciones. Si hace falta encadenar llamadas en un orden fijo, falta un endpoint.
Separa por diseño lo reversible de lo irreversible, y hazlo con estado, no con prompts.
Trata el alta del agente como onboarding de usuario, porque eso es exactamente lo que es.

Si quieres trastear, la spec está abierta en api.aikount.com/openapi.json y el plan gratuito llega hasta 24.000 € facturados al año, sin tarjeta y sin módulos de pago por separado.

Me interesa mucho el contraargumento, así que si crees que exponer intenciones en vez de CRUD es acoplar demasiado la API al dominio, dímelo en comentarios. Es la crítica que más me ronda.

Webhook-first API design: no polling, one signed callback, and an MCP server that is not a wrapper

Victor Cavero Gracia — Thu, 06 Aug 2026 18:31:36 +0000

Most video APIs I have integrated make you poll. You POST a job, get an id, and then write a loop that asks "are we there yet" every few seconds until something comes back or your timeout guess runs out. That loop is where the bugs live: doubled work on retries, jobs that hang forever on silence, and a scheduler that quietly burns rate limit while nothing happens.

While building OpenShorts, an open source tool that cuts long videos into vertical clips, we made three API decisions that removed most of that pain. Here they are, with the reasoning and the code.

1. One request in, one signed webhook out

The whole automation loop is two HTTP messages. Start a job:

curl -X POST https://api.openshorts.app/api/process \
  -H "Authorization: Bearer osk_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=...",
       "acknowledged": true,
       "webhook_url": "https://your-server.com/hooks/openshorts",
       "webhook_secret": "your-shared-secret"}'

You get a job id back immediately. Minutes later, when the clips are cut, subtitled and archived, you receive exactly one POST on your webhook with the clip titles and durable download links.

The part that matters more than it sounds: a failed job fires the webhook too. If failure is silent, every consumer has to reinvent a timeout, and every one of them picks a different number. Making failure a delivered event instead of an absence of events is what lets a pipeline be stateless.

2. Sign the callback, and compare in constant time

If you pass a webhook_secret, the delivery carries an X-OpenShorts-Signature header shaped like sha256=<hex>, which is the HMAC-SHA256 of the raw request body.

import hmac, hashlib

expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers["X-OpenShorts-Signature"]):
    return 401

Two details that get missed often enough to be worth repeating:

Hash the raw body, not the parsed and re-serialised JSON. Key order and whitespace will not survive a round trip through your framework.
Use compare_digest, not ==. A plain string comparison returns early on the first differing byte, which leaks how much of the prefix you guessed right.

3. Treat MCP as a first class surface, not a wrapper

We shipped an MCP server at mcp.openshorts.app/mcp so an agent can drive the pipeline directly. Connecting is one line:

claude mcp add --transport http openshorts https://mcp.openshorts.app/mcp \
  --header "Authorization: Bearer osk_..."

Any client that speaks Streamable HTTP works the same way. The server describes itself over the protocol, tool schemas included, so there is nothing else to configure.

Six tools cover the pipeline: process_video, get_job_status, list_clips, get_quota, add_subtitles and publish_clip.

get_quota is the one I would argue hardest for. An agent that cannot see its own budget will happily start a job it cannot finish, and you find out from a failed webhook twenty minutes later. Exposing the remaining balance as a tool lets the model check before it spends, which turns a runtime failure into a planning decision.

The other thing we refused to do was build the MCP server as a wrapper around a convenient subset of the REST API. Each tool calls the same pipeline the web app uses, with the same account, minutes and job history. The moment the agent surface is a subset, you have two products to keep in sync, and the agent one always loses.

The meter is an API design decision

This is the part I did not expect to matter, and it turned out to matter most.

Most tools in this space meter agent calls separately, per source minute or per operation. That is defensible billing and terrible ergonomics. An agent loop is exploratory by nature: it checks status, lists clips, retries the one that came out badly. If every call has a price, the correct engineering response is to write fewer, larger, more brittle calls, which is exactly the opposite of what you want from an agent.

We made API calls draw from the same flat minute balance as the dashboard. No separate meter, no per-call pricing. On the self-hosted edition there is no meter at all, which is what makes an always on pipeline affordable to run.

Scheduling is whatever you already have

Because starting a job is one POST, you do not need a scheduler integration. A cron line, a GitHub Action, an n8n HTTP Request node, all of them work without a dedicated connector. There is no official n8n template because the two step shape above is the entire integration.

Run it yourself

The code is on GitHub at mutonby/openshorts, the core is MIT licensed, and the self-hosted edition serves the same MCP endpoint as the cloud.

If you are building anything with webhooks and agents, the summary is short: deliver failures as events, sign the body and compare it in constant time, expose the budget as a tool, and do not put a price on the calls your agent needs to think.

QA retest: title semantics fix

Victor Cavero Gracia — Thu, 16 Jul 2026 08:10:58 +0000

Este es el cuerpo del articulo. Si este texto aparece como body y el titulo es el de devto_title, el fix funciona.

QA smoke test — Upload-Post staging

Victor Cavero Gracia — Thu, 16 Jul 2026 07:59:44 +0000

QA smoke test — Upload-Post staging