Copy page

Inteligência Artificial

API do Chat (IA)

A API do Chat expõe o Assistente Fiscal da Brasil NFe (a nossa IA, com o cérebro fiscal pronto) por HTTP, para você construir a sua própria interface. O cliente manda mensagens em linguagem natural - "emite uma NF-e para o cliente X de R$ 1.500" - e a nossa IA responde, executa a operação e devolve os documentos (DANFE em PDF, XML, cupom HTML).

É a mesma engine do chat do painel, autenticada pelo token de empresa (o mesmo do MCP e da REST API).

Quer ver funcionando antes de integrar? Abra a demo interativa - o mesmo assistente, sem instalar nada.

Chat API ou MCP? Qual usar

São dois caminhos diferentes para integrar IA:

	API do Chat (esta página)	Servidor MCP
Quem traz o modelo de IA	Nós (a nossa IA)	Você (o seu LLM/agente)
O que você constrói	só a interface (UI)	o agente inteiro
Você quer...	usar a nossa IA pronta	conectar a sua IA às nossas ferramentas
Transporte	REST (JSON) ou SSE	MCP (JSON-RPC / Streamable HTTP)

Resumo: se você quer a nossa IA respondendo o seu usuário, use a Chat API. Se você já tem uma IA e só quer dar a ela as ferramentas fiscais, use o MCP.

Endpoint base e autenticação

Recurso	URL
Base da API	https://api.brasilnfe.com.br/services/AiChatApi

Use o mesmo token de empresa da REST API. Envie em um destes cabeçalhos:

Code
Authorization: Bearer SEU_TOKEN
# ou
Token: SEU_TOKEN

O token identifica a empresa: CNPJ, regime tributário, certificado digital e contingência são resolvidos automaticamente a cada turno. O contexto fiscal fica travado na empresa do token - não há risco de cruzar dados entre clientes.

Fluxo geral

1. Crie uma sessão (POST /sessions) - recebe um sessionToken.
2. Envie mensagens para essa sessão (POST /sessions/{token}/messages).
3. A IA responde com texto + executa ferramentas (emitir, consultar, baixar) + gera artefatos.
4. Renderize os artefatos (PDF/XML/HTML) pelas URLs que vêm na resposta.

A sessão guarda o histórico no servidor - você não precisa reenviar a conversa a cada mensagem, só o sessionToken.

Endpoints

Método	Rota	Descrição
POST	/sessions	Cria uma sessão de chat. Retorna sessionToken.
POST	/sessions/{token}/messages	Envia uma mensagem. Modo JSON ou streaming (ver abaixo).
GET	/sessions/{token}/messages	Histórico da conversa.
GET	/sessions/{token}/artifacts	Lista os artefatos gerados na sessão.
GET	/sessions/{token}/artifacts/{messageId}/{kind}	Baixa um artefato inline (kind = pdf, xml, html).
GET	/sessions/{token}/artifacts/{messageId}/download	Baixa um anexo (Content-Disposition: attachment).
GET	/quota	Saldo de créditos disponível.

Todos exigem o cabeçalho Authorization: Bearer SEU_TOKEN.

1. Criar uma sessão

Code
curl -X POST https://api.brasilnfe.com.br/services/AiChatApi/sessions \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Length: 0"

POST exige Content-Length. Esta chamada não tem corpo, mas alguns servidores retornam 411 Length Required se o cliente não enviar Content-Length. Mande -H "Content-Length: 0" (ou um corpo vazio -d '{}').

Resposta:

Code
{
  "sessionToken": "f3a9...c21"
}

Guarde o sessionToken - ele identifica a conversa nas chamadas seguintes. O provedor e o modelo de IA são definidos pela configuração da conta (igual ao chat do painel) - você não escolhe nem precisa informar nada disso.

2. Enviar uma mensagem

O corpo aceita:

Campo	Tipo	Descrição
message	string	Obrigatório. A mensagem do usuário em linguagem natural.
tipoAmbiente	int	1 = produção (emissão real), 2 = homologação (teste). Default 2.

O cabeçalho Accept decide o formato da resposta:

• Accept: application/json (ou ausente) -> resposta única e consolidada.
• Accept: text/event-stream -> streaming SSE, igual ao chat do painel.

Eventos do streaming (SSE)

Evento	Quando	Payload
text	a IA escreve a resposta	{ delta }
tool_call_start	a IA começa uma ferramenta	{ callId, name }
tool_call_delta	argumentos chegando	{ callId, delta }
tool_call_end	argumentos completos	{ callId, args }
tool_result	a ferramenta terminou	{ callId, ok, summary }
artifact	um documento foi gerado	{ messageId, kind, fileName, url }
usage	fim do turno	{ quotaUsedPct, quotaSource }
done	turno encerrado	{ reason }
error	falha no turno	{ code, message, retryAfterSeconds }
session_changed	a conversa foi reiniciada por inatividade	{ sessionToken, reason }

Se você receber session_changed, passe a usar o novo sessionToken nas próximas mensagens.

3. Visualização (artefatos)

Quando a IA emite um documento, ela gera um artefato binário. Cada artefato vem com messageId, kind e uma url já pronta. Você decide como mostrar:

• PDF (kind: "pdf") - o DANFE pronto. Renderize num <iframe src="..."> ou ofereça download.
• XML (kind: "xml") - o XML autorizado. Útil para guardar ou processar.
• HTML (kind: "html") - o cupom da NFC-e. Embeda direto.

Code
curl https://api.brasilnfe.com.br/services/AiChatApi/sessions/f3a9...c21/artifacts/88/pdf \
  -H "Authorization: Bearer SEU_TOKEN" --output danfe.pdf

Para listar todos os artefatos de uma sessão (útil ao reabrir a conversa):

Code
curl https://api.brasilnfe.com.br/services/AiChatApi/sessions/f3a9...c21/artifacts \
  -H "Authorization: Bearer SEU_TOKEN"

Além do documento renderizado, a resposta da mensagem traz os dados estruturados (toolCalls[].summary, número, status) - você pode montar a sua própria visualização sem depender do nosso PDF.

4. Cobrança

Cada turno consome créditos da carteira da empresa do token (proporcional ao tamanho da resposta e às ferramentas usadas). Detalhes:

• O acesso via API consome apenas créditos comprados - não usa a cota grátis mensal do plano (essa é exclusiva do chat do painel).
• Sem saldo, o turno é recusado com HTTP 402. Compre créditos no painel para continuar.
• Consulte o saldo a qualquer momento:

Code
curl https://api.brasilnfe.com.br/services/AiChatApi/quota \
  -H "Authorization: Bearer SEU_TOKEN"

Code
{
  "source": "credits",
  "credits": {
    "balanceBrl": 92.0,
    "balanceCredits": 1840,
    "valuePerCreditBrl": 0.05,
    "expirationMonths": 8
  }
}

Produção vs homologação: use tipoAmbiente: 2 (homologação) enquanto integra - as NF-e de teste não têm valor fiscal. Mude para tipoAmbiente: 1 só quando for emitir de verdade.

Códigos de status

HTTP	code	Significado
401	missing_token / invalid_token	Token ausente ou inválido.
403	no_owner / session_blocked	Empresa sem dono vinculado, ou sessão bloqueada.
400	missing_message	O campo message não foi enviado.
404	session_not_found / invalid_session	Sessão inexistente para este token.
402	credits_empty / credits_exhausted	Sem créditos. Compre mais no painel.
429	rate_limited / global_cap	Excedeu o rate-limit. Veja Retry-After.
409	session_stale_empresa	A empresa mudou; recrie a sessão.
502	server_exception	Falha temporária. Tente novamente.

No modo JSON, o corpo sempre traz error: { code, message } quando há falha; no SSE, vem como evento error.

Boas práticas para produção

• Uma sessão por conversa. Reutilize o sessionToken enquanto for o mesmo diálogo; crie uma nova sessão para conversas independentes.
• Trate o 402. Mostre ao usuário um aviso de "sem créditos" e o link para comprar.
• Respeite o Retry-After nos 429.
• Comece em homologação (tipoAmbiente: 2) e só promova para produção depois de validar o fluxo.
• Guarde os artefatos que precisar (PDF/XML) do seu lado - as URLs são escopadas à sessão.