> ## Documentation Index > Fetch the complete documentation index at: https://docs.sherlocker.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar análise > Cria uma análise de risco assíncrona para um CNPJ (PJ) ou CPF (PF). O tipo é auto-detectado pelo tamanho do documento (14 → pj, 11 → pf) ou definido em subject_type. Análises de CPF exigem a feature analysis_engine_pf. Os tokens são debitados na criação; análises que terminam em failed são reembolsadas automaticamente. Retorna 202 na primeira submissão e 200 no replay idempotente (mesma Idempotency-Key + mesmo body em até 24h, sem nova cobrança). ## OpenAPI ````yaml /openapi/motor-analise.json post /analyses openapi: 3.0.0 info: title: Sherlocker Motor de Análise - API v1 description: >- API pública do Motor de Análise: cria análises de risco assíncronas de CNPJ (PJ) e CPF (PF) e consulta o resultado por polling. Autenticação por chave de API (Bearer slhk_) no header. Erros em RFC 7807 (application/problem+json). Em beta: requer as features analysis_engine (e analysis_engine_pf para CPF) habilitadas no workspace. version: '1.0' servers: - url: https://221b-api.sherlocker.com.br/api/v1 description: >- Mesma base da API 221b. Autentica via Authorization: Bearer slhk_ (nao usa ?token=). security: - bearerAuth: [] paths: /analyses: post: tags: - Análises summary: Criar análise description: >- Cria uma análise de risco assíncrona para um CNPJ (PJ) ou CPF (PF). O tipo é auto-detectado pelo tamanho do documento (14 → pj, 11 → pf) ou definido em subject_type. Análises de CPF exigem a feature analysis_engine_pf. Os tokens são debitados na criação; análises que terminam em failed são reembolsadas automaticamente. Retorna 202 na primeira submissão e 200 no replay idempotente (mesma Idempotency-Key + mesmo body em até 24h, sem nova cobrança). operationId: createAnalysis parameters: - name: Idempotency-Key in: header required: true schema: type: string description: >- Chave única por requisição lógica (UUID recomendado). Obrigatória. Reenviar a mesma chave com o mesmo body em até 24h devolve a resposta original (HTTP 200) sem nova cobrança; mesma chave com body diferente devolve 409. - name: x-request-id in: header required: false schema: type: string description: >- Identificador de rastreio opcional fornecido pelo cliente. Gerado pelo servidor se omitido; ecoado no header da resposta. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAnalysisRequest' examples: pj: summary: Análise de CNPJ (PJ) value: document: '12345678000195' subject_type: pj purpose: due diligence de fornecedor pf: summary: Análise de CPF (PF) value: document: 111.444.777-35 subject_type: pf legal_basis: protecao_credito purpose: onboarding KYC responses: '200': description: >- Replay idempotente: mesma Idempotency-Key + mesmo body dentro da janela de 24h. Corpo idêntico ao da resposta 202 original; nenhum token adicional é cobrado. content: application/json: schema: $ref: '#/components/schemas/CreateAnalysisAccepted' '202': description: Análise aceita e enfileirada para processamento. Tokens debitados. headers: x-request-id: schema: type: string description: Identificador da requisição (ecoado ou gerado). content: application/json: schema: $ref: '#/components/schemas/CreateAnalysisAccepted' example: id: a1b2c3d4-0000-0000-0000-000000000001 status: pending tokens_charged: 10 balance: 990 poll_after_seconds: 2 request_id: 3166fb9a-384c-44b7-ab77-90aca3146e0a '400': description: >- Requisição inválida: header Idempotency-Key ausente (bad_request), documento sem dígitos / tamanho errado / dígito verificador inválido (bad_request) ou campo com tipo/enum inválido (validation_error, com errors[]). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.sherlocker.com.br/problems/bad_request title: Bad Request status: 400 code: bad_request detail: Idempotency-Key header required instance: /v1?request_id=3166fb9a-384c-44b7-ab77-90aca3146e0a '401': description: Chave de API ausente, malformada, inválida ou revogada. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.sherlocker.com.br/problems/unauthorized title: Unauthorized status: 401 code: unauthorized detail: Authentication is required to access this resource. instance: /v1?request_id=3166fb9a-384c-44b7-ab77-90aca3146e0a '402': description: >- Saldo de tokens do workspace insuficiente. Campos extras: required (tokens necessários) e balance (saldo atual). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.sherlocker.com.br/problems/insufficient_tokens title: Payment Required status: 402 code: insufficient_tokens detail: 'Insufficient tokens: 5 available, 10 required' required: 10 balance: 5 instance: /v1?request_id=3166fb9a-384c-44b7-ab77-90aca3146e0a '403': description: >- Feature não habilitada no workspace: analysis_engine (qualquer chamada /v1) ou analysis_engine_pf (análises de CPF). Campo extra request_access_url indica onde solicitar acesso. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.sherlocker.com.br/problems/feature_not_enabled title: Feature Not Enabled status: 403 code: feature_not_enabled detail: >- The analysis_engine feature is not enabled for this workspace. To request access visit https://docs.sherlocker.com.br/api/access or contact support at https://docs.sherlocker.com.br/support. request_access_url: https://docs.sherlocker.com.br/api/access instance: /v1?request_id=3166fb9a-384c-44b7-ab77-90aca3146e0a '409': description: >- Conflito de idempotência: requisição concorrente com a mesma Idempotency-Key em andamento, ou mesma chave reutilizada com body diferente. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.sherlocker.com.br/problems/idempotency_conflict title: Conflict status: 409 code: idempotency_conflict detail: >- A request with the same idempotency key is already in progress or completed. instance: /v1?request_id=3166fb9a-384c-44b7-ab77-90aca3146e0a '422': description: >- Nenhuma engine disponível para a requisição: workspace sem engine padrão e sem template aplicável, engine_id inexistente/arquivada, ou subject_type incompatível com a engine. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.sherlocker.com.br/problems/no_engine title: Unprocessable Entity status: 422 code: no_engine detail: >- No analysis engine is configured or the engine cannot process this request. instance: /v1?request_id=3166fb9a-384c-44b7-ab77-90aca3146e0a components: schemas: CreateAnalysisRequest: type: object required: - document properties: document: type: string description: >- CNPJ (14 dígitos) ou CPF (11 dígitos) do analisado, com ou sem máscara. example: '12345678000195' subject_type: type: string enum: - pj - pf description: >- Tipo do analisado. Auto-detectado pelo tamanho do documento (14 → pj, 11 → pf). Se enviado, precisa ser compatível com o documento. engine_id: type: string format: uuid description: >- UUID da engine de análise a usar. Omitido: usa a engine padrão do workspace ou o template do sistema (PJ/PF). purpose: type: string description: >- Finalidade da análise (texto livre). Opcional; gravada no log de auditoria PF em análises de CPF. legal_basis: type: string enum: - consentimento - legitimo_interesse - cumprimento_obrigacao_legal - protecao_credito description: >- Base legal LGPD para tratamento de dados pessoais. Opcional; gravada no log de auditoria PF em análises de CPF. CreateAnalysisAccepted: type: object required: - id - status properties: id: type: string format: uuid description: UUID da análise criada. Use no GET /analyses/{id}. status: type: string enum: - pending description: Sempre pending imediatamente após a criação. tokens_charged: type: number description: Tokens debitados do saldo do workspace na criação. balance: type: number description: Saldo de tokens do workspace após o débito. poll_after_seconds: type: number description: Sugestão de espera (segundos) antes do primeiro poll. request_id: type: string description: >- Identificador da requisição para rastreio e suporte. Igual ao header x-request-id da resposta. Problem: type: object required: - type - title - status - code description: >- Erro no formato RFC 7807 (application/problem+json). Use o campo code para tratamento programático; type é apenas identificador. properties: type: type: string description: >- URI que identifica o tipo do problema (https://docs.sherlocker.com.br/problems/). title: type: string description: Resumo curto do tipo do problema. status: type: integer description: Status HTTP desta ocorrência. code: type: string description: >- Código estável para tratamento programático (ex.: insufficient_tokens). detail: type: string description: Explicação legível específica desta ocorrência. instance: type: string description: Identificador da ocorrência (/v1?request_id=). errors: type: array description: >- Erros de validação por campo. Presente apenas em validation_error (400). items: type: object properties: field: type: string message: type: string required: type: number description: Tokens necessários. Presente apenas em insufficient_tokens (402). balance: type: number description: Saldo atual de tokens. Presente apenas em insufficient_tokens (402). request_access_url: type: string description: Onde solicitar acesso. Presente apenas em feature_not_enabled (403). securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chave de API do workspace (prefixo slhk_), enviada no header: Authorization: Bearer slhk_sua_chave_aqui ````