Cómo integrar sistemas por API: contrato, estados y recuperación
Integrar sistemas por API permite intercambiar datos y ejecutar operaciones mediante interfaces definidas. El trabajo está completo cuando puede explicarse el origen de cada valor, el estado de cada operación y la recuperación tras los fallos. Esta guía prepara una conexión verificable entre dos sistemas, con un ejemplo pequeño y criterios para aprobar la entrega.
Al terminar, podrá:
- Especificar la entrada, la salida y los estados
- Distinguir los eventos de la sincronización completa
- Probar la repetición, el acceso y la recuperación
Elija la fuente responsable de cada campo
Describa el recorrido en términos de negocio: «una orden confirmada en el sistema comercial crea un trabajo en el sistema de operaciones». Identifique la referencia común y la dirección de los datos. Si ambos sistemas pueden cambiar la misma fecha, determine cuál prevalece y cómo llega un conflicto a revisión.
Haga un mapa por campo, no solo por aplicación. El sistema comercial puede ser responsable del pedido y el sistema de operaciones del estado de ejecución. Evite una sincronización bidireccional genérica que devuelva cada cambio al punto de origen. Defina qué cambios son relevantes y cuándo es necesario consultar el estado actual.
| Campo del ejemplo | Fuente responsable | Destino |
|---|---|---|
| order_id | Sistema comercial | Referencia externa del trabajo |
| service_code | Catálogo aprobado | Tipo de trabajo |
| requested_date | Solicitud confirmada | Preferencia, sujeta a planificación |
| work_status | Sistema de operaciones | Información de seguimiento |
Escriba el contrato antes de conectar las credenciales
Registre las operaciones, los campos, los tipos, los valores permitidos, las respuestas y los errores. OpenAPI define una forma de describir interfaces HTTP para personas y herramientas. Si el proveedor ofrece esa descripción, compruebe la versión y los ejemplos; si no, documente el contrato mínimo de la conexión. La documentación no sustituye el ensayo de la operación real.
Defina el significado de ausente, vacío y nulo. Una propiedad omitida puede significar «no modificar», mientras que null puede significar «borrar», según la API. Especifique también los formatos de fecha, las unidades, los límites y los campos calculados. Estas decisiones evitan que una sincronización borre información solo porque un sistema no la haya enviado.
Utilice una solicitud ficticia con un resultado esperado
En el ejemplo, la orden ORD-104 está confirmada y debe generar un trabajo. El evento tiene su propio identificador y una revisión de la orden. La fecha solicitada es una preferencia, no una reserva automática. Los nombres y el formato siguientes son una propuesta didáctica; deben adaptarse a las API realmente contratadas.
El procesamiento esperado valida el evento, busca la referencia externa, crea o actualiza el borrador permitido y guarda el identificador del trabajo. Repetir el mismo evento debe devolver el resultado ya registrado. Una revisión posterior puede cambiar campos autorizados; una revisión antigua recibida después no debe sustituir el estado más reciente.
{
"entrada": {
"schema_version": 1,
"event_id": "evt-demo-104-3",
"event_type": "order.confirmed",
"order": {
"order_id": "ORD-104",
"revision": 3,
"service_code": "MANUTENCAO",
"requested_date": "2026-11-25"
}
},
"resultado": {
"event_id": "evt-demo-104-3",
"processing_status": "completed",
"work_id": "TRAB-208",
"work_status": "draft"
}
}Autorice la operación y el registro concreto
Guarde las credenciales en el componente servidor y conceda solo las operaciones necesarias. Separe los entornos de pruebas y producción y defina cómo rotar las credenciales sin perder el control de la conexión. Los registros técnicos deben permitir investigar por referencia sin copiar secretos ni datos personales excesivos.
La autenticación identifica quién hace la solicitud; la autorización decide si puede actuar sobre ese registro. OWASP destaca la necesidad de verificar el acceso al objeto cuando una API recibe su identificador. Pruebe una referencia que pertenezca a otra cuenta ficticia: una credencial válida no debe dar acceso a todos los datos como consecuencia.
Combine los eventos con una forma de comprobar el conjunto
Un webhook informa de un acontecimiento; una consulta obtiene datos según el contrato de la API. Verifique la autenticidad de las notificaciones mediante el mecanismo del proveedor antes de confiar en su contenido. Stripe documenta, por ejemplo, la verificación de firmas, las repeticiones y la ausencia de garantía de orden en la entrega. Confirme el comportamiento de su proveedor en lugar de suponer que es igual.
La conciliación periódica compara referencias y estados para encontrar diferencias dejadas por un evento perdido. Al consultar listas, recorra la paginación: la primera respuesta puede contener solo una parte de los registros, como muestra la documentación de GitHub. Registre el cursor o punto de continuación y trate los cambios durante la lectura según las garantías de la API.
Distinga un fallo temporal de una solicitud inválida
Una conexión interrumpida puede dejar incierto el resultado: el destino puede haber guardado antes de perderse la respuesta. Utilice la referencia y el mecanismo de idempotencia disponible, confirmando el ámbito y el plazo de validez. Stripe documenta ese mecanismo; no significa que cualquier API acepte la misma clave o tenga las mismas garantías.
Limite los intentos, respete las indicaciones de espera del proveedor y envíe los fallos persistentes a revisión. Una cola puede volver a entregar un mensaje, como sucede en el modelo de entrega al menos una vez documentado por Cloudflare. Por eso, el consumidor también necesita reconocer las repeticiones. Un campo inválido no se corrige repitiendo indefinidamente la misma solicitud.
Apruebe los estados y la recuperación con pruebas concretas
En la prueba de aceptación, confirme que ORD-104 genera un único TRAB-208 incluso después de repetirlo y que completed se refiere al procesamiento de la integración, mientras que draft se refiere al trabajo. Son estados de entidades diferentes. Después simule un fallo, retome y compare los registros de ambos lados.
Incluya una versión antigua, un evento fuera de orden, un límite de uso, una credencial revocada y una lista con varias páginas. Defina al responsable de las alertas y de los cambios del contrato. Cuando una API anuncie una retirada, la actualización debe repetir estos ensayos antes de sustituir la conexión utilizada por el equipo.
| Prueba | Evidencia de aceptación |
|---|---|
| El mismo evento dos veces | Una operación de negocio y un resultado reutilizado |
| Respuesta perdida | La conciliación encuentra el resultado sin duplicarlo |
| Una revisión anterior llega después | El estado actual se conserva según la política |
| Varias páginas de datos | Todas las referencias esperadas comprobadas |
| Acceso a otra cuenta | Operación rechazada sin cambiar los datos |
Ficha para su proyecto
Recorrido de negocio y resultado esperado: Sistemas, entornos y responsables: Campos y fuente responsable de cada uno: Contrato, versión, entrada, salida y errores: Referencia común, evento y revisión: Permisos y conservación de los registros técnicos: Autenticidad de los eventos: Paginación, continuidad y conciliación: Idempotencia, intentos y fallos persistentes: Estados de procesamiento y de negocio: Casos de prueba y evidencias de ambos lados: Alertas, mantenimiento y procedimiento de recuperación:
Fuentes y criterios
Contenido elaborado con ayuda de IA e investigación en fuentes técnicas, con comprobación de los ejemplos y cálculos pertinentes. Las referencias fundamentan las decisiones de la guía; los ejemplos identificados como ficticios permiten probar el método.
