Exemplos completos

Codigo Node.js e Python pronto pra copiar — clientes completos com retry, webhooks e pipelines reais.

Copiar como .md

Codigo pronto pra copiar — copie o .md desta pagina e cole na sua IA pra ela te ajudar a integrar.

Node.js / TypeScript

Setup

npm install node-fetch form-data dotenv

.env:

BUILDSHIP_API_KEY=bld_sua_chave_aqui
BUILDSHIP_WEBHOOK_SECRET=seu_secret_webhook

Cliente completo

// 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}/sessions/${sessionId}`, { 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

// 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)

// 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

pip install requests python-dotenv

Cliente completo

# 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}/sessions/{session_id}', headers=HEADERS)
        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

# 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)

# 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

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

// 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

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
• Webhooks
• Tratamento de erros