API v1.0.0

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

  1. Ache o cliente pelo CNPJ e guarde o id: GET /clientes?documento=11222333000181
  2. Leia o resumo: processos judiciais e, dentro de cada um, os processos (créditos levantados): GET /clientes/<id>/resumo
  3. Abra as competências de um processo: GET /creditos/<id do processo>
  4. Monte o relatório de compensações do período: GET /clientes/<id>/compensacoes?de=2026-01-01&ate=2026-12-31
  5. 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 o codigo na sua lógica; a mensagem é 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 em AAAA-MM, competências em MM/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.
  • /clientes devolve 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. compensadoOriginal e compensadoSelic mostram 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âmetroOndeObrigatórioDescrição
documentoconsultanãoCNPJ 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âmetroOndeObrigatórioDescrição
idcaminhosimId 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âmetroOndeObrigatórioDescrição
idcaminhosimId 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âmetroOndeObrigatórioDescrição
idcaminhosimId do cliente.
deconsultanãoData inicial (inclusive), AAAA-MM-DD.
ateconsultanãoData final (inclusive), AAAA-MM-DD.
processoconsultanãoId 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âmetroOndeObrigatórioDescrição
idcaminhosimId 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

EventoQuando
cliente.criadoCliente cadastrado (ou restaurado depois de excluído).
cliente.atualizadoMudou o nome, o documento ou o tipo de documento do cliente.
cliente.excluidoCliente excluído.
compensacao.concluidaCompensação concluída (criada já concluída ou saiu do rascunho).
compensacao.atualizadaCompensação concluída foi editada, inclusive os itens.
compensacao.excluidaCompensação concluída foi excluída.
credito.criadoCrédito levantado (processo) cadastrado.
credito.atualizadoCrédito levantado ou alguma competência dele mudou.
credito.excluidoCrédito levantado excluído.
webhook.testeEnviado 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-Typeapplication/json
User-AgentInloco-Webhooks/1
X-Inloco-EventoO tipo do evento, igual a tipo no corpo.
X-Inloco-EntregaId desta entrega. Muda a cada endpoint, mas não muda entre tentativas.
X-Inloco-TentativaNúmero da tentativa, de 1 a 8.
X-Inloco-Assinaturat=<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

Erros

StatusCódigoQuandoO que fazer
400id_invalidoO id no caminho não é um UUID.Corrija a chamada.
400data_invalidade ou ate fora de AAAA-MM-DD.Corrija a chamada.
400processo_invalidoprocesso não é um UUID.Corrija a chamada.
401chave_ausenteSem o cabeçalho Authorization, ou chave fora do formato.Confira como a chave é enviada.
401chave_invalidaChave inexistente ou revogada.Peça uma chave nova ao administrador.
403sem_permissaoA chave não tem permissão de leitura do resumo.Peça uma chave nova ao administrador.
403api_desabilitadaA API está desligada para o workspace.Fale com o administrador do workspace.
404cliente_nao_encontradoO cliente não existe neste workspace ou foi excluído.Busque o cliente de novo em /clientes.
404credito_nao_encontradoO crédito não existe neste workspace.Releia o resumo do cliente.
429limite_excedidoMais de 60 requisições no minuto.Espere o Retry-After e tente de novo.
500erro_internoFalha 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.