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.
| Item | Endereç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 oclient_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ção | Como funciona |
|---|---|
$filter | eq 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, $orderby | Campos separados por vírgula; desc para ordem decrescente. |
$expand | As navegações de cada entidade (listadas abaixo), um nível, com $select,
$filter, $orderby e $top dentro dos parênteses, separados por ;. |
$top, $skip, $count | Sem $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=true | Traz 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
201com o registro e o cabeçalhoLocation. Alterar e excluir respondem204; usePrefer: return=representationpara receber o registro alterado. - Cada registro traz
@odata.etag. Mandando o mesmo valor emIf-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." } }
| Status | Quando |
|---|---|
| 400 | Consulta ou dado inválido, regra do sistema (o code diz qual), filial desconhecida no TenantId |
| 401 | Sem token, token vencido ou credencial revogada |
| 403 | Método desabilitado na entidade, credencial só de consulta ou papel sem permissão |
| 404 | Entidade ou registro não encontrado (ou de outra empresa) |
| 409 | Valor duplicado |
| 412 | O registro mudou desde a leitura (If-Match) |
| 429 | Passou do limite por minuto (veja Retry-After) |
| 504 | A consulta demorou demais: use $filter e $top |
9. Limites e segurança
- 120 chamadas por minuto por credencial.
- Só HTTPS. Guarde o
client_secretnum 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…