Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Consultas, Escriturações e Repasses

Suggest Edits

O que são Consulta de Eventos

Os eventos de garantia representam ações ocorridas durante o ciclo de vida de um contrato de crédito consignado.
Eles são armazenados em nossa base e podem ser consultados a qualquer momento via API.


Tipos de Evento Disponíveis

NomeTipo de EventoDescrição
EscrituraçãoBOOKKEEPINGEvento mensal que representa a escrituração (impressão da guia de pagamento das parcelas).
RepasseTRANSFEREvento mensal que representa o repasse financeiro da Dataprev para instituição financeira.
Consulta de VínculoALTER_ANNOTATIONEvento utilizado para consultar quando há novo vínculo empregatício do tomador.
Encerramento de VínculoALTER_ANNOTATIONEvento utilizado para consultar quando há encerramento de vínculo empregatício do tomador.

Endpoint


URL

GET /originator/guarantee-events

Lista todos os eventos de garantia de acordo com os filtros informados.
A resposta é paginada, permitindo navegação entre grandes volumes de dados.


Filtros Disponíveis

CampoTipoDescrição
applicationIdsArrayBusca eventos relacionados a uma ou mais operações específicas.
annotationIdUUIDBusca eventos relacionados a um annotationId específico.
contractNumberStringBusca pelo número da CCB.
eventTypeStringTipo do evento: BOOKKEEPING, TRANSFER, ALTER_ANNOTATION.
createdFromDateTime (ISO 8601)Retorna eventos criados a partir desta data (YYYY-MM-DDThh:mm:ssZ).
createdToDateTime (ISO 8601)Retorna eventos criados até esta data (YYYY-MM-DDThh:mm:ssZ).

💡

Dica: Combine filtros para refinar os resultados.

Exemplo: buscar apenas eventos TRANSFER de um annotationId específico.


Exemplo de Requisição

curl -X GET "https://api.exemplo.com/originator/guarantee-events?annotationId=123e4567-e89b-12d3-a456-426614174000&eventType=TRANSFER&createdFrom=2025-01-01T00:00:00Z&createdTo=2025-01-31T23:59:59Z&page=0&size=10" \
-H "Authorization: Bearer {seu_token}"

Neste exemplo:

  • Busca eventos do tipo TRANSFER;
  • Relacionados ao annotationId informado;
  • Criados entre 01/01/2025 e 31/01/2025;
  • Retorna a página 0, com até 10 registros.

Estrutura da Resposta (Comum)

{
  "content": [ ...eventos... ],
  "total_pages": 1,
  "total_elements": 7,
  "has_next": false
}

Campos Comuns

CampoTipoDescrição
content[].idUUIDIdentificador único do evento.
content[].event_typeStringTipo do evento (BOOKKEEPING, TRANSFER, ALTER_ANNOTATION).
content[].annotation_idUUIDIdentificador da anotação vinculada à garantia.
content[].created_atDateTime (ISO 8601)Data e hora em que o evento foi registrado.
payloadObjectEstrutura de dados com informações específicas do evento.

Response por Tipo de Evento


BOOKKEEPING — Escrituração

Representa a impressão mensal da guia de pagamento das parcelas.

{
  "id": "495bbce6-25ef-454b-a091-a937a52ee922",
  "event_type": "BOOKKEEPING",
  "annotation_id": "e3c95f23-b18f-49a5-b889-6739f5c3ac77",
  "payload": {
    "payload": {
      "id": "7f3b0c7e-6e2a-4b43-bc1c-59e87a7c5f92",
      "amount": 3.14,
      "agencyId": "bb38f4c1-1f47-47a0-b0db-5c7b9c8f72ad",
      "metadata": {
        "period": "202509",
        "agencyCode": 101,
        "processingDatetime": 1758643993.519
      },
      "contractNumber": "2364738"
    },
    "createdAt": 1758643993.519,
    "eventType": "BOOKKEEPING"
  },
  "created_at": "2025-10-22T14:09:42.612Z"
}

Campos Específicos — BOOKKEEPING

CampoTipoDescrição
payload.payload.idStringIdentificador interno do evento no sistema Dataprev.
payload.payload.amountNumberValor da escrituração.
payload.payload.metadata.periodStringPeríodo de referência (AAAAMM).
payload.payload.metadata.agencyCodeIntegerCódigo da agência responsável.
payload.payload.metadata.processingDatetimeNumberTimestamp de processamento.
payload.payload.contractNumberStringNúmero da CCB.

TRANSFER — Repasse


Representa o repasse financeiro da Dataprev à instituição financeira.

{
  "id": "cd259de8-0fc9-41d5-a373-68264311c938",
  "event_type": "TRANSFER",
  "payload": {
    "payload": {
      "id": "7f3b0c7e-6e2a-4b43-bc1c-59e87a7c5f92",
      "amount": 3.14,
      "metadata": {
        "agencyCode": 0,
        "paymentDatetime": 1758643993.519,
        "agencyTransferDatetime": 1758643993.519
      },
      "contractNumber": "2364738"
    },
    "createdAt": 1758643993.519,
    "eventType": "TRANSFER"
  },
  "created_at": "2025-10-22T14:10:39.077Z"
}

Campos Específicos — TRANSFER

CampoTipoDescrição
payload.payload.amountNumberValor do repasse efetuado.
payload.payload.metadata.agencyCodeIntegerCódigo da agência que realizou o repasse.
payload.payload.metadata.paymentDatetimeNumberTimestamp da data de pagamento.
payload.payload.metadata.agencyTransferDatetimeNumberTimestamp da data em que o valor foi transferido à agência.
payload.payload.contractNumberStringNúmero da CCB.

ALTER_ANNOTATION — Alteração de Vínculo


Representa atualizações de vínculo empregatício do tomador (criação ou encerramento).

{
  "id": "efb89185-707b-46c1-b555-cf7faffd9bd9",
  "event_type": "ALTER_ANNOTATION",
  "annotation_id": "d9a24dc0-14bd-4fe9-8912-eb76b3c12977",
  "payload": {
    "status": "SUCCESS",
    "contract": {
      "number": "2430205",
      "account": {
        "bank": "0",
        "branch": "668",
        "number": "N/A"
      },
      "sequence": "17905279972"
    },
    "action_type": "ALTER_ANNOTATION",
    "status_contract": "DEACTIVATED_TERMINATED_LINK",
    "created_at": "2025-10-09T15:01:07.645Z"
  },
  "created_at": "2025-10-22T14:12:41.996Z"
}

Campos Específicos — ALTER_ANNOTATION

CampoTipoDescrição
payload.statusStringStatus do processamento (SUCCESS, ERROR, etc.).
payload.contract.numberStringNúmero do contrato relacionado.
payload.contract.accountObjectConta associada ao contrato.
payload.status_contractStringSituação do vínculo (DEACTIVATED_RENEWED_LINK, DEACTIVATED_TERMINATED_LINK).
payload.action_typeStringTipo de ação executada (ex: ALTER_ANNOTATION).
payload.created_atDateTimeData e hora da criação do evento.

Códigos de Resposta HTTP

CódigoSignificadoDescrição
200OKRequisição bem-sucedida.
400Bad RequestFiltros inválidos ou formato incorreto.
401UnauthorizedToken de autenticação ausente ou inválido.
404Not FoundNenhum evento encontrado.
500Internal Server ErrorErro inesperado no servidor.

Resumo e Boas Práticas

Use este endpoint para consultar eventos de garantia registrados e acompanhar a movimentação contratual.
É possível filtrar por applicationId, annotationId, número da CCB, tipo de evento e intervalo de datas.


📘

Boas Práticas

  • Sempre utilize filtros para otimizar performance.
  • Limite o intervalo de datas em consultas.
  • Utilize cache local para dados históricos.
  • Utilize paginação para evitar sobrecarga.

Updated about 5 hours ago