API REST v1

Integre site, ERP, automações (Zapier, n8n, Make) e agentes. Crie a chave em Configurações → API e chaves; ela pertence a um workspace e pode ser somente leitura.

URL base: https://aguiacrm.orkestrai.com.br/api/v1

Autenticação: Authorization: Bearer aguia_sk_…

Formato: sucesso { data, meta? }, erro { error: { code, message, details? } }. Valores monetários em centavos.

Limite: 120 requisições por minuto por chave (resposta 429 com Retry-After).

OpenAPI 3.1: /api/v1/openapi.json (importe no Postman, Insomnia ou gere SDKs).

Workspace e escopos da chave

GET/meescopo read

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/me" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Encerrar a sessão (revoga a chave usada)

POST/logoutescopo read

Revoga na hora a chave enviada nesta requisição, na API REST e no servidor MCP. Qualquer chamada seguinte com ela recebe 401. Não afeta as outras chaves do workspace. Irreversível: para voltar a usar a API, crie uma chave nova em Configurações → API e chaves.

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/logout" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Listar contatos

GET/contactsescopo read

Busca por nome, e-mail, telefone ou empresa (`q`), filtros e paginação.

Parâmetros de busca

`q`	string
`page`	integer
`pageSize`	integer
`lifecycleStage`	lead \| qualified \| opportunity \| customer \| churned
`ownerId`	string
`companyId`	string
`tag`	string
`sort`	recent \| name \| score \| activity

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/contacts"?q=termo \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Criar contato

POST/contactsescopo write

Corpo (JSON)

`firstName`obrigatório	string
`lastName`	string \| null
`email`	string \| null
`phone`	string \| null
`whatsapp`	string \| null
`jobTitle`	string \| null
`document`	string \| null
`city`	string \| null
`state`	string \| null
`companyId`	string \| null
`lifecycleStage`	lead \| qualified \| opportunity \| customer \| churned
`source`	string \| null
`ownerId`	string \| null
`tags`	array
`customFields`	object

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/contacts" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Paula","lastName":"Martins","email":"paula@lojasol.com.br","whatsapp":"11987654321","source":"Site","tags":["inbound"]}'

Obter contato

GET/contacts/{id}escopo read

Inclui os fatores do score de lead.

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/contacts/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Atualizar contato

PATCH/contacts/{id}escopo write

Envie só os campos que mudam.

Corpo (JSON)

`firstName`	string
`lastName`	string \| null
`email`	string \| null
`phone`	string \| null
`whatsapp`	string \| null
`jobTitle`	string \| null
`document`	string \| null
`city`	string \| null
`state`	string \| null
`companyId`	string \| null
`lifecycleStage`	lead \| qualified \| opportunity \| customer \| churned
`source`	string \| null
`ownerId`	string \| null
`tags`	array
`customFields`	object

curl -X PATCH "https://aguiacrm.orkestrai.com.br/api/v1/contacts/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lifecycleStage":"qualified"}'

Excluir contato

DELETE/contacts/{id}escopo write

curl -X DELETE "https://aguiacrm.orkestrai.com.br/api/v1/contacts/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Listar empresas

GET/companiesescopo read

Parâmetros de busca

`q`	string
`page`	integer
`pageSize`	integer
`ownerId`	string
`tag`	string
`sort`	recent \| name

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/companies"?q=termo \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Criar empresa

POST/companiesescopo write

Corpo (JSON)

`name`obrigatório	string
`domain`	string \| null
`document`	string \| null
`industry`	string \| null
`size`	string \| null
`phone`	string \| null
`email`	string \| null
`website`	string \| null
`city`	string \| null
`state`	string \| null
`country`	string \| null
`description`	string \| null
`ownerId`	string \| null
`tags`	array
`customFields`	object

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/companies" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Loja Sol","domain":"lojasol.com.br","city":"Campinas","state":"SP"}'

Obter empresa

GET/companies/{id}escopo read

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/companies/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Atualizar empresa

PATCH/companies/{id}escopo write

Corpo (JSON)

`name`	string
`domain`	string \| null
`document`	string \| null
`industry`	string \| null
`size`	string \| null
`phone`	string \| null
`email`	string \| null
`website`	string \| null
`city`	string \| null
`state`	string \| null
`country`	string \| null
`description`	string \| null
`ownerId`	string \| null
`tags`	array
`customFields`	object

curl -X PATCH "https://aguiacrm.orkestrai.com.br/api/v1/companies/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Excluir empresa

DELETE/companies/{id}escopo write

curl -X DELETE "https://aguiacrm.orkestrai.com.br/api/v1/companies/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Listar funis e etapas

GET/pipelinesescopo read

Use os ids das etapas para criar e mover negócios.

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/pipelines" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Listar negócios

GET/dealsescopo read

Parâmetros de busca

`q`	string
`page`	integer
`pageSize`	integer
`pipelineId`	string
`stageId`	string
`status`	open \| won \| lost
`ownerId`	string
`contactId`	string
`companyId`	string

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/deals"?q=termo \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Criar negócio

POST/dealsescopo write

Sem `pipelineId`/`stageId`, usa o funil padrão e a primeira etapa aberta. Valores em centavos.

Corpo (JSON)

`title`obrigatório	string
`valueCents`	integer
`pipelineId`	string
`stageId`	string
`contactId`	string \| null
`companyId`	string \| null
`ownerId`	string \| null
`priority`	low \| medium \| high
`expectedCloseDate`	string \| null
`source`	string \| null
`tags`	array
`customFields`	object

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/deals" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Plano anual — Loja Sol","valueCents":1188000,"contactId":"ID_DO_CONTATO","expectedCloseDate":"2026-12-15"}'

Obter negócio

GET/deals/{id}escopo read

Inclui os itens (produtos).

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/deals/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Atualizar negócio

PATCH/deals/{id}escopo write

Corpo (JSON)

`title`	string
`valueCents`	integer
`contactId`	string \| null
`companyId`	string \| null
`ownerId`	string \| null
`priority`	low \| medium \| high
`expectedCloseDate`	string \| null
`source`	string \| null
`tags`	array
`customFields`	object

curl -X PATCH "https://aguiacrm.orkestrai.com.br/api/v1/deals/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Mover de etapa

POST/deals/{id}/moveescopo write

Etapas do tipo ganho/perdido fecham o negócio.

Corpo (JSON)

stageIdobrigatório string

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/deals/ID/move" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Marcar como ganho ou perdido

POST/deals/{id}/closeescopo write

Corpo (JSON)

`status`obrigatório	won \| lost
`lostReason`	string

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/deals/ID/close" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"won"}'

Excluir negócio

DELETE/deals/{id}escopo write

curl -X DELETE "https://aguiacrm.orkestrai.com.br/api/v1/deals/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Registrar venda paga

POST/purchasesescopo write

Grava uma venda já paga (loja, gateway de pagamento, planilha) como negócio ganho, com os itens, e ela aparece no histórico de compras do cliente. O cliente é encontrado por e-mail, telefone ou CPF/CNPJ; se não existir, é criado. Itens podem vir do catálogo por `productId` ou `sku` (nome e preço saem dele) ou avulsos com `name` e `unitPriceCents`. Com `externalId` o registro é idempotente: reenviar o mesmo pagamento devolve a venda existente (200, `created: false`) em vez de duplicar (201). `externalUrl` (https) vira o link "Ver pagamento" no negócio. Com `test: true` a venda aparece no cliente com a etiqueta Teste, mas fica fora dos totais e relatórios. O valor é gravado na moeda do workspace, sem conversão. Dispara os eventos `deal.created` e `deal.won`.

Corpo (JSON)

`source`	string
`externalId`	string
`paymentRef`	string
`externalUrl`	string
`test`	boolean
`contactId`	string
`customer`	object
`items`	array
`valueCents`	integer
`title`	string
`purchasedAt`	string
`pipelineId`	string

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/purchases" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"loja","externalId":"pedido-10482","customer":{"name":"Marina Lopes","email":"marina@exemplo.com.br","phone":"+55 11 98888-7777"},"items":[{"sku":"PLANO-PRO","quantity":1},{"name":"Implantação","unitPriceCents":50000}],"purchasedAt":"2026-11-01T14:30:00-03:00"}'

Listar atividades

GET/activitiesescopo read

`scope`: overdue, today, upcoming, done ou all.

Parâmetros de busca

`scope`	overdue \| today \| upcoming \| done \| all
`type`	task \| call \| meeting \| email \| whatsapp \| note
`assigneeId`	string
`contactId`	string
`dealId`	string
`companyId`	string
`limit`	integer

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/activities"?q=termo \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Criar atividade

POST/activitiesescopo write

Corpo (JSON)

`type`	task \| call \| meeting \| email \| whatsapp \| note
`title`obrigatório	string
`description`	string \| null
`dueAt`	null
`durationMin`	integer \| null
`contactId`	string \| null
`companyId`	string \| null
`dealId`	string \| null
`assigneeId`	string \| null
`completed`	boolean

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/activities" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"call","title":"Ligar para apresentar a proposta","dueAt":"2026-11-05T14:00:00-03:00","contactId":"ID_DO_CONTATO"}'

Atualizar ou concluir

PATCH/activities/{id}escopo write

Envie `{"completed": true}` para concluir.

Corpo (JSON)

`type`	task \| call \| meeting \| email \| whatsapp \| note
`title`	string
`description`	string \| null
`dueAt`	null
`durationMin`	integer \| null
`contactId`	string \| null
`companyId`	string \| null
`dealId`	string \| null
`assigneeId`	string \| null
`completed`	boolean

curl -X PATCH "https://aguiacrm.orkestrai.com.br/api/v1/activities/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Excluir atividade

DELETE/activities/{id}escopo write

curl -X DELETE "https://aguiacrm.orkestrai.com.br/api/v1/activities/ID" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Registrar nota

POST/notesescopo write

Aparece no histórico do registro.

Corpo (JSON)

`body`obrigatório	string
`contactId`	string
`companyId`	string
`dealId`	string

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/notes" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Cliente pediu desconto à vista.","dealId":"ID_DO_NEGOCIO"}'

Listar conversas

GET/conversationsescopo read

Parâmetros de busca

`status`	open \| pending \| closed
`channel`	whatsapp \| email
`assigneeId`	string
`q`	string

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/conversations"?q=termo \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Enviar WhatsApp ou e-mail

POST/messagesescopo write

Para um contato (`contactId` + `channel`) ou numa conversa existente (`conversationId`). Aceita variáveis como {{primeiro_nome}}.

Corpo (JSON)

`conversationId`	string
`contactId`	string
`channel`	whatsapp \| email
`body`obrigatório	string
`subject`	string \| null
`templateId`	string

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/messages" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"ID_DO_CONTATO","channel":"whatsapp","body":"Oi, {{primeiro_nome}}! Sua proposta está pronta."}'

Listar produtos

GET/productsescopo read

curl -X GET "https://aguiacrm.orkestrai.com.br/api/v1/products" \
  -H "Authorization: Bearer $AGUIA_API_KEY"

Criar produto

POST/productsescopo write

Corpo (JSON)

`name`obrigatório	string
`sku`	string \| null
`description`	string \| null
`priceCents`obrigatório	integer
`recurring`	boolean
`active`	boolean

curl -X POST "https://aguiacrm.orkestrai.com.br/api/v1/products" \
  -H "Authorization: Bearer $AGUIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'