Skip to Content
API de integração — v1
Visão geral

Documentação da API

Bem-vindo à documentação da API de integração — emissão e consulta de documentos fiscais eletrônicos (NF-e, NFC-e, NFS-e) de forma programática.

Como funciona

A API é REST, com respostas em JSON e autenticação por chave de API por empresa. Cada requisição autenticada opera sobre os dados da empresa dona da chave — nunca é preciso (nem permitido) informar o identificador da empresa.

Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxx

Primeiros passos

  1. Gere uma chave de API no painel, em Chaves de API (menu lateral). O segredo é exibido uma única vez — guarde-o com segurança.

  2. Faça uma chamada de teste para listar seus documentos fiscais:

    curl https://api.conttrole.io/v1/fiscal-documents \
  -H "Authorization: Bearer ck_live_sua_chave"

  3. Explore os endpoints na Referência da API.

Emitindo um documento

A emissão tem dois passos: criar o documento (rascunho) e emitir (processamento assíncrono junto ao fisco). O clientId deve ser de um cliente já cadastrado na sua empresa.

# 1. Cria o rascunho — use `"emit": true` para já enfileirar a emissão
curl -X POST https://api.conttrole.io/v1/fiscal-documents \
  -H "Authorization: Bearer ck_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "NFE",
    "clientId": "cli_xxx",
    "operationNature": "Venda de mercadoria",
    "items": [
      { "code": "P1", "description": "Produto 1", "cfop": "5102",
        "ncm": "61091000", "unit": "UN", "quantity": 2, "unitValue": 50.0 }
    ],
    "emit": true
  }'

A resposta (201) traz o documento criado. Quando emit: true, ele já entra em PROCESSING e a resposta inclui o runId.

Os impostos podem vir de três formas (nesta prioridade): campos explícitos no item; uma regra tributária (taxRuleId no documento ou no item — crie/liste em /v1/tax-rules); ou a configuração tributária da empresa. NCM ausente herda o da empresa. Em pagamentos, method é um enum (ex: PIX, CREDIT_CARD, OTHERS) e, quando OTHERS, a description é obrigatória.

# 2. (Opcional) Emita depois, se criou só o rascunho
curl -X POST https://api.conttrole.io/v1/fiscal-documents/doc_xxx/emit \
  -H "Authorization: Bearer ck_live_sua_chave"

A emissão roda em segundo plano — acompanhe pelo status do documento (GET /v1/fiscal-documents/{id}) até chegar em AUTHORIZED (ou REJECTED). Vale para NF-e (modelo 55), NFC-e (modelo 65) e NFS-e — o tipo vem no corpo.

Implementando com IA

Use o /llms.txt (índice) ou o /llms-full.txt (conteúdo completo) para alimentar assistentes de IA com o contexto desta API.

Recursos

Last updated on
Autenticação