Documentação da API

Referência da API ServixSys v1 para integração de clientes. Todos os exemplos usam dados fictícios.

Introdução

A API ServixSys é REST, recebe e devolve JSON e usa códigos HTTP padrão. Ela permite que seu sistema envie e mantenha atualizados cadastros de clientes dentro da plataforma.

Somente conexões HTTPS são aceitas.
Todo corpo de requisição deve usar Content-Type: application/json.
Datas seguem o padrão ISO 8601 (UTC).

Autenticação

Toda requisição deve ser autenticada com um token (API Key) enviado no cabeçalho Authorization.

Cabeçalho

Authorization: Bearer SEU_TOKEN

Nunca compartilhe a credencial com terceiros.
Nunca armazene o token diretamente no frontend.
Utilize somente conexão HTTPS.
Cada credencial pertence a uma empresa específica.

A geração e o gerenciamento das credenciais são exclusivos da administração da ServixSys. Solicite o acesso pela página Desenvolvedores.

Ambiente

Produção	`https://api.servixsys.com/api/v1`
Versão	v1

Sandbox (teste grátis)

Use o ambiente de sandbox para testar sua integração antes de receber a credencial de produção. Ele valida o payload e devolve uma resposta simulada: nada é gravado.

Base sandbox	`https://servixsys.com/api/public/v1/sandbox`
Autenticação	Opcional (qualquer token de teste)

Teste de conexão (GET)

curl https://servixsys.com/api/public/v1/sandbox/ping

Cliente de teste (POST)

curl -X POST https://servixsys.com/api/public/v1/sandbox/clientes \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Empresa Exemplo",
    "cpf_cnpj": "12345678000100",
    "email": "contato@empresa.com",
    "telefone": "11999999999"
  }'

Resposta

{
  "ok": true,
  "ambiente": "sandbox",
  "persistido": false,
  "cliente": { "id": "cli_sandbox_0001", "nome": "Empresa Exemplo" }
}

Campos inválidos retornam 422 com a lista de erros por campo — igual à produção.

Clientes

POST/api/v1/clientesCria um cliente

PUT/api/v1/clientes/{id}Atualiza um cliente

GET/api/v1/clientes/{id}Consulta um cliente

GET/api/v1/clientesLista clientes (paginado)

Campo	Tipo	Obrigatoriedade	Descrição
nome	string	Obrigatório	Nome ou razão social (2 a 120 caracteres).
cpf_cnpj	string	Obrigatório	Somente números, sem pontuação.
email	string	Opcional	E-mail válido de contato.
telefone	string	Opcional	Somente números, com DDD.

Criar cliente — requisição (cURL)

curl -X POST https://api.servixsys.com/api/v1/clientes \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Empresa Exemplo",
    "cpf_cnpj": "12345678000100",
    "email": "contato@empresa.com",
    "telefone": "11999999999"
  }'

Resposta 201 Created

{
  "data": {
    "id": "cli_9f2a17c4",
    "nome": "Empresa Exemplo",
    "cpf_cnpj": "12345678000100",
    "email": "contato@empresa.com",
    "telefone": "11999999999",
    "criado_em": "2026-09-01T13:22:41Z"
  }
}

Atualizar cliente — requisição (cURL)

curl -X PUT https://api.servixsys.com/api/v1/clientes/cli_9f2a17c4 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "telefone": "11988887777" }'

Resposta 200 OK

{
  "data": {
    "id": "cli_9f2a17c4",
    "nome": "Empresa Exemplo",
    "telefone": "11988887777",
    "atualizado_em": "2026-09-01T13:40:02Z"
  }
}

Consultar cliente — requisição e resposta

curl https://api.servixsys.com/api/v1/clientes/cli_9f2a17c4 \
  -H "Authorization: Bearer SEU_TOKEN"

{
  "data": {
    "id": "cli_9f2a17c4",
    "nome": "Empresa Exemplo",
    "cpf_cnpj": "12345678000100"
  }
}

Erro 422 — CPF/CNPJ inválido

{
  "error": "validation_error",
  "message": "Dados inválidos.",
  "details": [
    { "field": "cpf_cnpj", "message": "CPF/CNPJ inválido." }
  ]
}

Paginação

Listagens aceitam page (inicia em 1) e per_page (máximo 100). Use meta.total_pages para saber quando parar: quando page for igual a total_pages, não há mais registros.

Listar clientes — requisição (cURL)

curl "https://api.servixsys.com/api/v1/clientes?page=1&per_page=50" \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta 200 OK

{
  "data": [
    { "id": "cli_9f2a17c4", "nome": "Empresa Exemplo", "cpf_cnpj": "12345678000100" },
    { "id": "cli_1d77ab52", "nome": "Outra Empresa", "cpf_cnpj": "98765432000199" }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 1240, "total_pages": 25 }
}

Erro 400 — parâmetro de paginação inválido

{
  "error": "invalid_request",
  "message": "Parâmetro de paginação inválido.",
  "details": [
    { "field": "per_page", "message": "Deve ser um número entre 1 e 100." }
  ]
}

Códigos de retorno

Sempre trate a integração pelo código HTTP, não pelo texto da mensagem. Códigos 2xx indicam sucesso; 4xx indicam problema no envio (corrija e reenvie); 5xx indicam falha temporária (repita com backoff).

200	Requisição realizada com sucesso
201	Registro criado
400	Dados inválidos
401	Não autenticado
403	Acesso não permitido
404	Registro não encontrado
409	Conflito ou registro duplicado
422	Erro de validação
429	Limite de requisições excedido
500	Erro interno

Erros

Erros seguem sempre o mesmo formato: error (identificador estável para tratamento no código), message (texto para exibição) e details (lista por campo, quando houver).

Erro de validação (422)

{
  "error": "validation_error",
  "message": "Dados inválidos.",
  "details": [
    { "field": "cpf_cnpj", "message": "CPF/CNPJ inválido." }
  ]
}

Token ausente ou inválido (401)

{
  "error": "unauthorized",
  "message": "Token de acesso ausente ou inválido."
}

API não habilitada (403)

{
  "error": "API_NOT_ENABLED",
  "message": "API não habilitada para esta empresa."
}

Limite de requisições excedido (429)

{
  "error": "rate_limited",
  "message": "Limite de requisições excedido. Tente novamente em instantes.",
  "retry_after": 30
}

validation_error	Corrija os campos em details e reenvie.
invalid_request	Parâmetros ou JSON inválidos; não reenvie sem corrigir.
unauthorized	Renove ou revise o token no cabeçalho Authorization.
API_NOT_ENABLED	Solicite a liberação da API à administração da ServixSys.
API_SUSPENDED	Integração suspensa; entre em contato com a ServixSys.
conflict	Registro duplicado; use PUT para atualizar o existente.
rate_limited	Aguarde retry_after segundos e repita com backoff.
server_error	Falha temporária; repita a requisição com backoff.

Limites de utilização

Até 120 requisições por minuto por credencial.
Até 100 registros por página nas listagens.
Corpo da requisição limitado a 1 MB.
Ao exceder o limite a API responde 429; aguarde e repita com backoff.

Status da API

A utilização da API depende de habilitação prévia da empresa na ServixSys. Antes de iniciar a integração, consulte o endpoint de status para saber se a credencial está autorizada a consumir a API.

Verificar status

curl https://api.servixsys.com/api/v1/status \
  -H "Authorization: Bearer SEU_TOKEN"

API ativa

{
  "api_ativa": true,
  "status": "ativa",
  "mensagem": "API disponível para utilização."
}

API não habilitada

{
  "api_ativa": false,
  "status": "nao_habilitada",
  "mensagem": "API não habilitada para esta empresa."
}

API suspensa

{
  "api_ativa": false,
  "status": "suspensa",
  "mensagem": "API temporariamente indisponível para esta empresa."
}

Quando a API não estiver ativa, os endpoints respondem 403:

403 Forbidden

{
  "success": false,
  "code": "API_NOT_ENABLED",
  "message": "A API não está habilitada para esta empresa."
}

{
  "success": false,
  "code": "API_SUSPENDED",
  "message": "A API está temporariamente indisponível para esta empresa."
}

Também disponível em sandbox: GET https://servixsys.com/api/public/v1/sandbox/status. Questões de habilitação são tratadas pelo responsável administrativo da empresa junto à ServixSys.

Exemplos de integração

Criar cliente — Delphi

uses
  System.SysUtils, System.Classes, System.JSON,
  System.Net.HttpClient, System.Net.URLClient;

procedure EnviarCliente;
var
  Http: THTTPClient;
  Body: TStringStream;
  Json: TJSONObject;
  Resp: IHTTPResponse;
begin
  Json := TJSONObject.Create;
  try
    Json.AddPair('nome', 'Empresa Exemplo');
    Json.AddPair('cpf_cnpj', '12345678000100');
    Json.AddPair('email', 'contato@empresa.com');
    Json.AddPair('telefone', '11999999999');

    Body := TStringStream.Create(Json.ToJSON, TEncoding.UTF8);
    Http := THTTPClient.Create;
    try
      Http.ContentType := 'application/json';
      Http.CustomHeaders['Authorization'] :=
        'Bearer ' + GetEnvironmentVariable('SERVIXSYS_TOKEN');

      Resp := Http.Post('https://api.servixsys.com/api/v1/clientes', Body);

      if (Resp.StatusCode = 200) or (Resp.StatusCode = 201) then
        Writeln('Cliente enviado: ', Resp.ContentAsString)
      else
        Writeln('Falha ', Resp.StatusCode, ': ', Resp.ContentAsString);
    finally
      Http.Free;
      Body.Free;
    end;
  finally
    Json.Free;
  end;
end;

Boas práticas

Guarde o token em variáveis de ambiente ou cofre de credenciais no servidor.
Reenvie apenas registros alterados para reduzir requisições desnecessárias.
Use cpf_cnpj e codigo como chaves de deduplicação.
Implemente retentativa com backoff exponencial para 429 e 500.
Registre logs das respostas para auditoria da integração.
Nunca utilize credenciais reais em ambientes de teste públicos.