Como conectar uma aplicação externa à API pública do Tóch

🧭 Objetivo

Este artigo tem como objetivo orientar os clientes que desejam criar integrações automáticas entre sistemas externos e o Tóch, utilizando a API pública.
Através dessa integração, é possível criar cards, listar colunas e consultar boards, permitindo automatizar fluxos sem necessidade de intervenção manual.

⚙️ O que é a API pública do Tóch?

A Tóch API é uma interface aberta que permite interagir diretamente com os elementos principais da plataforma:

Boards (quadros): representam os fluxos de trabalho.
Columns (colunas): representam as etapas do processo.
Cards (cartões): representam tarefas, solicitações ou itens do processo.

Cada um desses elementos pode ser consultado, criado ou atualizado via API.

🔑 Endpoints principais

1. Consultar um board específico

Obtém informações sobre um fluxo de trabalho (board), suas colunas, campos e cartões.

GET /api/v1/public/{company_slug}/boards/{board_pk}/

2. Consultar detalhes de um card

Retorna todas as informações de um card (incluindo campos customizados, responsáveis e prazos).

GET /api/v1/public/{company_slug}/boards/{board_pk}/cards/{card_pk}/

🧱 Estrutura básica

🗂️ Board

Representa um fluxo de trabalho visual.
Campos principais:

id: Identificador único do board
title: Nome do fluxo
cards_count: Total de cartões existentes
columns: Lista de colunas associadas
portal_set: Lista de portais públicos vinculados

📌 Column

Cada coluna representa uma etapa do processo.
Campos principais:

id: Identificador único
title: Nome da etapa
index: Posição da coluna no board
allow_create_card: Permite criação de cards nesta etapa
final_stage: Indica se é a etapa final

🗃️ Card

Representa uma tarefa ou item de processo.
Campos principais:

id: Identificador único do card
title: Título
custom_fields: Campos personalizados
responsible: Usuário responsável
tags: Etiquetas associadas

🧩 Como criar um card via API

Para criar um novo card em um board público:

POST /api/v1/public/{company_slug}/boards/{board_pk}/cards/

Corpo da requisição (exemplo)

{   "title": "Nova solicitação de compra",   "custom_fields": {     "Solicitante": "João da Silva",     "Valor": 1250.50,     "Data de Solicitação": "2025-10-13"   } }

Retorno esperado

Um objeto JSON com os dados do card criado, incluindo ID, título e status da criação.

💡 Dicas de uso

Utilize o endpoint /initial-form para saber quais campos são obrigatórios antes de criar um card.
A ordem dos campos (index) pode ser usada para organizar visualmente o formulário no frontend.
Campos com disable: true devem ser exibidos apenas para leitura.
A API respeita as regras de transição definidas no fluxo (allowed_transactions).

🧠 Exemplo prático de automação

Você pode integrar um sistema externo (como ERP, CRM ou formulário web) para criar automaticamente cards no Tóch sempre que um evento ocorrer, como:

Novo lead cadastrado
Pedido de compra criado
Chamado de suporte aberto

Essa abordagem reduz o esforço manual, aumenta a produtividade e garante rastreabilidade de todos os processos dentro do Tóch.

📎 Próximos passos

Para saber mais detalhes técnicos e exemplos completos:
📄 Documentação técnica completa: Tóch API, Boards, Columns e Cards
📄 Guia prático: Fluxo de criação de um card em um board específico

Caso surjam dúvidas ou necessite de apoio em uma integração específica, entre em contato com o nosso time de Customer Success ou abra um ticket com o assunto Integração via API pública.