ServPilot API · Referência

API do ServPilot

Integre o ServPilot ao seu ERP, ao BI ou a outro sistema. A API segue o padrão OData v4: consulta, inclusão, alteração, exclusão e as ações do sistema (concluir OS, aprovar orçamento...). Abaixo do guia está a referência de todas as entidades, com campos, exemplos de retorno e um console para testar com a sua credencial.

ItemEndereço
Token (OAuth 2.0)…/api/token
Serviço OData…/api/odata
Modelo (CSDL)…/api/odata/$metadata (com token)
Esta referência (JSON)…/api/referencia

Para testar: crie uma credencial no painel (Administração › Integrações), cole o client_id e o client_secret no console e clique em Testar em qualquer chamada. Para explorar com segurança, use uma credencial só de consulta.

1. Credencial

No painel, em Administração › Integrações (API), o administrador da empresa cria uma credencial para cada sistema. Ela tem um client_id e um client_secret, que aparece uma única vez. A API age como o usuário que criou a credencial, só com os papéis escolhidos nela (gestor, financeiro ou técnico), e sempre dentro das empresas liberadas. Uma credencial pode ser só de consulta. Revogar vale na hora.

2. Token: bearer e refresh

POST /api/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET

Também aceita o client_id e o client_secret no cabeçalho Authorization: Basic. A resposta:

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 900,
  "refresh_token": "spr_…", "refresh_token_expires_in": 2592000 }
  • access_token: vale 15 minutos. Envie em toda chamada: Authorization: Bearer eyJ….
  • refresh_token: vale 30 dias e uma vez só. Troque por um par novo com grant_type=refresh_token&refresh_token=spr_… e guarde o novo. Se um refresh token já usado aparecer de novo, a sessão inteira é encerrada por segurança e é preciso pedir outro token com o client_secret.

3. Empresa e filial: TenantId

A conta é o grupo de empresas; cada empresa (CNPJ) pode ser matriz ou filial. Cadastre no painel os códigos da empresa no ERP (grupo, empresa, unidade e filial, conforme o seu sistema). Em cada chamada, escolha a filial no cabeçalho TenantId (grupo e filial separados por vírgula):

TenantId: 01,0101

Também vale ServPilot-Empresa: <código curto ou id da empresa>. Sem cabeçalho, vale a empresa principal da credencial. A filial precisa estar liberada na credencial.

4. Consultas

GET /api/odata/Clientes?$filter=contains(tolower(nome),'mercado') and ativo eq true&$select=nome,documento&$orderby=nome&$top=50&$count=true
GET /api/odata/Clientes(5d1c…)?$expand=Locais($select=nome,cidade)
GET /api/odata/OrdensServico?$filter=status eq 'aberta' and prevista_para le 2026-11-30&$expand=cliente($select=nome)
GET /api/odata/Clientes/$count
OpçãoComo funciona
$filtereq ne gt ge lt le, and or not, in (…), null, funções contains startswith endswith tolower toupper trim length year month day hour minute date now. Textos entre aspas simples; datas como 2026-11-01 ou 2026-11-01T10:00:00Z; ids sem aspas.
$select, $orderbyCampos separados por vírgula; desc para ordem decrescente.
$expandAs navegações de cada entidade (listadas abaixo), um nível, com $select, $filter, $orderby e $top dentro dos parênteses, separados por ;.
$top, $skip, $countSem $top, vêm 100 por página com @odata.nextLink para a próxima. Máximo 1.000 por chamada. Prefer: odata.maxpagesize=N também vale.
incluir_excluidos=trueTraz também os registros excluídos (para sincronizar exclusões).

5. Incluir, alterar e excluir

POST   /api/odata/Clientes            { "tipo": "pj", "nome": "Mercado Bom Preço", "documento": "11111111000111" }
PATCH  /api/odata/Clientes(5d1c…)     { "telefone": "45999990001" }      If-Match: W/"3"   (opcional)
PUT    /api/odata/Clientes(5d1c…)     registro completo (o que não vier volta ao padrão)
DELETE /api/odata/Clientes(5d1c…)
  • Incluir responde 201 com o registro e o cabeçalho Location. Alterar e excluir respondem 204; use Prefer: return=representation para receber o registro alterado.
  • Cada registro traz @odata.etag. Mandando o mesmo valor em If-Match, a alteração só acontece se ninguém mexeu no registro desde a leitura (senão, 412).
  • Excluir é lógico quando a entidade tem exclusão lógica: o registro some das consultas, mas continua no histórico.
  • Campos do sistema (conta_id, empresa_id, versao, datas de criação e alteração) são ignorados na gravação. Na referência, aparecem como só leitura.

6. Movimentos e ações

Ordens de serviço, orçamentos, planos e contratos gravam pelas mesmas regras do painel. Nelas, o corpo do POST, do PATCH e do DELETE segue a ação de incluir, alterar e excluir de cada uma, e as outras ações usam:

POST /api/odata/OrdensServico(…)/ServPilot.Acao   { "acao": "concluir", "laudo_final": "…" }

Cada entidade lista as ações dela, com os campos e um exemplo. Itens de OS, atendimentos, medições e similares são só consulta: mudam pela entidade principal.

7. De-para com o ERP: VinculosExternos

Guarde a chave do ERP de cada registro, sem precisar guardar os ids do ServPilot no ERP:

POST /api/odata/VinculosExternos
{ "sistema": "erp", "entidade": "Clientes", "registro_id": "5d1c…", "chave_externa": "000123|01", "filial_externa": "" }

GET /api/odata/VinculosExternos?$filter=entidade eq 'Clientes' and chave_externa eq '000123|01'

filial_externa vazia = cadastro sem filial no ERP.

8. Erros

{ "error": { "code": "metodo_desabilitado", "message": "Incluir OsItens pela API está desabilitado." } }
StatusQuando
400Consulta ou dado inválido, regra do sistema (o code diz qual), filial desconhecida no TenantId
401Sem token, token vencido ou credencial revogada
403Método desabilitado na entidade, credencial só de consulta ou papel sem permissão
404Entidade ou registro não encontrado (ou de outra empresa)
409Valor duplicado
412O registro mudou desde a leitura (If-Match)
429Passou do limite por minuto (veja Retry-After)
504A consulta demorou demais: use $filter e $top

9. Limites e segurança

  • 120 chamadas por minuto por credencial.
  • Só HTTPS. Guarde o client_secret num cofre ou parâmetro protegido; nunca em código-fonte.
  • Uma credencial por sistema, com os menores papéis possíveis. Revogue as que não usa.
  • Cada chamada fica registrada (90 dias) e pode ser vista no painel, na credencial.
  • As entidades de uma aplicação só respondem para empresas que usam essa aplicação.

Dúvidas: contato@servpilot.com.br.

Entidades

Tudo o que a API expõe hoje, gerado do próprio modelo. Em cada chamada, Testar leva a chamada para o console.

Carregando a referência…