Introducao

A API Externa Tesselys permite que equipes de TI integrem sistemas terceiros (CRMs, automacoes, BI) com a plataforma Tesselys de forma segura e padronizada.

Caracteristicas

Caracteristica	Detalhe
Protocolo	REST sobre HTTPS
Formato	JSON (request e response)
Encoding	UTF-8
Versionamento	Via path (/v1)
Autenticacao	API Key + Secret → Bearer Token

Base URL

https://api.tesselys.com.br/external/v1

Todas as requisicoes devem utilizar HTTPS. Requisicoes HTTP plano serao rejeitadas.

Recursos Disponiveis

Recurso	Endpoint base	Operacoes
Pessoas	/external/v1/persons	Listar, buscar, criar, atualizar
Negocios	/external/v1/deals	Listar, buscar, criar, atualizar
Lancamentos Financeiros	/external/v1/financial-entries	Listar, buscar, criar
Produtos	/external/v1/products	Listar, buscar, criar, atualizar
Projetos	/external/v1/projects	Listar, buscar, criar

Quick Start — 3 passos

1. Gere sua API Key

Acesse o painel administrativo Tesselys em Configuracoes → Integracoes → API Externa e clique em Gerar nova chave. Voce recebera:

• API Key: tesselys_ak_... (58 caracteres)
• Secret: string base64url (43 caracteres)

cuidado

A API Key e o Secret sao exibidos apenas uma vez. Copie e armazene em local seguro antes de fechar a tela.

2. Autentique-se

curl -X POST https://api.tesselys.com.br/external/v1/auth \
  -H "Content-Type: application/json" \
  -H "x-api-key: tesselys_ak_abc123..." \
  -d '{ "secret": "seu_secret_aqui" }'

Resposta:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "companyToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600
}

3. Chame um endpoint

curl https://api.tesselys.com.br/external/v1/persons \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "x-company-token: eyJhbGciOiJIUzI1NiIs..."

Pre-requisitos

• Conta ativa no Tesselys com role Owner ou Admin
• Feature API Externa (DF_EXT_API) habilitada no plano da empresa
• Ambiente com acesso HTTPS a api.tesselys.com.br

Proximos passos

• Autenticacao — detalhes completos do fluxo de auth
• Rate Limits — limites de uso e estrategia de retry
• Codigos de Erro — formato de erros e como trata-los