API de integração

Papéis, preços, perfis e cálculos de produção.

Conectar um sistema

  1. Entre como administrador em Usuários e API.
  2. Cadastre o usuário responsável, se necessário. Na lista, clique em Vincular token.
  3. Informe o nome da conexão, a permissão e a validade. Gere e copie o token, exibido apenas nessa criação.
  4. No servidor da integração, guarde o token como segredo e envie Authorization: Bearer SEU_TOKEN.

URL base: https://calculadora-tubos.krato.ai/api/v1

Leitura permite consultar dados e calcular prévias sem salvar. Leitura e gravação permite também cadastrar e atualizar papéis, perfis, preços e produções. Os dados são compartilhados pela empresa.

O token vence após o prazo escolhido (1 a 365 dias). Revogação, desativação do usuário, redefinição de senha ou mudança de permissão invalidam o acesso. A troca de token é feita gerando outro e revogando o anterior.

curl "https://calculadora-tubos.krato.ai/api/v1/compositions?page=1" \
  -H "Authorization: Bearer $TUBE_API_TOKEN"

Exemplo de terminal Linux/macOS. Configure TUBE_API_TOKEN no ambiente da integração. Não coloque o token no código público, na URL ou no JavaScript de uma página.

Operações disponíveis

MétodoEndpoint após /api/v1Operação
GET / POST/papersListar / cadastrar papéis
GET / PATCH/papers/{id}Consultar / alterar um papel
GET / POST/papers/{id}/pricesConsultar histórico / cadastrar preço por kg
GET / POST/compositionsListar / cadastrar perfis
GET / PATCH/compositions/{id}Consultar revisão atual / arquivar ou reativar perfil
GET / POST/compositions/{id}/revisionsListar / salvar revisões
GET/compositions/{id}/revisions/{revisionId}Consultar revisão histórica
POST/compositions/{id}/duplicateDuplicar perfil com novo código e nome
POST/calculations/previewCalcular peso, papel e custo sem gravar
GET / POST/revisions/{revisionId}/calculationsListar / calcular e salvar produções
GET/calculations/{id}Consultar resultado salvo

O contrato OpenAPI 3.1 contém os corpos de requisição, respostas e as 30 operações, incluindo saúde, sessão e administração. Pode ser importado no Postman ou Insomnia.

Calcular um perfil salvo — exemplo Node.js

O exemplo consulta o perfil e usa seus materiais históricos para calcular um lote de 100 tubos com 1.000 mm. Configure as variáveis de ambiente TUBE_API_TOKEN e TUBE_PROFILE_ID.

const base = 'https://calculadora-tubos.krato.ai/api/v1';
const token = process.env.TUBE_API_TOKEN;
const profileId = process.env.TUBE_PROFILE_ID;
if (!token || !profileId) throw new Error('Configure token e ID do perfil.');

async function api(path, body) {
  const response = await fetch(base + path, {
    method: body ? 'POST' : 'GET',
    headers: {
      Authorization: `Bearer ${token}`,
      ...(body ? {'Content-Type': 'application/json'} : {})
    },
    body: body ? JSON.stringify(body) : undefined
  });
  const data = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${data.message}`);
  return data;
}

const profile = await api(`/compositions/${profileId}`);
const production = {lengthMm: 1000, quantity: 100};
const result = await api('/calculations/preview', {
  diMm: profile.diMm,
  targetWallMm: profile.targetWallMm,
  sourceRevisionId: profile.id,
  items: profile.items.map(item => ({
    paperId: item.paperId,
    sourceItemId: item.id,
    count: item.count,
    widthMm: item.widthMm,
    wastePct: item.wastePct
  })),
  production
});
console.log({
  pesoPorTuboKg: result.perTube.weightKg,
  papelDoLoteComPerdaKg: result.batch.weightWithWasteKg,
  custoPorTubo: result.perTube.cost,
  custoDoLote: result.batch.cost
});

// Para gravar, use um token com permissão de gravação:
// const saved = await api(`/revisions/${profile.id}/calculations`, production);
// console.log(saved.id, saved.results.batch.cost);

profile.id é o ID da revisão retornada; profile.compositionId é o ID do perfil. Ambos são diferentes. Para localizar um perfil, consulte GET /compositions?q=LEVE.

Cadastrar papel e montar o perfil

Envie este JSON em POST /papers:

{
  "code": "MEU-PAPEL-350",
  "name": "Papel 350",
  "grammage": 350,
  "tp": 0.53,
  "widthMm": 100,
  "wastePct": 5,
  "pricePerKg": 4
}

Use id, version e priceId da resposta ao cadastrar POST /compositions:

{
  "code": "MEU-TUBO-2POL",
  "name": "Tubo 2 polegadas",
  "diMm": 50.8,
  "targetWallMm": 4,
  "items": [{
    "paperId": "ID_DO_PAPEL",
    "expectedPaperVersion": 1,
    "expectedPriceId": "PRICE_ID_DA_RESPOSTA",
    "count": 8,
    "widthMm": 100,
    "wastePct": 5
  }]
}

Inclua mais itens para combinar papéis e gramaturas. A espessura efetiva é a soma das camadas: no exemplo, 8 × 0,53 = 4,24 mm. O alvo de 4 mm não altera automaticamente as camadas.

Para alterar preço, envie {"expectedVersion": VERSAO_ATUAL, "pricePerKg": 4} em POST /papers/{id}/prices. Perfis já salvos preservam seus preços: atualize explicitamente os materiais em uma nova revisão para usar os preços atuais.

Regras para integrar corretamente

Administração de acessos

GET/POST /users, PATCH /users/{id}, POST /users/{id}/password, GET/POST /tokens e DELETE /tokens/{id} exigem sessão de administrador. Tokens não acessam esses endpoints.

Usuários não são excluídos, para preservar a autoria dos cadastros. O sistema impede a desativação ou rebaixamento do último administrador ativo.