Como criar um Card em um board específico usando a API pública do Tóch

🎯 Objetivo

Este artigo orienta como criar cards automaticamente em um board (quadro) do Tóch através da API pública, permitindo automatizar fluxos e conectar sistemas externos, como ERPs, CRMs, portais internos ou formulários web, sem necessidade de intervenção manual.

Essa prática faz parte da nossa estratégia Tech Touch, que visa oferecer autonomia, escalabilidade e rapidez para que você extraia o máximo valor do Tóch.

🧩 Pré-requisitos

Antes de iniciar, certifique-se de ter:

Seu token de acesso à API (para obter, entre em contato com o Suporte Tóch).
O ID do board (board_pk) e o slug da empresa (company_slug).
Acesso ao Swagger Público do Tóch:
👉 Toch API Public Swagger

⚙️ Etapas para criar um Card via API

🔹 Passo 1: Obter o ID do Board

Acesse o Dashboard do Tóch.
Localize o board onde deseja criar o card.
Na URL do navegador, identifique:
- board_pk → o ID do board.
- company_slug → o nome único da empresa (parte da URL).

🧠 Exemplo:

https://app.usetoch.com.br/company123/boards/5/

Neste caso:

company_slug = company123
board_pk = 5

🔹 Passo 2: Obter o Formulário Inicial do Board

Com esses valores em mãos, use o endpoint abaixo para obter o formulário inicial do quadro, que contém os campos personalizados (custom_fields) necessários para criar o card.

Endpoint:

GET /api/v1/public/{company_slug}/boards/{board_pk}/initial-form/

Cabeçalho de autenticação:

Authorization: Token <seu_token>

Resposta esperada:
Um objeto JSON contendo:

Campos obrigatórios e opcionais;
Tipos de dados esperados;
IDs de campo (field_id) que serão usados na criação do card.

💡 Dica: esse endpoint é essencial para entender como preencher corretamente os campos na etapa seguinte.

🔹 Passo 3: Criar o Card

Com base nas informações do formulário inicial, envie a requisição para criar o card no board.

Endpoint:

POST /api/v1/public/{company_slug}/boards/{board_pk}/create-card/

Cabeçalhos:

Authorization: Token <seu_token> Content-Type: application/json

Corpo da requisição (exemplo):

{   "column_to_move": 2,   "custom_fields": [     {       "field_id": "nome-completo",       "value": "João da Silva"     },     {       "field_id": "valor-da-compra",       "value": 1250.50     }   ] }

Resposta esperada:
Um objeto JSON com status 200 OK, confirmando a criação do card e retornando seus dados (ID, título, status e campos associados).

🔹 Passo 4: Confirmar a criação

Após o envio da requisição, o card será criado automaticamente no board indicado, na coluna definida em column_to_move (caso especificada).
Você pode confirmar a criação acessando o board no Tóch e verificando o novo card.

💡 Exemplo prático (via cURL)

1️⃣ Obter o formulário inicial:

curl -X GET "https://api.usetoch.com.br/api/v1/public/company123/boards/5/initial-form/" \ -H "Authorization: Token abc123"

2️⃣ Criar o card:

curl -X POST "https://api.usetoch.com.br/api/v1/public/company123/boards/5/create-card/" \ -H "Authorization: Token abc123" \ -H "Content-Type: application/json" \ -d '{   "custom_fields": [     {       "field_id": "nome-completo",       "value": "João Silva"     }   ] }'

📘 Resumo do Processo

Etapa	Ação	Endpoint	Método
1	Obter ID e slug da empresa	–	–
2	Obter formulário inicial	`/initial-form/`	GET
3	Enviar dados para criar o card	`/create-card/`	POST
4	Confirmar criação no board	–	–

🧠 Boas práticas e recomendações

Sempre consulte o endpoint initial-form antes de criar um card, ele garante que você tenha os campos corretos e atualizados.
Mantenha o seu token de autenticação seguro e evite compartilhá-lo publicamente.
Teste suas integrações em um ambiente de sandbox/laboratório antes de levar para produção.
Utilize automações para monitorar erros de integração (por exemplo, logs HTTP ou notificações em caso de falha).

🔗 Recursos úteis

📄 [Documentação completa da API Pública do Tóch , Boards, Columns e Cards]
💬 Suporte Técnico: abra um ticket com o assunto Integração via API Pública
🔐 Para obter o Token de Acesso: entre em contato com o Suporte Tóch

🎯 Conclusão

A integração via API pública do Tóch permite que sua empresa automatize a criação de cards e conecte sistemas externos de forma ágil e segura.
Essa abordagem reduz tarefas manuais, melhora a eficiência operacional e fortalece a jornada Tech Touch, dando autonomia à sua equipe para inovar com o Tóch.