Criando seu primeiro card
Do token ao card no board em 5 minutos, copiando e colando.
Este passo a passo cria um card em um board do seu CRM usando apenas o terminal (ou qualquer ferramenta que faça requisições HTTP, como Postman e Insomnia).
O que você vai precisar
- Um token de API — gere aqui
- O slug da sua organização — visível na URL do app (ex.:
app.perpetuus.com.br/acme→acme)
1. Descubra o ID do seu board
curl "https://api.perpetuus.com.br/api/boards" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "x-tenant-id: acme"Na resposta, copie o documentId do board desejado:
{
"data": [
{
"documentId": "bd1a2b3c",
"name": "Funil de Vendas",
"phases": [
{
"documentId": "ph0aaa",
"name": "Formulário",
"order": 0,
"fields": [
{ "slug": "name", "label": "Nome", "required": true },
{ "slug": "email", "label": "E-mail" },
{ "slug": "phone", "label": "Telefone" }
]
}
]
}
]
}Repare nos fields da fase de order 0 (o formulário de entrada): são os campos
aceitos na criação do card. O campo name costuma ser obrigatório.
2. Crie o card
curl -X POST "https://api.perpetuus.com.br/api/boards/bd1a2b3c/cards" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "x-tenant-id: acme" \
-H "Content-Type: application/json" \
-d '{
"data": {
"fields": {
"name": "Meu primeiro lead via API",
"email": "lead@cliente.com",
"phone": "+5511999999999"
},
"description": "Criado seguindo o guia da documentação 🎉"
}
}'A resposta traz o card criado, com documentId, title e a fase em que ele entrou:
{
"documentId": "cd9x8y7z",
"title": "Meu primeiro lead via API",
"currentPhase": { "documentId": "ph1ccc", "name": "Novo lead" },
"fields": {
"name": "Meu primeiro lead via API",
"email": "lead@cliente.com",
"phone": "+5511999999999"
}
}Abra o board no Perpetuus — o card está lá, na primeira coluna. ✅
Erros comuns
| Resposta | Causa | Solução |
|---|---|---|
400 — Header x-tenant-id é obrigatório | Faltou o header do tenant | Adicione -H "x-tenant-id: seu-slug" |
401 — Autenticação obrigatória | Token ausente/expirado | Gere um novo token |
400 — Campo "name" é obrigatório | O board exige name na Fase 0 | Inclua name em fields |
400 — Validação de campos falhou | Slug errado ou tipo inválido | Confira os slugs no passo 1 |