Grupo de assinantes do fornecedor

O grupo de assinantes define quem assina pelo fornecedor nos contratos de despesa e quantas assinaturas bastam (minimum_required_signers).

• Fornecedor pessoa física: recebe automaticamente um grupo padrão com ele mesmo na criação, e um novo a cada aprovação. Não precisa declarar nada.
• Fornecedor pessoa jurídica: normalmente recebe o grupo da própria análise, que a QI Tech deduz dos documentos societários ou que um analista declara. Use esta chamada para declarar o grupo você mesmo.

Um grupo declarado por esta chamada nasce valid e não depende da análise. Cada fornecedor tem no máximo um grupo padrão (is_default: true).

Na aprovação de uma análise:

• Um grupo com expiration_date anterior à data da aprovação não conta, seja o da análise ou o padrão: não é promovido nem copiado.
• Pessoa jurídica com grupo próprio na análise: o último grupo da análise passa a ser o padrão, e o padrão anterior deixa de ser.
• Pessoa jurídica sem grupo próprio na análise: o grupo padrão vigente é copiado para um novo grupo padrão ligado à análise.
• Pessoa jurídica sem nenhum grupo dentro da validade: a análise não é aprovada e fica em revisão manual.

Declarar grupo de assinantes

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/signer_group

MÉTODO

POST

Parâmetros de caminho

Parâmetro	Tipo	Descrição
vendor_key	string	Chave do fornecedor (UUID).

Corpo da requisição

{
    "minimum_required_signers": 1,
    "signers": [
        {
            "name": "João da Silva",
            "document_number": "123.456.789-09",
            "email": "joao.silva@auditoresexemplo.com.br"
        },
        {
            "name": "Maria Souza",
            "document_number": "987.654.321-00",
            "email": "maria.souza@auditoresexemplo.com.br"
        }
    ],
    "is_default": true,
    "expiration_date": "2027-12-31"
}

Atributos do corpo

Campo	Tipo	Obrigatório	Descrição
minimum_required_signers	integer	Sim	Quantas assinaturas bastam. Mínimo 1, no máximo o número de signers.
signers	array	Sim	Ao menos um assinante.
signers[].name	string	Sim	Nome, de 1 a 255 caracteres.
signers[].document_number	string	Sim	CPF com pontuação (123.456.789-09). Precisa ser o CPF de uma parte relacionada active ou pending_registry do fornecedor ou, para fornecedor pessoa física, o do próprio fornecedor. name e email são gravados como enviados.
signers[].is_required_signer	boolean	Não	Aceito, mas ignorado: a QI Tech recalcula o valor (ver atributos da resposta).
signers[].email	string	Sim	E-mail, de 1 a 255 caracteres.
is_default	boolean	Não	Torna este o grupo padrão, rebaixando o anterior. Padrão: false. O primeiro grupo do fornecedor é sempre padrão.
expiration_date	string	Não	Validade do grupo, YYYY-MM-DD. Não pode ser anterior à data de hoje em UTC (400, VRG000096); a própria data de hoje é aceita.

Resposta

STATUS

201

Corpo da resposta

{
    "signer_group_key": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
    "minimum_required_signers": 1,
    "is_default": true,
    "signers": [
        {
            "name": "João da Silva",
            "document_number": "123.456.789-09",
            "email": "joao.silva@auditoresexemplo.com.br",
            "is_required_signer": false
        },
        {
            "name": "Maria Souza",
            "document_number": "987.654.321-00",
            "email": "maria.souza@auditoresexemplo.com.br",
            "is_required_signer": false
        }
    ],
    "status": "valid",
    "analysis_key": null,
    "expiration_date": "2027-12-31"
}

Atributos da resposta

Campo	Tipo	Descrição
signer_group_key	string	Chave do grupo (UUID).
minimum_required_signers	integer	Assinaturas necessárias.
is_default	boolean	Grupo padrão do fornecedor.
signers	array	Assinantes. is_required_signer é calculado pela QI Tech: true para todos quando o número de assinantes é igual ao mínimo exigido; false para todos nos demais casos.
status	string	valid para grupos declarados por esta chamada. Grupos vindos da análise passam por pending e ficam valid na aprovação ou invalid na reprovação, no cancelamento ou na retirada da fila.
analysis_key	string	Análise que originou o grupo, ou null para grupos declarados por esta chamada e para o grupo automático criado com o fornecedor pessoa física.
expiration_date	string	Validade, YYYY-MM-DD. Presente só quando informada.

Listar grupos de assinantes

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Leitura
Consultoria	consultant-api	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/signer_group

MÉTODO

GET

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
limit	integer	Não	Itens por página, de 0 a 1000. Padrão: 10.
page	integer	Não	Página, a partir de 0. Padrão: 0.

Devolve todos os grupos do fornecedor, em qualquer status, do mais antigo para o mais recente.

Resposta

STATUS

200

Corpo da resposta

{
    "data": [
        {
            "signer_group_key": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
            "minimum_required_signers": 1,
            "is_default": true,
            "signers": [
                {
                    "name": "João da Silva",
                    "document_number": "123.456.789-09",
                    "email": "joao.silva@auditoresexemplo.com.br",
                    "is_required_signer": true
                }
            ],
            "status": "valid",
            "analysis_key": "8c2a6f0e-1b3d-4f7a-9c1e-2a4b6d8f0c13"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

Erros

STATUS

400

Assinantes insuficientes

signers tem menos assinantes do que minimum_required_signers.

{
  "title": "Signer Group Quorum Not Met",
  "description": "At least 2 signers are required, but only 1 were sent.",
  "translation": "Sao necessarios pelo menos 2 signatarios, mas apenas 1 foram enviados.",
  "code": "VRG000049"
}

Validade no passado

expiration_date é anterior à data de hoje (UTC).

{
  "title": "Signer Group Expiration Date In Past",
  "description": "The signer group expiration date (2026-11-08) cannot be earlier than today.",
  "translation": "A data de expiracao do grupo de assinantes (2026-11-08) nao pode ser anterior a hoje.",
  "code": "VRG000096"
}

CPF do assinante não pertence ao fornecedor

O CPF de um assinante não é de uma parte relacionada active ou pending_registry do fornecedor, nem do próprio fornecedor pessoa física.

{
  "title": "Signer Document Number Not Found",
  "description": "The document number (123.456.789-09) does not match the vendor's own document number or any of its active related parties.",
  "translation": "O numero de documento (123.456.789-09) nao corresponde ao documento do proprio fornecedor nem ao de nenhuma de suas partes relacionadas ativas.",
  "code": "VRG000050"
}

STATUS

404

Fornecedor não encontrado

A vendor_key não existe ou o fornecedor não é visível para você.

{
  "title": "Vendor not found",
  "description": "Vendor with the key 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 was not found.",
  "translation": "O fornecedor com a chave 5d2e7b9a-3c4f-4e8a-b1d6-9f0a2c3e4b57 nao foi encontrada.",
  "code": "VRG000014"
}

Erros de autenticação, permissão e host: veja Erros da API.

Próximo passo

Envio da análise.