API v1 · Guia
SDK e exemplos
Exemplos prontos em curl, Python, Node.js e n8n para criar contatos e negócios, e o SDK TypeScript.
Arquivos completos para copiar e rodar. Todos leem o token da variável de ambiente RUMO_TOKEN (crie em Configurações → API e integrações) e falam com o endereço de produção.
Exemplos prontos
curl
Cria um contato, abre um negócio, move de etapa e percorre a lista página por página.
exemplos.shPython (requests)
O mesmo fluxo com requests (Python 3.10 ou mais novo), repetindo em queda de conexão, 429, 502, 503 e 504 sem duplicar (Idempotency-Key).
exemplo.pyNode.js com o SDK
O mesmo fluxo com o SDK TypeScript: tipos, paginação e erros prontos.
exemplo.tsFluxo do n8n
Recebe o webhook contact.created, confere a Rumo-Signature e cria um negócio se o contato ainda não tem um no funil. Importe no n8n.
rumo-crm-contato-vira-negocio.json
SDK TypeScript
Prévia. O pacote @rumocrm/api ainda não está publicado no npm. Até lá, os exemplos em curl, Python e n8n funcionam sem ele.
- Sem dependências: usa o
fetchnativo do Node.js 20.3 ou mais novo. - É para servidor. A API não responde CORS, então uma página no navegador não consegue chamá-la, e token no navegador é token vazado. Chame do seu backend.
- Tipos de entrada e saída gerados da especificação OpenAPI.
listAll()percorre todas as páginas; erros chegam comoRumoApiErrorcomcodeerequestId.- Repete sozinho em queda de conexão (inclusive no meio da resposta), 408, 429, 502, 503 e 504, sempre com a mesma
Idempotency-Key: a nova tentativa nunca duplica um contato, negócio ou mensagem. Quando vemRetry-After(429 e503 server_busy), espera esse tempo. Um500numa escrita não é repetido (a API guarda esse 500 com a chave): confira com um GET antes de tentar com outra chave. A chave usada vem no erro e emidempotencyKeyOf(resultado). 503 queue_unavailableno envio de mensagem também não é repetido: a mensagem não saiu, mas cada tentativa pode ficar na conversa como mensagem com falha.idempotency_key_already_usedchega comoIdempotencyKeyAlreadyUsedError: a chave já foi usada e a API não guardou a resposta (grande demais, ou a empresa passou do total guardado nas últimas 24 horas). Nada rodou de novo.originalStatusdiz como a primeira vez terminou (2xx: a escrita rodou; 500: falhou). Consulte com GET antes de repetir com outra chave.webhookEndpoints.create()cadastra o endereço dos webhooks everifyWebhookSignature()confere aRumo-Signature, com o corpo de cada evento tipado.
// Cadastra um lead, abre um negócio no funil padrão, avança uma etapa e lista os negócios abertos.
// Rode com: RUMO_TOKEN=rumo_pat_... npx tsx exemplo.ts (Node 20.3+)
import { RateLimitError, RumoApiError, RumoCRM } from "@rumocrm/api";
const token = process.env.RUMO_TOKEN;
if (!token) throw new Error("Defina RUMO_TOKEN com um token criado em Configurações → API e integrações.");
const rumo = new RumoCRM({ token }); // endereço padrão: https://rumocrm.com/api/v1
async function main() {
// Upsert: o mesmo telefone (ou e-mail) devolve o mesmo contato. Só com nome, cria sempre.
const contato = await rumo.contacts.upsert({ name: "Maria Souza", phone: "(15) 99807-3400", tags: ["site"] });
const { data: funis } = await rumo.pipelines.list();
const funil = funis.find((f) => f.isDefault) ?? funis[0];
const { data: etapas } = await rumo.pipelines.listStages(funil.id);
// valueCents: dinheiro em centavos (R$ 1.500,00).
const negocio = await rumo.deals.create({
title: `Proposta - ${contato.name}`,
pipelineId: funil.id,
contactId: contato.id,
valueCents: 150000,
});
const segundaEtapa = etapas.filter((etapa) => etapa.type === "open")[1];
if (segundaEtapa) await rumo.deals.move(negocio.id, { stageId: segundaEtapa.id });
// Percorre todas as páginas sozinho (nextCursor/hasMore).
for await (const aberto of rumo.deals.listAll({ pipelineId: funil.id, status: "open" })) {
console.log(aberto.title, aberto.valueCents === null ? "sem valor" : aberto.valueCents / 100);
}
}
main().catch((erro: unknown) => {
if (erro instanceof RateLimitError) console.error(`Limite atingido; tente em ${erro.retryAfter ?? "?"} s`);
else if (erro instanceof RumoApiError) console.error(erro.status, erro.code, erro.message, erro.requestId);
else console.error(erro);
process.exitCode = 1;
});