Integre pela API v1

Base: https://seu-crm/api/v1. Gere uma chave em Configurações → Chaves de API e envie Authorization: Bearer legame_.... Use uma chave por integração; guarde-a no servidor da integração.

A chave herda as permissões e a visibilidade dos perfis ativos atribuídos ao usuário que a criou. Configure recursos, pipelines e etapas no mesmo editor de perfis, em Equipe → Perfis e permissões. Uma chave de um usuário desativado é rejeitada. Acesso exige simultaneamente escopo, permissão do recurso e visibilidade do pipeline/etapa.

Rotas e escopos

Os escopos de escrita não concedem criação/edição de contatos ao usuário: confira também as permissões Contatos → Criar/Editar. Quem apenas vincula um contato existente pode informar somente seu id.

Criar um negócio com vários clientes

curl 'https://seu-crm/api/v1/negocios' \
  -H 'Authorization: Bearer SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: formulario-familia-0001' \
  --data '{
    "titulo": "Cidadania — Família Silva",
    "valor": 9000,
    "coluna_id": 12,
    "clientes": [
      {"nome": "Maria Silva", "email": "maria@example.com", "referencia_externa": "contato-001", "papel_no_negocio": "principal"},
      {"nome": "João Silva", "email": "joao@example.com", "papel_no_negocio": "contato"},
      {"id": 45, "papel_no_negocio": "financeiro"}
    ],
    "campos_personalizados": {"servico": "Cidadania italiana"}
  }'

Use IDs reais da sua instalação. Descubra pipelines e etapas com /objetos?tipo=pipeline e /objetos?tipo=coluna&pipeline_id=.... As chaves dos campos personalizados precisam existir no cadastro; consulte /objetos?tipo=campo_personalizado&entidade_tipo=negocio.

Há um contato principal. Se nenhum for marcado, será o primeiro. Papéis aceitos: principal, contato, financeiro, representante. Uma mesma pessoa pode estar vinculada a vários negócios. Contatos repetidos no mesmo negócio são vinculados uma vez.

Para um contato novo, informe nome e pelo menos e-mail, telefone ou referência externa. Identificadores conflitantes de pessoas diferentes retornam 409; a API não faz uma unificação automática. IDs inválidos retornam 404. Se qualquer contato ou validação falhar, nenhum contato/negócio dessa requisição fica parcialmente cadastrado.

Também continuam aceitos o formato anterior cliente: {...}, os campos de contato na raiz, pipeline_id ou pipeline (nome). Prefira coluna_id para escolher uma etapa exata. Se não informar destino, a API usa a primeira etapa ativa disponível para aquela chave.

Resposta de criação, abreviada:

{
  "api_version": "v1",
  "data": {
    "criado": true,
    "negocio_id": 101,
    "cliente_id": 55,
    "clientes": [
      {"cliente_id": 55, "criado": true, "papel_no_negocio": "principal", "avisos": []},
      {"cliente_id": 56, "criado": true, "papel_no_negocio": "contato", "avisos": []},
      {"cliente_id": 45, "criado": false, "papel_no_negocio": "financeiro", "avisos": []}
    ]
  }
}

A resposta inclui outros metadados da criação. Campos personalizados desconhecidos geram avisos; confira-os para detectar erros de digitação.

Cadastrar contatos sem criar um negócio

curl 'https://seu-crm/api/v1/clientes' \
  -H 'Authorization: Bearer SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: contatos-importacao-0001' \
  --data '{"clientes":[
    {"nome":"Maria Silva","email":"maria@example.com","tipo":"PF","referencia_externa":"contato-001"},
    {"nome":"Empresa Exemplo","email":"financeiro@example.com","tipo":"PJ","campos_personalizados":{"origem":"Site"}}
  ]}'

A API procura por ID, referência, e-mail e telefone normalizado antes de cadastrar. Dados informados atualizam um contato existente quando o usuário tem permissão de edição. Campos omitidos preservam seus valores. A operação é atômica.

Buscar objetos

curl 'https://seu-crm/api/v1/objetos?tipo=negocio&q=Silva&pipeline_id=3&status=aberto&limit=50&offset=0' \
  -H 'Authorization: Bearer SUA_CHAVE'

Parâmetros comuns: id, q (nome/título ou ID exato), limit (1–100, padrão 50) e offset (0–1.000.000).

Filtros adicionais:

• Negócios: pipeline_id, coluna_id, responsavel_id, status.
• Tarefas/agenda: negocio_id, responsavel_id, status.
• Documentos/orçamentos: negocio_id.
• Chamados/parcelas/pagamentos/movimentos: negocio_id, status.
• Colunas/automações: pipeline_id.
• Campos personalizados: entidade_tipo.

Resposta: data.itens e data.paginacao com total, limit, offset, proximo_offset. Quando proximo_offset for null, acabou a coleção. IDs e totais respeitam a visibilidade; uma etapa oculta não aparece por busca ou filtro.

Consultar o negócio completo

curl 'https://seu-crm/api/v1/negocios/101' -H 'Authorization: Bearer SUA_CHAVE'

data reúne negocio, campos_personalizados, clientes (com seus campos), responsaveis, tarefas (com campos), orcamentos (itens/campos), documentos, financeiro, chamados, historico, comentarios, timeline e secoes_omitidas.

Documentos exigem adicionalmente crm:documents:read e a permissão de documentos. Financeiro exige crm:financial:read e a permissão financeira. Histórico/comentários/timeline exigem os dois escopos sensíveis, porque textos antigos podem conter essas informações. Outras seções dependem da permissão do recurso. secoes_omitidas informa o que não foi autorizado; não é um erro.

O valor comercial do negócio e dos orçamentos é parte dos dados comerciais. Parcelas, recebimentos, pagamentos, operações e saldos ficam na seção financeira. Campos personalizados retornam definição e valor, incluindo chave, nome, tipo, opcoes e obrigatorio_padrao.

Documentos novos normalmente têm url_externa. A API retorna o link sem buscar o conteúdo no servidor. A rota de download atende arquivos legados armazenados; para um link externo, consulte os metadados. Chaves internas de armazenamento e credenciais de canais não são expostas.

Repetições, limites e erros

Use Idempotency-Key nos POSTs. A chave é vinculada à chave de API e ao conteúdo da requisição. Uma repetição idêntica retorna 200 e idempotente:true; conteúdo diferente com a mesma chave retorna 409. Criação retorna 201. referencia_externa também pode ser usada como identificador de repetição; referências de negócio são únicas na instalação.

Limites: 256 KB de JSON, 50 contatos por requisição, 100 itens por página. Os endpoints de negócios mantêm compatibilidade com integrações anteriores. A API do portal mantém seus escopos portal:read, portal:documents, portal:financial e suas próprias regras de publicação.

Contatos do CRM são clientes da sua empresa. Empresas independentes que contratam o CRM precisam de instâncias e bancos separados. A API não aceita onboarding por tenant_id, workspace_id, empresa_id ou company_id. Veja TENANCY.md.