Pular para o conteúdo
PTEN

Cord Workbench

Crie, teste e depure a sua integração sem sair do Cord: cada requisição, cada erro, cada evento e cada entrega em um único painel.

O que é?

O Workbench é o console de desenvolvedores do Cord. Ele vive na parte de baixo do app como uma pílula Desenvolvedores e, ao ser aberto, exibe um painel com oito abas: Visão geral, Logs, Erros, Eventos, Webhooks, Shell, Chaves e Saúde. Na barra superior do painel fica o Inspetor, que encontra qualquer ID.

As chaves de API, os webhooks, os logs e os eventos vivem aqui. MCP, Inteligência artificial e Gerador de orçamentos incorporável continuam em Configurações, na seção Desenvolvedores do índice, porque são configurações feitas uma única vez.

Requisitos

  • Permissão de Configurações na sua função. Sem ela, o Workbench não aparece.
  • Modo desenvolvedor ativo. É uma preferência da sua conta, não da organização.
  • Está disponível em todos os planos. O histórico de entregas de webhooks, Tentar novamente e Reenviar exigem o plano Profissional ou superior.

Ativar

  1. Acesse Configurações e role até o final do índice de categorias.
  2. Ative o interruptor Modo desenvolvedor.
  3. A pílula Desenvolvedores aparece no canto inferior direito, em todo o app. Clique nela, arraste-a para cima ou pressione W.

O Modo desenvolvedor acompanha você em qualquer computador em que você entrar com a sua conta. Você também pode alterá-lo nas suas Preferências. Um link com ?wb= ou ?wbi= (veja Links diretos) também o ativa.

O painel

O Workbench aberto até a metade sobre Orçamentos, na aba Visão geral dos últimos 7 dias em produção: 2.523 requisições à API com 1,9% de erro, latência p95 de 412 ms e 99,5% das entregas de webhook bem-sucedidas; os principais erros por código, de onde vêm as requisições, a atividade recente, a integração sem alertas e 3.412 de 5.000 requisições do mês usadas.
  • Tamanho. Arraste a alça superior para aumentar ou diminuir o painel; solte-a perto da parte de baixo para fechá-lo.
  • Tela cheia. O botão ao lado de Fechar expande o painel para a janela inteira. Para sair, use o mesmo botão, ⇧W ou Esc.
  • Opções (⋯). Mostrar os horários em UTC muda na hora todas as datas do painel sem alterar o fuso horário da sua conta. O menu também lista os atalhos de teclado e leva a este guia e à especificação OpenAPI.
  • Ambiente. O Workbench mostra o ambiente em que o app está. No ambiente de teste você vê o que as suas chaves sk_test_ e o Shell em Teste fizeram; em produção, o que as suas chaves de produção fizeram. A Visão geral indica isso com uma etiqueta Teste ou Produção.
  • O painel lembra, neste navegador, se estava aberto, a aba, a altura, a tela cheia e a opção de UTC.

Atalhos de teclado

Tecla O que faz
W Abre ou fecha o Workbench.
⇧W Tela cheia.
/ Coloca o cursor no Inspetor.
1 a 8 Vai para a aba com esse número, na ordem da barra.
J / K Linha seguinte ou anterior em Logs e Eventos.
⌘↵ (Ctrl+↵ no Windows) Envia a requisição do Shell.
Esc Fecha o que estiver aberto: menu, diálogo, Inspetor, tela cheia e, por último, o painel.

Os atalhos de uma letra ou número não são ativados enquanto você digita em um campo. Em telas com menos de 880 px não há atalhos de uma tecla e o painel se abre como uma folha de borda a borda; nas mais estreitas, o Inspetor é um ícone da barra superior que se expande ao ser tocado.

As abas

Visão geral

A visão de entrada, com período de 24 horas, 7 dias ou 30 dias:

  • Indicadores: requisições de API, taxa de erro, latência p95 (com a p50 abaixo) e porcentagem de entregas de webhook bem-sucedidas.
  • Requisições ao longo do tempo: barras de bem-sucedidas e com erro.
  • Principais erros: os cinco códigos que mais se repetem. Um clique abre Logs filtrado por esse código.
  • De onde vêm: as requisições por origem. Um clique abre Logs filtrado por essa origem.
  • Atividade recente: as últimas seis requisições.
  • À direita: o cartão de saúde (leva você a Saúde), o uso da API este mês em relação ao que o seu plano inclui, os primeiros passos enquanto ainda não há requisições no período e os recursos para desenvolvedores.

No uso do mês só contam as chamadas com chaves de produção: as de teste e as do Workbench não consomem a sua cota.

A origem de cada requisição vem do cliente que a fez:

Origem Quando
SDK para Node, SDK para Python, SDK para PHP, CLI O SDK ou a CLI do Cord se identificou na requisição.
cURL A requisição saiu do curl.
MCP Uma chamada ao servidor MCP.
Cord Elements Uma chave publicável (pk_), como a do Cord Elements.
App conectado Um app autorizado por OAuth, como o Zapier ou o Make.
Workbench O Shell.
HTTP Qualquer outro cliente.

Logs

Cada requisição que chegou a /api/v1 e ao servidor MCP, em uma lista com o detalhe à direita. As chamadas de MCP mostram a ferramenta, por exemplo /mcp/tools/call:listar_productos.

O Workbench no ambiente de teste, na aba Logs: as requisições do início rápido feitas com cURL e a chave de teste, uma com o erro invalid_request e outra a partir do Shell do Workbench, e o detalhe de POST /v1/cotizaciones (201, 184 ms) com o request id, a versão 2026-10-01, o modo Teste e os botões Copiar como cURL e Abrir no Shell.
  • Busque por rota, por request id (req_…), por código de erro ou por uma Idempotency-Key exata. Um request id é buscado em todo o histórico, independentemente do período.
  • Filtre por método (GET, POST, PATCH, DELETE), por classe de status (2xx, 4xx, 5xx), por chave (ou só as do Workbench), por origem e por período (1 hora, 24 horas, 7 dias ou 30 dias).
  • Ao vivo adiciona as requisições novas no topo a cada poucos segundos enquanto a aba está visível. Carregar mais traz as 50 seguintes.

O detalhe de uma requisição mostra o status, o código de erro com a mensagem e um link para Como resolver em Erros, o request id, a data, a latência, a chave, a origem, a versão da API, o modo, o IP e a Idempotency-Key. Se o Cord devolveu a resposta guardada de uma requisição repetida, isso é marcado como Resposta repetida, e abaixo aparecem as outras requisições com a mesma Idempotency-Key.

  • Copiar como cURL copia a requisição pronta para colar no seu terminal: o header Authorization lê a sua chave da variável de ambiente $CORD_SECRET_KEY. O corpo não vai junto porque não é guardado.
  • Abrir no Shell a carrega no Shell com os parâmetros dela. Em produção, só aparece para requisições GET.
  • Inspecionar o recurso abre no Inspetor o ID que vem na rota.

O Cord não guarda o corpo das requisições nem das respostas da API, apenas os metadados. Guardá-los significaria conservar dados dos seus clientes (identificações fiscais, e-mails, valores) em cada chamada. Para ver uma resposta completa, repita a operação no Shell ou consulte o log do seu próprio servidor.

Cada requisição é guardada por 30 dias. Um processo diário apaga o que for mais antigo, então o período mais longo de Logs, Erros e Visão geral é de 30 dias. A exclusão é feita por uma função do banco de dados que só elimina registros com mais de 30 dias; nem mesmo o Cord pode usá-la para apagar algo mais recente.

Erros

As requisições com falha agrupadas por código, método e rota, com os IDs da rota substituídos por {id}, para ver a causa e não cada linha. Período de 1 hora, 24 horas, 7 dias ou 30 dias. Uma requisição sem código próprio aparece como http_ mais o status.

Cada grupo mostra quantas vezes aconteceu e quando foi a última. Ao abri-lo, você vê a última mensagem de erro, a rota, a primeira e a última vez, quantas chaves o provocaram e três ações: Ver requisições (Logs filtrado por esse código), Ver um exemplo (a requisição mais recente no Inspetor) e Como resolver.

Eventos

O histórico de eventos da sua empresa: o mesmo que GET /api/v1/events devolve, mesmo que você não tenha nenhum webhook.

  • Filtre por tipo de evento, por status da entrega (Com falha, Na fila, Entregues) e pelo ID do objeto. Ao vivo e Carregar mais funcionam como em Logs.
  • Cada linha mostra o status das entregas, o tipo, o objeto, quem o originou (API, MCP, Painel, Workflow, Workbench, Integração ou Sistema) e a data.
  • O detalhe mostra o ID do evento, a data, o objeto (um clique o abre no Inspetor), quem o originou com o nome da chave ou da pessoa, os dados do evento e uma entrega para cada endpoint inscrito: URL, status, tentativas, próxima tentativa, o evt_… que esse endpoint recebeu e o último erro.
  • Reenviar envia de novo uma entrega com o mesmo payload e o mesmo evt_…, para que o seu servidor possa eliminar o duplicado. Com mais de uma entrega com falha, aparece Reenviar as que falharam. Os dois exigem o plano Profissional ou superior.
  • O status do evento vem da última entrega para cada endpoint: um reenvio bem-sucedido substitui a falha. Uma entrega que o Cord cancelou porque desativou o endpoint aparece como Cancelado, não como entregue.

Os eventos internos, como quote.expiring ou invoice.due_soon, levam a etiqueta Interno: são usados pelos workflows e não são enviados por webhooks. As entregas de teste (o botão Testar de um endpoint ou o simulador sem objeto_id) não são eventos da sua empresa: não aparecem aqui, só nas entregas do endpoint.

Webhooks

Os seus endpoints, com a cota do seu plano. Adicionar endpoint abre um assistente em tela cheia:

  1. Escolher eventos. Os 41 eventos do catálogo, agrupados por família, com busca e uma caixa de seleção para marcar uma família inteira. Todos os eventos inclui também os que o Cord adicionar depois; se você não marcar nenhum, recebe todos.
  2. Configurar destino. Uma URL pública com https://.
  3. Guarde o segredo. O segredo de assinatura (whsec_…) é exibido uma única vez. Dali mesmo você pode Enviar evento de teste.
A aba Webhooks do Workbench em tela cheia: o endpoint do ERP com 93,1% de entregas bem-sucedidas em 7 dias, expandido em suas entregas; a mais recente, quote.approved na segunda tentativa, falhou com 500 e mostra o payload exato que o Cord enviou, o que o servidor respondeu e os botões Tentar novamente e Ver o evento.

Cada endpoint mostra o segredo mascarado, quantos eventos recebe, a última entrega e os últimos 7 dias: entregas por dia, taxa de sucesso e latência p95. As ações dele:

  • Testar envia ping ou qualquer um dos eventos inscritos com dados de exemplo, na versão da API fixada no endpoint. O payload leva "test": true no primeiro nível para que o seu servidor diferencie um teste de um evento real.
  • Editar, Rotacionar segredo (com uma janela de 1, 24 ou 72 horas em que os dois segredos continuam valendo), ativar ou pausar e Excluir.
  • Reativar ou Reativar e tentar novamente quando o Cord desativou o endpoint por uma sequência de falhas. A segunda opção coloca de novo na fila o que falhou nas últimas 24 horas.
  • Ao expandir a linha, você vê as últimas 50 entregas. Cada uma abre O que o Cord enviou (o payload exato) e O que seu servidor respondeu (até 2.000 caracteres), com Tentar novamente e, se ela veio de um evento, Ver o evento.

O guia completo (payload, assinaturas, catálogo e novas tentativas) está em Webhooks.

Shell

Executa qualquer operação da API pública com a sua sessão, sem criar uma chave.

  • Teste roda no seu ambiente de teste: você pode criar e modificar sem tocar em dados reais, e usar os simuladores de teste.
  • Produção · somente leitura lê os seus dados reais: só permite enviar operações GET.
  • Não rodam no Shell as operações vinculadas a uma chave (os endpoints de webhook por API e as sessões de cord listen) nem as que respondem em streaming ou enviam arquivos.

Escolha uma operação da lista (com busca), preencha os parâmetros e o corpo JSON, que traz um exemplo, e envie-a com Enviar ou ⌘↵. Em Headers opcionais você escolhe a versão da API (Cord-Version). A resposta mostra o status, a latência e o request id, e tem três visões: Resposta (até 200 KB), Headers e Código, com a mesma requisição em cURL, SDK para Node, JavaScript (fetch) e Python, usando a sua chave como $CORD_SECRET_KEY. Recentes guarda as suas últimas 15 chamadas desta organização neste navegador.

Cada chamada do Shell fica em Logs com a origem Workbench e não consome a cota de API do seu plano. Um clique no request id a abre no Inspetor. Se você a executou em um ambiente diferente do app (por exemplo, em Teste com o app em produção), o request id é apenas copiado: mude o modo de teste do app para vê-la em Logs.

Chaves

A aba Chaves do Workbench em tela cheia: no topo, 3.412 de 5.000 requisições à API usadas este mês e a versão 2026-10-01; abaixo, chaves secretas, restrita e publicável em produção e em teste, cada uma com o token mascarado e os últimos 4 caracteres, permissões, último uso, criação e vencimento, além de uma conexão OAuth e uma chave revogada.
  • Uso da API este mês em relação ao que o seu plano inclui, e a versão da API vigente. Cada chave e cada webhook ficam fixados na versão do dia em que são criados; o header Cord-Version a altera por requisição. Veja Versões.
  • Chaves de API: gere, edite, rotacione e revogue chaves secretas (sk_), restritas (rk_) e publicáveis (pk_), em teste ou em produção. Cada chave tem um botão Logs que abre as requisições dela dos últimos 7 dias. Os apps autorizados por OAuth aparecem como Conexão autorizada. Veja Chaves de API.
  • Referência da API: todas as operações, agrupadas, com um exemplo com curl, um botão Testar nas que podem ser executadas no Shell e o botão que gera um prompt de integração para o ChatGPT ou o Cursor.

Saúde

Uma lista de alertas ativos, cada um com um link para a aba em que o problema é resolvido:

  • um endpoint desativado ou com 3 ou mais falhas seguidas;
  • eventos que esgotaram as novas tentativas e tentativas atrasadas na fila;
  • uma taxa de erro de 5% ou mais com pelo menos 20 requisições em 24 horas;
  • erros 5xx nas últimas 24 horas;
  • uma chave que vence, ou uma chave rotacionada que deixa de funcionar, nos próximos 7 dias.

Abaixo, três cartões: o status de cada endpoint (ativo com a taxa de sucesso e o p95, pausado, desativado ou com falhas seguidas), a fila de eventos (na fila, tentativas atrasadas, esgotados e entrega p95) e a API nas últimas 24 horas (requisições, taxa de erro, 4xx, 5xx e latência p95).

Inspetor

Cole um ID no campo de busca da barra superior do painel, ou pressione /:

  • um request id (req_…) abre essa requisição;
  • um id de evento (evt_…) abre o evento que o originou, ou informa que foi uma entrega de teste;
  • o ID de um orçamento, fatura, cliente, produto, chave, endpoint de webhook ou evento.

Para um objeto, você vê o tipo, o nome ou número, os eventos que o mencionam e as requisições dos últimos 30 dias que o tocaram (ou que essa chave fez). Abrir no Cord leva à página dele quando ele tem uma, e em um orçamento, fatura ou cliente, Ver como a API o retorna o abre no Shell. Voltar ou Esc retornam à aba.

  • /app?wb=registros abre o Workbench nessa aba. Os nomes são resumen (Visão geral), registros (Logs), errores (Erros), eventos (Eventos), webhooks, shell, api (Chaves) e salud (Saúde).
  • /app?wbi=<id> abre o Inspetor com esse ID.

Os dois ativam o Modo desenvolvedor se ele estava desligado.

Perguntas frequentes

Por que não vejo uma requisição que fiz com uma chave de teste? O Workbench mostra o ambiente em que o app está. Entre no ambiente de teste para ver o que as suas chaves sk_test_ fizeram.

O Workbench conta contra a minha cota de API? Não. Navegar pelo painel não chama a sua API, e as chamadas do Shell também não contam. Só contam as requisições com chaves de produção.

Por que Eventos mostra eventos mesmo que eu não tenha webhooks? Porque ele lê o histórico de eventos da empresa, não as entregas. Sem endpoints, cada evento aparece como Sem endpoints.

Por que não consigo ver as entregas de um endpoint? O histórico de entregas, Tentar novamente e Reenviar exigem o plano Profissional ou superior. Criar endpoints, receber eventos, Testar, Rotacionar segredo e Reativar estão disponíveis em todos os planos.

Por quanto tempo os logs são guardados? 30 dias a partir de cada requisição. Se você precisa de um histórico mais longo, guarde o request id (Cord-Request-Id) e a resposta no seu próprio sistema.

A minha equipe vê o mesmo que eu? Sim. Qualquer membro com a permissão de Configurações vê os dados da organização. São pessoais o Modo desenvolvedor, que acompanha a sua conta, e, em cada navegador, o tamanho do painel e a opção de UTC. As chamadas recentes do Shell são guardadas em cada navegador por organização.