API REST — Guia de Integração

1 Visão geral e credenciais

Formato JSON (envie Content-Type: application/json). A API enxerga e faz exatamente o que o usuário do CRM vinculado à credencial pode fazer — perfis e compartilhamento valem na API.

As 3 credenciais — obrigatórias em toda requisição

2 Criar as credenciais

Feito uma única vez, no DeskCRM, por um administrador — menu ⚙️ Configurações → Integração.

3 Autenticação (login → token)

curl -u 'integracao:SENHA_DA_APLICACAO' \
  -H 'x-api-key: CHAVE_DA_API' \
  -H 'Content-Type: application/json' \
  -X POST 'https://deskcrm.com.br/webservice/WebserviceStandard/Users/Login' \
  -d '{"userName":"integracao.api","password":"SENHA_DO_USUARIO_API"}'

Resposta: {"status":1,"result":{"token":"…", …}} → guarde o token.

• Validade do token: 24 h após o login ou 4 h sem uso — o que vencer primeiro.
• Ao receber 401 em qualquer chamada, refaça o login e repita a chamada.
• Logout (opcional): PUT /Users/Logout com os 3 headers.

4 Descobrir módulos e todos os campos

/Fields responde, por campo: name (nome técnico usado no JSON), label, type, mandatory (obrigatório), picklistvalues (valores aceitos em listas), referenceList (módulos referenciáveis), defaultvalue… É a fonte da verdade: módulos e campos customizados aparecem aqui automaticamente.

Módulos principais do DeskCRM

5 CRUD de registros

curl -u 'integracao:SENHA' -H 'x-api-key: CHAVE' -H 'x-token: TOKEN' \
  -H 'Content-Type: application/json' \
  -X POST 'https://deskcrm.com.br/webservice/WebserviceStandard/Accounts/Record' \
  -d '{"accountname":"Empresa Exemplo LTDA","assigned_user_id":1,"cpf_cliente":"12345678900"}'

# → {"status":1,"result":{"id":1025,"name":"Empresa Exemplo LTDA"}}

curl … -X PUT '…/Accounts/Record/1025' -d '{"accountname":"Novo Nome"}'

Retorna os campos em formato de exibição. Com o header x-raw-data: 1, vem também o rawData (valores crus, como estão no banco).

Filtro (x-condition)

{"fieldName":"cpf_cliente","value":"12345678900","operator":"e"}

# composto:
{"condition":"AND","rules":[
  {"fieldName":"accounttype","value":"Customer","operator":"e"},
  {"fieldName":"createdtime","value":"2026-01-01","operator":"a"}
]}

Operadores comuns: e igual · n diferente · c contém · s começa com · a maior · m menor.

Outros endpoints úteis

6 Formato dos valores por tipo de campo

7 Erros e tratamento

Formato do erro: {"status":0,"error":{"message":"…","code":401}} — trate status: 0 como falha mesmo quando o HTTP vier 200.

Campos obrigatórios: consulte GET /{Módulo}/Fields → mandatory: true. POST sem eles retorna 400/406.

8 Boas práticas

• Só HTTPS; nunca versionar credenciais em repositório.
• Restrinja por IP no cadastro da aplicação se o consumidor tiver IP fixo.
• Um par aplicação + usuário por sistema integrado — rastreabilidade e revogação limpa.
• Reaproveite o token pelas 24 h / 4 h — não faça login a cada chamada.
• Histórico de acessos: tabela l_yf_api_login_history (mostra erros de login — útil no debug).

9 Teste de homologação executado

Ciclo completo executado em produção em 12/07/2026:

• ✓POST /Users/Login → token recebido
• ✓POST /Accounts/Record “TESTE API — PODE EXCLUIR” → criado (id 1025)
• ✓PUT /Accounts/Record/1025 alterou o nome (campo inexistente veio em skippedData)
• ✓GET /Accounts/Record/1025 confirmou a alteração
• ✓DELETE /Accounts/Record/1025 → lixeira
• ✓Registro e credenciais de teste removidos ao final