Cadastre empresas fiscais antes de emitir qualquer documento.

Empresas

Cada emissor opera dentro de uma empresa fiscal cadastrada na plataforma. Crie primeiro a chave de API: a empresa deve usar o mesmo ambiente da chave escolhida.

{
  "legal_name": "Empresa Exemplo de Comercio Ltda",
  "trade_name": "Empresa Exemplo",
  "document": "12345678000195",
  "tax_regime": "presumido",
  "state_registration": "123456789",
  "phone": "11999999999",
  "state_code": "SP",
  "city_code": "3550308",
  "street": "Rua das Araucarias",
  "number": "120",
  "district": "Centro",
  "city_name": "Sao Paulo",
  "postal_code": "01001000",
  "default_environment": "homologacao"
}

Paraná exige CSRT. Empresas com state_code PR só emitem NF-e depois que o identificador e o token do CSRT estiverem cadastrados em Responsável técnico. A SEFAZ-PR recusa com a Rejeição 975 quando o grupo infRespTec chega sem eles, e a exigência vale também em homologação. Sem o cadastro, a API recusa a montagem com 422 em vez de consumir numeração numa rejeição certa. O CSRT é emitido pelo portal da SEFAZ-PR para o CNPJ do responsável técnico.

Regime tributário e CRT

O campo tax_regime define o enquadramento fiscal da empresa e o Código de Regime Tributário (CRT) gerado nos documentos fiscais (NF-e, NFC-e e CT-e):

Emissão em homologação com empresa em produção (allows_homologation): empresas cadastradas com default_environment: "producao" podem habilitar allows_homologation: true. Isso permite utilizar a chave de produção da conta para criar, compilar e testar rascunhos em homologação (informando "environment": "homologacao" no payload), sem necessidade de cadastrar uma empresa espelho em homologação.

Identificação em rotas globais

Se uma chave estiver vinculada a várias empresas, use X-Company-Document: CNPJ_SEM_MASCARA. O alias legado X-Company-CNPJ continua aceito por compatibilidade, mas novas integrações devem usar o nome oficial.

Dados mínimos esperados

• Razão social e nome fantasia, quando houver.
• CNPJ da empresa emitente.
• Regime tributário correto.
• Inscrição estadual, quando aplicável.
• Endereço completo com código IBGE do município.

Emitir homologação em uma empresa de produção

Uma empresa de produção pode também gerar espelhos de homologação (notas de teste, sem valor fiscal) usando a mesma chave de API. Por padrão isso fica bloqueado; para liberar, ligue allows_homologation na empresa — pelo console do operador ou via API:

PATCH /api/v1/companies/{company}
{
  "allows_homologation": true
}

Com a liberação ativa, o ambiente de cada documento é definido no campo environment de cada rascunho: "producao" emite nota real (comportamento normal) e "homologacao" emite um espelho de teste. A produção não é afetada — a liberação vale apenas para o ambiente de homologação e é opt-in por empresa. A transição de default_environment para produção pode ser feita diretamente via PATCH com uma chave de API de produção, ou pelo console web.

Atualizar o cadastro

O PATCH aceita payload parcial: só os campos enviados são alterados, o resto fica como está. É o caminho para refletir na Contora uma correção feita no seu sistema depois do cadastro inicial — uma inscrição municipal preenchida mais tarde, uma mudança de endereço, a alíquota de ISS padrão.

{
  "trade_name": "Empresa Exemplo",
  "street": "Avenida Paulista",
  "number": "1000",
  "postal_code": "01310100",
  "phone": "1133334444",
  "settings": {
    "municipal_registration": "1122770",
    "nfse_service_code_default": "1.05",
    "nfse_municipal_tax_code_default": "004",
    "nfse_cnae_default": "6201500",
    "nfse_iss_rate_default": 2.5
  }
}

O bloco settings é mesclado chave a chave. Enviar apenas municipal_registration não apaga as demais configurações de NFS-e. Para limpar uma chave específica, envie-a com null. Omitir settings inteiro não toca em nada.

nfse_municipal_tax_code_default guarda o cTribMun de 3 dígitos usado no padrão nacional. Ele é exigido para prestadores não-MEI do Rio de Janeiro e não pode ser inferido pelo código nacional: um mesmo national_tax_code pode ter mais de um desdobramento municipal. Confirme o valor na tabela municipal ou com a contabilidade da empresa.

Além dos dados de endereço e identificação, o PATCH cobre o cnae fiscal do emitente (vai em emit/CNAE na NF-e, aceito como 6201-5/00 ou 6201500) e, dentro de settings, as duas características do município que definem o caminho de emissão da NFS-e: nfse_standard (nacional ou municipal) e nfse_municipal_registration_in_cnc. Quando a opção estiver ativa, municipal_registration deve ser uma string idêntica à IM registrada no CNC NFS-e, inclusive com zeros à esquerda; município, CNPJ/CPF e IM divergentes retornam E0116. Onde o município não registra a inscrição no CNC, informá-la faz o Sistema Nacional recusar com E0120 e a opção deve ficar como false.

O CNC é carregado por ambiente, e quem o alimenta é o município conveniado — o contribuinte não publica o próprio registro. É comum a mesma empresa já constar na produção restrita e ainda não constar em produção, e aí um único valor não atende os dois: falta a IM em homologação (E0116) ou sobra em produção (E0120). Para esse caso existe nfse_municipal_registration_in_cnc_producao, que sobrepõe a opção geral apenas em produção. Ausente ou null, produção segue a opção geral e nada muda para quem já estava configurado.

Municipios de leiaute proprio tambem podem exigir um login proprio do webservice — o usuario que consulta e acompanha a NFS-e junto a prefeitura. Em settings isso vai em nfse_ws_user e nfse_ws_password. As duas sao somente escrita: gravadas pelo PATCH e nunca devolvidas na resposta; o GET apenas informa nfse_ws_user_set e nfse_ws_password_set como true. Para limpar uma credencial, envie a chave com null. Uma atualizacao que nao fala sobre elas preserva o que ja estava guardado, como no resto do bloco.

O campo document não é alterável pela API, pois é a identidade fiscal do cadastro e âncora do histórico já emitido — outro CNPJ é outra empresa, criada com POST. Já o default_environment pode ser promovido de "homologacao" para "producao" enviando {"default_environment": "producao"} autenticado com uma chave de API de produção (vinculando a chave e mantendo allows_homologation ativo). A reversão de produção para homologação permanece restrita ao suporte e ao console web para evitar desativações acidentais. Repetir o valor atual de qualquer campo é aceito em silêncio; tentativas inválidas respondem 422 com immutable_field.

Sincronizar pelo CNPJ (upsert)

Para ERPs em que o cadastro local é a fonte da verdade e cada "Salvar" precisa ser refletido aqui, o upsert por CNPJ evita guardar o UUID e decidir entre criar e atualizar:

O CNPJ vai na URL somente com dígitos. A rota é idempotente: responde 201 quando cria o cadastro e 200 quando atualiza um existente, sempre com o cadastro completo no corpo. Quando o CNPJ existe, valem as mesmas regras do PATCH — inclusive a mesclagem de settings. Quando não existe, o corpo precisa trazer os campos obrigatórios de criação (legal_name, state_code, tax_regime). Um CNPJ pertencente a outra conta responde 409.

Logomarca nos documentos (DANFE, DANFCe, DACTe, DAMDFe)

É possível exibir a logomarca da empresa no topo dos documentos impressos. O upload pode ser feito pelo console do operador, em Empresas → abrir a empresa → seção Logomarca, ou pela API — útil quando a integração provisiona empresas sozinha. Aceita arquivos PNG ou JPG de até 1 MB; o arquivo é guardado em armazenamento privado e nunca é exposto publicamente — ele é usado apenas para compor o PDF.

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -F "logo=@/caminho/logo.png" \
  https://fiscal.contora.com.br/api/v1/companies/{company}/logo

Envio em multipart/form-data no campo logo. Responde 201 com o cadastro atualizado. DELETE na mesma rota remove a logomarca, e os próximos documentos voltam a ser emitidos sem ela — os já emitidos não mudam.

Depois de enviada, a logomarca passa a aparecer automaticamente nos próximos documentos emitidos (DANFE da NF-e, DANFCe da NFC-e, DACTe do CT-e e DAMDFe do MDF-e). Para conferir se uma empresa já possui logomarca cadastrada, a resposta da API traz o campo booleano has_logo:

GET /api/v1/companies/{company}
{
  "ok": true,
  "data": {
    "has_logo": true,
    ...
  }
}

Para trocar ou remover a logomarca pelo console, use os botões da mesma seção.

Responsável técnico e CSRT (infRespTec)

O responsável técnico representa a software house / desenvolvedor do ERP, e não a empresa emitente. O cadastro é feito uma única vez por conta e vale automaticamente para todas as empresas administradas por ela. A plataforma Fiscal Contora injeta o grupo <infRespTec> no XML de todas as NF-e (modelo 55) e NFC-e (modelo 65) emitidas pela sua conta, sem que você precise informar esses dados no payload de cada nota.

{
  "legal_name": "Software House Exemplo Ltda",
  "document": "98765432000188",
  "contact_name": "Equipe de Integracao Fiscal",
  "email": "[email protected]",
  "phone": "11999998888",
  "system_name": "MeuERP SaaS",
  "system_version": "4.2.0"
}

É idempotente: cria no primeiro envio e atualiza nos seguintes. Como o cadastro pertence à conta, uma chave de API sem usuário vinculado responde 409.

Credenciais de CSRT por Estado

Alguns estados (como Paraná (PR), Rio Grande do Sul (RS), Mato Grosso do Sul (MS), Alagoas (AL) e Tocantins (TO)) exigem o CSRT (Código de Segurança do Responsável Técnico) fornecido pela SEFAZ estadual. Sem o CSRT cadastrado, a SEFAZ recusa a emissão com as Rejeições 975 ou 976.

{
  "csrt_id": "01",
  "csrt_token": "CSRT-FORNECIDO-PELA-SEFAZ"
}

O csrt_token é obrigatório no primeiro cadastro da UF; omitido nas chamadas seguintes, o token guardado é mantido e só o csrt_id muda. O segredo é gravado cifrado e nunca volta na resposta — o que a API devolve é has_csrt_token: true. A Fiscal Contora calcula automaticamente o hashCSRT (SHA-1) em cada emissão. DELETE na mesma rota remove a credencial da UF.

Filtros da listagem

• q para buscar por razão social, nome fantasia ou CNPJ.
• document, tax_regime, default_environment e state_code.
• has_certificate para separar empresas prontas para emissão.