API da Inloco
Base https://inloco.ia.br/api/v1 · openapi.json · api.md
A API da Inloco dá acesso de leitura ao resumo financeiro dos clientes de um workspace: créditos levantados por processo e processo judicial, o detalhe por competência, as compensações feitas e o consumo do crédito mês a mês.
É uma API REST sobre HTTPS, só com GET, que responde JSON. Cada chave pertence a um workspace e só enxerga os clientes dele.
Fluxo típico
- Ache o cliente pelo CNPJ e guarde o
id:GET /clientes?documento=11222333000181 - Leia o resumo: processos judiciais e, dentro de cada um, os processos (créditos levantados):
GET /clientes/<id>/resumo - Abra as competências de um processo:
GET /creditos/<id do processo> - Monte o relatório de compensações do período:
GET /clientes/<id>/compensacoes?de=2026-01-01&ate=2026-12-31 - Desenhe os gráficos de consumo:
GET /clientes/<id>/consumo
Autenticação
Toda requisição leva a chave no cabeçalho Authorization: Bearer <chave>. A chave tem o formato ink_live_ seguido de 43 caracteres. Sem a chave, ou com uma chave revogada, a resposta é 401.
Quem cria a chave é um administrador do workspace na Inloco, em Configurações > Integrações > API. A chave aparece uma única vez, na criação. A Inloco guarda só um hash dela e não consegue mostrá-la de novo.
Ciclo de vida da chave
- Criar: um administrador gera a chave e entrega para quem integra por um canal seguro, como um cofre de senhas compartilhado. Nunca por chat ou e-mail aberto.
- Guardar: no servidor, num gerenciador de segredos ou variável de ambiente (
INLOCO_API_KEY). Nunca no código, no repositório, no front-end, em aplicativo móvel ou em log. - Trocar: o workspace pode ter até 5 chaves ativas. Para trocar sem parar a integração, crie a nova, publique no seu sistema, confirme que está funcionando e só então revogue a antiga. Recomendamos trocar a cada 6 meses e sempre que alguém com acesso à chave sair da equipe.
- Revogar: se a chave vazar ou deixar de ser usada, um administrador revoga em Configurações > Integrações. Ela para de funcionar na hora.
- Acompanhar: a tela mostra quando cada chave foi usada pela última vez. Uso que você não reconhece é motivo para revogar.
Limites e novas tentativas
Cada chave pode fazer até 60 requisições por minuto. Acima disso a resposta é 429 com o cabeçalho Retry-After (em segundos).
Em 429, espere o tempo do Retry-After antes de tentar de novo. Em 500, tente de novo com espera crescente (1 s, 2 s, 4 s...) e no máximo 5 tentativas. Não repita automaticamente 400, 401, 403 nem 404: a mesma chamada vai falhar de novo.
Use um tempo limite de 30 segundos por requisição. Se precisar de muitos clientes, faça as chamadas em sequência, não todas ao mesmo tempo.
Formato das respostas
- Sucesso: status 200 com o conteúdo em
dados. Erro:{"erro": {"codigo": "...", "mensagem": "..."}}. Use ocodigona sua lógica; amensagemé para pessoas e pode mudar. - Valores em reais são números (não texto) com até duas casas decimais.
- Datas em
AAAA-MM-DD, meses emAAAA-MM, competências emMM/AAAA. - Campos sem valor vêm como
null, nunca omitidos. - Os ids são UUIDs estáveis: guarde-os para não precisar buscar de novo.
/clientesdevolve todos os clientes do workspace numa única resposta, sem paginação.
De onde vêm os números
- Os valores são os mesmos que o escritório vê na Inloco, calculados na hora da consulta. Não há defasagem.
- Valores atualizados (
creditoAtualizado,saldoAtualizado) mudam todo mês, com a nova Selic, mesmo sem nenhuma compensação nova. - Só entram compensações concluídas. Rascunhos ficam de fora de todos os totais.
compensadoTotalé a soma do valor compensado nas compensações concluídas.compensadoOriginalecompensadoSelicmostram quanto do valor original e quanto da atualização Selic do crédito foram consumidos. São medidas diferentes: não some uma para conferir a outra.- Para saber quando algo mudou sem consultar o tempo todo, use os webhooks (seção abaixo).
Endpoints
GET/clientes
Lista os clientes do workspace
| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
documento | consulta | não | CNPJ ou CPF, com ou sem pontuação. Filtra pelo documento exato. |
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \ "https://inloco.ia.br/api/v1/clientes?documento=..."
Exemplo de resposta
{
"dados": [
{
"id": "3f6c2a1e-8b4d-4c2f-9a7e-1d2c3b4a5f60",
"nome": "Empresa Exemplo Ltda",
"documento": "11222333000181",
"tipoDocumento": "CNPJ"
}
]
}GET/clientes/{id}/resumo
Créditos do cliente agrupados por processo judicial e processo
Totais do cliente e, para cada processo judicial, os processos (créditos levantados) com levantado, compensado e saldo. Processos sem processo judicial vêm no grupo com processoJudicial: null, por último.
| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
id | caminho | sim | Id do cliente. |
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \ "https://inloco.ia.br/api/v1/clientes/<id>/resumo"
Exemplo de resposta
{
"dados": {
"cliente": {
"id": "3f6c2a1e-8b4d-4c2f-9a7e-1d2c3b4a5f60",
"nome": "Empresa Exemplo Ltda",
"documento": "11222333000181",
"tipoDocumento": "CNPJ"
},
"totais": {
"creditoOriginal": 150000,
"creditoAtualizado": 182340.55,
"compensadoTotal": 60210.4,
"compensadoOriginal": 50000,
"compensadoSelic": 10210.4,
"saldoOriginal": 100000,
"saldoAtualizado": 122130.15,
"compensacoes": 4
},
"porProcessoJudicial": [
{
"processoJudicial": {
"id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"codigo": "PJ-01",
"rotulo": "Exclusão do ICMS da base do PIS/Cofins",
"numeroJudicial": "0000000-00.2020.4.01.3400"
},
"totais": {
"creditoOriginal": 150000,
"creditoAtualizado": 182340.55,
"compensadoTotal": 60210.4,
"compensadoOriginal": 50000,
"compensadoSelic": 10210.4,
"saldoOriginal": 100000,
"saldoAtualizado": 122130.15
},
"processos": [
{
"id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"rotulo": "Habilitação 2021",
"numeroProcesso": "10000.000000/2021-00",
"tipo": "habilitacao_darf",
"tipoRotulo": "Habilitação (DARF)",
"dataHabilitacao": "2021-06-10",
"status": "disponivel",
"parcelas": 12,
"creditoOriginal": 150000,
"creditoAtualizado": 182340.55,
"compensadoTotal": 60210.4,
"compensadoOriginal": 50000,
"compensadoSelic": 10210.4,
"saldoOriginal": 100000,
"saldoAtualizado": 122130.15
}
]
}
]
}
}GET/creditos/{id}
Competências de um crédito levantado
Detalhe do crédito levantado (processo) com cada competência: original, atualizado, compensado e saldo.
| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
id | caminho | sim | Id do crédito levantado, como vem em processos[].id no resumo. |
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \ "https://inloco.ia.br/api/v1/creditos/<id>"
Exemplo de resposta
{
"dados": {
"id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"cliente": {
"id": "3f6c2a1e-8b4d-4c2f-9a7e-1d2c3b4a5f60",
"nome": "Empresa Exemplo Ltda"
},
"rotulo": "Habilitação 2021",
"numeroProcesso": "10000.000000/2021-00",
"numeroProcessoJudicial": "0000000-00.2020.4.01.3400",
"processoJudicialId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"tipo": "habilitacao_darf",
"tipoRotulo": "Habilitação (DARF)",
"dataHabilitacao": "2021-06-10",
"competencias": [
{
"id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
"competencia": "01/2020",
"tipo": null,
"valorOriginal": 12500,
"valorAtualizado": 15195.05,
"valorCompensado": 5000,
"saldoOriginal": 8333.33,
"saldoAtualizado": 10195.05,
"status": "parcialmente_utilizado"
}
]
}
}GET/clientes/{id}/compensacoes
Compensações concluídas do cliente
Rascunhos não entram. Com processo, só vêm as compensações que usaram aquele crédito, e os itens e totais ficam só com a parte dele.
| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
id | caminho | sim | Id do cliente. |
de | consulta | não | Data inicial (inclusive), AAAA-MM-DD. |
ate | consulta | não | Data final (inclusive), AAAA-MM-DD. |
processo | consulta | não | Id do crédito levantado. |
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \ "https://inloco.ia.br/api/v1/clientes/<id>/compensacoes?de=..."
Exemplo de resposta
{
"dados": [
{
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"data": "2026-03-15",
"perdcomp": "12345.67890.150326.1.3.04-1234",
"competenciaCompensada": "02/2026",
"tipo": "habilitacao_darf",
"tipoRotulo": "Habilitação (DARF)",
"debitosCompensados": "IRPJ e CSLL 02/2026",
"valorCompensado": 15052.6,
"valorOriginalUtilizado": 12500,
"valorSelicUtilizado": 2552.6,
"itens": [
{
"creditoLevantadoId": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"competencia": "01/2020",
"valorCompensado": 15052.6,
"valorOriginalUtilizado": 12500,
"valorSelicUtilizado": 2552.6
}
]
}
]
}GET/clientes/{id}/consumo
Consumo do crédito mês a mês
Série mensal do que foi compensado (original e Selic), no total do cliente e por processo. Serve para os gráficos de consumo.
| Parâmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
id | caminho | sim | Id do cliente. |
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \ "https://inloco.ia.br/api/v1/clientes/<id>/consumo"
Exemplo de resposta
{
"dados": {
"cliente": {
"id": "3f6c2a1e-8b4d-4c2f-9a7e-1d2c3b4a5f60",
"nome": "Empresa Exemplo Ltda",
"documento": "11222333000181",
"tipoDocumento": "CNPJ"
},
"total": [
{
"mes": "2026-02",
"original": 37500,
"selic": 7657.8,
"total": 45157.8
},
{
"mes": "2026-03",
"original": 12500,
"selic": 2552.6,
"total": 15052.6
}
],
"porProcesso": [
{
"creditoLevantadoId": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"rotulo": "Habilitação 2021",
"numeroProcesso": "10000.000000/2021-00",
"serie": [
{
"mes": "2026-02",
"original": 37500,
"selic": 7657.8,
"total": 45157.8
},
{
"mes": "2026-03",
"original": 12500,
"selic": 2552.6,
"total": 15052.6
}
]
}
]
}
}Webhooks
Webhooks avisam o seu sistema quando algo muda, para você não precisar consultar a API o tempo todo. Um administrador cadastra a URL em Configurações > Integrações > Webhooks e recebe um segredo (whsec_...), que aparece uma única vez. São até 3 URLs por workspace.
O aviso é enxuto: traz o tipo do evento e os ids, nunca valores. Ao receber, busque os dados atualizados pela API (por exemplo GET /clientes/<clienteId>/resumo). Assim o aviso não carrega dado fiscal, e a API continua sendo a única fonte dos números.
Eventos
| Evento | Quando |
|---|---|
cliente.criado | Cliente cadastrado (ou restaurado depois de excluído). |
cliente.atualizado | Mudou o nome, o documento ou o tipo de documento do cliente. |
cliente.excluido | Cliente excluído. |
compensacao.concluida | Compensação concluída (criada já concluída ou saiu do rascunho). |
compensacao.atualizada | Compensação concluída foi editada, inclusive os itens. |
compensacao.excluida | Compensação concluída foi excluída. |
credito.criado | Crédito levantado (processo) cadastrado. |
credito.atualizado | Crédito levantado ou alguma competência dele mudou. |
credito.excluido | Crédito levantado excluído. |
webhook.teste | Enviado pelo botão "Enviar teste". Não traz dados. |
Corpo do aviso
{
"id": "5b9d2f6e-1c3a-4e8b-9f0d-7a6c5b4e3d2c",
"tipo": "compensacao.concluida",
"criadoEm": "2026-11-10T14:32:05Z",
"workspaceId": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
"dados": {
"clienteId": "3f6c2a1e-8b4d-4c2f-9a7e-1d2c3b4a5f60",
"compensacaoId": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b"
}
}Cabeçalhos
Content-Type | application/json |
User-Agent | Inloco-Webhooks/1 |
X-Inloco-Evento | O tipo do evento, igual a tipo no corpo. |
X-Inloco-Entrega | Id desta entrega. Muda a cada endpoint, mas não muda entre tentativas. |
X-Inloco-Tentativa | Número da tentativa, de 1 a 8. |
X-Inloco-Assinatura | t=<unix>,v1=<hex>: HMAC-SHA256 de <t>.<corpo> com o seu segredo. |
Verificar a assinatura (Node.js)
import crypto from "node:crypto"
const TOLERANCIA_S = 300
export function avisoValido(corpoBruto, cabecalho, segredo) {
const partes = Object.fromEntries(cabecalho.split(",").map((p) => p.split("=")))
const t = Number(partes.t)
if (!t || !partes.v1) return false
if (Math.abs(Date.now() / 1000 - t) > TOLERANCIA_S) return false
const esperado = crypto.createHmac("sha256", segredo).update(`${t}.${corpoBruto}`).digest("hex")
const recebido = Buffer.from(partes.v1, "hex")
return recebido.length === 32 && crypto.timingSafeEqual(recebido, Buffer.from(esperado, "hex"))
}Regras de entrega
- Verifique a assinatura de todo aviso antes de usá-lo, com o corpo exatamente como chegou (antes de converter o JSON). Recuse avisos com mais de 5 minutos, para evitar reenvio de avisos antigos.
- Responda rápido: qualquer status 2xx em até 10 segundos conta como entregue. Grave o aviso numa fila e processe depois; não chame a API antes de responder.
- Novas tentativas: sem 2xx (erro, tempo esgotado ou redirecionamento), tentamos de novo depois de 1, 5, 15, 60, 180, 360 e 720 minutos. São até 8 envios em cerca de 22 horas. Redirecionamentos não são seguidos.
- Duplicados: o mesmo aviso pode chegar mais de uma vez. Use o
iddo corpo para ignorar o que você já processou. - Ordem: os avisos podem chegar fora de ordem. Como eles só trazem ids, sempre busque o estado atual na API em vez de confiar na sequência.
- Agrupamento: várias mudanças seguidas no mesmo recurso, antes do primeiro envio, viram um aviso só.
- Desativação: depois de 50 falhas seguidas o webhook é desativado e aparece assim na tela. Um administrador reativa quando o seu servidor voltar.
- Teste: o botão "Enviar teste" na tela manda um evento
webhook.testena hora e mostra a resposta do seu servidor. - A URL precisa ser pública e usar HTTPS. Endereços locais e de rede interna são recusados. Webhooks só funcionam com a API habilitada no workspace.
Erros
| Status | Código | Quando | O que fazer |
|---|---|---|---|
| 400 | id_invalido | O id no caminho não é um UUID. | Corrija a chamada. |
| 400 | data_invalida | de ou ate fora de AAAA-MM-DD. | Corrija a chamada. |
| 400 | processo_invalido | processo não é um UUID. | Corrija a chamada. |
| 401 | chave_ausente | Sem o cabeçalho Authorization, ou chave fora do formato. | Confira como a chave é enviada. |
| 401 | chave_invalida | Chave inexistente ou revogada. | Peça uma chave nova ao administrador. |
| 403 | sem_permissao | A chave não tem permissão de leitura do resumo. | Peça uma chave nova ao administrador. |
| 403 | api_desabilitada | A API está desligada para o workspace. | Fale com o administrador do workspace. |
| 404 | cliente_nao_encontrado | O cliente não existe neste workspace ou foi excluído. | Busque o cliente de novo em /clientes. |
| 404 | credito_nao_encontrado | O crédito não existe neste workspace. | Releia o resumo do cliente. |
| 429 | limite_excedido | Mais de 60 requisições no minuto. | Espere o Retry-After e tente de novo. |
| 500 | erro_interno | Falha do nosso lado. | Tente de novo com espera crescente. |
Segurança
- Chame a API só do seu servidor, sempre por HTTPS. A API não libera CORS: chamadas feitas de dentro de um navegador são bloqueadas de propósito.
- A chave só lê. Ela não cria, altera nem apaga nada na Inloco.
- Não registre a chave em logs, mensagens de erro ou ferramentas de monitoramento. Se precisar identificar a chave, use só o começo dela (por exemplo
ink_live_ab12cd). - Ids de outros workspaces respondem 404, como se não existissem. Uma chave nunca enxerga dados de outro escritório.
- Cada chamada fica registrada pela Inloco por 90 dias (chave, caminho, status, IP e horário), para auditoria.
Dados pessoais e sigilo
- As respostas trazem dados fiscais sigilosos dos clientes do escritório. Trate-os como confidenciais e siga a LGPD.
- Guarde só o que a sua aplicação usa, pelo tempo que precisar, com acesso restrito a quem precisa ver.
- Se um cliente deixar o escritório, apague os dados dele do seu sistema também.
Versões
- Esta é a versão 1 (
/api/v1). - Podemos acrescentar campos e rotas novos na v1 sem aviso. Sua integração deve ignorar campos que não conhece.
- Mudanças que quebram a integração (remover ou renomear campo, mudar tipo ou significado) só acontecem numa nova versão (
/api/v2), com aviso de pelo menos 90 dias. A v1 continua funcionando durante esse prazo.
Suporte
Dúvidas sobre a integração ou suspeita de vazamento de chave: fale com a Inloco em https://inloco.ia.br/support. Em caso de vazamento, revogue a chave primeiro e avise depois.