INTEGRACIÓN
SDK y Postman
Cliente de Python, cliente de TypeScript y colección de Postman, generados del contrato de la API de tu instancia.
Se generan en el momento de descargarlos a partir del contrato OpenAPI de esta instancia y ya apuntan a ella: cuando la API se amplía, vuelve a descargarlos. Los tres traen reintentos con retroceso, respeto de Retry-After, Idempotency-Key automática en los POST (un reintento no duplica), errores con codigo y request_id y la verificación de la firma de los webhooks.
| Descarga | Para qué |
|---|---|
guilda_work.py | Un solo fichero, solo biblioteca estándar (Python 3.9+). Un método por operación. |
guilda-work.ts | Un solo fichero con fetch (Node 18+, navegadores, Deno, Bun) y los tipos de todas las entidades. |
guilda-work.postman_collection.json | Colección de Postman (también vale en Insomnia, Bruno o Hoppscotch): una carpeta por tema, ejemplos y variables. |
Python
from guilda_work import Cliente, ErrorGuilda, verificar_firma_webhook
g = Cliente(token="TU_TOKEN") # o Cliente().login(email=..., contrasena=...)
nota = g.crear_nota(texto="Llamar al cliente", referencia_externa="CRM-881")
g.upsert_nota("CRM-881", texto="Llamar al cliente (hecho)") # crea o actualiza por tu propia referencia
for tarea in g.paginar(g.listar_tareas_outlook, estado="en_progreso"): # recorre todas las páginas
print(tarea["asunto"])
try:
g.cambiar_estado_tarea(57, estado="completada")
except ErrorGuilda as e:
if e.codigo == "tarea_bloqueada": # programa contra el código, no contra el texto
print("espera a otras tareas", e.request_id)
g.subir_adjuntos_nota(nota["id"], adjunto=[("extracto.pdf", open("extracto.pdf", "rb").read(), "application/pdf")])
Sincronizar sin volver a descargarlo todo
cursor = g.sincronizar()["cursor"] # antes de la descarga completa inicial; guárdalo
# ... más tarde:
for lote in g.sincronizar_desde(cursor):
aplicar(lote["cambios"], lote["eliminados"])
cursor = lote["cursor"] # guarda el último; si lote["reiniciar"], descarga todo otra vez
TypeScript
import { GuildaWork, ErrorGuilda, verificarFirmaWebhook } from "./guilda-work";
const g = new GuildaWork({ token: process.env.GUILDA_TOKEN });
const nota = await g.crearNota({ texto: "Llamar al cliente", referencia_externa: "CRM-881" });
// Los argumentos de camino van primero, luego el cuerpo y luego la consulta
await g.cambiarEstadoTarea(57, { estado: "en_progreso" });
for await (const t of g.paginar((limit, offset) => g.listarTareasOutlook({ limit, offset }))) console.log(t.asunto);
try { await g.obtenerNota(99999); } catch (e) { if (e instanceof ErrorGuilda && e.codigo === "no_encontrado") { /* ... */ } }
Verificar webhooks
Usa siempre el cuerpo crudo recibido y rechaza lo que tarde más de 5 minutos (X-Guilda-Signature-V2 lleva marca de tiempo).
if not verificar_firma_webhook(request.get_data(), request.headers, secreto):
return "firma no válida", 400
Postman
Importa el fichero (Import → File), abre la colección y rellena la variable token (o ejecuta auth → login, que la guarda solo). base_url ya apunta a esta instancia. Cada POST añade su Idempotency-Key y todas las peticiones un X-Request-Id; los parámetros opcionales vienen desactivados para activarlos con la casilla.
VERSION_API). Un cambio compatible solo añade métodos y campos opcionales; si alguna vez algo se rompe, la versión mayor sube y se avisa. Mientras tanto, un cliente antiguo sigue funcionando.