Onboarding de un cliente de API en un día

Una integración nueva casi nunca se traba en la parte difícil. Se traba esperando: una credencial que llega el martes, un documento que estaba en un correo viejo, un error que nadie sabe leer. El calendario se estira por coordinación, no por complejidad.

Llamamos onboarding al tramo que va del acuerdo a la primera respuesta reproducible en un entorno de prueba, con un criterio de cierre escrito antes de empezar. Con esa definición acotada, un día es un objetivo razonable: lo que se promete es el camino, no una decisión de arquitectura para toda la flota.

Conviene decir qué no entra. Dimensionar volumen, calibrar reintentos y acordar ventanas de cobertura necesitan datos de uso: meterlas en la primera jornada no las acelera, las convierte en supuestos.

El paquete que se entrega antes de la primera llamada

El día empieza mal con una reunión de presentación. Empieza bien si el equipo que va a integrar recibe, de entrada, todo lo que necesita para no volver a preguntar:

• la descripción de la API en un formato legible por máquinas;
• credenciales propias del entorno de prueba, distintas de las de producción;
• casos de ejemplo con su respuesta esperada, incluidos los incómodos;
• el nombre de una persona que responde durante esa jornada.

OpenAPI cubre el primer punto. La especificación define cómo describir en un solo documento las rutas, las operaciones, los esquemas de datos, los ejemplos y los esquemas de seguridad de una API HTTP, y también los servidores disponibles, que su propio ejemplo lista por entorno. Ese documento no reemplaza la explicación, pero permite empezar sin ella y expone temprano las diferencias entre lo que se dijo y lo que el servidor responde.

La elección del mecanismo de autenticación es una discusión previa y tiene su propia comparación. Para el día uno alcanza con que las credenciales existan, estén separadas por entorno y no viajen en el mismo mensaje donde se explica qué hacen.

La primera hora: provocar los errores a propósito

El orden intuitivo —hacer que funcione y después ver qué pasa cuando falla— deja para el final lo que más tarda en acordarse. Invertimos ese orden: la primera hora se dedica a llamadas que tienen que fallar. Sin credencial; con una credencial inválida; con una credencial válida pero sin permiso sobre ese recurso; con un identificador inexistente; con un cuerpo mal formado.

RFC 9110 pide que un 401 viaje con al menos un desafío que indique cómo autenticarse, y describe el 403 como un pedido que el servidor entendió y se niega a cumplir, sea porque considera insuficientes las credenciales presentadas o por un motivo ajeno a ellas. El día uno no se prueba esa taxonomía: se prueba que el cliente no traduzca ninguna de las dos a “sin infracciones”.

RFC 9457 define un formato para el cuerpo de esos errores, con campos de tipo, título, estado, detalle e instancia, y admite miembros de extensión propios de cada tipo de problema. Comprobá el día uno que el cliente lee ese cuerpo —y no sólo el número—: evita que meses después un incidente se diagnostique con la frase “da error”.

El camino feliz enseña menos de lo que parece

Recién ahí viene la consulta que devuelve resultados. Y aparece un tercer grupo de respuestas que no son ni éxito ni error: pendiente, parcial, fuente sin datos. Un resultado parcial leído como vacío es un error caro porque no se nota: alguien concluye que el vehículo está limpio y sigue adelante. Ese caso lo tratamos en timeout no significa “sin multas”.

La prueba concreta es corta. Sobre el mismo caso de ejemplo, el cliente tiene que distinguir “no hay infracciones informadas” de “todavía no sabemos”, y registrar cuál de las dos recibió.

Datos de prueba, no la flota real

Usar patentes reales el primer día es cómodo y evitable. La Ley 25.326 prohíbe usar datos personales para finalidades distintas o incompatibles con las que motivaron su obtención y obliga a adoptar medidas técnicas y organizativas de seguridad; una prueba de conectividad no es una finalidad que justifique mover el padrón de una empresa por canales improvisados.

Pedí que el entorno de prueba ya devuelva, con identificadores imposibles, los casos que existen de verdad en el dominio: con resultados, vacío, parcial y fallido. Diseñar ese sandbox es trabajo previo, no tarea de la jornada.

El criterio de salida, escrito antes de empezar

Escribí antes de la primera llamada una lista corta y verificable, y cerrá el día cuando esté marcada: se autenticó contra el entorno de prueba; obtuvo un resultado y lo guardó; reprodujo los cinco errores y los distinguió entre sí; diferenció un resultado parcial de uno vacío; y sabe a quién escribir cuando algo cambie.

Lo que no está en esa lista no se declara terminado: queda agendado con fecha. Volumen, límites de ritmo, alertas y credenciales de producción son trabajo de la semana siguiente, ya con un cliente funcionando contra el que medirlas.

Un día bien usado no acelera la integración. Elimina las esperas que la hacían durar semanas.

Preguntas frecuentes

¿Se puede integrar una API de infracciones en un solo día?

Depende de qué se llame integrar. Una jornada alcanza para que un equipo reciba credenciales, lea el contrato, haga llamadas reales contra el entorno de prueba y sepa interpretar tanto los resultados como los errores. Dimensionar volumen, acordar cobertura y calibrar reintentos necesitan datos de uso que ese día todavía no existen.

¿Qué tiene que estar listo antes de empezar el onboarding?

Cuatro cosas, juntas y de entrada: la descripción de la API en un formato legible por máquinas, credenciales propias del entorno de prueba, casos de ejemplo con su respuesta esperada y alguien disponible para responder durante la jornada. Lo que falte de ese paquete se convierte en espera, y la espera es lo que estira el calendario.

¿Por qué conviene probar primero los errores y no el caso exitoso?

Porque el manejo de errores es lo que después falla en producción y lo que más tarda en acordarse. RFC 9110 distingue la falta de credenciales válidas de la negativa a cumplir un pedido que el servidor entendió, y RFC 9457 define un formato para el cuerpo del error. Comprobar el día uno que el cliente distingue esos casos evita diagnósticos posteriores del tipo “da error”.

¿Se pueden usar patentes reales el primer día de pruebas?

Conviene evitarlo. La Ley 25.326 prohíbe usar datos personales para finalidades distintas o incompatibles con las que motivaron su obtención y obliga a adoptar medidas de seguridad; una prueba de conectividad no justifica mover el padrón de una empresa por canales improvisados. Un entorno de prueba con identificadores imposibles cubre los mismos casos.

Notas relacionadas