Eventos de garantia (Escrituração e repasse)

Visão geral

Esta é a documentação de integração da API de eventos de garantia do crédito
consignado CLT: as escriturações (o desconto reconhecido na folha de pagamento) e os
repasses (o dinheiro que o empregador efetivamente transfere). É por ela que o seu
sistema acompanha, mês a mês, se a garantia de cada CCB está se comportando.

O ciclo do consignado CLT

Averbação — o contrato é registrado no empregador, que passa a descontar a parcela
da folha do trabalhador. É o que transforma o empréstimo em consignado.
Escrituração (BOOKKEEPING) — a folha reconhece o desconto de uma competência. É
a promessa: o valor foi retido, o empregador deve repassá-lo.
Repasse (TRANSFER) — o dinheiro chega. É o caixa.
Alteração de averbação (ALTER_ANNOTATION) — mudança no vínculo (inclusive o
encerramento, quando a garantia deixa de existir).

Escriturado não é recebido. Essa é a distinção que a API existe para expor: uma
competência escriturada e não repassada é dinheiro retido do trabalhador que não chegou
ao credor. Toda a conciliação da seção 7 gira em torno disso.

Duas formas de consumir

Modo	Como funciona	Quando usar
Consulta (pull)	Você chama `GET /banking/originator/guarantee-events` por CCB	Conciliação, telas sob demanda, fechamento mensal
Webhook (push)	Você expõe uma URL e recebe os eventos	Reagir na hora (alerta de vínculo encerrado, baixa automática)

Os dois entregam o mesmo evento. A consulta é a fonte de verdade e nunca deve ser
dispensada: webhook perdido acontece (rede, deploy, indisponibilidade do seu listener), e
só a consulta reconcilia o que ficou para trás.

Antes de começar

Credenciais

Você recebe um par client_id / client_secret do seu originador. Ele dá acesso ao
escopo /banking/originator — ou seja, aos dados do seu originador apenas. Consultar
uma CCB de outro originador com a sua credencial não retorna erro: retorna lista vazia.
Não confunda isso com "contrato sem eventos".

Guarde o client_secret como segredo de produção. Ele não é recuperável: se for
perdido, uma nova credencial precisa ser emitida — e a anterior pode ser invalidada.

Ambientes

Ambiente	`auth_host`	`api_host`
Homologação	`https://sandbox.auth.flowfinance.com.br`	`https://sandbox.platform.flowfinance.com.br`
Produção	`https://auth.flowfinance.com.br`	`https://platform.flowfinance.com.br`

As credenciais não são intercambiáveis entre ambientes.

Ao longo do documento, {auth_host} e {api_host} referem-se à linha correspondente ao
seu ambiente.

Autenticação

OAuth 2.0, fluxo client credentials. O client_id e o client_secret vão no header
Authorization como Basic (base64 de client_id:client_secret), e o corpo carrega apenas
o grant_type.

Requisição:

POST /oauth2/token HTTP/1.1
Host: platform.flowfinance.com.br
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Em curl:

curl -X POST "{auth_host}/oauth2/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

Resposta (200):

{
  "access_token": "eyJ4NXQiOiJOVGRtWmpNNFpEazNOalkwWXpjNU...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.banking/originator"
}

O access_token vai em todas as chamadas seguintes:

Authorization: Bearer eyJ4NXQiOiJOVGRtWmpNNFpEazNOalkwWXpjNU...

Reaproveite o token até perto do vencimento (expires_in, em segundos) em vez de
autenticar a cada requisição. Uma rotina de conciliação que pede um token por CCB
multiplica a carga sem necessidade.

Consultar eventos de garantia

GET /banking/originator/guarantee-events?contract_number=3911954&page=0&size=25
Authorization: Bearer {access_token}

Parâmetros:

Parâmetro	Obrigatório	Descrição
`contract_number`	sim	Número do contrato (CCB). É o `sequential_id` da operação
`page`	não	Página, começando em 0
`size`	não	Tamanho da página. Veja o item 4 da seção 6 — o valor pedido não é honrado

Resposta (200):

{
  "content": [
    {
      "id": "3f2a1c88-5b41-4f0e-9a77-1d0f4e6b2c33",
      "event_type": "BOOKKEEPING",
      "annotation_id": "a7c9e1b4-2f60-4d3a-8e15-90b7c2d41f88",
      "created_at": "2026-07-05T12:00:00Z",
      "payload": {
        "contract_number": "3911954",
        "payload": {
          "contract_number": "3911954",
          "amount": 45.50,
          "consignee_id": "8b2e40d1-77aa-4c19-93de-6f1a08c5b742",
          "agency_id": "0001",
          "created_at": 1751716800,
          "metadata": {
            "period": "202607",
            "loan": { "installment_amount": 93.00 },
            "analytic": {
              "exists_employee_booked": true,
              "exists_contract_number_booked": true,
              "corresponding_data": true,
              "correct_link": true,
              "correct_agency": true,
              "correct_installment_amount": false
            },
            "document": "12345678901",
            "employee_code": "0004512",
            "employer_registration": "0001",
            "employer_number": "12345678000190"
          }
        }
      }
    },
    {
      "id": "9d51b7e0-33c2-4a6f-b8d9-77e4a1c05e26",
      "event_type": "TRANSFER",
      "annotation_id": "a7c9e1b4-2f60-4d3a-8e15-90b7c2d41f88",
      "created_at": "2026-07-20T12:00:00Z",
      "payload": {
        "contract_number": "3911954",
        "payload": {
          "contract_number": "3911954",
          "amount": 93.00,
          "created_at": 1753012800,
          "metadata": { "competence": 202607 }
        }
      }
    }
  ],
  "page": 0,
  "size": 25,
  "total_pages": 3,
  "has_next": true
}

Os três eventos

Todos chegam no mesmo envelope:

Campo do envelope	Tipo	Descrição
`id`	string	Identificador único do evento. Use-o para deduplicar
`event_type`	string	`BOOKKEEPING`, `TRANSFER` ou `ALTER_ANNOTATION`
`annotation_id`	string	Averbação a que o evento pertence
`created_at`	string ISO 8601	Quando o evento foi gerado
`payload`	objeto	Conteúdo, com formato próprio por tipo (abaixo)

BOOKKEEPING — escrituração

A folha reconheceu o desconto de uma competência.

{
  "id": "3f2a1c88-5b41-4f0e-9a77-1d0f4e6b2c33",
  "event_type": "BOOKKEEPING",
  "annotation_id": "a7c9e1b4-2f60-4d3a-8e15-90b7c2d41f88",
  "created_at": "2026-07-05T12:00:00Z",
  "payload": {
    "contract_number": "3911954",
    "payload": {
      "contract_number": "3911954",
      "amount": 45.50,
      "consignee_id": "8b2e40d1-77aa-4c19-93de-6f1a08c5b742",
      "agency_id": "0001",
      "created_at": 1751716800,
      "metadata": {
        "period": "202607",
        "loan": { "installment_amount": 93.00 },
        "analytic": { "correct_installment_amount": false, "correct_link": true }
      }
    }
  }
}

Campo	Caminho	Descrição
Competência	`payload.payload.metadata.period`	String `"AAAAMM"`
Valor escriturado	`payload.payload.amount`	Pode ser uma fatia da parcela (item 5 da seção 6)
Parcela cheia	`payload.payload.metadata.loan.installment_amount`	O valor contratual da parcela
Batimento	`payload.payload.metadata.analytic`	Flags de conferência averbado × folha
Consignatário	`payload.payload.consignee_id`	Também pode vir em `metadata.consignee_id`
Agência	`payload.payload.agency_id`	Idem

Flags de analytic:

Flag	Significa
`exists_employee_booked`	O trabalhador foi localizado na folha
`exists_contract_number_booked`	O contrato foi localizado na folha
`corresponding_data`	Os dados cadastrais conferem
`correct_link`	O vínculo empregatício confere
`correct_agency`	A agência/estabelecimento confere
`correct_installment_amount`	O valor deste evento é a parcela cheia

TRANSFER — repasse

O dinheiro da competência foi transferido.

{
  "id": "9d51b7e0-33c2-4a6f-b8d9-77e4a1c05e26",
  "event_type": "TRANSFER",
  "annotation_id": "a7c9e1b4-2f60-4d3a-8e15-90b7c2d41f88",
  "created_at": "2026-07-20T12:00:00Z",
  "payload": {
    "contract_number": "3911954",
    "payload": {
      "contract_number": "3911954",
      "amount": 93.00,
      "created_at": 1753012800,
      "metadata": { "competence": 202607 }
    }
  }
}

Campo	Caminho	Descrição
Competência	`payload.payload.metadata.competence`	Inteiro `202607` — não é `period`
Valor repassado	`payload.payload.amount`	Pode vir ausente; a presença do evento é o que prova o repasse

ALTER_ANNOTATION — alteração da averbação

Mudança no vínculo. É aqui que aparece o encerramento, o evento mais importante do
ponto de vista de risco.

{
  "id": "c4e08a76-1b93-4d52-a0f7-2e6c9b1d3548",
  "event_type": "ALTER_ANNOTATION",
  "annotation_id": "a7c9e1b4-2f60-4d3a-8e15-90b7c2d41f88",
  "created_at": "2026-07-02T09:00:00Z",
  "payload": {
    "status_contract": "DEACTIVATED_TERMINATED_LINK",
    "metadata": {
      "employer_name": "EMPRESA EXEMPLO LTDA",
      "employee_name": "NOME DO TRABALHADOR",
      "registration": "0004512"
    },
    "contract": { "number": "3911954" }
  }
}

Campo	Caminho	Descrição
Situação	`payload.status_contract`	Prefixo `DEACTIVATED` = vínculo encerrado
Empregador	`payload.metadata.employer_name`	Razão social
CCB	`payload.contract.number`	Ver item 1 da seção 6

Glossário

Termo	Significado
Averbação	Registro do contrato junto ao empregador, que autoriza o desconto em folha
CCB	Cédula de Crédito Bancário — o título do empréstimo
Competência	Mês de referência da folha, no formato `AAAAMM`
Consignatário	Instituição que concede o crédito e recebe o repasse
Cronograma	Lista de parcelas contratadas, com vencimento e valor
Escrituração	Reconhecimento, na folha, do desconto de uma competência
Margem consignável	Parcela da remuneração que pode ser comprometida com consignado
Repasse	Transferência do valor descontado ao consignatário
Vínculo	Relação de emprego que sustenta a garantia. Encerrado, a garantia deixa de existir