Saltar al contenido
ESEN

Cord Workbench

Construye, prueba y depura tu integración sin salir de Cord: cada petición, cada error, cada evento y cada entrega en un solo panel.

¿Qué es?

El Workbench es la consola de desarrolladores de Cord. Vive al fondo de la app como una píldora Desarrolladores y, al abrirla, despliega un panel con ocho pestañas: Resumen, Registros, Errores, Eventos, Webhooks, Shell, Llaves y Salud. En la barra superior del panel está el Inspector, que encuentra cualquier ID.

Las llaves de API, los webhooks, los registros y los eventos viven aquí. MCP, Inteligencia artificial y Cotizador embebible siguen en Ajustes, en la sección Desarrolladores del índice, porque son configuración de una sola vez.

Requisitos

  • Permiso Ajustes en tu rol. Sin él, el Workbench no aparece.
  • Modo desarrollador activo. Es una preferencia de tu cuenta, no de la organización.
  • Está en todos los planes. El historial de entregas de webhooks, Reintentar y Reenviar piden el plan Profesional o superior.

Activarlo

  1. Entra a Ajustes y baja hasta el final del índice de categorías.
  2. Activa el interruptor Modo desarrollador.
  3. Aparece la píldora Desarrolladores en la esquina inferior derecha, en toda la app. Haz clic en ella, arrástrala hacia arriba o pulsa W.

El Modo desarrollador te sigue en cualquier computadora donde entres con tu cuenta. También lo cambias en Tus preferencias. Un enlace con ?wb= o ?wbi= (ver Enlaces directos) también lo activa.

El panel

El Workbench abierto a media altura sobre Cotizaciones, en la pestaña Resumen de los últimos 7 días en vivo: 2,523 peticiones a la API con 1.9% de error, latencia p95 de 412 ms y 99.5% de las entregas de webhook correctas; los errores principales por código, de dónde vienen las peticiones, la actividad reciente, la integración sin alertas y 3,412 de 5,000 peticiones del mes usadas.
  • Tamaño. Arrastra el tirador superior para agrandar o achicar el panel; suéltalo cerca del fondo para cerrarlo.
  • Pantalla completa. El botón junto a Cerrar expande el panel a toda la ventana. Sales con el mismo botón, con ⇧W o con Esc.
  • Opciones (⋯). Mostrar las horas en UTC cambia al instante todas las fechas del panel sin tocar la zona horaria de tu cuenta. El menú también lista los atajos de teclado y enlaza a esta guía y a la especificación OpenAPI.
  • Entorno. El Workbench muestra el entorno en el que está la app. En el entorno de prueba ves lo que hicieron tus llaves sk_test_ y el Shell en Prueba; en vivo, lo de tus llaves en vivo. El Resumen lo marca con una etiqueta Prueba o En vivo.
  • El panel recuerda en este navegador si estaba abierto, la pestaña, el alto, la pantalla completa y la opción de UTC.

Atajos de teclado

Tecla Qué hace
W Abre o cierra el Workbench.
⇧W Pantalla completa.
/ Pone el cursor en el Inspector.
1 a 8 Va a la pestaña con ese número, en el orden de la barra.
J / K Fila siguiente o anterior en Registros y Eventos.
⌘↵ (Ctrl+↵ en Windows) Envía la petición del Shell.
Esc Cierra lo que esté abierto: menú, diálogo, Inspector, pantalla completa y, al final, el panel.

Los atajos de una letra o número no se activan mientras escribes en un campo. En pantallas de menos de 880 px no hay atajos de una tecla y el panel se abre como una hoja de borde a borde; en las más angostas, el Inspector es un icono de la barra superior que se expande al tocarlo.

Las pestañas

Resumen

La vista de entrada, con periodo de 24 horas, 7 días o 30 días:

  • Indicadores: peticiones de API, tasa de error, latencia p95 (con la p50 debajo) y porcentaje de entregas de webhook correctas.
  • Peticiones en el tiempo: barras de correctas y con error.
  • Errores principales: los cinco códigos que más se repiten. Un clic abre Registros filtrado por ese código.
  • De dónde vienen: las peticiones por origen. Un clic abre Registros filtrado por ese origen.
  • Actividad reciente: las últimas seis peticiones.
  • A la derecha: la tarjeta de salud (te lleva a Salud), el uso de la API este mes contra lo que incluye tu plan, los primeros pasos cuando todavía no hay peticiones en el periodo y los recursos para desarrolladores.

En el uso del mes solo cuentan las llamadas con llaves en vivo: las de prueba y las del Workbench no consumen tu cuota.

El origen de cada petición sale del cliente que la hizo:

Origen Cuándo
SDK de Node, SDK de Python, SDK de PHP, CLI El SDK o el CLI de Cord se identificó en la petición.
cURL La petición salió de curl.
MCP Una llamada al servidor MCP.
Cord Elements Una llave publicable (pk_), como la de Cord Elements.
App conectada Una app autorizada por OAuth, como Zapier o Make.
Workbench El Shell.
HTTP Cualquier otro cliente.

Registros

Cada petición que llegó a /api/v1 y al servidor MCP, en una lista con su detalle a la derecha. Las llamadas de MCP muestran la herramienta, por ejemplo /mcp/tools/call:listar_productos.

El Workbench en el entorno de prueba, en la pestaña Registros: las peticiones del inicio rápido hechas con cURL y la llave de prueba, una con el error invalid_request y otra desde el Shell del Workbench, y el detalle de POST /v1/cotizaciones (201, 184 ms) con su request id, la versión 2026-10-01, el modo Prueba y los botones Copiar como cURL y Abrir en el Shell.
  • Busca por ruta, por request id (req_…), por código de error o por una Idempotency-Key exacta. Un request id se busca en todo el historial, sin importar el periodo.
  • Filtra por método (GET, POST, PATCH, DELETE), por clase de status (2xx, 4xx, 5xx), por llave (o solo las del Workbench), por origen y por periodo (1 hora, 24 horas, 7 días o 30 días).
  • En vivo agrega las peticiones nuevas arriba cada pocos segundos mientras la pestaña está a la vista. Cargar más trae las siguientes 50.

El detalle de una petición muestra el status, el código de error con su mensaje y un enlace a Cómo resolverlo en Errores, el request id, la fecha, la latencia, la llave, el origen, la versión de la API, el modo, la IP y la Idempotency-Key. Si Cord devolvió la respuesta guardada de una petición repetida, lo marca como Respuesta repetida, y debajo lista las otras peticiones con la misma Idempotency-Key.

  • Copiar como cURL copia la petición lista para pegar en tu terminal: el encabezado Authorization lee tu llave de la variable de entorno $CORD_SECRET_KEY. El cuerpo no viaja porque no se guarda.
  • Abrir en el Shell la carga en el Shell con sus parámetros. En vivo solo aparece para peticiones GET.
  • Inspeccionar el recurso abre en el Inspector el ID que trae la ruta.

Cord no guarda el cuerpo de las peticiones ni de las respuestas de la API, solo sus datos. Guardarlos implicaría conservar datos de tus clientes (identificadores fiscales, correos, montos) en cada llamada. Para ver una respuesta completa, repite la operación en el Shell o revisa el log de tu propio servidor.

Cada petición se conserva 30 días. Un proceso diario borra lo anterior, así que el periodo más largo de Registros, Errores y Resumen es 30 días. El borrado lo hace una función de la base de datos que solo elimina registros con más de 30 días; ni siquiera Cord puede usarla para borrar algo más reciente.

Errores

Las peticiones fallidas agrupadas por código, método y ruta, con los IDs de la ruta reemplazados por {id}, para ver la causa y no cada fila. Periodo de 1 hora, 24 horas, 7 días o 30 días. Una petición sin código propio aparece como http_ y su status.

Cada grupo muestra cuántas veces pasó y cuándo fue la última. Al abrirlo ves el último mensaje de error, la ruta, la primera y la última vez, cuántas llaves lo provocaron y tres acciones: Ver peticiones (Registros filtrado por ese código), Ver un ejemplo (la petición más reciente en el Inspector) y Cómo resolverlo.

Eventos

El historial de eventos de tu negocio: el mismo que devuelve GET /api/v1/events, aunque no tengas ningún webhook.

  • Filtra por tipo de evento, por estado de la entrega (Fallidas, En cola, Entregadas) y por el ID del objeto. En vivo y Cargar más funcionan igual que en Registros.
  • Cada fila muestra el estado de sus entregas, el tipo, el objeto, quién lo originó (API, MCP, Panel, Workflow, Workbench, Integración o Sistema) y la fecha.
  • El detalle muestra el ID del evento, la fecha, el objeto (un clic lo abre en el Inspector), quién lo originó con el nombre de la llave o de la persona, los datos del evento y una entrega por cada endpoint suscrito: URL, status, intentos, próximo intento, el evt_… que recibió ese endpoint y el último error.
  • Reenviar vuelve a mandar una entrega con el mismo payload y el mismo evt_…, para que tu servidor la pueda deduplicar. Con más de una entrega fallida aparece Reenviar las fallidas. Ambos piden el plan Profesional o superior.
  • El estado del evento sale de la última entrega a cada endpoint: un reenvío correcto reemplaza al fallo. Una entrega que Cord canceló porque desactivó el endpoint se ve como Cancelado, no como entregada.

Los eventos internos, como quote.expiring o invoice.due_soon, llevan la etiqueta Interno: los usan los workflows y no se envían por webhooks. Las entregas de prueba (el botón Probar de un endpoint o el simulador sin objeto_id) no son eventos de tu negocio: no aparecen aquí, solo en las entregas del endpoint.

Webhooks

Tus endpoints, con el cupo de tu plan. Agregar endpoint abre un asistente de pantalla completa:

  1. Elige los eventos. Los 44 eventos del catálogo, agrupados por familia, con buscador y una casilla para marcar toda una familia. Todos los eventos incluye también los que Cord agregue después; si no marcas ninguno, recibes todos.
  2. Configura el destino. Una URL pública con https://.
  3. Guarda el secreto. El secreto de firma (whsec_…) se muestra una sola vez. Desde ahí mismo puedes Enviar evento de prueba.
La pestaña Webhooks del Workbench en pantalla completa: el endpoint del ERP con 93.1% de entregas correctas en 7 días, expandido en sus entregas; la más reciente, quote.approved en su segundo intento, falló con 500 y muestra el payload exacto que envió Cord, lo que respondió el servidor y los botones Reintentar y Ver el evento.

Cada endpoint muestra su secreto enmascarado, cuántos eventos recibe, su última entrega y los últimos 7 días: entregas por día, tasa de éxito y latencia p95. Sus acciones:

  • Probar manda ping o cualquiera de sus eventos suscritos con datos de ejemplo, en la versión de la API que fijó el endpoint. El payload lleva "test": true en el primer nivel para que tu servidor distinga una prueba de un evento real.
  • Editar, Rotar secreto (con una ventana de 1, 24 o 72 horas en la que siguen valiendo los dos secretos), activar o pausar y Eliminar.
  • Reactivar o Reactivar y reintentar cuando Cord desactivó el endpoint por una racha de fallos. La segunda reencola lo que falló en las últimas 24 horas.
  • Al expandir la fila ves sus últimas 50 entregas. Cada una abre lo que Cord envió (el payload exacto) y lo que respondió tu servidor (hasta 2,000 caracteres), con Reintentar y, si salió de un evento, Ver el evento.

La guía completa (payload, firmas, catálogo y reintentos) está en Webhooks.

Shell

Corre cualquier operación de la API pública con tu sesión, sin crear una llave.

  • Prueba corre sobre tu entorno de prueba: puedes crear y modificar sin tocar datos reales, y usar los simuladores de prueba.
  • En vivo · solo lectura lee tus datos reales: solo deja enviar operaciones GET.
  • No corren en el Shell las operaciones ligadas a una llave (los endpoints de webhook por API y las sesiones de cord listen) ni las que responden en streaming o suben archivos.

Elige una operación de la lista (con buscador), llena sus parámetros y su cuerpo JSON, que trae un ejemplo, y envíala con Enviar o ⌘↵. En Encabezados opcionales eliges la versión de la API (Cord-Version). La respuesta muestra el status, la latencia y el request id, y tiene tres vistas: Respuesta (hasta 200 KB), Encabezados y Código, con la misma petición en cURL, SDK de Node, JavaScript (fetch) y Python, usando tu llave como $CORD_SECRET_KEY. Recientes guarda tus últimas 15 llamadas de esta organización en este navegador.

Cada llamada del Shell queda en Registros con el origen Workbench y no consume la cuota de API de tu plan. Un clic en el request id la abre en el Inspector. Si la corriste en un entorno distinto al de la app (por ejemplo, en Prueba con la app en vivo), el request id solo se copia: cambia el modo de prueba de la app para verla en Registros.

Llaves

La pestaña Llaves del Workbench en pantalla completa: arriba, 3,412 de 5,000 peticiones a la API usadas este mes y la versión 2026-10-01; abajo, llaves secretas, restringida y pública en modo vivo y prueba, cada una con su token enmascarado y sus últimos 4 caracteres, permisos, último uso, creación y vencimiento, más una conexión OAuth y una llave revocada.
  • Uso de la API este mes contra lo que incluye tu plan, y la versión de la API vigente. Cada llave y cada webhook quedan fijados a la versión del día en que se crean; el encabezado Cord-Version la cambia por petición. Ver Versiones.
  • Claves de API: genera, edita, rota y revoca llaves secretas (sk_), restringidas (rk_) y publicables (pk_), en prueba o en vivo. Cada llave tiene un botón Registros que abre sus peticiones de los últimos 7 días. Las apps autorizadas por OAuth aparecen como Conexión autorizada. Ver Claves de API.
  • Referencia de la API: todas las operaciones, agrupadas, con un ejemplo con curl, un botón Probar en las que se pueden correr en el Shell y el botón que genera un prompt de integración para ChatGPT o Cursor.

Salud

Una lista de alertas activas, cada una con un enlace a la pestaña donde se resuelve:

  • un endpoint desactivado o con 3 o más fallos seguidos;
  • eventos que agotaron sus reintentos y reintentos vencidos en la cola;
  • una tasa de error de 5% o más con al menos 20 peticiones en 24 horas;
  • errores 5xx en las últimas 24 horas;
  • una llave que vence, o una llave rotada que deja de funcionar, en los próximos 7 días.

Debajo, tres tarjetas: el estado de cada endpoint (activo con su tasa de éxito y p95, en pausa, desactivado o con fallos seguidos), la cola de eventos (en cola, reintentos vencidos, agotados y entrega p95) y la API en las últimas 24 horas (peticiones, tasa de error, 4xx, 5xx y latencia p95).

Inspector

Pega un ID en el buscador de la barra superior del panel, o pulsa /:

  • un request id (req_…) abre esa petición;
  • un id de evento (evt_…) abre el evento que lo originó, o te dice que fue una entrega de prueba;
  • el ID de una cotización, factura, cliente, producto, llave, endpoint de webhook o evento.

Para un objeto ves su tipo, su nombre o folio, los eventos que lo mencionan y las peticiones de los últimos 30 días que lo tocaron (o que hizo esa llave). Abrir en Cord lleva a su página cuando tiene una, y en una cotización, factura o cliente, Ver como lo devuelve la API lo abre en el Shell. Volver o Esc regresan a la pestaña.

Enlaces directos

  • /app?wb=registros abre el Workbench en esa pestaña. Los nombres son resumen, registros, errores, eventos, webhooks, shell, api (Llaves) y salud.
  • /app?wbi=<id> abre el Inspector con ese ID.

Los dos activan el Modo desarrollador si estaba apagado.

Preguntas frecuentes

¿Por qué no veo una petición que hice con una llave de prueba? El Workbench muestra el entorno en el que está la app. Entra al entorno de prueba para ver lo de tus llaves sk_test_.

¿El Workbench cuenta contra mi cuota de API? No. Navegar por el panel no llama a tu API, y las llamadas del Shell tampoco cuentan. Solo cuentan las peticiones con llaves en vivo.

¿Por qué Eventos muestra eventos aunque no tengo webhooks? Porque lee el historial de eventos del negocio, no las entregas. Sin endpoints, cada evento aparece como Sin endpoints.

¿Por qué no puedo ver las entregas de un endpoint? El historial de entregas, Reintentar y Reenviar piden el plan Profesional o superior. Crear endpoints, recibir eventos, Probar, Rotar secreto y Reactivar están en todos los planes.

¿Cuánto tiempo se guardan los registros? 30 días desde cada petición. Si necesitas un historial más largo, guarda el request id (Cord-Request-Id) y la respuesta en tu propio sistema.

¿Mi equipo ve lo mismo que yo? Sí. Cualquier miembro con permiso Ajustes ve los datos de la organización. Son personales el Modo desarrollador, que va con tu cuenta, y en cada navegador el tamaño del panel y la opción de UTC. Los recientes del Shell se guardan en cada navegador por organización.