Qué preguntarle a una documentación de API antes de firmar

El patrón se repite: alguien elige herramienta por la demo, firma un año y en la semana tres descubre que el proyecto que había imaginado no se puede construir. No porque la herramienta sea mala, sino porque su capa técnica no da para eso, y eso estaba escrito desde el principio en una página que nadie abrió.

Esa página es la documentación para desarrolladores. No hace falta saber programar para sacarle las seis respuestas que deciden si tu proyecto es viable, cuánto va a costar montarlo y qué pasa el día que crezcas.

1. ¿La herramienta avisa, o tengo que preguntar yo?

Es la primera y la que más cambia el presupuesto. Un webhook es la herramienta avisando a tu sistema en cuanto pasa algo: se ha pagado una factura, ha entrado un mensaje, ha cambiado el stock. Si no hay webhooks, la única forma de enterarse es preguntar cada pocos minutos, que es más lento, más frágil y consume el cupo de llamadas que te deje tu plan.

Busca en la documentación una página que se llame «Webhooks» o «Events». Si existe, mira que los eventos estén nombrados uno a uno —invoice.create, ticket.status_changed— y no descritos como «notificaciones de actividad». La diferencia entre una lista de eventos concretos y una frase genérica es la diferencia entre poder montar algo preciso y tener que filtrar ruido.

2. ¿Cuántas llamadas me deja mi plan al mes?

Casi todo el mundo mira el límite por minuto, que rara vez molesta, y casi nadie mira el mensual, que es el que se agota. Y a diferencia del primero, el mensual no se resuelve esperando: cuando se acaba, se acabó hasta el mes que viene o hasta que subas de plan.

Esas cifras son reales y salen de la documentación de Holded, que tiene el mérito de publicarlas en una tabla por plan. Lo incómodo no es el límite: es que el límite viva en la documentación técnica y no en la página de precios, donde lo vería quien decide.

Haz la cuenta antes de firmar. Multiplica tus pedidos, mensajes o facturas mensuales por el número de llamadas que hace falta para cada uno —dos o tres, normalmente— y compáralo con el cupo. Si el resultado se acerca al tope, tienes dos opciones: subir de plan o no montar el proyecto.

3. ¿La API está en mi plan, o en el de arriba?

Este es el que más caro sale, porque no se descubre leyendo la tarifa: se descubre leyendo la documentación. La documentación de Odoo lo dice con todas las letras: «el acceso a los datos a través de la API externa solo está disponible en los planes Personalizados» y «no está disponible en los planes One App Free ni Estándar». Es decir, que el plan gratuito y el intermedio no pueden conectarse con nada.

No es un caso aislado. En Quipu la API aparece como función del plan intermedio, no del de entrada. En Callbell, la línea «API e integraciones» es lo que separa el plan de 15 $ del de 20 $. Y en Wati la API existe en todos los planes pero los webhooks no: el de entrada no los tiene.

4. ¿Qué pasa exactamente cuando me paso del límite?

Hay dos comportamientos posibles y la diferencia importa. O la herramienta devuelve un error —el famoso429 Too Many Requests— y tu proceso se para, o te factura el exceso y sigue funcionando. Ninguna de las dos es mala; lo malo es no saber cuál te toca.

Una documentación decente te dice también cómo reintentar: una cabecera Retry-After con los segundos que hay que esperar, y contadores que te avisan de cuánto te queda antes de chocar. Si eso está, quien monte tu integración puede hacerla resistente. Si no está, la integración fallará en silencio algún día y nadie sabrá por qué.

5. Si me voy, ¿me llevo mis datos?

Busca si existe alguna forma de exportar en bloque y de forma incremental: traerte solo lo que ha cambiado desde la última vez, sin repetir filas ni descargar el histórico entero cada noche. Es lo que permite tener tu propio cuadro de mando, y también lo que permite marcharse sin perderlo todo.

Una herramienta que solo deja exportar a Excel desde la interfaz no es una herramienta de la que sea fácil salir. Y conviene mirarlo ahora, precisamente porque ahora es cuando no lo necesitas.

6. ¿Lo que me llega viene firmado?

Si vas a recibir webhooks, tu sistema va a tener una dirección pública escuchando, y cualquiera que la descubra puede mandarle datos falsos. La protección estándar es una firma: la herramienta calcula un código con un secreto que solo conocéis los dos y lo manda en una cabecera, de modo que tu endpoint puede rechazar lo que no venga de ella.

Lo mismo con los reenvíos. Los buenos sistemas reintentan si tu servidor no contesta, así que el mismo aviso puede llegarte dos veces. Si cada envío trae un identificador único, tu sistema puede ignorar el duplicado y no emitir dos facturas por el mismo pedido. Estas dos cosas están o no están, y se ven en un minuto.

Las seis, en una lista para copiar

1. ¿Hay webhooks y con qué eventos concretos? Si no los hay, todo será consultar en bucle.
2. ¿Cuántas llamadas al mes trae mi plan? Haz la cuenta con tu volumen real, no con el de la demo.
3. ¿La API y los webhooks están en MI plan? Con frecuencia viven en el de arriba.
4. ¿Qué pasa al pasarme? Error que para el proceso o factura por el exceso.
5. ¿Puedo exportar de forma incremental? Es tu salida y tu cuadro de mando.
6. ¿Los envíos vienen firmados y con identificador único? Seguridad y no duplicar.

Ninguna de las seis exige saber programar. Todas se responden con la documentación pública abierta en una pestaña, y las seis juntas te dicen, antes de firmar, si lo que quieres montar se puede montar. Es la parte de la decisión que no se puede recuperar después: el precio se renegocia, el plan se cambia, pero una herramienta sin eventos salientes no los va a tener porque tú la hayas contratado.