Visão Geral
A API de Consulta de Eventos de Garantias passou por uma evolução e conta agora com uma nova versão, trazendo maior abrangência e robustez na consulta dos eventos relacionados às CCBs.
A consulta permite acompanhar o histórico dos eventos relacionados a uma CCB ao longo da operação.
Por meio dela, o originador pode identificar os eventos recebidos, trazendo maior visibilidade sobre as movimentações que ocorrem após a averbação do contrato.
Entre os eventos disponíveis estão:
BOOKKEEPING: informações relacionadas à escrituração;TRANSFER: informações relacionadas aos repasses;ALTER_ANNOTATION: alterações relacionadas à mudança de vínculo.
A consulta pode ser realizada diretamente pelo número da CCB (sequential_id) e também permite utilizar filtros como tipo de evento, competência e período.
Com isso, o cliente consegue consultar o histórico de eventos de uma CCB e utilizar essas informações para acompanhamento operacional, conciliação e tratamento das movimentações.
Endpoint
GET /originator/guarantee-events/v2Parâmetros de consulta
Os parâmetros são opcionais e podem ser combinados de acordo com a necessidade da consulta.
| Parâmetro | Tipo / Formato | Descrição | Exemplo |
|---|---|---|---|
sequential_id | Integer | Número da CCB que será consultada. A CCB deve pertencer ao originador autenticado. | 8581721 |
event_type | Enum | Tipo do evento. Valores disponíveis: BOOKKEEPING, TRANSFER ou ALTER_ANNOTATION. | BOOKKEEPING |
status_contract | Enum | Disponível somente quando event_type=ALTER_ANNOTATION. Valores aceitos: DEACTIVATED_TERMINATED_LINK ou DEACTIVATED_RENEWED_LINK. | DEACTIVATED_TERMINATED_LINK |
competence | String (YYYYMM) | //// Competência relacionada ao evento, composta por ano e mês. | 202601 |
created_from | ISO 8601 | Data e hora inicial para consulta dos eventos com base no created_at. | 2026-01-01T00:00:00Z |
created_to | ISO 8601 | Data e hora final para consulta dos eventos com base no created_at. | 2026-01-31T23:59:59Z |
page | Integer | Número da página que será consultada. A paginação inicia em 0. | 0 |
size | Integer | Quantidade de registros por página. O valor padrão e máximo permitido é 25. | 25 |
Exemplo
GET /originator/guarantee-events/v2?sequential_id=8581721&event_type=BOOKKEEPING&competence=202601&page=0&size=25
Authorization: Bearer <token>-
A consulta considera automaticamente o originador autenticado, retornando somente eventos relacionados às suas CCBs.
-
Todos os parâmetros são opcionais e podem ser combinados.
-
Quando nenhum filtro é informado, são retornados os eventos do originador ordenados do mais recente para o mais antigo.
-
Caso
sizeseja superior a25, a consulta considera automaticamente o limite máximo de 25 registros por página.
Resposta
A resposta da consulta possui uma estrutura padrão, independentemente do tipo de evento retornado.
Os campos abaixo são mantidos na estrutura da resposta, enquanto o conteúdo de metadata pode variar de acordo com o event_type e com as informações disponíveis para o evento.
{
"content": [
{
"sequential_id": 249258,
"event_type": "BOOKKEEPING",
"competence": "202603",
"created_at": "2026-08-13T16:00:03.178Z",
"metadata": {
// Conteúdo variável de acordo com o evento
}
}
],
"page": 0,
"size": 25,
"total_pages": 1,
"total_elements": 1,
"has_next": false
}Os campos sequential_id, event_type, competence e created_at identificam e contextualizam o evento. Os campos page, size, total_pages, total_elements e has_next correspondem às informações de paginação da consulta.
CampometadataO campo
metadataapresenta os dados específicos de cada evento.Seu conteúdo varia de acordo com o
event_typee pode receber novos campos conforme as informações disponibilizadas pela DataprevPor esse motivo, a integração deve estar preparada para consumir o
metadatasem depender de uma estrutura fixa ou da ordem das chaves.
Exemplos
BOOKKEPING
{
"sequential_id": 5755355,
"event_type": "BOOKKEEPING",
"competence": "202608",
"created_at": "2026-09-18T08:00:34.963Z",
"metadata": {
"loan": { "agency_code": 668, "contract_number": "5755359", "installment_amount": 212.48 },
"period": 202608,
"analytic": {
"is_correct_link": true,
"is_correct_agency": true,
"corresponding_data": true,
"e_social_event_type": { "code": 1, "description": "Evento não periódico (desligamento ou término de vínculo)" },
"exists_employee_booked": true,
"exists_contract_number_booked": true,
"is_correct_installment_amount": false
},
"document": "12345678555",
"event_id": "1181458580000002026091514380801001",
"agency_code": 668,
"employee_code": "000123",
"employer_number": "18145858",
"inclusion_datetime": "2026-09-18T00:00:00",
"employer_registration": { "code": 1, "description": "CNPJ" },
"amount": 705.83
}
},TRANSFER
{
"sequential_id": 5755355,
"event_type": "TRANSFER",
"competence": "202607",
"created_at": "2026-08-30T00:00:05.057Z",
"metadata": {
"nsu": 544858387,
"trf_code": 142982318,
"document": "12345678955",
"agency_code": 668,
"competence": 202607,
"fine_amount": 4.25,
"registration": "000123",
"severance_pay": false,
"payment_datetime": 1787684751.0,
"inclusion_datetime": "2026-08-29T17:15:06.000Z",
"late_interest_amount": 0.35,
"payment_guide_number": 5260825569838694,
"agency_transfer_datetime": 1787832000.0,
"monetary_correction_value": 0.02,
"employer_registration_number": "18145858",
"amount": 212.48
}
},ALTER_ANNOTATION
{
"sequential_id": 5755355,
"event_type": "ALTER_ANNOTATION",
"status_contract": "DEACTIVATED_TERMINATED_LINK",
"created_at": "2026-06-19T17:52:00.488Z",
"metadata": {
"document": "12345678555",
"net_amount": 1000,
"authorized": false,
"loan_amount": 1015.52,
"employee_name": "NOME DO TRABALHADOR OCULTO",
"employer_name": "EMPREGADOR",
"registration": "000123",
"situation_loan": { "code": 15, "description": "Encerrado por término do vínculo" },
"employer_number": "18145858",
"update_date_time": "2026-08-30T03:00:15",
"contract_end_date": "2027-01-26",
"end_discount_date": 202612,
"termination_date": "2026-08-20",
"bookings_quantity": 1,
"init_discount_date": 202607,
"payments_quantity": 1,
"contract_start_date": "2026-06-19",
"installment_amount": 212.48,
"installment_quantity": 6,
"employer_registration": { "code": 1, "description": "CNPJ" },
"financial_institution": { "code": 668, "description": "CELCOIN SOCIEDADE DE CRÉDITO DIRETO S/A" },
"inclusion_loan_date_time": "2026-06-19T14:52:01"
}
Erros
| HTTP | Cenário |
|---|---|
400 | sequential_id não numérico ou menor/igual a zero. |
400 | event_type ou status_contract fora dos valores aceitos. |
400 | competence fora do formato YYYYMM ou com mês inválido. |
400 | status_contract enviado sem event_type=ALTER_ANNOTATION. |
400 | created_from ou created_to fora do formato ISO 8601. |
404 | sequential_id não localizado para o originador autenticado. |
200 | CCB válida, porém sem eventos correspondentes aos filtros. Nesse cenário, content é retornado vazio. |
Integrações que já utilizam a consulta de eventos (v1)
O endpoint anteriormente disponibilizado continua funcionando normalmente:
GET /originator/guarantee-eventsPara utilização do novo endpoint, considere os seguintes ajustes:
| Consulta anterior | Novo endpoint |
|---|---|
Filtros annotation_id, contract_number ou application_ids | Utiliza sequential_id, correspondente ao número da CCB |
Dados do evento em payload | Dados do evento em metadata |
| CCB não localizada retorna lista vazia | Consulta por sequential_id não localizado retorna 404 |
Além disso, a consulta oferece maior abrangência e robustez no retorno dos eventos, contemplando de forma mais completa as informações recebidas ao longo do processamento.
A adoção do novo endpoint pode ser realizada conforme a necessidade da integração. O endpoint anterior permanece disponível sem alterações nesse primeiro momento, e avisaremos quando ele será descontinuado.