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.
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çalhoReferer: 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
Originrecebe403 origem_recusada. A API é de sistema para sistema; a sessão do aplicativo não abre/api/v1.
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,
nullpara 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;nullnos 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.
- 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,
- 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.
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ê.
| Rota | O que devolve | Papel do dono |
|---|---|---|
/api/v1/fundos | os fundos no escopo | todos |
/api/v1/fundos/:id/carteira | totais da carteira de hoje | todos |
/api/v1/fundos/:id/creditos | a carteira de hoje, crédito a crédito, paginada | Gestor, Analista, Administradora, Auditor |
/api/v1/creditos/:id | um crédito | Gestor, Analista, Administradora, Auditor |
/api/v1/creditos/:id/avaliacoes | o histórico de avaliações de um crédito | Gestor, Analista, Administradora, Auditor |
/api/v1/fundos/:id/competencias | os meses do fundo e o estado de cada um | todos |
/api/v1/fundos/:id/fechamentos | as versões fechadas de cada mês | Gestor, Analista, Administradora, Auditor |
/api/v1/fundos/:id/fechamentos/:fechamentoId/itens | um mês fechado, crédito a crédito, paginado | Gestor, Analista; Administradora e Auditor só da versão vigente: true |
/api/v1/trilha | a trilha de auditoria da empresa | quem 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
}
Os campos e o que cada um significa.
Fundo
| Campo | Significado |
|---|---|
id | id do fundo no Agente Marcos |
cnpj | CNPJ do fundo |
nome | nome do fundo |
administradora | administradora do fundo, ou null |
situacao | ativo 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ó.
| Campo | Significado |
|---|---|
fundoId | o fundo |
creditos | créditos ativos de Cobrança |
mtmCentavos | soma 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 |
creditosE3 | créditos de Cobrança com enquadramento e3 (em discussão) |
foraDoCalculo | créditos sem região na planilha, fora do cálculo do MTM até a região ser informada: contados em creditos e sem MTM |
familias | uma 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) |
porEnquadramento | lista de { enquadramento, creditos, mtmCentavos } dos créditos de Cobrança |
porCluster | lista de { cluster, creditos, mtmCentavos } dos créditos de Cobrança (a Ação em curso não tem cluster) |
estoqueFora | na 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
| Campo | Significado |
|---|---|
id | id do crédito no Agente Marcos (estável) |
fundoId | fundo do crédito |
codigo | o código do crédito na planilha do cliente |
devedor.nome | nome do devedor |
devedor.documento | { tipo: 'cpf' | 'cnpj', numero }, completo ou mascarado (veja Acesso); null se a planilha não trouxe |
cnjPrincipal | número CNJ do processo principal, ou null |
tribunal | sigla do tribunal (ex.: TJSP), ou null |
fase | a fase do processo como veio na planilha do cliente, texto livre |
ativo | false quando o crédito saiu da carteira |
valorFaceCentavos | valor de face |
saldoCentavos | saldo devedor (o valor de face, se a planilha não trouxe saldo) |
avaliacao | a 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.
| Campo | Significado |
|---|---|
id, em | id e momento da avaliação |
familia | privada (Cobrança) ou litigio (Ação em curso) |
gatilho | o 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") | |
score | 0 a 100: combina processo (F), patrimônio (L) e cobrança (C) com os pesos da régua; null conforme o papel (veja Acesso) |
cluster | faixa de risco pelo score: A (melhor) a E (pior); RJ quando o devedor está em recuperação judicial |
banda | provavel, possivel ou remoto: a faixa de score mais alta, intermediária ou mais baixa da régua |
enquadramento | Resolução CMN 5.343: fora (fora do escopo), e3 (em discussão) ou definitivo |
regraEnquadramento | a regra que decidiu o enquadramento (tabela abaixo) |
eixos.f | nível do eixo processual, de 0 (não ajuizado) a 5 (leilão ou acordo); null junto com o score |
eixos.l | nível do eixo patrimonial, de 0 (nenhum bem) a 5 (dinheiro bloqueado); null junto com o score |
eixos.pontosF, eixos.pontosL, eixos.pontosC | pontos de cada eixo na régua; null fora da régua própria |
eixos.erv, eixos.tir | ERV e TIR do cluster, em fração (0,12 = 12%); null fora da régua própria |
eixos.prazoMeses | prazo estimado até a recuperação, em meses, ou null |
ervLiquidoCentavos | valor esperado de recuperação depois dos custos do caso; null fora da régua própria |
mtmCentavos | MTM: o valor de marcação do crédito (o ERV líquido trazido a valor presente pela TIR do cluster, no prazo) |
inconsistencia | regiao_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") | |
estagio | a 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) |
chance | a 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 |
recebimentoPrevisto | a data em que se espera receber (AAAA-MM-DD) |
valorJustoCentavos | o valor justo da ação: o valor esperado vezes a chance de receber, menos os custos, trazido a valor presente até o recebimento previsto |
provisaoSucumbenciaCentavos | a provisão para honorários de sucumbência se a ação for perdida; fica fora do valor justo |
| Nos dois tipos | |
reguaVersao | versão da régua do fundo usada nesta avaliação |
reguaOrigem | padrao (a régua padrão), ajustada (parte dos números da empresa) ou empresa (régua própria) |
regraEnquadramento
| Valor | Enquadramento | Quando |
|---|---|---|
5343.fora.nao_ajuizado | fora | crédito sem ação judicial |
5343.fora.titulo_em_execucao | fora | título em execução |
5343.fora.concursal | fora | devedor em processo concursal |
5343.e3.embargos_pendentes | em discussão | impugnação, embargos ou defesa pendentes de julgamento (na régua padrão 3, também com acordo) |
5343.e3.acao_conhecimento | em discussão | ação de conhecimento em curso |
5343.e3.sentenca_sem_transito | em discussão | sentença sem trânsito em julgado |
5343.e3.impugnacao_nao_superada | em discussão | cumprimento de sentença com o prazo de impugnação não superado |
5343.definitivo.cumprimento_sentenca | definitivo | cumprimento de sentença |
5343.definitivo.confissao_divida | definitivo | confissão de dívida |
5343.fora.origem | fora | classe de origem do crédito com efeito fora do escopo |
5343.e3.origem | em discussão | classe de origem do crédito com efeito em discussão |
5343.definitivo.origem | definitivo | classe 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
| Campo | Significado |
|---|---|
fundoId, mes | o fundo e o mês (AAAA-MM) |
estado | aberta, fechando ou fechada |
versao | a versão vigente (fechada) ou a que o próximo fechamento gravará (aberta) |
fechadaEm, fechadaPor, hash | quando, quem e o hash da versão fechada; null enquanto aberta |
reguaVersao, creditos, mtmCentavos, foraDoCalculo | os 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 |
outrasFamilias | os 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 |
emCurso | true quando o mês ainda não terminou (não fecha) |
reabertura | aberta 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 |
versaoReaberta | aberta depois de reabrir: { versao, creditos, mtmCentavos, foraDoCalculo, reguaVersao } da versão reaberta, para comparar; null nos outros casos |
trava | aberta 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 |
resolvidos | os 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 |
retificaveis | sempre 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
| Campo | Significado |
|---|---|
id, fundoId, mes, versao | a versão fechada do mês; o id é o :fechamentoId da rota de itens |
vigente | false 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, fechadaPor | quando e quem fechou (fechadaPor pode ser null) |
hash, hashFormato | o hash da fotografia gravada e o formato dele (1, 2 ou 3) |
reguaVersao, creditos, mtmCentavos, foraDoCalculo | os 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 |
previa | só 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 |
retificacao | esta 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 |
ciencia | a 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) |
envios | os 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) |
comEnvio | o fechamento saiu com o relatório emitido e o envio por e-mail |
mudancasDeRegua | as 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 |
mudancasDaAcaoEmCurso | o 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 |
exigenciaDeParecer | a 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) |
resolvidos | os 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
| Campo | Significado |
|---|---|
id, em | número sequencial e momento do registro |
ator, atorTipo | quem fez e o tipo de autor: usuario (pessoa da empresa, inclusive as leituras pelo token dela), sistema ou operador (da Liqi) |
acao, alvo | o 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, depoisRef | referência (hash) do estado antes e depois, ou null |
motivo | o 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 |
motivoOmitido | presente 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) |
alvoOmitido | presente 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, hashVersao | o encadeamento: cada registro aponta o hash do anterior, o que permite conferir a cadeia |
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 poride confiratotalno fim. - Mês fechado (
/fundos/:id/fechamentose/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/fechamentose escolha a versão (mes,versao;vigente: trueé a que vale). - Pagine
GET /api/v1/fundos/:id/fechamentos/:fechamentoId/itens?pagina=N&porPagina=200até a página vir com menos itens do que oporPaginapedido. - Confira: o número de itens é igual a
totale acreditosdo fechamento, e a soma deavaliacao.mtmCentavosdos itens é igual aomtmCentavosdo fechamento. Se a leitura parou no meio (erro, rede,429sem 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."
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>."
}
}
| Status | Código | Quando |
|---|---|---|
| 400 | token_na_url | o token veio no endereço ou no Referer |
| 400 | parametro_desconhecido | parâmetro de consulta que a rota não aceita |
| 400 | dados_invalidos | parâmetro fora do formato ou da faixa |
| 401 | token_invalido | sem cabeçalho, formato errado ou token inexistente (mesma resposta, com WWW-Authenticate: Bearer) |
| 401 | token_revogado | o token foi revogado ou rotacionado |
| 401 | token_expirado | o token venceu |
| 401 | token_sem_dono | o dono do token ou o Admin que o criou perdeu esse acesso (o token foi revogado) |
| 401 | empresa_inativa | a empresa do token não está ativa |
| 403 | origem_recusada | pedido de navegador |
| 403 | sem_permissao | o papel do dono não lê esta rota |
| 403 | trilha_exige_todos_os_fundos | trilha com token de fundos nomeados |
| 403 | so_fechamento_vigente | itens de uma versão reaberta com token de dono Administradora ou Auditor (só a vigente) |
| 404 | fundo_nao_encontrado | o fundo não existe ou está fora do escopo |
| 404 | credito_nao_encontrado | o crédito não existe ou está fora do escopo |
| 404 | fechamento_nao_encontrado | o fechamento não existe ou está fora do escopo |
| 429 | teto_api | o token ou a empresa chegou a um limite de volume; o cabeçalho Retry-After diz em quantos segundos voltar |
| 429 | muitas_tentativas | muitas requisições por segundo do mesmo endereço IP; vem sem Retry-After: espere um minuto |
Limites de volume.
| Limite | Valor |
|---|---|
| Requisições por token, por hora | 600 |
| Requisições por token, em 24 horas | 5.000 |
| Linhas lidas por token, em 24 horas | 100.000 |
| Linhas lidas pela empresa (todos os tokens), em 24 horas | 300.000 |
| Itens por página | até 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.
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 comoapi.negada; o limite atingido, comoapi.teto. - Criar, rotacionar e revogar entram como
token_api.criado,token_api.rotacionadoetoken_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.