Clientes — Visão geral

Um cliente é o cadastro de uma pessoa física ou jurídica na empresa — o tomador (ou possível tomador) de crédito. Diferente de um card, que representa um processo de crédito específico e pertence a exatamente um flow, um cliente é um registro independente do cadastro geral da empresa: o mesmo cliente pode estar associado a vários cards, em vários flows, ao longo do tempo, e pode existir no cadastro mesmo sem nenhum processo de crédito em andamento.

Para a lista de clientes associados a um card específico, veja o endpoint GET /v1/cards/{cardId}/clients, documentado no domínio Cards. Este domínio (Clientes) trata do cadastro geral da empresa, não de uma associação a um card específico.

Endpoints deste domínio

Método	Caminho	Descrição
`POST`	`/v1/clients`	Cria um cliente
`GET`	`/v1/clients`	Lista os clientes da empresa (paginado, com busca)
`GET`	`/v1/clients/{clientId}`	Retorna o perfil completo de um cliente
`PUT`	`/v1/clients/{clientId}`	Atualiza os campos dinâmicos de um cliente
`GET`	`/v1/clients/{clientId}/agrisk`	Consulta dados consolidados de fontes externas sobre o cliente
`GET`	`/v1/clients/{clientId}/cards`	Lista os cards em que o cliente está envolvido

Onde obter os identificadores

clientId: retornado pela listagem deste domínio (GET /v1/clients), pela listagem de clientes de um card específico (GET /v1/cards/{cardId}/clients, domínio Cards) ou no array clients de um card já existente.

flow de referência (usado no cabeçalho ag-flow-id, quando enviado): obtido em GET /v1/flows (domínio Fluxo) ou na URL do flow dentro da aplicação AgFlow.

URL base e autenticação: ver o documento de Introdução no topo desta documentação.

Comportamentos importantes

O cabeçalho ag-flow-id é opcional. Quando enviado, identifica um flow existente da empresa — obtido em GET /v1/flows (domínio Fluxo) ou na URL do flow dentro da aplicação AgFlow. Omiti-lo não impede nenhuma das chamadas deste domínio.

A listagem (GET /v1/clients) devolve apenas dados básicos de identificação (identificador, documento, nome, tipo, data de criação) — para o perfil completo, use a obtenção individual (GET /v1/clients/{clientId}).

O shape do perfil completo varia conforme o tipo de cliente. Campos como nome da mãe/pai, gênero, data de nascimento e estado civil fazem sentido para pessoa física; nome fantasia, natureza jurídica, quadro societário e capital social fazem sentido para pessoa jurídica. Nem todo campo estará preenchido para todo cliente.

A atualização (PUT) só grava campos dinâmicos — os mesmos campos configuráveis pela empresa no domínio Configuração de Cliente. Ela não altera nome, documento ou qualquer dado obtido de fontes externas.

A situação cadastral do documento (taxIdStatus) pode incluir o valor literal "null" como string, distinto de o campo simplesmente não estar presente — indica que a situação não foi apurada, e não deve ser confundido com ausência de dado.

A autorização de consulta ao SCR (scrAuthorized) é um sinalizador próprio do cliente, independente da autorização geral da empresa — controla se o histórico de operações de crédito do cliente no Sistema de Informações de Créditos do Banco Central pode ser consultado.

O endpoint de dados consolidados (/agrisk) é um recorte mais enxuto do resultado de consultas externas automáticas (ver domínio Consulta a Bureau), complementar — não substituto — ao perfil completo do cliente.

Como em qualquer chamada autenticada da API, o acesso a estes endpoints está sujeito às permissões atribuídas ao usuário/token utilizado.

Clientes — Visão geral

Endpoints deste domínio#

Onde obter os identificadores#

Comportamentos importantes#

Endpoints deste domínio

Onde obter os identificadores

Comportamentos importantes