Qué resuelve
La API permite que un sistema externo trabaje con los datos y operaciones del tenant sin utilizar la interfaz humana.
Antes de empezar
Definí el caso de uso: sincronizar catálogo, consultar pedidos, actualizar stock, alimentar un ERP o construir una experiencia headless. Esa decisión determina qué endpoints y permisos necesitás.
Flujo recomendado
Crear credencial → guardar secreto → probar autenticación → consultar recurso → validar tenant → implementar escritura → manejar errores → monitorear.
La primera prueba
Empezá con una operación de lectura. Confirmá que la respuesta pertenece al tenant correcto y que el contrato de datos coincide con lo que tu sistema espera.
Escrituras
Cuando pases a crear/editar recursos, implementá idempotencia cuando el endpoint/flujo lo permita y guardá el identificador externo de la operación. No reintentes a ciegas una escritura que pudo haber sido aceptada.
Webhooks
Cuando un proveedor o Structura te notifique un evento, validá autenticidad, registrá el evento, procesalo de forma idempotente y respondé según el contrato.
Seguridad
- API key solo del lado servidor.
- Rotación periódica.
- Revocación inmediata ante exposición.
- No usar la sesión de un administrador como credencial de integración.
- Separar ambientes cuando corresponda.
Qué significa “integración terminada”
No es “el endpoint respondió 200”. Es poder recorrer el proceso real, tolerar reintentos/fallos y demostrar qué ocurrió cuando un dato externo cambia.