Resumo: as rotas deste módulo usam o mesmo endereço e a mesma autenticação do resto da API. O que muda é que elas exigem uma capacidade da organização e o caminho é versionado. O que está nesta página vale para todos os endpoints do grupo.
Endereço e autenticação
gyra-client-id e gyra-client-secret por um token em POST /auth/authenticate e use Authorization: Bearer <token>. O token vale 24 horas.
As credenciais são geradas por você em Configurações, API & MCP. Ver Chaves de API.
Versionamento
Cada rota responde nos dois caminhos:Capacidades
Sem a capacidade, a rota responde404 com a mensagem Recurso não encontrado.: ela não existe para aquela organização.
Com credencial de integração, as rotas
/v1/registry exigem kycEnabled. Pedir numa solicitação um item que a organização não contratou responde 403 com o nome do item, por exemplo Sua organização não pode pedir verificação de identidade nesta solicitação. Fale com a GYRA+ para habilitar.can-use-registry-api (credencial de integração) ou can-generate-report. As rotas de webhook pedem can-use-registry-api ou can-manage-settings.
Erros
O corpo é sempre{ code, message }, com a mensagem em português.
Identificadores
Todo id é um ObjectId de 24 caracteres hexadecimais. CNPJ e CPF são aceitos com ou sem máscara e devolvidos só com dígitos.Modelos: filtrar e ligar ou desligar
Filtros da listagem
GET /v1/collection-templates aceita, além de search, itemKind, skip e take:
Cada modelo da listagem traz
enabled, scope e, quando o formulário público está configurado, publicFormUrl com o endereço pronto. metrics traz o uso do modelo na sua organização: collections, completedCollections, completionRate e averageCompletionHours.
onCompleted diz o que o modelo faz ao concluir: kind é NONE, POLICY ou OPERATION, e id é a política ou a esteira. Quando o modelo tem um destino para CNPJ e outro para CPF, eles vêm em byEntityType, com as chaves COMPANY e PERSON, cada uma com o próprio kind e id.
Em items, um item com appliesTo igual a PJ só nasce quando o cadastro é de pessoa jurídica, e PF só quando é de pessoa física. Sem appliesTo, o item vale para os dois.
Ligar ou desligar um modelo
id pode ser o de qualquer versão: a mudança vale para todas as versões do modelo, e updated diz quantas foram alteradas. Num modelo GYRA+, a mudança vale só para a sua organização e updated é 1.
Modelo desligado some da escolha de modelo (nova solicitação e etapa da esteira), mas continua na listagem. Não é exclusão: solicitação já enviada com ele segue valendo, e o slug dele continua aceito em POST /v1/collections. Modelo inexistente responde 404 com Modelo não encontrado.
Listar as validações de identidade
Esta rota exige
kycEnabled. Organização que tem apenas scrEnabled recebe 404.- O documento sai sempre mascarado. Imagens e o retorno cru do provedor não saem nesta rota.
- A contagem olha as 5.000 verificações mais recentes de cada origem. Acima disso,
totalesummarypassam a se referir a essa janela.
O que não está aqui
A API pública cobre a integração: ler documento, montar dossiê, pedir ao cliente e receber aviso. Além das páginas de cada rota, veja Pessoas, contatos e dados declarados e Baixar a via assinada. Configuração fica no toolbox: a régua de validação, a montagem dos modelos de coleta e de termo (pela API você lista e liga ou desliga, como acima), a marca e os canais de envio e os indicadores de acurácia. São telas com previa e versionamento, e um valor errado ali afeta todo documento que entrar depois. As rotas do link do destinatário e do formulário público também não entram: elas pertencem às páginas que o seu cliente abre, sem credencial de integração.Próximos passos
Integrar do zero
Da credencial ao webhook chegando, em cinco etapas.
Validar um documento
A chamada mais curta que entrega valor.