Quickstart

Faça sua primeira chamada à API do MIXY CRM em 5 minutos. Crie um token, liste pessoas e registre um novo deal.

Esse guia leva você do zero ao primeiro deal criado via API em menos de 5 minutos. Você vai precisar de uma conta no MIXY CRM com permissão de admin no workspace (apenas admins podem criar API tokens).

1. Crie um API token

No app, vá em Configurações → API Tokens e clique em Novo token.

Preencha:

• Nome: descrição do uso (ex.: n8n production, meu-app-staging). Aparece no audit log; faça-o reconhecível.
• Scope: comece com read_write para o quickstart. Mais tarde, refine para scopes granulares (crm:person:read, crm:deal:write, etc.) — veja o guia de Autenticação.
• Expiração (opcional): tokens sem expiração não são recomendados em produção.

O token aparece uma única vez e tem o formato manu_<base64url-32-bytes>. Copie imediatamente — depois de fechar o modal, só o prefixo (primeiros 12 caracteres) fica visível.

2. Liste suas pessoas

Vamos confirmar que o token funciona listando as pessoas do CRM:

curl https://api.mixycrm.com.br/api/v1/people?pageSize=5 \
  -H "Authorization: Bearer manu_seu_token_aqui"

Resposta (resumida):

{
  "data": [
    {
      "id": "ad8e3f9b-...",
      "fullName": "Marina Souza",
      "primaryEmail": "marina@acme.com.br",
      "primaryPhone": "+5511999999999",
      "lifecycleStage": "lead",
      "leadSource": "form-site",
      "ownerId": "1f0c...",
      "companyId": null,
      "createdAt": "2026-04-12T14:33:00Z",
      "updatedAt": "2026-04-30T09:12:00Z"
    }
  ],
  "page": 1,
  "pageSize": 5,
  "total": 142,
  "hasMore": true
}

Se você recebeu um erro 401, verifique o token. 403 indica scope insuficiente. 429 indica que você passou do rate limit (300 req/min).

3. Crie uma pessoa

Vamos cadastrar um novo lead:

curl -X POST https://api.mixycrm.com.br/api/v1/people \
  -H "Authorization: Bearer manu_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "João Pereira",
    "primaryEmail": "joao@startup.com.br",
    "primaryPhone": "+5511988887777",
    "leadSource": "api",
    "lifecycleStage": "lead"
  }'

Você recebe 201 Created com o objeto criado, incluindo o id gerado. Guarde esse id — vamos usar no próximo passo.

4. Crie um deal pra ela

Negócios (deals) vivem dentro de um pipeline com stages. A v1 atual ainda não expõe /pipelines na API pública — pegue o pipelineId e o stageId do estágio inicial direto da URL no app web (ou copie da lista em Configurações → Pipelines) e armazene como configuração da sua integração.

curl -X POST https://api.mixycrm.com.br/api/v1/deals \
  -H "Authorization: Bearer manu_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implantação - Startup Inc",
    "value": 24000.00,
    "currency": "BRL",
    "pipelineId": "<pipeline-id>",
    "stageId": "<stage-id>",
    "primaryPersonId": "<id-da-pessoa-do-passo-3>",
    "expectedCloseDate": "2026-06-30"
  }'

Pronto. Abra o app web e o deal já está lá, no pipeline, com a pessoa ligada. Foi seu primeiro deal via API.

5. Próximos passos

Você acabou de fazer o trio essencial: autenticar, ler, escrever. Agora:

• Aprenda os padrões de paginação pra puxar grandes volumes sem timeout.
• Configure webhooks pra ser avisado quando o deal for ganho (deal.won) — sem precisar pollar.
• Explore a API Reference completa — todos os endpoints, campos e formatos.
• Se você está construindo um app pra distribuir, leia Construir um app e publique no marketplace.