Integrations

Escopo: transversal. Aplica-se a qualquer linguagem ou stack do projeto.

Um sistema em produção troca dados em vários formatos. O JSON (JavaScript Object Notation · Notação de Objetos JavaScript) sobre HTTP (HyperText Transfer Protocol · Protocolo de Transferência de Hipertexto) cobre a API (Application Programming Interface · Interface de Programação de Aplicações) do seu produto, e o resto chega em outro formato.

É o arquivo que configura a ferramenta, o XML assinado que a Receita exige, o arquivo de retorno do banco, a etiqueta que a impressora térmica imprime, os bytes que a balança envia pela porta serial. Este guia cobre os formatos e protocolos mais comuns, dos modernos aos legados, e o cuidado que cada um exige.

Um grafo (graph) é uma estrutura de dados formada por entidades chamadas nós (nodes) e pelas conexões entre elas, chamadas arestas (edges). Os dados de um sistema real formam um grafo por conta própria: um pedido pertence a um cliente, que tem endereços, que têm cidades, que têm países.

Pedido
  ├─→ Cliente  → Endereço → Cidade → País
  └─→ Itens    → Produto  → Categoria

GraphQL tira o nome daí. Em vez de expor recursos isolados como /orders e /customers, ele expõe o grafo inteiro, e o cliente descreve em uma única consulta o caminho que quer percorrer.

GraphQL é uma linguagem de consulta que roda sobre a sua API. O banco continua o mesmo, com o mesmo schema. O que muda é quem escolhe os campos da resposta: o cliente pede a lista exata e o servidor devolve só aqueles campos. Isso elimina o over-fetching (trazer campos que ninguém vai usar) e o under-fetching (trazer menos do que a tela precisa, o que obriga a uma segunda chamada).

query {
  order(id: "123") {
    id
    status
    customer {
      name
      email
    }
  }
}

Quando considerar GraphQL:

Quando não usar:

A evolução do schema também funciona de um jeito próprio. Onde o REST publica uma /v2, o GraphQL soma o campo novo e marca o antigo como deprecated; quem consome escolhe quando parar de pedir o campo velho. Se o que você quer é apenas uma leitura com filtro grande, sem trocar de paradigma, o verbo QUERY resolve dentro do envelope REST: veja api-design.md.

O erro mais caro em query grande é buscar a lista inteira e filtrar um item no cliente: a rede transporta todos os registros e o navegador descarta quase todos. Declarar a variável na query move o filtro para o servidor, que devolve apenas o item pedido.

Os exemplos abaixo usam a Countries API, uma API GraphQL pública.

_{Exemplo de grafo: cada nó representa um tipo de dado, cada aresta representa uma relação entre eles.}

const response = await fetch("https://countries.trevorblades.com/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: `{ countries { code name capital currency languages { code name native } continent { code name } states { code name } } }`,
  }),
});

const json = await response.json();
const country = json.data.countries.find((c) => c.code === "BR");

const GET_COUNTRY = `
  query GetCountry($code: ID!) {
    country(code: $code) {
      name
      capital
      currency

      languages {
        name
      }

      continent {
        name
      }
    }
  }
`;

async function fetchCountry(code) {
  const response = await fetch("https://countries.trevorblades.com/", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: GET_COUNTRY,
      variables: { code },
    }),
  });

  const { data, errors } = await response.json();
  const [firstError] = errors ?? [];
  if (firstError) throw new Error(firstError.message);

  const country = data.country;
  return country;
}

Escolha TOML quando a configuração for plana e os tipos importarem. A sintaxe delimita com = e [seção], e um espaço a mais ou a menos não muda o significado do arquivo. Essa é a diferença prática para o YAML no dia a dia.

# config.toml
[database]
host = "localhost"
port = 5432
name = "app_db"

[server]
port = 8080
timeout = 30

[features]
maintenance_mode = false

Comum em: Cargo.toml (Rust), pyproject.toml (Python), configurações de ferramentas CLI.

YAML domina a configuração de infraestrutura: pipelines de CI/CD (Continuous Integration/Continuous Delivery · Integração e Entrega Contínuas), Kubernetes, Docker Compose e ferramentas de automação. A indentação expressa a hierarquia, o que deixa o arquivo enxuto e frágil: um tab no lugar de um espaço quebra o parse sem mensagem clara.

# docker-compose.yml
services:
  api:
    image: app:latest
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://localhost/app_db

Armadilhas comuns:

Formatos e protocolos anteriores ao JSON e ao REST, ainda em uso: eles sustentam a integração fiscal, a bancária, a industrial e a de hardware periférico.

Os WebServices SOAP são o padrão de integração dos sistemas fiscais brasileiros (NF-e, CT-e, NFS-e) e dos sistemas corporativos antigos. A mensagem viaja dentro de um SOAP Envelope (envelope SOAP), um XML (eXtensible Markup Language · Linguagem de Marcação Extensível) de estrutura fixa, e o contrato do serviço vem descrito em um arquivo WSDL.

O erro mais comum é navegar o XML sem levar os namespaces em conta. O documento da NF-e usa o namespace http://www.portalfiscal.inf.br/nfe, e buscar a tag sem informar esse namespace devolve nulo, sem erro e sem pista. Em Node.js, a biblioteca @xmldom/xmldom oferece um DOMParser que entende namespace.

import { DOMParser } from "@xmldom/xmldom";

const doc = new DOMParser().parseFromString(xml, "text/xml");

// sem namespace: não encontra o nó em documento fiscal com prefixo nfe:
const invoiceNumber = doc.getElementsByTagName("nNF")[0].textContent;

import { DOMParser } from "@xmldom/xmldom";

const NS = "http://www.portalfiscal.inf.br/nfe";

function extractInvoiceNumber(xml) {
  const doc = new DOMParser().parseFromString(xml, "text/xml");

  const ide = doc.getElementsByTagNameNS(NS, "ide")[0];
  const invoiceNumber =
    ide?.getElementsByTagNameNS(NS, "nNF")[0]?.textContent ?? null;

  const hasInvoiceNumber = invoiceNumber !== null;
  if (!hasInvoiceNumber)
    throw new ValidationError({ message: "Invoice number not found in XML." });

  return invoiceNumber;
}

Boas práticas ao consumir WebServices SOAP:

A integração bancária (CNAB), a obrigação fiscal (SPED), a exportação de ERP e a troca entre sistemas antigos usam arquivo de texto, com layout fixo ou delimitado. O risco está nos números soltos: a posição e o índice do campo espalhados pelo código. Quando o banco muda o layout, o código continua lendo e entrega o dado errado, sem nenhum erro visível.

O arquivo SPED usa pipe como separador, e cada linha começa com o tipo do registro (|0000|, |C100|).

const fields = line.replace(/^\||\|$/g, "").split("|");

const companyRegistrationNumber = fields[6]; // CNPJ
const companyName = fields[5];
const periodStart = fields[3];

function parseRecord0000(line) {
  const fields = line.replace(/^\||\|$/g, "").split("|");

  const record = {
    periodStart: fields[3],
    periodEnd: fields[4],
    companyName: fields[5],
    companyRegistrationNumber: fields[6], // CNPJ
  };

  return record;
}

O arquivo CNAB (240 ou 400 caracteres por linha) define cada campo por posição e comprimento. Declare os dois juntos, em um objeto de layout que dá para conferir linha a linha contra o manual do banco.

const bankCode = line.slice(0, 3);
const serviceBatch = line.slice(3, 7);
const recordType = line.slice(7, 8);
const companyRegistrationNumber = line.slice(18, 32); // CNPJ

const CNAB240_HEADER = {
  bankCode: { pos: 0, len: 3 },
  serviceBatch: { pos: 3, len: 4 },
  recordType: { pos: 7, len: 1 },
  companyRegistrationNumber: { pos: 18, len: 14 }, // CNPJ
};

function extractField(line, { pos, len }) {
  const field = line.slice(pos, pos + len);
  return field;
}

const bankCode = extractField(line, CNAB240_HEADER.bankCode);
const companyRegistrationNumber = extractField(
  line,
  CNAB240_HEADER.companyRegistrationNumber,
); // CNPJ

Boas práticas para arquivos de texto:

A impressora Zebra usa ZPL como protocolo nativo. Cada etiqueta é um pequeno programa ZPL, enviado como texto puro pela porta serial, por USB ou por TCP/IP na porta 9100. No caso do TCP, abrir um socket para ip:9100 e escrever a string já imprime, sem nenhum driver instalado.

Estrutura mínima de uma etiqueta ZPL:

^XA              ; início do label
^FO50,50         ; posição de origem (x, y em pontos)
^A0N,30,30       ; fonte, altura, largura
^FDTexto^FS      ; conteúdo do campo
^XZ              ; fim do label

const zpl =
  "^XA^FO50,50^A0N,30,30^FD" +
  product.name +
  "^FS" +
  "^FO50,100^BCN,80,Y,N,N^FD" +
  product.barcode +
  "^FS" +
  "^FO50,200^A0N,20,20^FDLote: " +
  product.lot +
  "^FS^XZ";

port.write(zpl);

function buildProductLabel({ name: productName, barcode, lot: lotNumber }) {
  const label = [
    "^XA",
    `^FO50,50^A0N,30,30^FD${productName}^FS`,
    `^FO50,100^BCN,80,Y,N,N^FD${barcode}^FS`,
    `^FO50,200^A0N,20,20^FDLote: ${lotNumber}^FS`,
    "^XZ",
  ].join("\n");

  return label;
}

const label = buildProductLabel(product);
port.write(label);

Principais comandos ZPL:

Balança, catraca, leitor de código de barras antigo e equipamento industrial se comunicam pela porta serial RS-232. Em Node.js, o pacote serialport entrega a leitura como um stream de eventos. Sem timeout configurado, o equipamento que não responde deixa o processo esperando para sempre.

import { SerialPort } from "serialport";
import { ReadlineParser } from "@serialport/parser-readline";

const port = new SerialPort({ path: "COM3", baudRate: 9600 });
const parser = port.pipe(new ReadlineParser({ delimiter: "\r\n" }));

parser.on("data", (rawLine) => {
  const weight = parseWeight(rawLine);
});

import { SerialPort } from "serialport";
import { ReadlineParser } from "@serialport/parser-readline";

function readWeight(path = "COM3") {
  const weightReading = new Promise((resolve, reject) => {
    const port = new SerialPort({ path, baudRate: 9600 });
    const parser = port.pipe(new ReadlineParser({ delimiter: "\r\n" }));

    const responseTimeout = setTimeout(() => {
      port.close();
      reject(new Error("Balança não respondeu no tempo esperado."));
    }, 2000);

    parser.once("data", (rawLine) => {
      clearTimeout(responseTimeout);
      port.close();

      const weight = parseWeight(rawLine);
      resolve(weight);
    });

    port.on("error", (serialError) => {
      clearTimeout(responseTimeout);
      reject(serialError);
    });
  });

  return weightReading;
}

Parâmetros comuns de configuração serial:

RTS (Ready to Send · Pronto para Enviar) e CTS (Clear to Send · Livre para Enviar) são sinais de controle de fluxo feitos em hardware. O dispositivo ativa a linha RTS para avisar que quer transmitir, e o receptor responde com CTS quando está pronto para receber. Sem esse handshake, o equipamento lento perde bytes durante a transmissão.

Boas práticas:

A API de um modelo de linguagem é REST com JSON, como qualquer outra, e tem três características próprias: a cobrança acontece por token, a resposta chega em pedaços por streaming e o provedor impõe um teto de chamadas por minuto. Ignorar esses três pontos gera custo desnecessário, uma UX (User Experience · Experiência do Usuário) lenta e falhas em produção.

A API key (chave da API) fica fora do código. A aplicação lê a chave de uma variável de ambiente na inicialização.

const client = new Anthropic({ apiKey: "sk-ant-..." });

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

Ver security.md para gestão de segredos.

O modelo produz a resposta token a token, e o streaming entrega cada pedaço assim que ele sai. Sem streaming, o cliente espera a resposta inteira antes de renderizar, o que deixa a tela parada por dezenas de segundos em textos longos. Com streaming, a primeira palavra aparece em milissegundos.

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: prompt }],
});

console.log(message.content[0].text);

const stream = client.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: prompt }],
});

for await (const chunk of stream) {
  if (chunk.type === "content_block_delta") {
    process.stdout.write(chunk.delta.text);
  }
}

A API de LLM (Large Language Model · Modelo de Linguagem de Grande Escala) impõe um teto por minuto, contado em requisições (RPM) e em tokens (TPM). Passar do teto devolve 429 Too Many Requests, e isso acontece em produção com tráfego normal. Trate o 429 como parte do fluxo: espere e tente de novo, dobrando a espera a cada tentativa (exponential backoff · recuo exponencial), para não aumentar a carga sobre um serviço que já está no limite.

const response = await fetch(apiUrl, options);

if (!response.ok) {
  throw new Error("API error");
}

async function callWithRetry(requestFn, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const response = await requestFn();

    if (response.status !== 429) {
      return response;
    }

    const delayMs = Math.pow(2, attempt) * 1000;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error("Rate limit exceeded after retries");
}

O contrato estável é o que torna essa integração barata. Com um envelope único, um error.code previsível e o traceId em toda resposta (repetido no cabeçalho X-Trace-Id), toda ferramenta de observabilidade e de alerta lê os mesmos campos, e nenhuma rota precisa de adaptação própria.

Quem produz esses campos é a biblioteca de log estruturado da sua stack: Serilog no .NET, Pino ou Winston no Node.js. Ela emite o log em JSON, com o traceId e o error.code em cada linha, e envia esse log ao destino por um sink (saída configurável do log). Trocar o destino é mudar configuração, sem tocar no código que loga. Quem consome está na tabela abaixo.

Esses são os nomes mais comuns, e qualquer outra plataforma entra pelo mesmo caminho, porque o que ela consome é o contrato. O percurso do traceId, da resposta até a linha de log, está em observability.md.

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.