Agentes de IA

O Emitti é desenhado para ser operado por agentes de IA. Como a API é JSON limpa e os erros são traduzidos, um LLM consegue montar o payload e emitir uma nota com confiança — via tool calling ou via um servidor MCP pronto.

Há um arquivo /llms.txt na raiz para que agentes descubram esta documentação automaticamente.

Tool calling (function calling)

Exponha o Emitti como uma ferramenta para o seu modelo. A definição abaixo segue o formato de tool da API da Anthropic (name, description, input_schema):

{
  "name": "emitir_nfse",
  "description": "Emite uma Nota Fiscal de Serviço (NFS-e) no Brasil. Use quando o usuário pedir para emitir/gerar uma nota de serviço.",
  "input_schema": {
    "type": "object",
    "properties": {
      "prestador": {
        "type": "object",
        "properties": {
          "cnpj": { "type": "string" },
          "inscricao_municipal": { "type": "string" }
        },
        "required": ["cnpj", "inscricao_municipal"]
      },
      "tomador": {
        "type": "object",
        "properties": {
          "razao_social": { "type": "string" },
          "cnpj": { "type": "string" },
          "cpf": { "type": "string" }
        }
      },
      "servico": {
        "type": "object",
        "properties": {
          "codigo_municipio": { "type": "string" },
          "codigo_servico": { "type": "string" },
          "discriminacao": { "type": "string" },
          "valor_servicos": { "type": "number" },
          "aliquota_iss": { "type": "number" }
        },
        "required": ["codigo_municipio", "codigo_servico", "discriminacao", "valor_servicos", "aliquota_iss"]
      }
    },
    "required": ["prestador", "tomador", "servico"]
  }
}

Loop com Claude (Node.js)

O modelo monta o JSON da nota a partir do pedido em linguagem natural; seu código apenas executa o POST /v1/nfse e devolve o resultado:

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

const tools = [/* a definição de emitir_nfse acima */];
let messages = [{
  role: "user",
  content: "Emita uma NFS-e de R$ 499,90 (assinatura SaaS) do meu CNPJ 12345678000190 / IM 1122334 para o Cliente X (CNPJ 98765432000110), em São Paulo, código de serviço 01.05, ISS 2%.",
}];

while (true) {
  const res = await client.messages.create({
    model: "claude-opus-4-8",
    max_tokens: 16000,
    tools,
    messages,
  });
  if (res.stop_reason !== "tool_use") { console.log(res.content); break; }

  messages.push({ role: "assistant", content: res.content });
  const results = [];
  for (const block of res.content) {
    if (block.type !== "tool_use") continue;
    // Claude montou o payload; você só executa a chamada ao Emitti
    const r = await fetch("https://api.emitti.com.br/v1/nfse", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + process.env.EMITTI_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(block.input),
    });
    results.push({ type: "tool_result", tool_use_id: block.id, content: await r.text() });
  }
  messages.push({ role: "user", content: results });
}

Use o modelo mais capaz disponível (ex.: claude-opus-4-8). A nota é assíncrona: o 202 traz o emissao_id; confirme o resultado por webhook ou GET /v1/nfse/{id}.

MCP (Model Context Protocol)

Para assistentes que falam MCP (Claude Desktop, Claude Code), o Emitti oferece um servidor MCP que expõe as tools emitir_nfse e consultar_nfse. O assistente passa a emitir notas em linguagem natural, sem você escrever o loop de tool calling.

Servidor de referência

Código aberto e pronto para rodar em examples/mcp-emitti (TypeScript, stdio). Build:

cd examples/mcp-emitti
npm install && npm run build

Configurar no Claude Desktop

No claude_desktop_config.json:

{
  "mcpServers": {
    "emitti": {
      "command": "node",
      "args": ["/caminho/para/emitti-mcp/dist/index.js"],
      "env": { "EMITTI_API_KEY": "sk_live_..." }
    }
  }
}

Configurar no Claude Code

# Claude Code — adicionar o servidor MCP do Emitti
claude mcp add emitti --env EMITTI_API_KEY=sk_live_... \
  -- node /caminho/para/emitti-mcp/dist/index.js

🔒 A API key fica na configuração do MCP (variável EMITTI_API_KEY), do lado do cliente — nunca no prompt nem no histórico do modelo.

Veja também a referência completa da API.