> For the complete documentation index, see [llms.txt](https://ajuda.livechat360.com.br/crm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.livechat360.com.br/crm/api-docs/guia-rapido-integracao-completa.md).

# Guia rapido integracao completa

A jornada de integração completa em uma única sessão de terminal, do CRM vazio a uma negociação **ganha**, com contato, empresa, produtos, tarefa, arquivo, proposta e linha do tempo. Cada id é capturado com `jq` (instale-o, ou copie os ids manualmente), então o bloco roda de cima a baixo como está. No Windows, execute no Git Bash.

## Antes de começar

Obtenha no painel:

* os **ids do funil e dos estágios**: abra o funil, a URL é `/dashboard/funis/{KANBAN_ID}/...`; os ids dos estágios estão nas configurações do funil;
* se quiser atribuir responsáveis, o **id de um usuário** da conta.

Campos personalizados também precisam existir previamente no painel (chaves desconhecidas retornam 422).

{% hint style="warning" %}
**Acentos no Windows:** o curl do Git Bash converte argumentos `-d '...'` digitados na linha de comando pela página de código ANSI do Windows, corrompendo caracteres acentuados (ç, ã, í…). Para payloads com texto acentuado, salve o JSON em um arquivo UTF-8 e envie com `--data-binary @corpo.json`. Arquivos são transmitidos byte a byte, sem conversão.
{% endhint %}

## A sessão completa

{% stepper %}
{% step %}

## Configurar a sessão

```bash
export KEY="lc360_live_..."       # chave de API com todos os escopos
export BASE="https://app-api.atendeserver.com.br/v1"
export KANBAN_ID=9                # id do funil (da URL do painel)
export STAGE_NEW=40               # id do estágio de entrada
export STAGE_NEGOTIATING=41       # id de um estágio intermediário
export OWNER_ID=3                 # id de usuário da conta (opcional em todo o guia)

AUTH="Authorization: Bearer $KEY"
JSON="Content-Type: application/json"
```

{% endstep %}

{% step %}

## Origem

```bash
SOURCE_ID=$(curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"name":"Google Ads"}' "$BASE/sources" | jq -r '.data.id')
```

{% endstep %}

{% step %}

## Empresa

O CNPJ é validado, único e imutável depois de criado.

```bash
COMPANY_ID=$(curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"name":"Auto360 Veículos","cnpj":"12.345.678/0001-90","segment":"Concessionária","owner_id":'$OWNER_ID'}' \
  "$BASE/companies" | jq -r '.data.id')
```

{% endstep %}

{% step %}

## Produto do catálogo

A categoria `"Assinatura"` é criada se não existir.

```bash
PRODUCT_ID=$(curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"name":"Plano Mensal Premium","price":199.90,"category":"Assinatura","recurring":true}' \
  "$BASE/products" | jq -r '.data.id')
```

{% endstep %}

{% step %}

## Contato

Tags são criadas por nome; `custom_fields` usa o NOME do campo.

```bash
LEAD_ID=$(curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"name":"Maria Souza","phone":"5543999998888","email":"maria@email.com","tags":["vip","newsletter"],"custom_fields":{"erp_id":"9981"}}' \
  "$BASE/leads" | jq -r '.data.id')
```

{% endstep %}

{% step %}

## Atualizar o contato

PUT parcial: só os campos enviados mudam. `company_id` vincula o contato à empresa criada acima.

```bash
curl -s -X PUT -H "$AUTH" -H "$JSON" \
  -d '{"occupation":"Designer","address_city":"Londrina","address_uf":"pr","company_id":'$COMPANY_ID'}' \
  "$BASE/leads/$LEAD_ID" | jq '.data | {id, occupation, address_uf, company_id}'
```

{% endstep %}

{% step %}

## Criar a negociação

Reúne contato + empresa + origem no funil. Aparece em tempo real no quadro; as automações de criação são disparadas.

```bash
DEAL_ID=$(curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"kanban_id":'$KANBAN_ID',"kanban_status_id":'$STAGE_NEW',"contact_ids":['$LEAD_ID'],"name":"Negociação - Plano Anual","company_id":'$COMPANY_ID',"source_id":'$SOURCE_ID',"owner_id":'$OWNER_ID',"rating":4,"expected_close_date":"2026-07-31"}' \
  "$BASE/deals" | jq -r '.data.id')
```

{% endstep %}

{% step %}

## Adicionar uma linha de produto

O valor da negociação é calculado a partir das linhas de produto.

```bash
LINE_ID=$(curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"product_id":'$PRODUCT_ID',"quantity":2,"discount_type":"percentage","discount":10}' \
  "$BASE/deals/$DEAL_ID/products" | jq -r '.data.id')

curl -s -H "$AUTH" "$BASE/deals/$DEAL_ID" \
  | jq '.data | {total_amount, recurring_amount, one_time_amount}'   # valores calculados
```

{% endstep %}

{% step %}

## Criar uma tarefa

A categoria `"Ligação"` é criada por nome; `owner_id` substitui os responsáveis.

```bash
TASK_ID=$(curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"deal_id":'$DEAL_ID',"name":"Ligar para confirmar proposta","category":"Ligação","due_date":"2026-07-10T14:00:00Z","owner_id":'$OWNER_ID'}' \
  "$BASE/tasks" | jq -r '.data.id')
```

{% endstep %}

{% step %}

## Anexar um arquivo

Multipart, binário no campo `file`. Aponte para um arquivo existente na sua máquina. O `;type=` importa: o padrão do curl (`application/octet-stream`) é rejeitado — declare o tipo MIME real do seu arquivo.

```bash
FILE_ID=$(curl -s -X POST -H "$AUTH" \
  -F "file=@contrato.pdf;type=application/pdf" -F "name=Contrato assinado.pdf" \
  "$BASE/deals/$DEAL_ID/files" | jq -r '.data.id')
```

{% endstep %}

{% step %}

## Criar uma proposta

```bash
PROPOSAL_ID=$(curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"title":"Proposta Comercial - Plano Anual","amount":1500,"expires_at":"2026-07-10T23:59:00Z"}' \
  "$BASE/deals/$DEAL_ID/proposals" | jq -r '.data.id')
```

{% endstep %}

{% step %}

## Adicionar uma anotação

Com `user_id` é uma nota do usuário; sem, do sistema.

```bash
curl -s -X POST -H "$AUTH" -H "$JSON" \
  -d '{"description":"Cliente pediu retorno na próxima semana.","user_id":'$OWNER_ID'}' \
  "$BASE/deals/$DEAL_ID/annotations" | jq '.data'
```

{% endstep %}

{% step %}

## Avançar a negociação

```bash
curl -s -X PUT -H "$AUTH" -H "$JSON" -d '{"is_completed":true}' "$BASE/tasks/$TASK_ID" \
  | jq '.data | {id, is_completed}'

curl -s -X PUT -H "$AUTH" -H "$JSON" -d '{"kanban_status_id":'$STAGE_NEGOTIATING'}' \
  "$BASE/deals/$DEAL_ID" | jq '.data | {kanban_status_id, status}'    # mudança de estágio

curl -s -X PUT -H "$AUTH" -H "$JSON" -d '{"status":"won"}' "$BASE/deals/$DEAL_ID" \
  | jq '.data | {status, closed_at}'    # → "won" + closed_at preenchido; 🎉 na linha do tempo
```

{% endstep %}
{% endstepper %}

## Chamadas do dia a dia

```bash
# Encontrar um contato pelo id do seu ERP (filtro de campo personalizado)
curl -s -H "$AUTH" "$BASE/leads?custom__erp_id=9981" | jq '.data[].id'

# Negociações ganhas no mês, mais recentes primeiro
curl -s -H "$AUTH" "$BASE/deals?status=won&closed_at__gte=2026-07-01&sort=-closed_at" | jq '.meta'

# Tarefas abertas com vencimento nesta semana
curl -s -H "$AUTH" "$BASE/tasks?is_completed=false&due_date__lte=2026-07-12" | jq '.data'

# A linha do tempo completa da negociação (registros do sistema têm user_id: null)
curl -s -H "$AUTH" "$BASE/deals/$DEAL_ID/annotations?per_page=50" | jq '.data'

# Reabrir a negociação — sair do estágio terminal limpa o closed_at
curl -s -X PUT -H "$AUTH" -H "$JSON" -d '{"kanban_status_id":'$STAGE_NEGOTIATING'}' \
  "$BASE/deals/$DEAL_ID" | jq '.data | {status, closed_at}'

# Exclusões disponíveis: linhas de produto, arquivos e contatos
curl -s -X DELETE -H "$AUTH" "$BASE/deals/$DEAL_ID/products/$LINE_ID" -w "%{http_code}\n"
curl -s -X DELETE -H "$AUTH" "$BASE/deals/$DEAL_ID/files/$FILE_ID" -w "%{http_code}\n"
curl -s -X DELETE -H "$AUTH" "$BASE/leads/$LEAD_ID" -w "%{http_code}\n"
```