Endpoint HTTP que recebe um documento ou uma placa, consulta o banco do ServiceERP
e devolve o resultado na mesma requisição. Somente leitura, autenticado por chave,
com resposta previsível mesmo quando o banco está fora do ar.
Protocolo JSON-RPC 2.0 sobre HTTPSAcesso somente leituraResposta síncrona
Primeira chamada
Três coisas bastam para começar: o endereço, a chave que você recebeu e o nome do
método. Cole no terminal, trocando a chave e o documento.
Se a chave estiver correta e o documento existir, a resposta traz
"status": "ok" e o histórico no campo result. Para conferir
que o serviço está no ar antes de qualquer coisa, GET /health responde
sem exigir chave.
Endereços
O endereço depende de onde o seu sistema roda. Todos servem os mesmos métodos.
ativohttps://api-db.gpsceara.shop/rpcHTTPS
Todas as chamadas usam HTTPS. Requisições em texto claro não são atendidas.
Autenticação
Chave no cabeçalho X-API-Key. Sem OAuth e sem token de sessão — a mesma
chave vale para todas as chamadas, até o vencimento.
X-API-Key: sua-chave
Uma por parceiroCada integração recebe a sua. Isso permite revogar uma sem afetar as demais.
Não exporA chave dá acesso a dados cadastrais e financeiros de clientes. Guarde em variável de ambiente ou cofre de segredos — nunca no código-fonte, no front-end ou em repositório.
RotaçãoEm caso de suspeita de vazamento, solicite uma chave nova. A antiga é invalidada na hora.
Limites por chaveCada chave tem limites próprios, definidos em contrato. As respostas trazem quanto resta da janela; ao estourar, vem 429 com Retry-After.
Rotas abertas/health e /ping não exigem chave — servem para monitoração externa.
Chave ausente, inválida, vencida ou revogada devolve
unauthorized com HTTP 401.
Requisição
Sempre POST, sempre em /rpc, sempre com o mesmo formato de
corpo. O que muda entre uma consulta e outra é o method e o conteúdo de
params.
{
"jsonrpc": "2.0", // fixo"id": 1, // livre; volta igual na resposta"method": "historicoFinanceiro",
"params": { "documento": "123.456.789-00" }
}
jsonrpcSempre "2.0". Aceito como constante.
idNúmero ou texto à sua escolha, devolvido inalterado. Serve para correlacionar requisição e resposta nos seus registros.
methodNome do método. GET /methods lista os disponíveis.
paramsObjeto com os parâmetros do método. Pode ser omitido quando o método não exige nenhum.
Uma chamada por requisição. O padrão JSON-RPC permite enviar um vetor de
chamadas em lote; esta API não implementa isso. Para consultar vários documentos,
faça requisições sequenciais.
Montar chamada
Escolha o método, preencha os parâmetros e copie o código pronto na linguagem que
você usa. O código é gerado aqui no navegador — nada é enviado.
Gerador de requisiçãoPOST https://api-db.gpsceara.shop/rpc
Resposta
Sucesso e falha usam o mesmo formato. Leia o campo status — não o
código HTTP, que em certas situações vem da infraestrutura e não do serviço.
{
"jsonrpc": "2.0",
"id": 1,
"status": "ok",
"ok": true,
"found": true,
"dbConnected": true,
"message": "Consulta realizada com sucesso",
"result": { /* varia conforme o método */ },
"timestamp": "2026-09-02T19:10:39.434Z"
}
statusO que aconteceu, em uma palavra. É o campo de decisão.
okA requisição foi processada sem falha — inclusive quando nada foi encontrado.
foundVeio dado do banco. Separa "não existe" de "deu erro".
dbConnectedHouve conexão efetiva com o banco nesta requisição.
messageTexto pronto para exibir a quem está do outro lado.
resultOs dados, ou null.
errorPresente só em falha: code, message e, quando habilitado, detail técnico.
Por que ok: true com found: false?
Um cliente que não existe não é erro — a consulta rodou e a resposta é "não há
registro". Tratar isso como falha faria o seu sistema repetir eternamente uma
busca por um dado que nunca vai aparecer.
Erros
Sete estados possíveis. A distinção entre eles é o que permite decidir se vale
repetir, corrigir a chamada ou avisar o usuário.
status
HTTP
code
Quando acontece
O que fazer
ok
200
—
Consultou e encontrou.
Usar result.
not_found
200
—
Consultou; nenhum registro corresponde.
Informar que não há cadastro. Não repetir.
invalid_params
400
-32602
Parâmetro ausente ou malformado. O banco nem foi consultado.
Corrigir a chamada — message diz o quê.
unauthorized
401
-32001
Chave ausente ou inválida.
Conferir a chave configurada.
method_not_found
404
-32601
O método não existe. A resposta lista os disponíveis em error.detail.
Corrigir o nome do método.
rate_limited
429
-32020
Limite por minuto ou quota diária da chave atingidos.
Aguardar o tempo do cabeçalho Retry-After e repetir.
db_unavailable
503
-32010
Não houve conexão com o banco. Nenhuma consulta foi executada.
Repetir depois. Falha temporária de infraestrutura.
query_failed
502
-32011
Conectou, mas a consulta não pôde ser concluída.
Não repetir — o problema está na consulta. Reportar.
{
"status": "db_unavailable",
"ok": false,
"found": false,
"dbConnected": false,
"message": "Nao houve conexao efetiva com o banco de dados. Nenhuma consulta foi executada. Tente novamente em instantes.",
"result": null,
"error": { "code": -32010, "message": "..." }
}
Trate também a resposta que não segue este formato. O envelope só existe
enquanto o serviço está no ar para respondê-lo. Se o processo cair, quem responde é
a camada de rede acima dele — com o formato dela, onde status costuma
ser o número do erro HTTP, não um texto.
Uma comparação direta com "ok" quebra nesse caso. Só a resposta do
serviço traz o campo jsonrpc — é o que distingue falha do serviço de
falha de infraestrutura.
Métodos
Três métodos disponíveis. GET /methods devolve este catálogo em JSON,
útil para descobrir novidades sem consultar esta página.
historicoFinanceiro
Histórico financeiro completo do cliente: todas as duplicatas com situação de
pagamento, juros e multa já calculados, mais um totalizador com indicadores de
comportamento.
documento obrigatório
CPF (11 dígitos) ou CNPJ (14). Pontuação opcional — é normalizada.
dataInicio
AAAA-MM-DD. Filtra por vencimento. Ausente = sem limite.
dataFim
AAAA-MM-DD. Filtra por vencimento. Ausente = sem limite.
somenteBoleto
Restringe a formas de pagamento com boleto. Padrão false.
detalharAgrupadas
Inclui componentes de agrupamentos como linhas informativas, marcadas com ContaNoTotal: false — não entram no totalizador. Padrão false; use apenas quando esse detalhe for necessário.
Pago em dia · Pago em atraso · Boleto a Vencer · Boleto Vencendo hoje · Boleto Vencido
Juros e multa são calculados no momento da consulta, com base nos dias de
atraso até hoje e nos percentuais configurados para a empresa. Duas consultas em
dias diferentes trazem valores diferentes para o mesmo título em aberto.
buscarClienteVeiculo
Localiza o cliente por documento ou placa e devolve cadastro, veículo, situação
financeira em aberto e a última localização registrada.
termo obrigatório
CPF, CNPJ ou placa. Pontuação e hífen são normalizados.
LOCAL vem como link de mapa com a última posição conhecida, ou
null quando não há registro. Valores monetários já vêm formatados em
reais.
Busca por documento de cliente com mais de um veículo devolve apenas o
primeiro registro. Buscando por placa não há ambiguidade — prefira a placa
quando ela for conhecida.
getCliente
Cadastro completo do cliente pelo código interno do ERP. Útil quando o código já é
conhecido por uma consulta anterior.
codCliente obrigatório
Inteiro positivo — o CodCliente do ServiceERP.
Devolve a linha de cadastro do cliente como está no ERP.
Sua chave
GET /chaves mostra a situação da sua chave e quanto dela já foi
consumido hoje — medido no processo em execução, não estimado. Serve para
acompanhar a quota sem precisar perguntar a ninguém.
situacaovalida, sem prazo, expira em N dias, expirada ou revogada.
consumo.diaRequisições feitas hoje. restanteDia é o que sobra da quota.
escopopropria — cada chave enxerga apenas a si mesma.
O valor da chave nunca aparece na resposta, e uma chave não enxerga a existência
das outras. As mesmas informações vêm nos cabeçalhos de toda resposta de
/rpc: X-RateLimit-Remaining-Minute e
X-RateLimit-Remaining-Day.
Chave com prazo. Se a sua tem expiraEm, acompanhe
diasRestantes e peça a substituta antes do vencimento — expirada,
ela passa a receber unauthorized em toda chamada.
Guia de integração
O que separa uma integração que aguenta o dia a dia de uma que quebra na primeira
instabilidade.
1. Decida pelo campo status
Converta antes de comparar. Em falha de infraestrutura o campo pode chegar como
número, e uma comparação estrita de texto quebra:
// resiste a resposta fora do formato esperadoconst corpo = await resposta.json();
const status = String(corpo?.status ?? 'sem_resposta');
const doServico = Boolean(corpo?.jsonrpc); // falso = falha de infraestruturaif (status === 'ok') usar(corpo.result);
else if (status === 'not_found') avisarSemCadastro();
else if (status === 'db_unavailable') repetirMaisTarde();
else registrarFalha(corpo);
2. Repita só o que vale a pena
db_unavailableRepetir depois de alguns segundos, com espera crescente.
Timeout / sem respostaRepetir com espera crescente, no máximo 2 ou 3 vezes.
query_failedNão repetir. O erro está na consulta e vai se repetir igual. Registrar e reportar.
invalid_params · unauthorized · method_not_foundNão repetir. São erros da chamada — repetir só gasta tempo.
not_foundNão repetir. Não é falha: o cadastro não existe.
3. Dimensione o tempo limite
Use 30 segundos. Limites de 3 ou 5 segundos são curtos demais: uma consulta
eventual pode passar disso legitimamente, e a chamada seria abortada sem necessidade.
4. Cuide dos dados que receber
As respostas contêm nome, documento, contato, endereço e situação financeira de
pessoas físicas. Trate como dado pessoal: restrinja quem vê, evite gravar em log
integralmente e não repasse a terceiros sem base legal.
5. Monitore pelo /health
A rota responde sem chave e sempre com HTTP 200 — o campo status traz
ok ou degraded, e database.latencyMs mostra o
tempo de ida e volta até o banco. Serve direto em qualquer monitor externo.
Limites
VolumeLimite por minuto e quota diária, definidos em contrato para cada integração. Ao estourar, 429 com Retry-After. Volumes maiores são combinados previamente.
EscritaNão existe. A API é exclusivamente de leitura — nenhum método altera dados no ERP.
LoteUma chamada por requisição. Vetor de chamadas JSON-RPC não é suportado.
VersionamentoSem versão no caminho. Métodos e campos só são acrescentados; remoção ou mudança de significado é comunicada antes.
Ao adicionar campos. Novos campos podem aparecer nas respostas sem aviso.
Sua integração não deve quebrar com campo desconhecido — leia o que precisa e
ignore o resto.
Garantias
O que a integração pode assumir sobre o comportamento do serviço.
Somente leituraNenhum método altera dados no ERP. Não há operação de escrita exposta, e a credencial usada no banco não tem permissão para escrever.
SíncronoUma requisição, uma resposta, na mesma conexão. Sem fila, sem callback, sem estado entre chamadas.
Sem efeito colateralRepetir uma consulta produz o mesmo resultado e não gera cobrança, registro ou alteração de nada — repetição em caso de falha é segura.
Resposta sempre legívelToda situação prevista devolve o envelope padrão com status e message, inclusive indisponibilidade. O serviço não devolve erro sem explicação.
Dados no momento da consultaNão há cache: cada chamada reflete o estado atual do ERP. Juros e multa são calculados na hora, então o mesmo título em aberto muda de valor conforme os dias passam.
Como funciona
A requisição chega, o serviço consulta a base do ERP e devolve o resultado na mesma
conexão. Não há callback nem URL de retorno para configurar do lado de quem consome.
A base do ERP fica em rede privada e não é acessível pela internet. O serviço de
integração é a única porta de entrada, e expõe apenas as consultas descritas na
referência da API — não há acesso genérico à base.
Quando algo falha
Como o fluxo é síncrono, quem chama fica esperando. O serviço é construído para que
essa espera seja curta mesmo quando a base está indisponível.
Falha temporária de rede
Falhas de conexão são repetidas internamente antes de o serviço desistir. Repetir é
seguro porque todas as consultas são de leitura. Erro na consulta em si não é
repetido — devolve query_failed de imediato, já que
repetir não mudaria o resultado.
Base indisponível
Persistindo a falha, o serviço passa a responder
db_unavailable imediatamente, em vez de deixar cada
requisição esperando. A recuperação é automática: assim que a base volta, o serviço
volta a atender sem intervenção.
Nesse estado a resposta continua no formato padrão, com dbConnected em
false e mensagem pronta para exibir ao usuário final. Vale repetir a
chamada depois de alguns segundos.
Trate também a resposta que não segue o formato. O envelope só existe
enquanto o serviço está no ar para respondê-lo. Se o serviço estiver fora, quem
responde é a camada de rede acima dele, com o formato dela — onde
status costuma ser o número do erro HTTP, não um texto. Só a resposta
do serviço traz o campo jsonrpc.
Tratamento de dados
As respostas contêm nome, documento, contato, endereço e situação financeira de
pessoas físicas. O serviço trata esses dados com os cuidados abaixo, e espera o
mesmo de quem consome.
Acesso identificadoCada integração usa uma chave própria, com limites e validade definidos. Uma chave pode ser revogada isoladamente, sem afetar as demais.
Registro de acessoToda consulta é registrada, permitindo responder quem acessou os dados de um cliente e quando. Os documentos consultados não são gravados em texto claro.
Transporte cifradoSomente HTTPS. Requisições em texto claro não são atendidas.
Monitoramento de usoO padrão de consumo de cada chave é acompanhado. Uso incompatível com o combinado leva à suspensão da chave.
Do lado de quem consome: restrinja quem enxerga as respostas, evite gravar
o conteúdo integral em registros de aplicação, e não repasse os dados a terceiros
sem base legal. A chave dá acesso a dados pessoais — guarde em cofre de segredos
ou variável de ambiente, nunca no código-fonte ou no aplicativo distribuído.
Rotas de serviço
Rota
Chave
Para que serve
GET /health
pública
Estado do serviço. Responde 200 sempre — status vira degraded quando as consultas estão indisponíveis.
GET /ping
pública
Prova de vida do serviço.
GET /methods
chave
Catálogo dos métodos disponíveis, com parâmetros e descrição.
GET /chaves
chave
Situação e consumo da própria chave.
POST /rpc
chave
Execução das consultas.
/health e /ping dispensam chave para permitir monitoração
externa. Nenhuma das duas devolve dado de cliente.