Agente MARCOS.
API de leitura

A carteira e os meses fechados no seu sistema.

Para o sistema da administradora ou o ERP da gestora lerem a carteira de hoje, o histórico de avaliações e os meses fechados sem planilha. A API só lê: nenhuma rota altera dados.

Versão 1.0 · outubro de 2026

Endereço base: https://agentemarcos.com.br/api/v1

01 · Autenticação

Um token por sistema, só no cabeçalho.

O Admin da empresa cria o token em Configurações › Tokens de API, confirmando com a senha e com o mesmo 2º fator do login. O segredo aparece uma única vez, na criação ou na rotação. O Agente Marcos guarda só o prefixo e um hash: um token perdido não se recupera, só se rotaciona.

marcos_<8 letras>_<43 caracteres>

O prefixo (marcos_<8 letras>) aparece na tela, na trilha e nos e-mails; o resto, nunca.

Envie o token só no cabeçalho Authorization: Bearer:

curl -H "Authorization: Bearer marcos_xxxxxxxx_…" https://agentemarcos.com.br/api/v1/fundos
  • Token no endereço é recusado (400 token_na_url) antes de qualquer consulta, assim como no cabeçalho Referer: a URL vai para logs e históricos. Se isso acontecer, peça ao Admin para rotacionar o token.
  • Navegador é recusado: pedido com cabeçalho Origin recebe 403 origem_recusada. A API é de sistema para sistema; a sessão do aplicativo não abre /api/v1.
02 · Acesso

O token enxerga o que o dono dele enxerga.

O token lê com o acesso de quem é dono dele, uma pessoa da empresa. O acesso é recalculado a cada requisição.

  • Fundos: o escopo do token, limitado aos fundos que o dono vê hoje e aos que o Admin que criou o token vê hoje. Se o dono perde um fundo, o token perde junto, na hora. Um token de “Todos os fundos” inclui os fundos que o dono passar a ver, inclusive os cadastrados depois.
  • Papel: as mesmas permissões e a mesma máscara das telas, campo a campo. O que a ficha do crédito esconde, a API esconde (vem null):
    • pontos dos eixos, ERV e TIR do cluster e ERV líquido: só com a régua própria da empresa e para o token de Gestor, Analista ou Administradora (o do Auditor, com o termo de confidencialidade em vigor); com a régua padrão ou ajustada, null para qualquer papel;
    • score e níveis F e L (eixos.f, eixos.l): para Gestor, Analista, Administradora e Auditor, também com a régua padrão; null nos créditos avaliados por uma régua própria sobre a régua padrão 2. Quem não vê o score não vê os níveis;
    • Cotista lê só fundos, resumo da carteira e competências, nunca crédito por crédito.
  • CPF e CNPJ: completos só se o token foi criado com “Incluir CPF e CNPJ completos” e o papel do dono vê documento (Gestor e Analista). Senão, saem mascarados (***.***.*89-**; CNPJ **.***.***/0001-**), e o nome do devedor sai com o documento que tiver dentro trocado por [CPF] ou [CNPJ].
  • O token para na hora, e é revogado, quando: o dono sai da empresa ou muda de papel; o Admin que o criou perde a permissão de Admin; a empresa é encerrada; ele vence (até 365 dias, padrão 90); ou é revogado ou rotacionado. Uma leitura em andamento no momento da revogação também recebe 401 token_revogado.
03 · Rotas

Nove rotas, só de leitura.

Todas são GET e respondem JSON. Valores em centavos (inteiro). Datas em ISO 8601 (UTC). Fundo, crédito ou fechamento fora do escopo responde 404, igual a um que não existe: a API não confirma o que o token não vê.

RotaO que devolvePapel do dono
/api/v1/fundosos fundos no escopotodos
/api/v1/fundos/:id/carteiratotais da carteira de hojetodos
/api/v1/fundos/:id/creditosa carteira de hoje, crédito a crédito, paginadaGestor, Analista, Administradora, Auditor
/api/v1/creditos/:idum créditoGestor, Analista, Administradora, Auditor
/api/v1/creditos/:id/avaliacoeso histórico de avaliações de um créditoGestor, Analista, Administradora, Auditor
/api/v1/fundos/:id/competenciasos meses do fundo e o estado de cada umtodos
/api/v1/fundos/:id/fechamentosas versões fechadas de cada mêsGestor, Analista, Administradora, Auditor
/api/v1/fundos/:id/fechamentos/:fechamentoId/itensum mês fechado, crédito a crédito, paginadoGestor, Analista; Administradora e Auditor só da versão vigente: true
/api/v1/trilhaa trilha de auditoria da empresaquem baixa relatório, só com token de todos os fundos

GET /api/v1/fundos

Os fundos no escopo do token, por nome. Resposta: { itens: Fundo[] } (veja Fundo).

Resposta de GET /api/v1/fundos

{
  "itens": [{
    "id": "7f3c9a12-4b6d-4e8f-a1c2-3d5e7f9b1a20",
    "cnpj": "12.345.678/0001-00",
    "nome": "FIDC Exemplo Créditos Judiciais",
    "administradora": "Administradora Exemplo S.A.",
    "situacao": "ativo"
  }]
}

Exemplo com dados sintéticos, como todos desta página.

GET /api/v1/fundos/:id/carteira

Os totais da carteira de hoje do fundo, com uma linha para cada tipo de crédito. Resposta: Carteira.

Resposta de GET /api/v1/fundos/7f3c…/carteira

{
  "fundoId": "7f3c9a12-4b6d-4e8f-a1c2-3d5e7f9b1a20",
  "creditos": 2814,
  "mtmCentavos": 1191250310,
  "creditosE3": 402,
  "foraDoCalculo": 3,
  "familias": [
    { "familia": "privada", "nome": "Cobrança", "creditos": 2814, "valorFaceCentavos": 4210500000, "valorCentavos": 1191250310 },
    { "familia": "litigio", "nome": "Ação em curso", "creditos": 37, "valorFaceCentavos": 1850000000, "valorCentavos": 412500000 }
  ],
  "porEnquadramento": [
    { "enquadramento": "definitivo", "creditos": 1650, "mtmCentavos": 902114500 },
    { "enquadramento": "e3", "creditos": 402, "mtmCentavos": 201335810 },
    { "enquadramento": "fora", "creditos": 762, "mtmCentavos": 87800000 }
  ],
  "porCluster": [
    { "cluster": "A", "creditos": 120, "mtmCentavos": 210500000 },
    { "cluster": "B", "creditos": 640, "mtmCentavos": 498300000 },
    { "cluster": "C", "creditos": 910, "mtmCentavos": 301250310 },
    { "cluster": "D", "creditos": 744, "mtmCentavos": 151200000 },
    { "cluster": "E", "creditos": 400, "mtmCentavos": 30000000 }
  ],
  "estoqueFora": null
}

GET /api/v1/fundos/:id/creditos?pagina=1&porPagina=100

A carteira de hoje, crédito a crédito, na ordem do codigo (e do id no empate). Parâmetros: pagina (a partir de 1, padrão 1) e porPagina (1 a 200, padrão 100). Resposta: { itens: Credito[], pagina, porPagina, total } (veja Credito e Paginação).

Resposta de GET /api/v1/fundos/7f3c…/creditos?pagina=1&porPagina=2

{
  "itens": [{
    "id": "0b8e2d4a-5c1f-4e7a-9d3b-2f6a8c1e4b70",
    "fundoId": "7f3c9a12-4b6d-4e8f-a1c2-3d5e7f9b1a20",
    "codigo": "AUR-000123",
    "devedor": { "nome": "Comércio Exemplo Ltda.", "documento": { "tipo": "cnpj", "numero": "**.***.***/0001-**" } },
    "cnjPrincipal": "0001234-56.2019.8.26.0100",
    "tribunal": "TJSP",
    "fase": "Cumprimento de sentença",
    "ativo": true,
    "valorFaceCentavos": 15000000,
    "saldoCentavos": 14250000,
    "avaliacao": {
      "id": "5d1e7c3b-2a4f-4b6e-8c9d-0e1f2a3b4c5d",
      "em": "2026-10-20T13:05:00.000Z",
      "gatilho": "evento",
      "familia": "privada",
      "score": 62,
      "cluster": "B",
      "banda": "possivel",
      "enquadramento": "definitivo",
      "regraEnquadramento": "5343.definitivo.cumprimento_sentenca",
      "eixos": { "f": 4, "l": 2, "pontosF": null, "pontosL": null, "pontosC": null, "erv": null, "tir": null, "prazoMeses": 18 },
      "ervLiquidoCentavos": null,
      "mtmCentavos": 4120000,
      "inconsistencia": null,
      "reguaVersao": 3,
      "reguaOrigem": "padrao"
    }
  }, {
    "id": "6c2f8a1d-3e5b-4d7f-9a0c-5b7d9e1f3a46",
    "fundoId": "7f3c9a12-4b6d-4e8f-a1c2-3d5e7f9b1a20",
    "codigo": "AUR-000125",
    "devedor": { "nome": "Indústria Exemplo S.A.", "documento": { "tipo": "cnpj", "numero": "**.***.***/0001-**" } },
    "cnjPrincipal": "0004321-65.2021.8.26.0100",
    "tribunal": "TJSP",
    "fase": "Apelação",
    "ativo": true,
    "valorFaceCentavos": 100000000,
    "saldoCentavos": 100000000,
    "avaliacao": {
      "id": "2b4d6f8a-0c1e-4a3b-8d5f-7e9a1c3b5d68",
      "em": "2026-10-20T13:05:00.000Z",
      "familia": "litigio",
      "gatilho": "importacao",
      "estagio": "sentenca_favoravel",
      "chance": 0.55,
      "recebimentoPrevisto": "2029-04-30",
      "enquadramento": "e3",
      "regraEnquadramento": "5343.e3.sentenca_sem_transito",
      "valorJustoCentavos": 31840000,
      "provisaoSucumbenciaCentavos": 0,
      "reguaVersao": 1,
      "reguaOrigem": "padrao"
    }
  }],
  "pagina": 1,
  "porPagina": 2,
  "total": 2814
}

GET /api/v1/creditos/:id

Um crédito da carteira de hoje, com a avaliação vigente. Resposta: Credito.

Resposta de GET /api/v1/creditos/3a9c…

{
  "id": "3a9c1e5f-7b2d-4c8e-a6f4-1d3b5c7e9a02",
  "fundoId": "7f3c9a12-4b6d-4e8f-a1c2-3d5e7f9b1a20",
  "codigo": "AUR-000124",
  "devedor": { "nome": "Maria Exemplo da Silva", "documento": { "tipo": "cpf", "numero": "***.***.*89-**" } },
  "cnjPrincipal": null,
  "tribunal": null,
  "fase": "Não ajuizado",
  "ativo": true,
  "valorFaceCentavos": 870000,
  "saldoCentavos": 870000,
  "avaliacao": {
    "id": "8e2b4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d13",
    "em": "2026-10-02T09:30:00.000Z",
    "gatilho": "importacao",
    "familia": "privada",
    "score": 21,
    "cluster": "E",
    "banda": "remoto",
    "enquadramento": "fora",
    "regraEnquadramento": "5343.fora.nao_ajuizado",
    "eixos": { "f": 1, "l": 1, "pontosF": null, "pontosL": null, "pontosC": null, "erv": null, "tir": null, "prazoMeses": 36 },
    "ervLiquidoCentavos": null,
    "mtmCentavos": 52200,
    "inconsistencia": null,
    "reguaVersao": 3,
    "reguaOrigem": "padrao"
  }
}

GET /api/v1/creditos/:id/avaliacoes

As avaliações do crédito, da mais recente para a mais antiga (até 500). Resposta: { creditoId, itens: Avaliacao[] } (veja Avaliacao).

Resposta de GET /api/v1/creditos/0b8e…/avaliacoes

{
  "creditoId": "0b8e2d4a-5c1f-4e7a-9d3b-2f6a8c1e4b70",
  "itens": [
    {
      "id": "5d1e7c3b-2a4f-4b6e-8c9d-0e1f2a3b4c5d",
      "em": "2026-10-20T13:05:00.000Z",
      "gatilho": "evento",
      "familia": "privada",
      "score": 62,
      "cluster": "B",
      "banda": "possivel",
      "enquadramento": "definitivo",
      "regraEnquadramento": "5343.definitivo.cumprimento_sentenca",
      "eixos": { "f": 4, "l": 2, "pontosF": null, "pontosL": null, "pontosC": null, "erv": null, "tir": null, "prazoMeses": 18 },
      "ervLiquidoCentavos": null,
      "mtmCentavos": 4120000,
      "inconsistencia": null,
      "reguaVersao": 3,
      "reguaOrigem": "padrao"
    },
    {
      "id": "9a7c5e3b-1d2f-4a6c-8e0b-4d6f8a2c1e57",
      "em": "2026-09-28T10:00:00.000Z",
      "gatilho": "importacao",
      "familia": "privada",
      "score": 58,
      "cluster": "B",
      "banda": "possivel",
      "enquadramento": "e3",
      "regraEnquadramento": "5343.e3.sentenca_sem_transito",
      "eixos": { "f": 4, "l": 2, "pontosF": null, "pontosL": null, "pontosC": null, "erv": null, "tir": null, "prazoMeses": 24 },
      "ervLiquidoCentavos": null,
      "mtmCentavos": 3870000,
      "inconsistencia": null,
      "reguaVersao": 3,
      "reguaOrigem": "padrao"
    }
  ]
}

GET /api/v1/fundos/:id/competencias

Os meses do fundo e o estado de cada um. Resposta: { itens: Competencia[] } (veja Competencia).

Resposta de GET /api/v1/fundos/7f3c…/competencias

{
  "itens": [
    {
      "fundoId": "7f3c9a12-4b6d-4e8f-a1c2-3d5e7f9b1a20",
      "mes": "2026-10",
      "estado": "aberta",
      "versao": 1,
      "fechadaEm": null,
      "fechadaPor": null,
      "hash": null,
      "reguaVersao": 3,
      "creditos": 2814,
      "mtmCentavos": 1191250310,
      "foraDoCalculo": 3,
      "outrasFamilias": [{ "familia": "litigio", "creditos": 37, "valorCentavos": 412500000, "reguaVersao": 1 }],
      "emCurso": true,
      "reabertura": null,
      "versaoReaberta": null,
      "trava": null,
      "resolvidos": [{
        "creditoId": "5b8d1f3a-7c2e-4a9b-8d6f-1e3c5a7b9d02",
        "codigo": "CRD-000187",
        "data": "2026-10-14",
        "valorRecebidoCentavos": 1850000,
        "mtmAnteriorCentavos": 1420000,
        "por": "Ana Exemplo",
        "em": "2026-10-15T13:20:00.000Z"
      }],
      "retificaveis": null
    },
    {
      "fundoId": "7f3c9a12-4b6d-4e8f-a1c2-3d5e7f9b1a20",
      "mes": "2026-09",
      "estado": "fechada",
      "versao": 1,
      "fechadaEm": "2026-10-03T14:10:00.000Z",
      "fechadaPor": "Ana Exemplo",
      "hash": "9f2c…64 caracteres…",
      "reguaVersao": 3,
      "creditos": 2811,
      "mtmCentavos": 1183400221,
      "foraDoCalculo": 0,
      "outrasFamilias": [{ "familia": "litigio", "creditos": 37, "valorCentavos": 409800000, "reguaVersao": 1 }],
      "emCurso": false,
      "reabertura": null,
      "versaoReaberta": null,
      "trava": null,
      "resolvidos": [],
      "retificaveis": null
    }
  ]
}

GET /api/v1/fundos/:id/fechamentos

Todas as versões fechadas de cada mês, inclusive as reabertas (seguem listadas; os itens delas, legíveis e idênticos, só para Gestor e Analista). Resposta: { itens: Fechamento[] } (veja Fechamento).

Resposta de GET /api/v1/fundos/7f3c…/fechamentos

{
  "itens": [{
    "id": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e81",
    "fundoId": "7f3c9a12-4b6d-4e8f-a1c2-3d5e7f9b1a20",
    "mes": "2026-09",
    "versao": 1,
    "vigente": true,
    "reabrivel": true,
    "fechadaEm": "2026-10-03T14:10:00.000Z",
    "fechadaPor": "Ana Exemplo",
    "hash": "9f2c…64 caracteres…",
    "hashFormato": 2,
    "reguaVersao": 3,
    "creditos": 2811,
    "mtmCentavos": 1183400221,
    "foraDoCalculo": 0,
    "reabertura": null,
    "previa": { "creditos": 2811, "mtmCentavos": 1183400221, "foraDoCalculo": 0, "reguaVersao": 3, "retificaveis": 0 },
    "retificacao": null,
    "ciencia": { "situacao": "dada", "registros": [{ "por": "Carla Exemplo", "em": "2026-10-04T12:00:00.000Z", "ressalva": null }], "minha": false, "aceitaRessalva": true },
    "envios": [],
    "comEnvio": true,
    "mudancasDeRegua": [],
    "mudancasDaAcaoEmCurso": [],
    "exigenciaDeParecer": { "noInicio": true, "mudancas": [] },
    "resolvidos": []
  }]
}

GET /api/v1/fundos/:id/fechamentos/:fechamentoId/itens?pagina=1&porPagina=100

Um mês fechado, crédito a crédito, com a avaliação gravada no fechamento (a da data de corte), não a de hoje. Com token de dono Administradora ou Auditor, só a versão vigente: true: a reaberta dá 403 so_fechamento_vigente. Mesmos parâmetros pagina e porPagina da carteira. Resposta: { itens: ItemFechamento[], pagina, porPagina, total }; cada item segue o formato ItemFechamento da seção de campos.

Resposta de GET /api/v1/fundos/7f3c…/fechamentos/c2a4…/itens?pagina=1&porPagina=1

{
  "itens": [{
    "creditoId": "0b8e2d4a-5c1f-4e7a-9d3b-2f6a8c1e4b70",
    "codigo": "AUR-000123",
    "valorFaceCentavos": 15000000,
    "avaliacao": {
      "id": "9a7c5e3b-1d2f-4a6c-8e0b-4d6f8a2c1e57",
      "em": "2026-09-28T10:00:00.000Z",
      "gatilho": "importacao",
      "familia": "privada",
      "score": 58,
      "cluster": "B",
      "banda": "possivel",
      "enquadramento": "e3",
      "regraEnquadramento": "5343.e3.sentenca_sem_transito",
      "eixos": { "f": 4, "l": 2, "pontosF": null, "pontosL": null, "pontosC": null, "erv": null, "tir": null, "prazoMeses": 24 },
      "ervLiquidoCentavos": null,
      "mtmCentavos": 3870000,
      "inconsistencia": null,
      "reguaVersao": 3,
      "reguaOrigem": "padrao"
    }
  }],
  "pagina": 1,
  "porPagina": 1,
  "total": 2811
}

GET /api/v1/trilha?desde=0&limite=100

A trilha de auditoria da empresa, em ordem. Como cobre a empresa inteira, só um token de “Todos os fundos” a lê (403 trilha_exige_todos_os_fundos). Parâmetros: desde (o id do último item recebido, padrão 0) e limite (1 a 200, padrão 100). Resposta: { itens: ItemTrilha[], proximo }, com proximo igual ao valor de desde da próxima chamada, ou null no fim (veja ItemTrilha).

Resposta de GET /api/v1/trilha?desde=0&limite=2

{
  "itens": [
    {
      "id": 1,
      "em": "2026-10-03T14:10:00.000Z",
      "ator": "Ana Exemplo",
      "atorTipo": "usuario",
      "acao": "fechamento.fechado",
      "alvo": "2026-09",
      "antesRef": null,
      "depoisRef": "9f2c…64 caracteres…",
      "motivo": null,
      "hashAnterior": null,
      "hash": "41d8…64 caracteres…",
      "hashVersao": 2
    },
    {
      "id": 2,
      "em": "2026-10-04T12:00:00.000Z",
      "ator": "Carla Exemplo",
      "atorTipo": "usuario",
      "acao": "fechamento.ciencia",
      "alvo": "2026-09",
      "antesRef": null,
      "depoisRef": null,
      "motivo": null,
      "hashAnterior": "41d8…64 caracteres…",
      "hash": "a07e…64 caracteres…",
      "hashVersao": 2
    }
  ],
  "proximo": 2
}
04 · Campos

Os campos e o que cada um significa.

Fundo

CampoSignificado
idid do fundo no Agente Marcos
cnpjCNPJ do fundo
nomenome do fundo
administradoraadministradora do fundo, ou null
situacaoativo ou encerrado

Carteira

Os créditos ativos de hoje. Num fundo com Cobrança e Ação em curso, os totais (creditos, mtmCentavos, creditosE3, foraDoCalculo) e as listas porEnquadramento e porCluster são os da Cobrança, e cada tipo de crédito tem a sua linha em familias. Nenhum número soma os tipos: o MTM Base da Cobrança e o valor justo da Ação em curso são medidas diferentes. Num fundo só de Cobrança, os totais são os de todos os créditos ativos e familias traz uma linha só.

CampoSignificado
fundoIdo fundo
creditoscréditos ativos de Cobrança
mtmCentavossoma do MTM Base dos créditos de Cobrança. O valor justo da Ação em curso nunca entra nesta soma: ele é outra medida e fica em valorJustoCentavos de cada crédito
creditosE3créditos de Cobrança com enquadramento e3 (em discussão)
foraDoCalculocréditos sem região na planilha, fora do cálculo do MTM até a região ser informada: contados em creditos e sem MTM
familiasuma linha para cada tipo de crédito com crédito ativo, sempre separadas (a Cobrança primeiro): familia (privada para a Cobrança, litigio para a Ação em curso, como na Avaliacao), nome (o nome do tipo na tela), creditos, valorFaceCentavos (soma do valor de face dos créditos do tipo) e valorCentavos (na Cobrança, o MTM Base; na Ação em curso, o valor justo)
porEnquadramentolista de { enquadramento, creditos, mtmCentavos } dos créditos de Cobrança
porClusterlista de { cluster, creditos, mtmCentavos } dos créditos de Cobrança (a Ação em curso não tem cluster)
estoqueForana carteira que veio da exportação do sistema da administradora, { linhas, valorNominalCentavos, referenciaEm } dos recebíveis sem número de processo válido, que ficam fora do monitoramento: não entram em creditos nem em mtmCentavos. referenciaEm é a data de referência da exportação, ou null. null nos outros layouts

Credito

CampoSignificado
idid do crédito no Agente Marcos (estável)
fundoIdfundo do crédito
codigoo código do crédito na planilha do cliente
devedor.nomenome do devedor
devedor.documento{ tipo: 'cpf' | 'cnpj', numero }, completo ou mascarado (veja Acesso); null se a planilha não trouxe
cnjPrincipalnúmero CNJ do processo principal, ou null
tribunalsigla do tribunal (ex.: TJSP), ou null
fasea fase do processo como veio na planilha do cliente, texto livre
ativofalse quando o crédito saiu da carteira
valorFaceCentavosvalor de face
saldoCentavossaldo devedor (o valor de face, se a planilha não trouxe saldo)
avaliacaoa avaliação vigente (Avaliacao), ou null se o crédito ainda não foi avaliado

Avaliacao

Uma avaliação gravada nunca muda. O campo familia diz qual régua avaliou o crédito e quais campos vêm: privada (Cobrança, com score, cluster e MTM Base em mtmCentavos) ou litigio (Ação em curso, com a fase da ação, a chance de receber e o valor justo em valorJustoCentavos). Os dois valores têm nomes diferentes para que nunca sejam somados.

CampoSignificado
id, emid e momento da avaliação
familiaprivada (Cobrança) ou litigio (Ação em curso)
gatilhoo que causou a avaliação: importacao (carga da carteira), evento (andamento dos autos com prova), regua (régua nova aplicada), cobranca (base de cobrança), correcao (correção de campo), ajuste_de_partida (ajuste da carteira de partida), patrimonio (bem localizado ou bloqueado), resolucao_desfeita (marcação de liquidado desfeita pelo Gestor: o crédito volta à carteira avaliado pela régua vigente)
Só na Cobrança (familia: "privada")
score0 a 100: combina processo (F), patrimônio (L) e cobrança (C) com os pesos da régua; null conforme o papel (veja Acesso)
clusterfaixa de risco pelo score: A (melhor) a E (pior); RJ quando o devedor está em recuperação judicial
bandaprovavel, possivel ou remoto: a faixa de score mais alta, intermediária ou mais baixa da régua
enquadramentoResolução CMN 5.343: fora (fora do escopo), e3 (em discussão) ou definitivo
regraEnquadramentoa regra que decidiu o enquadramento (tabela abaixo)
eixos.fnível do eixo processual, de 0 (não ajuizado) a 5 (leilão ou acordo); null junto com o score
eixos.lnível do eixo patrimonial, de 0 (nenhum bem) a 5 (dinheiro bloqueado); null junto com o score
eixos.pontosF, eixos.pontosL, eixos.pontosCpontos de cada eixo na régua; null fora da régua própria
eixos.erv, eixos.tirERV e TIR do cluster, em fração (0,12 = 12%); null fora da régua própria
eixos.prazoMesesprazo estimado até a recuperação, em meses, ou null
ervLiquidoCentavosvalor esperado de recuperação depois dos custos do caso; null fora da régua própria
mtmCentavosMTM: o valor de marcação do crédito (o ERV líquido trazido a valor presente pela TIR do cluster, no prazo)
inconsistenciaregiao_pendente: sem região na planilha, fora do cálculo do MTM até a região ser informada (o mtmCentavos 0 não é preço); null quando calculado
Só na Ação em curso (familia: "litigio")
estagioa fase da ação: conhecimento (ação de conhecimento, sem sentença), sentenca_favoravel, acordao_favoravel e transito_favoravel (sentença, acórdão ou trânsito em julgado favoráveis), cumprimento (cumprimento de sentença com valor definido), deposito (valor depositado ou penhorado, aguardando levantamento), sentenca_desfavoravel, acordao_desfavoravel e transito_desfavoravel (decisões desfavoráveis)
chancea chance de receber aplicada, em fração (0,55 = 55%): vem da fase da ação e da classe do devedor; a avaliação do advogado, quando informada, só pode baixá-la
recebimentoPrevistoa data em que se espera receber (AAAA-MM-DD)
valorJustoCentavoso valor justo da ação: o valor esperado vezes a chance de receber, menos os custos, trazido a valor presente até o recebimento previsto
provisaoSucumbenciaCentavosa provisão para honorários de sucumbência se a ação for perdida; fica fora do valor justo
Nos dois tipos
reguaVersaoversão da régua do fundo usada nesta avaliação
reguaOrigempadrao (a régua padrão), ajustada (parte dos números da empresa) ou empresa (régua própria)

regraEnquadramento

ValorEnquadramentoQuando
5343.fora.nao_ajuizadoforacrédito sem ação judicial
5343.fora.titulo_em_execucaoforatítulo em execução
5343.fora.concursalforadevedor em processo concursal
5343.e3.embargos_pendentesem discussãoimpugnação, embargos ou defesa pendentes de julgamento (na régua padrão 3, também com acordo)
5343.e3.acao_conhecimentoem discussãoação de conhecimento em curso
5343.e3.sentenca_sem_transitoem discussãosentença sem trânsito em julgado
5343.e3.impugnacao_nao_superadaem discussãocumprimento de sentença com o prazo de impugnação não superado
5343.definitivo.cumprimento_sentencadefinitivocumprimento de sentença
5343.definitivo.confissao_dividadefinitivoconfissão de dívida
5343.fora.origemforaclasse de origem do crédito com efeito fora do escopo
5343.e3.origemem discussãoclasse de origem do crédito com efeito em discussão
5343.definitivo.origemdefinitivoclasse de origem do crédito com efeito definitivo

ItemFechamento

{ creditoId, codigo, valorFaceCentavos, avaliacao }: o crédito no mês fechado, com a Avaliacao gravada no fechamento. valorFaceCentavos pode ser null quando a fotografia não o registrou. A soma de mtmCentavos dos itens de Cobrança é o mtmCentavos do Fechamento; os itens da Ação em curso trazem valorJustoCentavos, fora dessa soma.

Competencia

CampoSignificado
fundoId, meso fundo e o mês (AAAA-MM)
estadoaberta, fechando ou fechada
versaoa versão vigente (fechada) ou a que o próximo fechamento gravará (aberta)
fechadaEm, fechadaPor, hashquando, quem e o hash da versão fechada; null enquanto aberta
reguaVersao, creditos, mtmCentavos, foraDoCalculoos números do mês (da versão fechada, ou os de agora se aberta); num fundo com Cobrança e Ação em curso, são os da Cobrança
outrasFamiliasos outros tipos de crédito do mês, uma linha para cada, nunca somados ao MTM Base: familia (litigio para a Ação em curso), creditos, valorCentavos (o valor justo) e reguaVersao (a versão da régua dela no mês; nula em fechamento anterior às réguas por tipo); lista vazia no fundo só da Cobrança
emCursotrue quando o mês ainda não terminou (não fecha)
reaberturaaberta depois de reabrir: { motivo, por, em } da reabertura da versão anterior; null nos outros casos. motivo e por vêm null para o Cotista
versaoReabertaaberta depois de reabrir: { versao, creditos, mtmCentavos, foraDoCalculo, reguaVersao } da versão reaberta, para comparar; null nos outros casos
travaaberta que ainda não fecha porque a 1ª coleta nos tribunais não terminou: codigo (primeira_coleta_em_andamento), mensagem (a frase que o aplicativo mostra), feitos e total (processos já consultados e ligados ao fundo), falhas (processos com falha na leitura ou atrasados; feitos + falhas não passa de total) e falta: com um só processo faltando, { processo, desde, ate } (o número dele, desde quando espera resposta e até que dia, AAAA-MM-DD, ele segura o fechamento); senão null. null na fechada, para o Cotista e depois do 1º fechamento
resolvidosos créditos marcados como liquidados ou recebidos com data dentro do mês: creditoId, codigo, data (do recebimento), valorRecebidoCentavos (o MTM do crédito resolvido), mtmAnteriorCentavos (o MTM que ele tinha ao sair da carteira ativa), por e em (quem marcou e quando). Na fechada, os que valiam no fechamento; na aberta, os de agora
retificaveissempre null nesta API (no aplicativo, a lista dos créditos com correção feita depois do mês que podem entrar na versão seguinte de um mês reaberto: creditoId, codigo, avaliacaoId, bloqueio, antes e depois com { cluster, mtmCentavos, foraDoCalculo }, e correcoes com { texto, por, em })

Fechamento

CampoSignificado
id, fundoId, mes, versaoa versão fechada do mês; o id é o :fechamentoId da rota de itens
vigentefalse quando a versão foi reaberta (segue listada; os itens dela, legíveis e idênticos, só para Gestor e Analista)
reabrivelé a fechada mais recente do fundo (só ela reabre)
fechadaEm, fechadaPorquando e quem fechou (fechadaPor pode ser null)
hash, hashFormatoo hash da fotografia gravada e o formato dele (1, 2 ou 3)
reguaVersao, creditos, mtmCentavos, foraDoCalculoos números gravados no fechamento. Num fundo com Cobrança e Ação em curso, creditos e mtmCentavos são os da Cobrança: o valor justo da Ação em curso não se soma ao MTM Base
reabertura{ motivo, por, em } se esta versão foi reaberta, ou null
previasó na reabrível: { creditos, mtmCentavos, foraDoCalculo, reguaVersao } que a versão seguinte gravaria se o mês fosse reaberto e fechado agora, e retificaveis (quantos créditos têm correção feita depois do mês que pode entrar nela); null nas outras
retificacaoesta versão substitui outra: versaoSubstituida e creditos, os créditos com o preço retificado nesta versão do fechamento (codigo, clusterAntes, clusterDepois, mtmAntesCentavos, mtmDepoisCentavos, correcao e em); null nas outras
cienciaa ciência da administradora: situacao (pendente, dada, dispensada quando a contratante é a própria administradora, reaberta quando a versão foi substituída), registros ({ por, em, ressalva } de cada ciência; ressalva é o texto registrado com ela, ou null), minha (o dono do token já deu ciência desta versão) e aceitaRessalva (a ciência pode levar uma ressalva agora)
enviosos e-mails desta versão, do mais antigo ao mais novo: id, usuarioId e para (quem recebeu), papel dessa pessoa, motivo (fechamento ou reenvio), em, situacao (na_fila, enviado ou nao_enviado), terminouEm, falha (o motivo, em texto), enderecoRecusado (o servidor de e-mail recusou o endereço) e desligado (ambiente sem envio de e-mail)
comEnvioo fechamento saiu com o relatório emitido e o envio por e-mail
mudancasDeReguaas versões da régua aplicadas dentro do mês: versao, fechouCom (o fechamento usou esta versão), por, em, motivo, parecerExigido, parecer ({ arquivo, sha256, tamanhoBytes, paginas, paginasSemTexto } do parecer anexado, ou null) e previa, os números da prévia com que foi aplicada: em, creditos, movem, mudamCluster, mudamBanda, mudamEnquadramento, saemDoCalculo, voltamAoCalculo, mtmAntesCentavos, mtmDepoisCentavos e deltaMtmCentavos
mudancasDaAcaoEmCursoo mesmo para a régua da Ação em curso, que tem numeração de versão própria (vazio quando ela não mudou no mês): versao, fechouCom (o fechamento usou esta versão para a Ação em curso), por, em, motivo, perfil (o nome do perfil escolhido no assistente: Conservador, Padrão, Arrojado ou Personalizado; null na régua aplicada sem o assistente), perfilId (o mesmo perfil por um identificador que não muda, para ler por programa: conservador, padrao, arrojado ou personalizado; null junto com perfil), parecerExigido, parecer (como acima, ou null) e previa, os números da prévia com que foi aplicada: creditos, movem, mtmAntesCentavos e mtmDepoisCentavos
exigenciaDeParecera exigência de parecer para mudar a régua no mês: noInicio (valia no começo do mês) e mudancas ({ exigir, por, em } de cada mudança)
resolvidosos créditos marcados como liquidados ou recebidos com data dentro do mês, como estavam no fechamento (a lista de uma versão fechada não muda): creditoId, codigo, data (do recebimento), valorRecebidoCentavos (o MTM do crédito resolvido), mtmAnteriorCentavos (o MTM que ele tinha ao sair da carteira ativa), por e em (quem marcou e quando)

ItemTrilha

CampoSignificado
id, emnúmero sequencial e momento do registro
ator, atorTipoquem fez e o tipo de autor: usuario (pessoa da empresa, inclusive as leituras pelo token dela), sistema ou operador (da Liqi)
acao, alvoo que foi feito e sobre o quê. Quando o alvo é uma conta da equipe Liqi (a saída de cada conta da Liqi na entrada da empresa, membro.desativado_na_entrada), alvo vem null, com alvoOmitido
antesRef, depoisRefreferência (hash) do estado antes e depois, ou null
motivoo motivo escrito por quem agiu, ou null. Sem documento no escopo do token, CPF e CNPJ saem redigidos. Ação de operador da Liqi vem sem o motivo, que é interno
motivoOmitidopresente e true nas ações antigas de operador em que o motivo entrou no hash e foi omitido: o hash delas não se refaz a partir do item (vale o encadeamento)
alvoOmitidopresente e true quando o alvo gravado é uma conta da equipe Liqi e sai como null (antes desta versão, o item trazia o identificador da conta). O registro continua na trilha, com id, hashAnterior e hash gravados: o hash dele não se refaz a partir do item, porque foi calculado com o alvo, e a conferência vale pelo encadeamento (o hashAnterior do registro seguinte é o hash dele, e o hashAnterior dele é o hash do anterior)
hashAnterior, hash, hashVersaoo encadeamento: cada registro aponta o hash do anterior, o que permite conferir a cadeia
05 · Paginação

A carteira de hoje e os meses fechados.

pagina (a partir de 1) e porPagina (1 a 200, padrão 100); a resposta traz pagina, porPagina e total. A ordem é o codigo do crédito e, no empate, o id. Parâmetro desconhecido responde 400 parametro_desconhecido; valor fora da faixa, 400 dados_invalidos.

  • Carteira de hoje (/fundos/:id/creditos, /creditos/:id, /fundos/:id/carteira): a avaliação vigente agora, que muda a cada andamento, importação ou régua nova. Se a carteira mudar durante a leitura, um crédito pode pular de página ou aparecer duas vezes: deduplique por id e confira total no fim.
  • Mês fechado (/fundos/:id/fechamentos e /fechamentos/:fechamentoId/itens): não muda, então a paginação é estável. Para uma leitura consistente, leia o mês fechado.

Como ler e conferir um mês fechado

  • Chame GET /api/v1/fundos/:id/fechamentos e escolha a versão (mes, versao; vigente: true é a que vale).
  • Pagine GET /api/v1/fundos/:id/fechamentos/:fechamentoId/itens?pagina=N&porPagina=200 até a página vir com menos itens do que o porPagina pedido.
  • Confira: o número de itens é igual a total e a creditos do fechamento, e a soma de avaliacao.mtmCentavos dos itens é igual ao mtmCentavos do fechamento. Se a leitura parou no meio (erro, rede, 429 sem esperar), o mês está incompleto: não grave a soma parcial como fechamento.

Exemplo: ler a carteira de hoje inteira

Em bash, com curl e jq. Só termina com sucesso (código 0) quando a soma das páginas bate com total. Num 429, espera os segundos do Retry-After e pede a mesma página de novo (até 10 vezes seguidas); em 401, 403, 5xx ou rede caída, para com código 1; se a soma não bater com total, para com código 2. Para o mês fechado, o laço é o mesmo em /fundos/$FUNDO/fechamentos/$FECHAMENTO/itens, conferindo também a soma do MTM dos itens com a do fechamento.

#!/usr/bin/env bash
# Lê a carteira de hoje de um fundo, página a página. Sai com 0 só quando leu tudo (soma das páginas = total).
# Uso: TOKEN=marcos_… FUNDO=<id> ./ler-carteira.sh
set -u
API="${API:-https://agentemarcos.com.br/api/v1}"
p=1; lidos=0; total=0; esperas=0
while :; do
  cab=$(mktemp)
  status=$(curl -sS -o "pagina-$p.json" -D "$cab" -w '%{http_code}' \
    -H "Authorization: Bearer $TOKEN" "$API/fundos/$FUNDO/creditos?pagina=$p&porPagina=200") || status=000
  espera=$(awk -F': *' 'tolower($1) == "retry-after" { gsub("\r", ""); print $2 }' "$cab")
  rm -f "$cab"
  if [ "$status" = 429 ] && [ "$esperas" -lt 10 ]; then
    # limite da API: Retry-After diz quantos segundos esperar; o limite por endereço IP não traz o cabeçalho: 60 s
    echo "Limite da API na página $p: esperando ${espera:-60} s para continuar." >&2
    sleep "${espera:-60}"; esperas=$((esperas + 1)); continue
  fi
  if [ "$status" != 200 ]; then
    echo "Extração INCOMPLETA: HTTP $status na página $p; $lidos de $total créditos lidos." >&2
    cat "pagina-$p.json" >&2 2>/dev/null; echo >&2
    exit 1
  fi
  esperas=0
  if ! n=$(jq -e '.itens | length' "pagina-$p.json") || ! total=$(jq -e '.total' "pagina-$p.json"); then
    echo "Extração INCOMPLETA: resposta sem itens ou sem total na página $p." >&2
    exit 1
  fi
  lidos=$((lidos + n))
  [ "$n" -lt 200 ] && break
  p=$((p + 1))
done
if [ "$lidos" -ne "$total" ]; then
  echo "Extração INCOMPLETA: $lidos créditos lidos, a API diz $total (a carteira mudou durante a leitura)." >&2
  exit 2
fi
echo "Carteira completa: $lidos créditos em $p páginas."
06 · Erros

Erros em português, com código estável.

Formato: { "erro": { "codigo": "...", "mensagem": "..." } }. Programe pelo código; a mensagem é para pessoas.

Sem Authorization, a resposta tem status 401 e traz WWW-Authenticate: Bearer.

Resposta de GET /api/v1/fundos

{
  "erro": {
    "codigo": "token_invalido",
    "mensagem": "Token de API ausente ou inválido. Envie o token no cabeçalho Authorization: Bearer <token>."
  }
}
StatusCódigoQuando
400token_na_urlo token veio no endereço ou no Referer
400parametro_desconhecidoparâmetro de consulta que a rota não aceita
400dados_invalidosparâmetro fora do formato ou da faixa
401token_invalidosem cabeçalho, formato errado ou token inexistente (mesma resposta, com WWW-Authenticate: Bearer)
401token_revogadoo token foi revogado ou rotacionado
401token_expiradoo token venceu
401token_sem_donoo dono do token ou o Admin que o criou perdeu esse acesso (o token foi revogado)
401empresa_inativaa empresa do token não está ativa
403origem_recusadapedido de navegador
403sem_permissaoo papel do dono não lê esta rota
403trilha_exige_todos_os_fundostrilha com token de fundos nomeados
403so_fechamento_vigenteitens de uma versão reaberta com token de dono Administradora ou Auditor (só a vigente)
404fundo_nao_encontradoo fundo não existe ou está fora do escopo
404credito_nao_encontradoo crédito não existe ou está fora do escopo
404fechamento_nao_encontradoo fechamento não existe ou está fora do escopo
429teto_apio token ou a empresa chegou a um limite de volume; o cabeçalho Retry-After diz em quantos segundos voltar
429muitas_tentativasmuitas requisições por segundo do mesmo endereço IP; vem sem Retry-After: espere um minuto
07 · Limites

Limites de volume.

LimiteValor
Requisições por token, por hora600
Requisições por token, em 24 horas5.000
Linhas lidas por token, em 24 horas100.000
Linhas lidas pela empresa (todos os tokens), em 24 horas300.000
Itens por páginaaté 200
Requisições por endereço IP (qualquer token)20 por segundo, com rajada de 40

A janela de 24 horas anda de hora em hora. O limite por endereço IP conta o endereço, não o token: quem pagina em paralelo bate nele antes e recebe 429 muitas_tentativas; leia uma página por vez. Com porPagina=200, uma carteira de 50 mil créditos sai em 250 requisições, dentro dos limites de um token.

429 teto_api e Retry-After: a resposta traz o cabeçalho Retry-After com os segundos até o limite estourado voltar a ter folga. No limite por hora, é o começo da próxima hora; nos de 24 horas, o momento em que as horas mais antigas saem da janela. Espere esse tempo e retome da página em que parou.

Ao passar de 80% do limite de 24 horas, o dono do token e os Admins da empresa recebem um e-mail de leitura acima do normal, com a rota e o endereço de origem da leitura; ao chegar ao limite, outro e-mail. Cada aviso vai uma vez por nível a cada 24 horas.

08 · Trilha e guarda

Cada leitura fica gravada na trilha.

  • Cada leitura entra na trilha de auditoria (api.leitura) com o prefixo do token, a rota, o número de linhas e o endereço IP. Recusa depois de autenticado entra como api.negada; o limite atingido, como api.teto.
  • Criar, rotacionar e revogar entram como token_api.criado, token_api.rotacionado e token_api.revogado. Senha ou código errados ao criar ou rotacionar contam para o bloqueio da conta, como no login.
  • O segredo nunca aparece em log, mensagem de erro, trilha nem e-mail: só o prefixo.
  • Guarde o token no cofre de segredos do sistema que lê, nunca em planilha, e-mail ou código-fonte. O prefixo marcos_ existe para que varreduras de segredo o reconheçam.
  • Rotacione pelo menos a cada 90 dias e sempre que alguém que viu o segredo sair do projeto.

Escreva para contato@liqi.com.br com dúvidas sobre a API.