Como emitir uma NF com um agente (Awa Rails, beta fechado)

Resposta curta: a emissão e a recepção reais de NF com o Awa Rails ainda estão em desenvolvimento e chegam em breve para o beta fechado (early access). O fluxo planejado é: gerar uma chave de API, conectar o MCP ao agente (ou chamar a API) e receber eventos por webhook. Hoje o app está no ar em beta fechado, com o núcleo (API, MCP e webhook) funcionando; o transporte fiscal ainda é simulado. Acesso gratuito, com aprovação manual.

Status honesto. No ar em beta fechado (núcleo funcionando, transporte fiscal ainda simulado): cadastro, envio de certificado, chave de API, MCP, webhook e formulário de beta. Em desenvolvimento: recepção, ciência, manifestação e emissão de NF. Login sem senha por Google ou código por email ainda em testes. Os comandos e campos abaixo vêm do código em testes. O MCP foi testado com o Claude Code contra uma build local do mesmo código, ainda não com uma chave de produção (a produção ainda não tem organização aprovada). Todo resultado de recepção, ciência e emissão hoje é simulado (mock) e traz mocked: true, sem validade fiscal.

O que é o Awa Rails?

Uma API fiscal para agentes de IA e automações, em beta fechado. O objetivo é receber e emitir notas com o certificado digital da empresa, por API e MCP, com webhook de eventos. O front é mínimo e não há interface para visualizar documentos fiscais. Feito para agentes como Claude, GPT e Grok via MCP ou API (uso pretendido, sem parceria anunciada).

O que você vai precisar

Passo 1: onboarding

Cadastre a empresa e envie o certificado digital. A proposta é login sem senha (Google ou código por email); isso ainda está em testes.

No envio, o app abre o arquivo PFX, confere se a raiz do CNPJ bate com a empresa e se o certificado não está vencido (máximo de 256 KB). O teste de conexão do certificado ainda é simulado (mock).

Passo 2: gere sua chave de API

Crie a chave nas configurações e guarde-a como variável de ambiente.

A chave tem o formato afk_..., aparece uma única vez e é guardada com hash. A mesma chave vale para a API REST e para o MCP, enviada no cabeçalho Authorization: Bearer afk_.... Base da API REST: https://rails.awafinance.com/api/v1.

export AWA_RAILS_API_KEY="afk_YOUR_KEY"

Passo 3: conecte o MCP ao seu agente

Endpoint: POST https://rails.awafinance.com/mcp. Transporte: MCP Streamable HTTP, sem estado, só respostas JSON (sem SSE nem sessões). Um GET retorna 405 e um POST sem chave retorna 401. Status: em testes. Foi verificado com o Claude Code contra uma build local, ainda não com uma chave de produção.

Claude Code:

claude mcp add --transport http awa-rails https://rails.awafinance.com/mcp --header "Authorization: Bearer afk_YOUR_KEY"

Configuração JSON genérica (o formato url/headers é o comum para servidores remotos, mas só foi testado no Claude Code):

{ "mcpServers": { "awa-rails": { "url": "https://rails.awafinance.com/mcp", "headers": { "Authorization": "Bearer afk_YOUR_KEY" } } } }

Ferramentas (12): list_companies, upload_certificate, test_certificate, set_auto_ciencia, set_webhook, sync_notes, list_notes, get_note, manifest_note, emit_nfse, reconcile_emission, list_emissions.

Skill de onboarding (a confirmar)

Uma skill para ensinar o agente a usar a API e o MCP está em preparação.

Passo 4: emissão de NF (em breve no beta)

A emissão básica de NFS-e (NFS-e Nacional, DPS v1.01, serviço prestado a empresa) está em desenvolvimento. O app monta e assina a DPS, mas por padrão não transmite à SEFIN: o resultado é simulado e não tem validade fiscal. Somente homologação pode ser habilitada; produção está bloqueada no código. Não é NF-e de produto.

# Corpo resumido. Campos reais, resposta simulada (mock).
curl -X POST https://rails.awafinance.com/api/v1/companies/COMPANY_ID/emissions \
  -H "Authorization: Bearer afk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"inv-2026-10-001","competence":"2026-10-01",
 "issuer":{"municipality_code":"3304557","municipal_registration":"123456","simple_national_option":"1","special_tax_regime":"0"},
 "customer":{"cnpj":"11444777000161","name":"CLIENTE EXEMPLO LTDA","address":{"municipality_code":"3304557","postal_code":"20040020","street":"Rua Exemplo","number":"100","district":"Centro"}},
 "service":{"municipality_code":"3304557","national_tax_code":"010501","municipal_tax_code":"001","description":"..."},
 "values":{"service_amount":"2000.00","iss_taxation":"1","iss_retention":"1","iss_rate":"5.00"}}'

# Resposta (mock, sem validade fiscal):
{"id":"a2f67aca-...","status":"authorized","series":"1","number":1,
 "environment":"mock","mocked":true,
 "message":"MOCK: DPS built and signed for real, but NOT transmitted to SEFIN; no fiscal validity"}

Status possíveis: pending, submitted, authorized, failed, ambiguous, cancelled. Se vier ambiguous, chame POST .../emissions/{id}/reconcile e nunca reenvie.

Passo 5: webhook de eventos

O webhook está no ar em beta fechado. Notas recebidas de verdade, ciência automática e manifestação dependem da recepção, que está em desenvolvimento.

Cada empresa tem uma webhook_url (https). O segredo whsec_... é devolvido uma única vez, no primeiro salvamento. Cada entrega leva os cabeçalhos Awa-Rails-Signature: t=<unix>,v1=<hex>, em que v1 = HMAC_SHA256(segredo, t + "." + corpo bruto), e Awa-Rails-Delivery: <id>. Eventos: nfe.received, nfe.manifested, nfe.full_xml_available, nfse.emitted, webhook.test. Até 6 tentativas com espera exponencial; destinos em IPs privados ou loopback são bloqueados em produção. Como a recepção ainda é simulada, o exemplo abaixo é ilustrativo.

{"event":"nfe.received","company_id":"...","created_at":"...Z",
 "data":{"note_id":"...","chave":"44 dígitos","kind":"summary","emitter_cnpj":"...","emitter_name":"...","amount_cents":150200}}

Métricas de uso

O app inclui uma página de uso. Os indicadores exibidos ainda não foram detalhados aqui.

Perguntas frequentes

O Awa Rails já emite e recebe notas de verdade?

Ainda não. Estamos em beta fechado (early access). Recepção, ciência, manifestação e emissão estão em desenvolvimento e chegam em breve para o beta. Hoje o núcleo de API, MCP e webhook está em testes.

Isso é um sistema com telas para ver minhas notas?

Não. O Awa Rails é uma API com MCP e webhook. O painel é mínimo e cuida só de onboarding, configurações, cobrança, pagamentos, métricas de uso e chaves de API/MCP.

O Awa Rails tem custo?

O beta é gratuito. O acesso é liberado manualmente pela nossa equipe.

Preciso de certificado digital?

Sim. As operações fiscais vão usar o certificado digital da empresa, enviado no onboarding.

Como meu certificado é protegido?

O certificado A1 é armazenado criptografado (AES-256-GCM) e usado apenas para operações fiscais da sua empresa. Detalhes de segurança serão publicados antes do lançamento geral.

Preciso criar uma senha?

A proposta é onboarding sem senha. O login por Google ou código por email ainda está em testes.

Funciona com o meu agente?

Foi feito para agentes como Claude, GPT e Grok, via MCP ou API. Qualquer agente compatível com MCP, ou capaz de chamar uma API HTTP, deve conseguir usar. Ainda em testes, sem parceria anunciada.

Quando recebo o acesso?

Pedidos entram numa fila e liberamos manualmente. Avisaremos pelo email informado.

In English: issuing an invoice (NF) with an agent

Awa Rails is a fiscal API for AI agents, in closed beta (early access). The API, MCP server and event webhook are in testing; real invoice receiving, acknowledgment, manifestation and issuing are still in development and not yet live. Free beta with manual approval. MCP endpoint: POST https://rails.awafinance.com/mcp (Streamable HTTP, header Authorization: Bearer afk_...), tested with Claude Code against a local build, not yet with a production key. All fiscal results are mocked today.