Codigo pronto pra copiar — copie o .md desta pagina e cole na sua IA pra ela te ajudar a integrar.
## Node.js / TypeScript
### Setup
```bash
npm install node-fetch form-data dotenv
```
`.env`:
```
BUILDSHIP_API_KEY=bld_sua_chave_aqui
BUILDSHIP_WEBHOOK_SECRET=seu_secret_webhook
```
### Cliente completo
```ts
// src/buildship-client.ts
import fetch from 'node-fetch';
import FormData from 'form-data';
import fs from 'fs';
const BASE = 'https://api.buildship.com.br/api/v1';
const KEY = process.env.BUILDSHIP_API_KEY!;
export class BuildShip {
private headers = { 'X-API-Key': KEY };
async chat(opts: { message: string; sessionId?: string; endUserId?: string; templateId?: string; templateVars?: Record<string, string> }) {
const res = await fetch(`${BASE}/chat`, {
method: 'POST',
headers: { ...this.headers, 'Content-Type': 'application/json' },
body: JSON.stringify(opts),
});
if (!res.ok) throw new Error(`BuildShip ${res.status}: ${await res.text()}`);
return res.json();
}
async process(filePath: string, prompt: string, opts?: { endUserId?: string; templateId?: string }) {
const form = new FormData();
form.append('file', fs.createReadStream(filePath));
form.append('prompt', prompt);
if (opts?.endUserId) form.append('endUserId', opts.endUserId);
if (opts?.templateId) form.append('templateId', opts.templateId);
const res = await fetch(`${BASE}/process`, {
method: 'POST',
headers: this.headers,
body: form as any,
});
if (!res.ok) throw new Error(`BuildShip ${res.status}: ${await res.text()}`);
return res.json();
}
async getSession(sessionId: string) {
const res = await fetch(`${BASE}/chat/${sessionId}`, { headers: this.headers });
if (!res.ok) throw new Error(`BuildShip ${res.status}`);
return res.json();
}
async listSessions(opts?: { endUserId?: string; limit?: number; offset?: number }) {
const qs = new URLSearchParams();
if (opts?.endUserId) qs.set('endUserId', opts.endUserId);
if (opts?.limit !== undefined) qs.set('limit', String(opts.limit));
if (opts?.offset !== undefined) qs.set('offset', String(opts.offset));
const res = await fetch(`${BASE}/chat/sessions?${qs}`, { headers: this.headers });
if (!res.ok) throw new Error(`BuildShip ${res.status}`);
return res.json();
}
async pollUntilDone(sessionId: string, maxWaitMs = 120_000) {
const start = Date.now();
while (Date.now() - start < maxWaitMs) {
const session = await this.getSession(sessionId);
if (session.status === 'completed' || session.status === 'failed') return session;
await new Promise(r => setTimeout(r, 2000));
}
throw new Error('Timeout aguardando IA');
}
}
```
### Uso
```ts
// src/index.ts
import { BuildShip } from './buildship-client';
const bs = new BuildShip();
async function main() {
// 1. Chat simples
const chat = await bs.chat({
message: 'Resuma este texto: Lorem ipsum...',
endUserId: 'user-123',
});
console.log('Sessao:', chat.sessionId);
// 2. Aguardar resultado (polling)
const result = await bs.pollUntilDone(chat.sessionId);
console.log('Resposta:', result.lastOutput);
// 3. Processar arquivo
const fileResult = await bs.process(
'./curriculo.pdf',
'Extraia nome, email e telefone',
{ endUserId: 'user-123' },
);
const cv = await bs.pollUntilDone(fileResult.sessionId);
console.log('CV:', cv.lastOutput);
}
main().catch(console.error);
```
### Com webhook (recomendado em producao)
```ts
// src/server.ts — receba callbacks do BuildShip
import express from 'express';
import crypto from 'crypto';
const app = express();
const SECRET = process.env.BUILDSHIP_WEBHOOK_SECRET!;
app.post('/buildship/callback',
express.raw({ type: 'application/json' }),
(req, res) => {
const sig = req.header('X-Buildship-Signature');
const expected = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
if (sig !== expected) return res.status(401).send('invalid signature');
const event = JSON.parse(req.body.toString());
switch (event.type) {
case 'completion':
console.log(`✓ session=${event.sessionId} output=${event.output.slice(0, 80)}`);
// Salva no DB, notifica usuario, etc
break;
case 'error':
console.error(`✗ session=${event.sessionId} error=${event.error}`);
break;
}
res.send('ok');
}
);
app.listen(3000, () => console.log('Webhook listener em :3000'));
```
---
## Python
### Setup
```bash
pip install requests python-dotenv
```
### Cliente completo
```python
# buildship_client.py
import os
import time
import requests
BASE = 'https://api.buildship.com.br/api/v1'
KEY = os.environ['BUILDSHIP_API_KEY']
HEADERS = {'X-API-Key': KEY}
class BuildShip:
def chat(self, message, session_id=None, end_user_id=None, template_id=None, template_vars=None):
body = {'message': message}
if session_id: body['sessionId'] = session_id
if end_user_id: body['endUserId'] = end_user_id
if template_id: body['templateId'] = template_id
if template_vars: body['templateVars'] = template_vars
r = requests.post(f'{BASE}/chat', headers={**HEADERS, 'Content-Type': 'application/json'}, json=body)
r.raise_for_status()
return r.json()
def process(self, file_path, prompt, end_user_id=None, template_id=None):
with open(file_path, 'rb') as f:
files = {'file': f}
data = {'prompt': prompt}
if end_user_id: data['endUserId'] = end_user_id
if template_id: data['templateId'] = template_id
r = requests.post(f'{BASE}/process', headers=HEADERS, files=files, data=data)
r.raise_for_status()
return r.json()
def get_session(self, session_id):
r = requests.get(f'{BASE}/chat/{session_id}', headers=HEADERS)
r.raise_for_status()
return r.json()
def list_sessions(self, end_user_id=None, limit=20, offset=0):
params = {'limit': limit, 'offset': offset}
if end_user_id: params['endUserId'] = end_user_id
r = requests.get(f'{BASE}/chat/sessions', headers=HEADERS, params=params)
r.raise_for_status()
return r.json()
def poll_until_done(self, session_id, max_wait=120):
start = time.time()
while time.time() - start < max_wait:
session = self.get_session(session_id)
if session['status'] in ('completed', 'failed'):
return session
time.sleep(2)
raise TimeoutError('IA nao terminou em ' + str(max_wait) + 's')
```
### Uso
```python
# main.py
from buildship_client import BuildShip
bs = BuildShip()
# 1. Chat
chat = bs.chat(message='Ola, IA!', end_user_id='user-123')
print('Sessao:', chat['sessionId'])
result = bs.poll_until_done(chat['sessionId'])
print('Resposta:', result['lastOutput'])
# 2. Processar arquivo
file_res = bs.process('./curriculo.pdf', 'Extraia nome, email, telefone')
cv = bs.poll_until_done(file_res['sessionId'])
print('CV:', cv['lastOutput'])
```
### Webhook listener (Flask)
```python
# webhook_server.py
import hmac
import hashlib
import os
from flask import Flask, request
app = Flask(__name__)
SECRET = os.environ['BUILDSHIP_WEBHOOK_SECRET']
@app.route('/buildship/callback', methods=['POST'])
def callback():
sig = request.headers.get('X-Buildship-Signature')
expected = hmac.new(SECRET.encode(), request.data, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig or '', expected):
return 'invalid signature', 401
event = request.json
if event['type'] == 'completion':
print(f"✓ session={event['sessionId']} output={event['output'][:80]}")
elif event['type'] == 'error':
print(f"✗ session={event['sessionId']} error={event.get('error')}")
return 'ok', 200
if __name__ == '__main__':
app.run(port=3000)
```
---
## Pipeline completo: extrator de CVs
Cenario: receber CVs de candidatos via webhook e extrair dados estruturados.
### 1. Criar template
```bash
curl -X POST https://api.buildship.com.br/api/v1/templates \
-H "X-API-Key: $BUILDSHIP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Extrator de CV v1",
"promptTemplate": "Extraia do curriculo:\n- Nome\n- Email\n- Telefone\n- Anos de experiencia em {{area}}\n- Educacao\n\nRetorne JSON valido com chaves: name, email, phone, experience_years, education.",
"variables": { "area": "engenharia de software" }
}'
```
→ Salva o `id` retornado (`tmpl_xyz`).
### 2. Endpoint que recebe upload + dispara processamento
```ts
// Recebe upload do candidato e dispara IA com webhook
import express from 'express';
import multer from 'multer';
import { BuildShip } from './buildship-client';
const app = express();
const upload = multer({ dest: '/tmp' });
const bs = new BuildShip();
app.post('/api/cv', upload.single('cv'), async (req, res) => {
const result = await bs.process(req.file!.path, '', {
templateId: 'tmpl_xyz',
endUserId: req.user.id,
});
res.json({ jobId: result.sessionId, status: 'processing' });
});
```
### 3. Webhook handler que persiste
```ts
app.post('/buildship/callback', validateSignature, async (req, res) => {
const event = JSON.parse(req.body.toString());
if (event.type !== 'completion') return res.send('ignored');
const cv = JSON.parse(event.output); // template retornou JSON
await db.candidates.upsert({
sessionId: event.sessionId,
userId: event.endUserId,
...cv,
});
res.send('ok');
});
```
Pronto — usuario faz upload, IA extrai dados, persiste no DB. Tudo async, sem polling.
---
## Mais exemplos
- [Templates avancados](/docs/api/templates)
- [Webhooks](/docs/api/webhooks)
- [Tratamento de erros](/docs/api/errors)
Quer integrar com ajuda da IA?
Copia esta pagina como .md e cola no ChatGPT/Claude — ela vai te guiar na integracao