Guia: Integração via API REST

Visão Geral

O Termatica oferece uma API REST completa para automação e integração com sistemas externos. Com a API você pode:

- Listar documentos e versões - Registrar aceites programaticamente - Verificar status de aceite de usuários - Criar e gerenciar documentos - Consultar histórico de aceites

---

Autenticação

Obtendo um Token de API

1. Acesse Configurações > Tokens de API 2. Clique em Novo Token 3. Configure: - Nome: Identificador do token (ex: "Integração App Mobile") - Escopo: read, write ou admin 4. Clique em Gerar 5. Copie o token - ele só é exibido uma vez!

Formato do Token

Os tokens seguem o formato:

` tm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx tm_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx `

- tm_live_ = Token de produção - tm_test_ = Token de teste/sandbox

Usando o Token

Inclua o token no header Authorization:

`bash curl -X GET "https://termatica.com.br/api/v1/documents/" \ -H "Authorization: Bearer tm_live_seu_token_aqui" `

Escopos de Permissão

| Escopo | Permissões | |--------|------------| | read | Listar e consultar documentos, versões e aceites | | write | Read + Criar aceites e atualizar documentos | | admin | Write + Gerenciar tokens, webhooks e configurações |

---

Endpoints Disponíveis

Base URL

` https://termatica.com.br/api/v1/ `

Documentos

| Método | Endpoint | Descrição | |--------|----------|-----------| | GET | /documents/ | Lista todos os documentos | | GET | /documents/{document_key}/ | Detalhes de um documento | | POST | /documents/ | Cria novo documento | | PUT | /documents/{document_key}/ | Atualiza documento | | DELETE | /documents/{document_key}/ | Remove documento |

Versões de Documentos

| Método | Endpoint | Descrição | |--------|----------|-----------| | GET | /documents-versions/ | Lista todas as versões | | GET | /documents-versions/{version_key}/ | Detalhes de uma versão | | GET | /documents-versions/active/ | Versões ativas e vigentes |

Aceites

| Método | Endpoint | Descrição | |--------|----------|-----------| | POST | /documents/accept-user/ | Registra aceite de usuário | | GET/POST | /documents/check-status/ | Verifica pendências | | GET | /documents/accepted-latest/ | Verifica aceite da última versão |

---

Exemplos de Uso

Listar Documentos

Request: `bash curl -X GET "https://termatica.com.br/api/v1/documents/" \ -H "Authorization: Bearer tm_live_seu_token" `

Response: `json { "count": 2, "next": null, "previous": null, "results": [ { "document_key": "550e8400-e29b-41d4-a716-446655440000", "name": "Termos de Uso", "code": "terms_of_use", "description": "Termos e condições de uso", "is_active": true, "order": 1, "target_audience": "user", "created_at": "2024-01-01T10:00:00Z" }, { "document_key": "660e8400-e29b-41d4-a716-446655440001", "name": "Política de Privacidade", "code": "privacy_policy", "description": "Política de tratamento de dados", "is_active": true, "order": 2, "target_audience": "user", "created_at": "2024-01-01T10:00:00Z" } ] } `

Obter Versão Ativa

Request: `bash curl -X GET "https://termatica.com.br/api/v1/documents-versions/active/?document_code=terms_of_use" \ -H "Authorization: Bearer tm_live_seu_token" `

Response: `json [ { "version_key": "770e8400-e29b-41d4-a716-446655440002", "version": "2.0", "title": "Termos de Uso - Versão 2.0", "document": { "document_key": "550e8400-e29b-41d4-a716-446655440000", "name": "Termos de Uso", "code": "terms_of_use" }, "effective_date": "2024-01-01", "is_active": true, "is_published": true, "created_at": "2024-01-01T10:00:00Z" } ] `

Registrar Aceite de Usuário

Request: `bash curl -X POST "https://termatica.com.br/api/v1/documents/accept-user/" \ -H "Authorization: Bearer tm_live_seu_token" \ -H "Content-Type: application/json" \ -d '{ "document_version": "770e8400-e29b-41d4-a716-446655440002", "user_email": "usuario@exemplo.com", "user_name": "João da Silva", "ip_address": "192.168.1.100", "user_agent": "MeuApp/1.0 (iOS 17.0)" }' `

Response: `json { "acceptance_key": "880e8400-e29b-41d4-a716-446655440003", "document_version": "770e8400-e29b-41d4-a716-446655440002", "user_email": "usuario@exemplo.com", "user_name": "João da Silva", "accepted_at": "2024-01-15T14:30:00Z", "ip_address": "192.168.1.100", "user_agent": "MeuApp/1.0 (iOS 17.0)", "acceptance_hash": "abc123def456..." } `

Verificar Status de Aceite

Request: `bash curl -X POST "https://termatica.com.br/api/v1/documents/check-status/" \ -H "Authorization: Bearer tm_live_seu_token" \ -H "Content-Type: application/json" \ -d '{ "user_email": "usuario@exemplo.com" }' `

Response: `json { "pending_documents": [ { "version_key": "990e8400-e29b-41d4-a716-446655440004", "version": "1.0", "title": "Política de Cookies", "document": { "name": "Política de Cookies", "code": "cookie_policy" } } ], "accepted_documents": [ { "version_key": "770e8400-e29b-41d4-a716-446655440002", "version": "2.0", "title": "Termos de Uso", "document": { "name": "Termos de Uso", "code": "terms_of_use" } } ], "has_pending": true } `

Verificar Aceite da Última Versão

Request: `bash curl -X GET "https://termatica.com.br/api/v1/documents/accepted-latest/?user_email=usuario@exemplo.com&document_code=terms_of_use" \ -H "Authorization: Bearer tm_live_seu_token" `

Response: `json { "document_code": "terms_of_use", "latest_version_key": "770e8400-e29b-41d4-a716-446655440002", "latest_version": "2.0", "accepted": true, "accepted_at": "2024-01-15T14:30:00Z", "acceptance_key": "880e8400-e29b-41d4-a716-446655440003" } `

---

Integrações por Linguagem

JavaScript / Node.js

`javascript const TERMATICA_API = 'https://termatica.com.br/api/v1'; const API_TOKEN = 'tm_live_seu_token';

// Função auxiliar para requisições async function termaticaAPI(endpoint, options = {}) { const response = await fetch(${TERMATICA_API}${endpoint}, { ...options, headers: { 'Authorization': Bearer ${API_TOKEN}, 'Content-Type': 'application/json', ...options.headers } });

if (!response.ok) { throw new Error(API Error: ${response.status}); }

return response.json(); }

// Verificar se usuário aceitou os termos async function checkUserAcceptance(email) { return termaticaAPI('/documents/check-status/', { method: 'POST', body: JSON.stringify({ user_email: email }) }); }

// Registrar aceite async function registerAcceptance(versionKey, email, name, ip) { return termaticaAPI('/documents/accept-user/', { method: 'POST', body: JSON.stringify({ document_version: versionKey, user_email: email, user_name: name, ip_address: ip }) }); }

// Uso (async () => { // Verificar pendências const status = await checkUserAcceptance('usuario@exemplo.com');

if (status.has_pending) { console.log('Documentos pendentes:', status.pending_documents);

// Registrar aceite do primeiro documento pendente const pending = status.pending_documents[0]; const acceptance = await registerAcceptance( pending.version_key, 'usuario@exemplo.com', 'João da Silva', '192.168.1.100' );

console.log('Aceite registrado:', acceptance.acceptance_key); } })(); `

Python

`python import requests

TERMATICA_API = 'https://termatica.com.br/api/v1' API_TOKEN = 'tm_live_seu_token'

class TermaticaClient: def __init__(self, api_token: str): self.token = api_token self.headers = { 'Authorization': f'Bearer {api_token}', 'Content-Type': 'application/json' }

def _request(self, method: str, endpoint: str, data: dict = None): url = f'{TERMATICA_API}{endpoint}' response = requests.request( method, url, headers=self.headers, json=data ) response.raise_for_status() return response.json()

def check_status(self, user_email: str) -> dict: """Verifica documentos pendentes para um usuário""" return self._request('POST', '/documents/check-status/', { 'user_email': user_email })

def register_acceptance( self, version_key: str, user_email: str, user_name: str, ip_address: str = None ) -> dict: """Registra aceite de um documento""" return self._request('POST', '/documents/accept-user/', { 'document_version': version_key, 'user_email': user_email, 'user_name': user_name, 'ip_address': ip_address })

def list_documents(self) -> list: """Lista todos os documentos""" return self._request('GET', '/documents/')

def get_active_versions(self, document_code: str = None) -> list: """Retorna versões ativas""" endpoint = '/documents-versions/active/' if document_code: endpoint += f'?document_code={document_code}' return self._request('GET', endpoint)

Uso

client = TermaticaClient(API_TOKEN)

Verificar pendências

status = client.check_status('usuario@exemplo.com')

if status['has_pending']: print('Documentos pendentes:') for doc in status['pending_documents']: print(f" - {doc['title']} (v{doc['version']})")

# Registrar aceite pending = status['pending_documents'][0] acceptance = client.register_acceptance( version_key=pending['version_key'], user_email='usuario@exemplo.com', user_name='João da Silva', ip_address='192.168.1.100' )

print(f"Aceite registrado: {acceptance['acceptance_key']}") `

PHP

`php <?php

class TermaticaClient { private $apiUrl = 'https://termatica.com.br/api/v1'; private $token;

public function __construct(string $token) { $this->token = $token; }

private function request(string $method, string $endpoint, array $data = null) { $ch = curl_init();

$url = $this->apiUrl . $endpoint; $headers = [ 'Authorization: Bearer ' . $this->token, 'Content-Type: application/json' ];

curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

if ($method === 'POST') { curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); }

$response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);

if ($httpCode >= 400) { throw new Exception("API Error: $httpCode - $response"); }

return json_decode($response, true); }

public function checkStatus(string $email): array { return $this->request('POST', '/documents/check-status/', [ 'user_email' => $email ]); }

public function registerAcceptance( string $versionKey, string $email, string $name, string $ip = null ): array { return $this->request('POST', '/documents/accept-user/', [ 'document_version' => $versionKey, 'user_email' => $email, 'user_name' => $name, 'ip_address' => $ip ]); } }

// Uso $client = new TermaticaClient('tm_live_seu_token');

$status = $client->checkStatus('usuario@exemplo.com');

if ($status['has_pending']) { $pending = $status['pending_documents'][0];

$acceptance = $client->registerAcceptance( $pending['version_key'], 'usuario@exemplo.com', 'João da Silva', $_SERVER['REMOTE_ADDR'] );

echo "Aceite registrado: " . $acceptance['acceptance_key']; } `

---

Tratamento de Erros

Códigos de Status HTTP

| Código | Significado | |--------|-------------| | 200 | Sucesso | | 201 | Criado com sucesso | | 400 | Requisição inválida (dados incorretos) | | 401 | Não autenticado (token inválido) | | 403 | Sem permissão (escopo insuficiente) | | 404 | Recurso não encontrado | | 429 | Rate limit excedido | | 500 | Erro interno do servidor |

Formato de Erro

`json { "error": "Descrição do erro", "code": "ERROR_CODE", "details": { "field": ["mensagem de erro específica"] } } `

Exemplo de Tratamento

`javascript try { const result = await termaticaAPI('/documents/accept-user/', { method: 'POST', body: JSON.stringify(data) }); } catch (error) { if (error.status === 400) { console.error('Dados inválidos:', error.details); } else if (error.status === 401) { console.error('Token inválido ou expirado'); } else if (error.status === 429) { console.error('Rate limit excedido. Aguarde antes de tentar novamente.'); } else { console.error('Erro inesperado:', error); } } `

---

Rate Limiting

A API possui limites de requisições:

| Escopo | Limite | |--------|--------| | read | 1000 req/hora | | write | 500 req/hora | | admin | 500 req/hora |

Headers de Rate Limit

` X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 998 X-RateLimit-Reset: 1705334400 `

---

Webhooks

Para receber notificações em tempo real, configure webhooks:

1. Acesse Configurações > Webhooks 2. Clique em Novo Webhook 3. Configure: - URL: Endpoint que receberá as notificações - Eventos: Selecione os eventos desejados - Secret: Chave para validar assinatura

Eventos Disponíveis

| Evento | Descrição | |--------|-----------| | acceptance.created | Novo aceite registrado | | document.published | Nova versão publicada | | document.updated | Documento atualizado |

Payload de Exemplo

`json { "event": "acceptance.created", "timestamp": "2024-01-15T14:30:00Z", "data": { "acceptance_key": "880e8400-e29b-41d4-a716-446655440003", "user_email": "usuario@exemplo.com", "document": { "name": "Termos de Uso", "version": "2.0" } } } `

---

Documentação Interativa

Acesse a documentação interativa da API:

- Swagger UI: /api/docs/swagger/ - ReDoc: /api/docs/redoc/ - RapiDoc: /api/docs/

---

Próximos Passos

- Incorporação e Embedding - Alternativa sem código backend - Leitura Pública - Exibir documentos via API - Configurando Documentos - Criar documentos antes de integrar