# API da Inloco (v1.0.0)

Base: `https://inloco.ia.br/api/v1` · Especificação OpenAPI: `https://inloco.ia.br/api/v1/openapi.json`

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âmetro | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `documento` | consulta | não | CNPJ ou CPF, com ou sem pontuação. Filtra pelo documento exato. |

```bash
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \
  "https://inloco.ia.br/api/v1/clientes?documento=..."
```

Resposta 200 (exemplo):

```json
{
  "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. |

```bash
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \
  "https://inloco.ia.br/api/v1/clientes/<id>/resumo"
```

Resposta 200 (exemplo):

```json
{
  "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. |

```bash
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \
  "https://inloco.ia.br/api/v1/creditos/<id>"
```

Resposta 200 (exemplo):

```json
{
  "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. |

```bash
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \
  "https://inloco.ia.br/api/v1/clientes/<id>/compensacoes?de=..."
```

Resposta 200 (exemplo):

```json
{
  "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. |

```bash
curl -sS -H "Authorization: Bearer $INLOCO_API_KEY" \
  "https://inloco.ia.br/api/v1/clientes/<id>/consumo"
```

Resposta 200 (exemplo):

```json
{
  "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

```json
{
  "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"
  }
}
```

`dados` traz `clienteId` em todos os eventos, mais `compensacaoId` nos de compensação e `creditoId` nos de crédito. Em `webhook.teste`, `dados` vem vazio. Em `cliente.*`, busque o cliente atualizado em `GET /clientes`.

### Cabeçalhos

| Cabeçalho | Conteúdo |
|---|---|
| `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)

```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 `id` do 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.teste` na 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.