# Fiscal Contora - API Fiscal Brasileira para Desenvolvedores e SaaS > API REST/JSON unificada e de alta performance para emissão e gestão de documentos fiscais eletrônicos no Brasil: NF-e (Modelo 55), NFC-e (Modelo 65), NFS-e Nacional (SPED) e Municipal, CT-e (Modelo 57) e MDF-e (Modelo 58). > Desenvolvida especificamente para desenvolvedores, software houses, ERPs e micro-SaaS. Oferece franquia gratuita perpétua de até 500 notas fiscais por mês em ambiente de produção. --- ## Informações Gerais & Base URL - **Base URL Produção & Homologação:** `https://fiscal.contora.com.br/api/v1` - **Ambiente de Testes:** Homologação e Produção usam a mesma URL base, diferenciados pela chave de API (`environment` da API Key) e pelo parâmetro `"environment": "homologacao" | "producao"` no payload. - **Autenticação:** Toda requisição REST deve enviar o header HTTP: ```http Authorization: Bearer Accept: application/json Content-Type: application/json ``` - **Arquitetura Multi-Empresa (Software House):** Um único Token Master de Software House pode emitir para centenas de empresas clientes. Para definir o emitente da requisição, informe: - Header HTTP: `X-Company-Document: ` (Recomendado) - Ou use rotas com prefixo hierárquico: `/companies/{company_id}/...` - **Idempotência Garantida:** Toda operação de criação (`POST`) aceita o cabeçalho: `Idempotency-Key: ` Isso evita duplicação de notas fiscais em caso de retentativas de rede. --- ## Formato Padrão de Resposta da API Todas as respostas da API Fiscal Contora seguem contrato JSON previsível: ### Resposta de Sucesso (HTTP 200 / 201) ```json { "ok": true, "data": { "id": "18f017f7-a69c-4fa6-89c7-05f52fcc8be4", "status": "authorized", "access_key": "41260900000000000191550010000010011000010010", "protocol": "141260000000001" } } ``` ### Resposta de Erro (HTTP 4xx / 5xx) ```json { "ok": false, "message": "Erro de validação fiscal", "error": { "type": "validation_error", "details": { "items.0.taxes.icms.code": ["O campo ICMS é obrigatório para o regime tributário selecionado."] } } } ``` --- ## Ciclo de Vida dos Documentos Fiscais ### 1. NF-e (Modelo 55) e NFC-e (Modelo 65) - Venda de Mercadorias e PDV O fluxo de emissão de NF-e/NFC-e segue 3 passos assíncronos e ultra-resilientes: 1. **Criar Rascunho:** `POST /nfe/drafts` (ou `POST /nfce/drafts`) Envia os dados de negócio (cliente, itens, valores, impostos, pagamentos). Retorna o ID do documento (`DOCUMENT_ID`). 2. **Montar e Assinar (Build):** `POST /nfe/drafts/{DOCUMENT_ID}/build` A API gera o XML oficial, aplica validações de esquema XSD, assina digitalmente com o Certificado A1 da empresa e prepara o lote. 3. **Transmitir para a SEFAZ (Dispatch):** `POST /nfe/drafts/{DOCUMENT_ID}/dispatch` com payload: ```json { "action": "authorize" } ``` A API transmite para a SEFAZ e enfileira a autorização. 4. **Consultar Situação (Polling ou Webhook):** `GET /nfe/drafts/{DOCUMENT_ID}/status` Estados possíveis: `draft` -> `building` -> `built` -> `transmitting` -> `authorized` (ou `rejected` / `error`). 5. **Baixar Artefatos Fiscais (XML e PDF):** - XML Autorizado pela SEFAZ: `GET /nfe/drafts/{DOCUMENT_ID}/artifacts/xml_authorized` - DANFE em PDF: `GET /nfe/drafts/{DOCUMENT_ID}/artifacts/pdf_danfe` --- ### 2. NFS-e - Nota Fiscal de Serviços (Padrão Nacional Sefin / SPED & Municipal) A Fiscal Contora unifica a fragmentação das prefeituras brasileiras em um único contrato JSON: 1. **Criar Rascunho de Serviço:** `POST /nfse/drafts` Envia dados do tomador, descrição do serviço, código nacional (`national_tax_code`), alíquota de ISS e valores. *Nota: Os dados do prestador (CNPJ, Inscrição Municipal, Endereço) são injetados automaticamente a partir do cadastro da empresa na Contora.* 2. **Transmitir e Autorizar:** `POST /nfse/drafts/{DOCUMENT_ID}/dispatch` Transmite a DPS diretamente para o Sefin Nacional ou provedor municipal homologado. 3. **Consultar Status e Baixar Artefatos:** - Status: `GET /nfse/drafts/{DOCUMENT_ID}/status` - XML da NFS-e: `GET /nfse/drafts/{DOCUMENT_ID}/artifacts/xml_nfse` - DANFSe em PDF: `GET /nfse/drafts/{DOCUMENT_ID}/artifacts/pdf_nfse` --- ## Exemplos de Payloads Prontos para Uso ### Exemplo 1: NFS-e Nacional (Simples Nacional / MEI) `POST https://fiscal.contora.com.br/api/v1/nfse/drafts` ```json { "environment": "homologacao", "payload": { "service": { "description": "Desenvolvimento e manutenção de software sob encomenda", "service_code": "01.05.01", "national_tax_code": "010501", "cnae": "6201501", "iss_rate": 2.0, "iss_withheld": false }, "taker": { "name": "Cliente de Exemplo LTDA", "document": "12345678000199", "email": "financeiro@cliente.com.br", "address": { "street": "Avenida Paulista", "number": "1000", "district": "Bela Vista", "city_code": "3550308", "state_code": "SP", "postal_code": "01310100" } }, "amounts": { "service_amount": 1250.00, "net_amount": 1250.00 } } } ``` ### Exemplo 2: NF-e Mercadorias (Simples Nacional - CSOSN 102) `POST https://fiscal.contora.com.br/api/v1/nfe/drafts` ```json { "document_type": "nfe", "environment": "homologacao", "series": 1, "payload": { "nature_operation": "Venda de mercadoria", "recipient": { "name": "Consumidor Final Exemplo", "document": "00000000000", "indicator_state_registration": "9", "address": { "street": "Rua das Flores", "number": "123", "district": "Centro", "city_code": "4106902", "city_name": "Curitiba", "state_code": "PR", "postal_code": "80000000" } }, "items": [ { "code": "PROD-001", "name": "Fone de Ouvido Bluetooth", "ncm": "85183000", "cfop": "5102", "unit": "UN", "quantity": 1, "unit_price": 199.90, "taxes": { "icms": { "code": "102", "origin": 0 } } } ], "payments": [ { "method": "01", "amount": 199.90 } ] } } ``` ### Exemplo 3: NF-e Regime Geral (Lucro Presumido / Real - CST 00) ```json { "taxes": { "icms": { "code": "00", "origin": 0, "aliquot": 18.00 }, "pis": { "code": "01", "aliquot": 1.65 }, "cofins": { "code": "01", "aliquot": 7.60 } } } ``` --- ## Webhooks: Notificações em Tempo Real Receba alertas automáticos quando a SEFAZ ou prefeitura autorizar, rejeitar ou cancelar um documento fiscal. ### Cabeçalhos de Segurança Cada disparo envia: - `X-Fiscal-Signature`: Assinatura hexadecimal HMAC-SHA256 - `X-Fiscal-Timestamp`: Unix timestamp em segundos do momento do disparo ### Validação Criptográfica (Timing-Safe) A assinatura esperada é calculada com: `HMAC-SHA256(timestamp + "." + rawBody, webhookSecret)` Exemplo em Node.js / TypeScript: ```typescript import crypto from 'crypto'; function verifyFiscalWebhook(rawBody: string, signature: string, timestamp: string, secret: string): boolean { const payloadToSign = `${timestamp}.${rawBody}`; const expectedHash = crypto.createHmac('sha256', secret).update(payloadToSign).digest('hex'); return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedHash)); } ``` --- ## Recursos Diferenciais da Fiscal Contora 1. **Responsável Técnico Automático (CSRT / `infRespTec`):** Você não precisa gerar hash nem informar o bloco `infRespTec` nas notas. A plataforma injeta as credenciais cadastradas na sua conta (`PUT /technical-responsible`) automaticamente no XML. 2. **Reforma Tributária 2026 (IBS / CBS):** Suporte pronto para os campos de transição da Reforma Tributária no bloco `taxes.ibscbs` (`cst`, `classification_code`, `state_rate`, `cbs_rate`). 3. **500 Notas Fiscais Grátis/Mês:** Todo desenvolvedor ou software house tem franquia perpétua de até 500 notas fiscais por mês em produção, sem necessidade de cartão de crédito para começar. 4. **Sem Dependências Pesadas:** API puramente HTTP/JSON REST. Elimina completamente a necessidade de servidores Windows, drivers Java, DLLs legadas ou ACBr. --- ## Índice Completo da Documentação Oficial Para explorar endpoints detalhados, tabelas fiscais e especificações avançadas: - [Quickstart da API](https://fiscal.contora.com.br/documentacao/quickstart): Primeiros passos da criação de chave à primeira nota autorizada. - [Referência OpenAPI 3.0](https://fiscal.contora.com.br/documentacao/openapi): Especificação formal e interativa Swagger/OpenAPI. - [Emissão de NF-e](https://fiscal.contora.com.br/documentacao/nfe): Manual exaustivo do Modelo 55 (ICMS, IPI, PIS, COFINS, IBS/CBS, Devolução, Remessa, Fatura e Duplicatas). - [Emissão de NFS-e](https://fiscal.contora.com.br/documentacao/nfse): Manual de Serviços (Padrão Nacional, DPS, substituição com grupo subst e municípios integrados). - [Emissão de NFC-e](https://fiscal.contora.com.br/documentacao/nfce): Varejo, frente de caixa e contingência offline (tpEmis 9). - [Empresas & Multi-Tenant](https://fiscal.contora.com.br/documentacao/empresas): Gestão de múltiplos CNPJs emitentes em uma única conta. - [Certificados Digitais A1](https://fiscal.contora.com.br/documentacao/certificados): Upload e validação de certificados .pfx / .p12. - [Webhooks & Resiliência](https://fiscal.contora.com.br/documentacao/webhooks): Configuração de endpoints, retries exponenciais e assinatura HMAC. - [Prompts para IA (Cursor, Claude, Copilot)](https://fiscal.contora.com.br/documentacao/ia-prompts): Prompts prontos e regras de contexto para assistentes de inteligência artificial. - [Dicionário de Erros & Rejeições SEFAZ](https://fiscal.contora.com.br/documentacao/erros): Solução para rejeições comuns (204, 539, 610, infRespTec, E0116, E0120). - [Dicionário Completo de Rejeições SEFAZ & NFS-e Nacional](https://fiscal.contora.com.br/blog/dicionario-de-rejeicoes-sefaz-nfe-nfse-guia-completo): Catálogo interativo com mais de 20 rejeições detalhadas (865, 869, 778, 539, 610, cBenef 388, X800, E0116, E0084) e payloads JSON prontos. - [Documentação Exaustiva Completa (LLMs-Full)](https://fiscal.contora.com.br/llms-full.txt): Referência integral concatenada com SDKs em PHP, TypeScript, Python e cURL.