Referência da API REST

Estável

A API REST da Riskora permite integração total com sistemas externos: criação de análises, manutenção de cadastros, consulta de scores e limites em tempo real. Todos os exemplos abaixo usam curl, mas se aplicam a qualquer cliente HTTP.

Credenciais e URLs de ambiente

Para obter o token de acesso e as URLs de produção e homologação da API, é necessário possuir uma conta ativa na Riskora e solicitar as credenciais ao nosso suporte técnico.

Solicitar credenciais ao suporte

Autenticação

Todas as requisições requerem um header Authorization com token Bearer e Content-Type: application/json.

headers

Authorization: Bearer SEU_TOKEN_AQUI
Content-Type: application/json

Nos exemplos a seguir, substitua $RISKORA_API_URL pela URL do seu ambiente (produção ou homologação) e $RISKORA_TOKEN pelo seu token.

POST

Criar nova análise

Invoca o processo ProcZEvalAnalysisProcess para criar uma análise a partir de uma política e um documento (CPF/CNPJ). Se o avaliado ainda não existe, é criado automaticamente.

Endpoint

POST $RISKORA_API_URL/processes/proczevalanalysisprocess

Requisição

curl

curl -X POST "$RISKORA_API_URL/processes/proczevalanalysisprocess" \
  -H "Authorization: Bearer $RISKORA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Z_Eval_Policy_ID": 1000001,
    "z_Documento": "13823508000131",
    "z_ReferenceNo": "PED-2026-1234",
    "z_ReferenceNoEvaluee": "CLI-0042",
    "z_RequestedAmount": 50000,
    "z_InitiatedBy": "API",
    "z_AutoStart": true,
    "SalesRep_ID": 1000010,
    "z_ContactEmail": "cliente@empresa.com.br",
    "z_ContactPhone": "+5511999999999",
    "z_PreferredChannel": "E"
  }'

Parâmetros

Campo	Tipo	Descrição
`Z_Eval_Policy_ID`	int	ID da política de avaliação (obrigatório)
`z_Documento`	string	CPF ou CNPJ sem formatação (obrigatório se Z_Evaluee_ID não for enviado)
`Z_Evaluee_ID`	int	Alternativa ao documento; usa avaliado existente pelo ID
`z_ReferenceNo`	string	Código de referência externo da análise (pedido, contrato, etc.)
`z_ReferenceNoEvaluee`	string	Código de referência externo do avaliado (ID no seu ERP)
`z_RequestedAmount`	decimal	Valor solicitado (limite pretendido)
`z_InitiatedBy`	string	Origem (ex: "API", "ERP", "Vendedor")
`z_AutoStart`	boolean	true (padrão) inicia coleta automaticamente; false cria em Draft
`z_ContactEmail`	string	Email do contato no avaliado; usado para portal externo
`z_ContactPhone`	string	Telefone do contato
`z_PreferredChannel`	string	Canal preferido: `E` email, `S` SMS, `W` WhatsApp

Resposta (200 OK)

json

{
  "summary": "Análise criada: RK-PJ_AVANCADA_IC943<br/> Link externo: https://riskora.ai/eval/collect/abc123...<br/> Status: Coleta iniciada",
  "isError": false,
  "logs": []
}

O campo summary contém o código da análise (Value) e, quando aplicável, o link externo do portal do avaliado para coleta de dados adicional.

PUT

Atualizar dados informativos do avaliado

Atualiza campos de comportamento e histórico do Z_Evaluee (limite usado, faturamento 12m, ticket médio, etc.). Esses dados enriquecem o contexto da IA e podem ser usados em regras de scoring.

Passo 1 · Localizar o ID do avaliado pelo documento

curl

curl -X GET "$RISKORA_API_URL/models/z_evaluee?\$filter=Value%20eq%20'13823508000131'&\$select=Z_Evaluee_ID,Value,Name" \
  -H "Authorization: Bearer $RISKORA_TOKEN"

O campo Value de Z_Evaluee guarda o documento (CPF/CNPJ sem formatação).

Passo 2 · Atualizar os campos informativos

curl

curl -X PUT "$RISKORA_API_URL/models/z_evaluee/1000042" \
  -H "Authorization: Bearer $RISKORA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "z_UsedLimit": 25000,
    "z_TotalPurchases12m": 180000,
    "z_AverageTicket": 15000,
    "z_LastPurchaseDate": "2026-04-01",
    "z_PaymentBehavior": "EXCELLENT",
    "z_LastExternalUpdate": "2026-04-08T12:30:00"
  }'

Campos disponíveis

Campo	Tipo	Descrição
`z_UsedLimit`	decimal	Limite atualmente utilizado pelo cliente
`z_TotalPurchases12m`	decimal	Faturamento total dos últimos 12 meses
`z_AverageTicket`	decimal	Ticket médio por pedido
`z_LastPurchaseDate`	date	Data da última compra (ISO 8601)
`z_PaymentBehavior`	string	Comportamento de pagamento (texto livre ou categoria)
`z_ContactEmail`	string	Email de contato principal
`z_ContactPhone`	string	Telefone de contato
`z_PreferredChannel`	string	Canal preferido (`E`/`S`/`W`)
`z_LastExternalUpdate`	timestamp	Data/hora da última sincronização externa
`z_ReferenceNo`	string	Código de referência do avaliado no seu sistema

Campos calculados pela plataforma (z_CurrentScore, z_CurrentLimit, z_CurrentTier, z_RiskLevel) são atualizados automaticamente a cada análise aprovada; não devem ser editados via API.

GET

Consultar status, score e limite de uma análise

Retorna o estado completo de uma análise filtrando pelo código (Value) ou pelo z_ReferenceNo externo. Útil para polling de status e exibição de resultado em sistemas parceiros.

Por código da análise (Value)

curl

curl -X GET "$RISKORA_API_URL/models/z_eval_analysis?\$filter=Value%20eq%20'RK-PJ_AVANCADA_IC943'&\$select=Value,z_ReferenceNo,z_EvalStatus,z_FinalScore,z_TierValue,z_ApprovedLimit,z_CalculatedLimit,z_RiskLevel,z_AIRecommendation,z_AIOpinionShort" \
  -H "Authorization: Bearer $RISKORA_TOKEN"

Por referência externa (z_ReferenceNo)

curl

curl -X GET "$RISKORA_API_URL/models/z_eval_analysis?\$filter=z_ReferenceNo%20eq%20'PED-2026-1234'&\$select=Value,z_EvalStatus,z_FinalScore,z_ApprovedLimit,z_TierValue,z_RiskLevel" \
  -H "Authorization: Bearer $RISKORA_TOKEN"

Resposta (200 OK)

json

{
  "records": [
    {
      "Value": "RK-PJ_AVANCADA_IC943",
      "z_ReferenceNo": "PED-2026-1234",
      "z_EvalStatus": { "id": "AP", "identifier": "Aprovado" },
      "z_FinalScore": 782,
      "z_TierValue": "B",
      "z_ApprovedLimit": 45000,
      "z_CalculatedLimit": 50000,
      "z_RiskLevel": { "id": "L", "identifier": "Baixo" },
      "z_AIRecommendation": "APROVAR",
      "z_AIOpinionShort": "Empresa com bom histórico de pagamento e faturamento estável"
    }
  ]
}

Valores possíveis de z_EvalStatus

Código	Descrição
`DR`	Draft. Criada, aguardando início
`IP`	In Progress. Em coleta ou processamento
`MR`	Manual Review. Aguardando revisão humana
`AP`	Approved. Aprovada (estado final)
`RJ`	Rejected. Rejeitada (estado final)
`CA`	Canceled. Cancelada (estado final)
`EX`	Expired. Expirada (estado final)

GET

Consultar score e limite atual de um avaliado

Retorna o score, limite concedido, tier e nível de risco atuais de um avaliado, sempre refletindo a última análise aprovada. Ideal para decisões em tempo real no checkout ou em integrações com ERP.

Por documento (CPF/CNPJ)

curl

curl -X GET "$RISKORA_API_URL/models/z_evaluee?\$filter=Value%20eq%20'13823508000131'&\$select=Value,Name,z_EvalueeType,z_EvalueeStatus,z_CurrentScore,z_CurrentLimit,z_CurrentTier,z_RiskLevel,z_UsedLimit,z_LastAnalysisDate,z_LastAnalysis_ID" \
  -H "Authorization: Bearer $RISKORA_TOKEN"

Em Z_Evaluee, o campo Value armazena o documento sem formatação (CPF, CNPJ, placa, matrícula, etc. dependendo do tipo).

Resposta (200 OK)

json

{
  "records": [
    {
      "Value": "13823508000131",
      "Name": "Grupo Mundo do Café S/A",
      "z_EvalueeType": { "id": "PJ", "identifier": "Pessoa Jurídica" },
      "z_EvalueeStatus": { "id": "A", "identifier": "Ativo" },
      "z_CurrentScore": 782,
      "z_CurrentLimit": 45000,
      "z_CurrentTier": "B",
      "z_RiskLevel": { "id": "L", "identifier": "Baixo" },
      "z_UsedLimit": 25000,
      "z_LastAnalysisDate": "2026-04-08T01:47:15",
      "z_LastAnalysis_ID": {
        "id": 1000156,
        "identifier": "RK-PJ_AVANCADA_IC943"
      }
    }
  ]
}

Os campos z_CurrentScore, z_CurrentLimit, z_CurrentTier e z_RiskLevel refletem o resultado da última análise aprovada. Se o avaliado nunca teve análise aprovada, esses campos retornam null.

Dicas de uso

•OData filters: use $filter, $select, $orderby, $top e $skip para refinar consultas. Strings são delimitadas por aspas simples e escapadas duplicando: 'O''Reilly'.
•Referências FK/RefList: campos de chave estrangeira ou lista de referência são retornados como objetos {id, identifier}. Use .id para o valor interno e .identifier para a descrição amigável.
•Rate limiting: a API impõe limites de requisição por token. Use z_ReferenceNo nas análises para idempotência; consultar por referência é mais eficiente que criar duplicadas.
•Polling de análise: análises com IA podem levar de 10 a 30 segundos para concluir. Recomendamos polling a cada 5 segundos no endpoint #3 até z_EvalStatus virar AP, RJ ou MR. Para eliminar polling, consulte a seção de Webhooks.
•Tratamento de erros: respostas 4xx retornam { "errors": [...] } com detalhes. 401 indica token inválido; 404 registro inexistente; 422 validação de negócio (ex: política incompatível com tipo de avaliado).

Precisa de ajuda com integração?

Nossa equipe técnica pode ajudar com configuração, exemplos em outras linguagens, sandbox para testes e dúvidas sobre regras de negócio.

Falar com a equipe