Cookbook

Receitas

Soluções prontas para cenários comuns. Diferente dos guides (que ensinam conceitos), receitas são "como fazer X no menor número de chamadas".

Criar lead a partir do seu formulário externo

Problema: Seu site tem um form custom (não landing page do MIX). Você quer enviar o submit pra API e criar uma pessoa.

TypeScript

// No backend que processa o form:
const res = await fetch("https://api.usemix.app/api/v1/people", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MIX_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fullName: form.nome,
    primaryEmail: form.email,
    primaryPhone: form.telefone,
    leadSource: "site-form",
  }),
});

if (res.status === 409) {
  // E-mail duplicado. A v1 atual não filtra GET /people por e-mail —
  // pra atualizar quem já existe, prefira webhooks de entrada com
  // dedup automático.
  console.warn("Pessoa já existe; use webhook inbound com dedup.");
}

Nota: Pra fluxos com chance alta de duplicatas, use **webhooks de entrada** com dedup por email — o servidor faz upsert automático e simplifica seu código.

Mover um deal pra ganho quando algo externo acontece

Problema: Cliente pagou via Mercado Pago / Stripe / PIX. Você quer marcar o deal correspondente como ganho.

TypeScript

// 1. Você precisa do dealId armazenado no seu sistema externo
//    (ex.: salvou quando criou o link de pagamento).
const dealId = mapPaymentToDeal(paymentId);
if (!dealId) return;

// 2. Mova pro stage 'won' (precisa do stageId 'won' do pipeline,
//    armazenado em config — a v1 não expõe /pipelines).
await fetch(`https://api.usemix.app/api/v1/deals/${dealId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    stageId: "<id-do-stage-won-do-seu-pipeline>",
  }),
});

Nota: O webhook `deal.won` será disparado automaticamente quando o stage virar `won`. Cache `pipelineId` e `stageId` na sua infra — eles raramente mudam.

Reagir a `deal.won` em tempo real

Problema: Quando um deal é ganho, você quer disparar onboarding interno (criar conta, enviar contrato, etc.).

TypeScript

// Em um endpoint público no seu servidor:
import crypto from "node:crypto";
const SECRET = process.env.MANU_WEBHOOK_SECRET!;

app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const sig = req.header("x-manu-signature") ?? "";
  if (!verifyHmac(req.body.toString("utf8"), sig)) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.type !== "deal.won") return res.status(200).end();

  // Busque os detalhes do deal pra obter valor, pessoa, etc.
  const deal = await fetch(
    `https://api.usemix.app/api/v1/deals/${event.data.dealId}`,
    { headers: { Authorization: `Bearer ${TOKEN}` } },
  ).then(r => r.json());

  await provisionarOnboarding(deal);
  res.status(200).end();
});

Nota: Eventos chegam ao menos uma vez — sempre dedupe por `event.id`. Veja [Segurança HMAC](/developers/webhooks/security) pra o `verifyHmac` completo.

Adicionar tag a um lote de pessoas

Problema: Você quer marcar pessoas específicas com uma tag.

Python

import os, requests

TOKEN = os.environ["MIX_TOKEN"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
BASE = "https://api.usemix.app/api/v1"

# Lista os IDs que você quer marcar (puxados de outro sistema, CSV, etc.)
people_ids = ["1f0c...", "2a4b...", "..."]

for pid in people_ids:
    # Lê os tags atuais
    p = requests.get(f"{BASE}/people/{pid}", headers=HEADERS).json()
    new_tags = list(set((p.get("tags") or []) + ["campanha-q2-2026"]))

    requests.patch(
        f"{BASE}/people/{pid}",
        json={"tags": new_tags},
        headers=HEADERS,
    )

Nota: Throttle pra ~5 req/s pra ficar bem abaixo do limite de 300/min. Pra >1000 itens, considere automações no-code do app web (executadas no servidor, sem rate limit local).

Criar deal já vinculado à pessoa

Problema: Você acabou de criar uma pessoa e quer criar um deal pra ela na hora.

TypeScript

const person = await fetch("https://api.usemix.app/api/v1/people", {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ fullName: "João", primaryEmail: "joao@x.com" }),
}).then(r => r.json());

const deal = await fetch("https://api.usemix.app/api/v1/deals", {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    title: `Deal - ${person.fullName}`,
    value: 1000,
    pipelineId: PIPELINE_ID,    // armazenado em config — v1 não expõe /pipelines
    stageId: FIRST_STAGE_ID,    // idem
    primaryPersonId: person.id,
  }),
}).then(r => r.json());

Nota: Cache `pipelineId` e `stageId` no seu serviço. A v1 atual não expõe `/pipelines`; pegue os IDs no app web (Configurações → Pipelines) ao configurar a integração.