Entorno de PRE: solo datos de prueba. Los correos solo llegan al equipo y los cobros son de prueba.
Guilda WorkDevelopers

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.

Python TypeScript Postman Sin dependencias

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.

DescargaPara qué
guilda_work.pyUn solo fichero, solo biblioteca estándar (Python 3.9+). Un método por operación.
guilda-work.tsUn solo fichero con fetch (Node 18+, navegadores, Deno, Bun) y los tipos de todas las entidades.
guilda-work.postman_collection.jsonColección de Postman (también vale en Insomnia, Bruno o Hoppscotch): una carpeta por tema, ejemplos y variables.

Python

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

python
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

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).

python
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.

Versionado. Los clientes llevan la versión de la API con la que se generaron (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.