Fiscal Contora
Fiscal Contora Infraestrutura fiscal
Documentação / Quickstart v1
Quickstart OpenAPI IA Health
API REST fiscal

Da conta criada ao primeiro build de NF-e em homologação.

Siga esta ordem exata para validar a integração sem transmitir documento para produção. Todos os comandos abaixo usam uma chave e uma empresa configuradas em homologação.

Atualizado em .

Antes de começar

Você precisará de uma conta validada, um certificado A1 da empresa e dados fiscais revisados. Use somente dados da sua própria empresa e confirme a tributação com o contador antes de qualquer emissão real.

Ambiente protegido: uma chave de homologação só acessa empresas e documentos de homologação. Para produção, crie outra chave e vincule-a a uma empresa configurada no mesmo ambiente.

1. Crie a chave de homologação

  1. Crie a conta e valide o código recebido por e-mail.
  2. Entre no console e abra Chaves de API.
  3. Gere uma chave com ambiente Homologação.
  4. Copie o token imediatamente; ele é exibido apenas uma vez.

Valide a chave antes de cadastrar qualquer recurso:

curl --request GET \
  --url https://fiscal.contora.com.br/api/v1/me \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

2. Cadastre a empresa e o certificado

No console, abra Empresas, selecione a chave criada no passo anterior e mantenha o ambiente da empresa como Homologação. Depois, abra a empresa e envie o certificado A1.

Se preferir cadastrar a empresa pela API:

curl --request POST \
  --url https://fiscal.contora.com.br/api/v1/companies \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: empresa-SEU_CNPJ' \
  --data '{
    "legal_name": "SUA RAZAO SOCIAL",
    "trade_name": "SEU NOME FANTASIA",
    "document": "SEU_CNPJ_14_DIGITOS",
    "state_registration": "SUA_INSCRICAO_ESTADUAL",
    "state_code": "UF",
    "city_code": "CODIGO_IBGE",
    "street": "SUA RUA",
    "number": "100",
    "district": "SEU BAIRRO",
    "city_name": "SUA CIDADE",
    "postal_code": "SEU_CEP",
    "tax_regime": "simples",
    "default_environment": "homologacao"
  }'

Guarde o campo data.id da resposta como COMPANY_ID.

curl --request POST \
  --url https://fiscal.contora.com.br/api/v1/companies/COMPANY_ID/certificate \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --form 'certificate=@/caminho/certificado.pfx' \
  --form 'password=SENHA_DO_CERTIFICADO'

3. Crie um rascunho que também passa no build

Este exemplo usa Simples Nacional com CSOSN 102. Ajuste CFOP, NCM, tributação, destinatário e valores ao seu cenário fiscal. O campo taxes.icms.code é obrigatório no build.

Regime e UF precisam ser coerentes: para mei e simples, use CSOSN em taxes.icms.code (como 102). Para presumido e real, use o CST aplicável (como 00). O CFOP também deve refletir o destino: 5102 é um exemplo de venda interna; em operação interestadual, valide o CFOP correspondente com o contador antes de transmitir. 
curl --request POST \
  --url https://fiscal.contora.com.br/api/v1/companies/COMPANY_ID/nfe/drafts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-1001-create' \
  --data '{
    "document_type": "nfe",
    "environment": "homologacao",
    "series": 1,
    "number": 1001,
    "payload": {
      "number": 1001,
      "series": 1,
      "nature_operation": "Venda de mercadoria",
      "operation_type": "saida",
      "consumer_final": true,
      "presence_indicator": 1,
      "recipient": {
        "name": "CLIENTE DE HOMOLOGACAO",
        "document": "CPF_OU_CNPJ",
        "state_registration_indicator": 9,
        "address": {
          "street": "RUA DO CLIENTE",
          "number": "200",
          "district": "CENTRO",
          "city_name": "CIDADE",
          "city_code": "CODIGO_IBGE",
          "state_code": "UF",
          "postal_code": "CEP"
        }
      },
      "items": [{
        "code": "SKU-1",
        "name": "PRODUTO DE HOMOLOGACAO",
        "ncm": "22030000",
        "cfop": "5102",
        "unit": "UN",
        "quantity": 1,
        "unit_price": 10.00,
        "taxes": {
          "icms": {"code": "102", "origin": 0},
          "pis": {"code": "49", "aliquot": 0},
          "cofins": {"code": "49", "aliquot": 0}
        }
      }],
      "payments": [{"method": "01", "amount": 10.00}]
    }
  }'

Guarde o campo data.id como DOCUMENT_ID.

4. Faça o build antes de transmitir

Primeiro valide a montagem sem assinatura e sem contato com a SEFAZ:

curl --request POST \
  --url https://fiscal.contora.com.br/api/v1/companies/COMPANY_ID/nfe/drafts/DOCUMENT_ID/build \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-1001-build' \
  --data '{"sign": false}'
Ponto seguro de validação: receber HTTP 200 no build confirma que empresa, payload e estrutura fiscal mínima foram aceitos. Isso ainda não autoriza nem transmite a NF-e.

5. Autorize somente quando estiver pronto

curl --request POST \
  --url https://fiscal.contora.com.br/api/v1/companies/COMPANY_ID/nfe/drafts/DOCUMENT_ID/dispatch \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-1001-authorize' \
  --data '{"action": "authorize"}'

A resposta HTTP 202 significa que o documento entrou na fila. Consulte:

curl --request GET \
  --url https://fiscal.contora.com.br/api/v1/companies/COMPANY_ID/nfe/drafts/DOCUMENT_ID/status \
  --header 'Authorization: Bearer SEU_TOKEN'
Ciclo completo de NF-e Configurar webhooks Erros e rejeições Abrir playground

Multiempresa

Nas rotas globais, se uma chave estiver vinculada a mais de uma empresa, identifique o emissor com X-Company-Document: CNPJ_SEM_MASCARA. As rotas hierárquicas com /companies/COMPANY_ID/ continuam sendo a opção mais explícita.