Pular para o conteúdo principal

Livro de prompts

Com o servidor MCP conectado, você constrói uma integração com a Cogneris descrevendo o que quer. Estes prompts funcionam como estão no chat de agente do VS Code, Visual Studio, Cursor e Claude Code — cole um, ajuste os nomes e caminhos ao seu projeto e revise o que o assistente propõe antes de aceitar.

Este vídeo mostra o fluxo inteiro no VS Code: uma chave de API, a extração e a classificação em Python e um webhook com assinatura verificada.

MCP da Cogneris: Cogneris no VS Code: MCP, chave de API, código Python e webhooks Assistir no YouTube
Use o modo Agent

No VS Code e no Visual Studio, as ferramentas da Cogneris só ficam disponíveis com o Copilot Chat no modo Agent.

Como escrever um prompt que funciona de primeira​

  • Diga "Cogneris". Isso faz o assistente usar as ferramentas da Cogneris em vez de adivinhar a API.
  • Diga a linguagem e o framework se o projeto não deixar isso óbvio — ".NET 8 minimal API", "Node com TypeScript", "Python com FastAPI".
  • Diga onde ficam os segredos. "Leia a chave de COGNERIS_API_KEY" mantém a chave fora do código.
  • Diga sandbox ou produção. Chaves de sandbox (xtkt_test_…) cobrem o fluxo assíncrono de jobs (/api/v1/artifacts e /api/v1/document-jobs); as rotas síncronas /Document/* e os classificadores precisam de uma chave de produção (xtkt_live_…).
  • Peça um teste. "…e rode contra samples/nota.pdf" faz o assistente provar a integração em vez de só escrevê-la.

Integrar a extração​

Envie um documento para a Cogneris e receba os campos em JSON.

Usando a Cogneris, adicione a esta solução .NET um serviço InvoiceExtractor. Ele recebe o caminho de um PDF, envia o arquivo para a API de extração da Cogneris e devolve os campos extraídos num record tipado Invoice (fornecedor, número da nota, data de emissão, total, moeda). Leia a chave de API de COGNERIS_API_KEY e a URL base de COGNERIS_API_BASE_URL. Trate hasErrors e o limite de taxa 429 com nova tentativa. Adicione um teste xUnit que rode contra samples/nota.pdf.

O que o assistente faz

  1. cogneris_whoami — confirma o seu tenant, o ambiente e a URL base da API a usar.
  2. cogneris_docs_search e cogneris_api_reference para POST /Document/extraction — lê a requisição (multipart/form-data, campo file, ComplementaryPrompt opcional), o envelope da resposta, os erros e os limites (10 MB por arquivo, 50 requisições por minuto por chave).
  3. Escreve o código no seu projeto, seguindo o exemplo de referência da sua linguagem.
  4. Roda o teste, se você pediu — depois de conferir que há uma chave em COGNERIS_API_KEY (crie uma se não houver).

O tipo de código que volta (C#, resumido):

using System.Net.Http.Headers;
using System.Text.Json;

public sealed class InvoiceExtractor(HttpClient http)
{
    public async Task<JsonElement> ExtractAsync(string path, CancellationToken ct = default)
    {
        await using var file = File.OpenRead(path);
        using var form = new MultipartFormDataContent();
        var part = new StreamContent(file);
        part.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
        form.Add(part, "file", Path.GetFileName(path));

        using var response = await http.PostAsync("/Document/extraction", form, ct);
        // The body is JSON even when Content-Type says text/plain.
        using var body = JsonDocument.Parse(await response.Content.ReadAsStringAsync(ct));
        var root = body.RootElement;
        if (!response.IsSuccessStatusCode || root.GetProperty("hasErrors").GetBoolean())
            throw new InvalidOperationException($"Cogneris extraction failed: {root}");

        return root.GetProperty("data").GetProperty("metadata").GetProperty("fields").Clone();
    }
}

// Program.cs
builder.Services.AddHttpClient<InvoiceExtractor>(c =>
{
    c.BaseAddress = new Uri(builder.Configuration["COGNERIS_API_BASE_URL"] ?? "https://api-eu.cogneris.ai");
    c.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", builder.Configuration["COGNERIS_API_KEY"]);
});

Para volumes altos: o fluxo assíncrono​

Usando a Cogneris, mude o extrator para o fluxo assíncrono de jobs: envie o arquivo como artefato, submeta um document job de Extraction com um Idempotency-Key derivado do hash do arquivo e aguarde o resultado. Tem que funcionar com uma chave de sandbox.

O assistente passa a usar POST /api/v1/artifacts → POST /api/v1/document-jobs → GET /api/v1/document-jobs/{jobId} e lê o resultado no artefato de saída do job. Uma submissão repetida com o mesmo Idempotency-Key devolve o job original em vez de processar o documento duas vezes. Combine com um webhook para parar de consultar.

Criar uma chave de API​

Crie uma chave de API de sandbox da Cogneris chamada invoice-importer-dev, só com os escopos de que este projeto precisa, e coloque-a no .env como COGNERIS_API_KEY. Garanta que o .env está no .gitignore.

O que o assistente faz

  1. cogneris_apikeys_create — uma chave de sandbox, com os escopos mínimos para o código que ele viu.
  2. Confere que o .env é ignorado pelo git, grava o valor ali e não o repete no chat. O valor aparece uma única vez; depois a Cogneris mostra só os quatro últimos caracteres.

Para produção, diga explicitamente — "crie uma chave de produção…" — e o assistente pede a sua confirmação antes de criá-la. Para fazer a limpeza depois:

Liste as minhas chaves de API da Cogneris e revogue as que não foram usadas nos últimos 90 dias. Mostre a lista antes de revogar.

Isso exige um token de desenvolvedor com o escopo apikeys.manage. Prefere a tela? Gere uma chave de API na plataforma.

APIs da Cogneris #1: Como gerar e proteger a chave de API da Cogneris Assistir no YouTube

Gerar a sua própria API sobre a Cogneris​

Exponha a extração para o resto da sua empresa por uma API que é sua, com a sua autenticação e o seu formato de resposta.

Usando a Cogneris, crie um novo projeto ASP.NET Core minimal API DocumentGateway com POST /invoices/extract: ele recebe o upload de um PDF (máx. 10 MB), envia para a extração da Cogneris e devolve { supplier, invoiceNumber, issueDate, total, currency }. Devolva 422 quando a Cogneris reportar erros e 503 com Retry-After em caso de limite de taxa. Adicione OpenAPI, health check, um Dockerfile, e leia a chave da Cogneris da configuração — nunca do código. Crie uma chave de API de sandbox da Cogneris para o desenvolvimento local.

O assistente lê as duas rotas da Cogneris com cogneris_api_reference, cria o projeto, conecta o cliente, cria a chave de sandbox no .env e, se você pedir, sobe o serviço e o chama com um arquivo de exemplo.

Criar um webhook​

Seja avisado quando a Cogneris terminar um documento, em vez de ficar consultando.

Usando a Cogneris, registre um webhook em https://api.example.com/hooks/cogneris para documentos processados. Escreva o receptor neste projeto como um endpoint ASP.NET Core que verifica a assinatura da Cogneris sobre o corpo bruto, ignora entregas que já viu e enfileira o id do job. Guarde o segredo de assinatura no .env como COGNERIS_WEBHOOK_SECRET. Depois envie uma entrega de teste e me mostre o resultado.

O que o assistente faz

  1. cogneris_webhooks_event_types — encontra o evento, com.cogneris.document.processed.v1, e confere se ele está ativo (enviado hoje) e não apenas planejado.
  2. cogneris_webhooks_create — registra o endpoint. O segredo de assinatura volta uma única vez, junto com o código do receptor em Node, Python e C#; o assistente grava o segredo no .env.
  3. Escreve o receptor: verifica Cogneris-Webhook-Signature, rejeita carimbos de tempo com mais de 300 segundos e usa Cogneris-Webhook-Id (o mesmo em toda nova tentativa) como chave de idempotência.
  4. cogneris_webhooks_test e depois cogneris_webhooks_deliveries_get — envia uma entrega de teste assinada e mostra o código de status que o seu receptor respondeu.

A assinatura é t=<segundos unix>,v1=<hex>: um HMAC-SHA256 de "<t>." + corpo bruto, com o segredo de assinatura decodificado de base64url como chave — usar o texto do segredo como chave nunca confere. Esta é a verificação que o assistente escreve:

static bool VerifyCogneris(byte[] rawBody, string? signatureHeader, string secret)
{
    string? ts = null, v1 = null;
    foreach (var part in (signatureHeader ?? "").Split(',', StringSplitOptions.TrimEntries))
    {
        if (part.StartsWith("t=")) ts = part[2..];
        else if (part.StartsWith("v1=")) v1 = part[3..];
    }
    if (!long.TryParse(ts, out var t) || v1 is null) return false;
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;
    byte[] supplied;
    try { supplied = Convert.FromHexString(v1); } catch (FormatException) { return false; }
    var key = Base64Url.DecodeFromChars(secret);
    var signed = Encoding.UTF8.GetBytes($"{t}.").Concat(rawBody).ToArray();
    return CryptographicOperations.FixedTimeEquals(HMACSHA256.HashData(key, signed), supplied);
}

O endpoint precisa ser HTTPS público na porta 443 — para um receptor na sua máquina, exponha-o antes por um túnel. Isso exige um token de desenvolvedor com o escopo webhooks.manage.

Quando uma entrega falhar:

Por que as últimas entregas de webhook da Cogneris falharam? Mostre os códigos de status que o meu endpoint respondeu e reenvie as que falharam depois que o receptor estiver corrigido.

APIs da Cogneris #4: Webhooks da Cogneris: assinatura HMAC, novas tentativas e idempotência Assistir no YouTube

Criar o seu próprio tipo de documento​

O servidor traz este fluxo como prompt pronto — no VS Code, digite / no chat e escolha Create and train a Cogneris classifier. Ou escreva:

Usando a Cogneris, crie um classificador chamado "Nota fiscal de fornecedor" a partir dos PDFs em samples/notas/, treine e me avise quando estiver pronto.

O assistente envia as amostras (até 10 arquivos de 10 MB cada por chamada), inicia o treinamento e acompanha o status até Finished. Um classificador pronto passa a conduzir a classificação e a extração do seu tenant.

Perguntar sobre a sua conta​

Quantos documentos e páginas processamos na Cogneris nos últimos 7 dias, por tipo de documento?

Quais rotas da API da Cogneris fazem face match? Mostre a requisição em curl.

Veja também​