Documentação - Cloud Fiscal

Autenticação

O Cloud Fiscal utiliza API Tokens via Bearer Auth para autenticar as requisições do seu ERP. A maioria dos endpoints exige que o Token seja passado pelo cabeçalho HTTP Authorization.

Cabeçalho (Header)

Authorization: Bearer 1|seu_token_gerado_no_painel
Accept: application/json
Content-Type: application/json

Você pode gerar seu API Token pelo Painel Dashboard ou por meio direto da API enviando as credenciais cadastradas.

Cadastrar Empresa (Tenant)

Cria um novo Tenant debaixo do seu Guarda-chuva (se você for o dono do Ecossistema) ou cadastra a primeira empresa do contexto da conta.

POST /api/tenants

Parâmetro	Tipo	Descrição
`name`	string	Razão Social da Empresa.
`cnpj`	string	CNPJ válido (14 dígitos). Único no sistema.
`certificate_password`	string	Senha que será utilizada para descriptografar o Certificado Digital A1 enviado futuramente.

Exemplo de Requisição (JSON Payload)

{
    "name": "Minha Empresa de Testes LTDA",
    "cnpj": "12345678000199",
    "certificate_password": "senha_secreta"
}

Configurar Certificado A1 (.pfx)

Faz o Upload do Certificado Digital A1 da empresa requisitante. Sem o certificado configurado, não é possível assinar a NFe.
Atenção: Esta requisição utiliza multipart/form-data.

POST /api/tenants/certificate

Autenticação: Requer Bearer Token

Parâmetro	Tipo	Descrição
`certificate`	file	Arquivo binário .pfx ou .p12 válido contendo a cadeia do certificado A1.

Configurar Logomarca (DANFE)

Faz o Upload do logotipo da empresa. Esta imagem será injetada automaticamente no cabeçalho dos seus PDFs impressos (DANFE).

POST /api/tenants/logo

Autenticação: Requer Bearer Token

Parâmetro	Tipo	Descrição
`logo`	image	Arquivo de imagem (.jpg, .png) máximo 2MB.

Emitir NFe (Simplificado)

Recebe a estrutura dos itens e emitente simplificada e automaticamente a converte, assina, valida schema e transmite para o WebService Sefaz do seu estado de Origem.

POST /api/nfe/issue

Autenticação: Requer Bearer Token

Exemplo de Requisição (JSON Payload NFe Completa Sefaz)

{
    "natureza_operacao": "VENDA DE MERCADORIA",
    "modelo": 55,
    "ambiente": 2, // 1: Produção, 2: Homologação
    "emitente": {
        "cnpj": "12345678000199",
        "inscricao_estadual": "123456789",
        "razao_social": "Minha Empresa de Testes LTDA",
        "endereco": {
            "logradouro": "Rua das Flores",
            "numero": "123",
            "bairro": "Centro",
            "codigo_municipio": "3550308", // IBGE
            "municipio": "Sao Paulo",
            "uf": "SP",
            "cep": "01000000"
        }
    },
    "destinatario": {
        "cpf_cnpj": "11122233344",
        "nome": "Cliente de Teste",
        "indicador_ie": 9 // 9 = Não Contribuinte
    },
    "itens": [
        {
            "numero_item": 1,
            "codigo": "PROD001",
            "descricao": "Produto Exemplo Teste",
            "ncm": "84713012",
            "cfop": "5102",
            "unidade": "UN",
            "quantidade": 1.0000,
            "valor_unitario": 100.00,
            "impostos": {
                "icms": { "origem": 0, "cst": "00", "aliquota": 18.00 }
            }
        }
    ]
}

Resposta de Sucesso (200 OK)

{
    "status": "Transmissão Concluída",
    "nfe_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "sefaz_response": {
        "status_code": "100",
        "motivo": "Autorizado o uso da NF-e",
        "protocolo": "135240001234567",
        "recibo": "351000000000000"
    }
}

Consultar Status Sefaz

Retorna o Status mais recente de processamento da NFe pelo banco de dados baseando-se no ID interno mapeado.

GET /api/nfe/{id}/status

Autenticação: Requer Bearer Token

Parâmetro de Rota	Tipo	Descrição
`id`	UUID	A Identificação alfanumérica Exclusiva da NFe retornada durante o envio.

Status do Serviço SEFAZ

Verifica se os servidores de emissão da SEFAZ estão operacionais no seu Estado. Ideal para acionar contingência offline (NFCe) de forma inteligente de dentro do PDV.

GET /api/sefaz/status?uf=SP

Autenticação: Requer Bearer Token

Query Param	Tipo	Descrição
`uf`	string	(Opcional) A sigla do Estado. Se omitido, usa a do seu Tenant.

Emitir NFCe (Consumidor Final)

A emissão de Nota Fiscal de Consumidor Eletrônica (Modelo 65) ocorre no mesmo endpoint estrutural da NFe. Basta alterar o modelo para 65 e, na maioria dos casos, omitir os dados do destinatário (venda anônima no balcão de varejo).

POST /api/nfe/issue

Exemplo de Requisição (JSON Payload NFCe)

{
    "natureza_operacao": "VENDA DE MERCADORIA",
    "modelo": 65, // 65 = NFCe
    "ambiente": 2, // Homologação
    "emitente": { /* Mesmo da NFe */ },
    "itens": [ /* Matriz de Produtos */ ],
    "pagamento": {
        "tipo": "01", // Dinheiro
        "valor": 100.00
    }
}
// O nó 'destinatario' pode ser enviado apenas com CPF caso o cliente solicite CPF na Nota.

Cancelamento de NFe/NFCe (Evento 110111)

Anula a nota fiscal. Deve ser feito dentro do prazo legal da UF (Ex: 24h para NFe SP, 30 min para NFCe) e desde que a mercadoria não tenha saído da empresa ou o serviço não tenha sido prestado.

POST /api/nfe/{id}/cancel

Autenticação: Requer Bearer Token

Parâmetro	Tipo	Descrição
`justificativa`	string	Motivo do cancelamento (mínimo de 15 caracteres).

Exemplo de Requisição (JSON Payload)

{
    "justificativa": "Erro na digitação do CFOP e valor dos impostos"
}

Carta de Correção Eletrônica (Evento 110110)

Permite corrigir erros específicos na nota fiscal (como endereço do destinatário, transportadora ou dados adicionais), desde que não altere variáveis que determinam o valor do imposto ou data de emissão.

POST /api/nfe/{id}/cce

Exemplo de Requisição (JSON Payload)

{
    "correcao": "O numero correto do endereco do destinatario é 1500 e não 150."
}

Inutilização de Numeração (Evento 110110)

Utilizado quando há quebra de sequência numérica da nota fiscal devido a falhas técnicas no ERP, informando à SEFAZ quais números de fato não foram utilizados e prevenindo malha fina.

POST /api/nfe/inutilize

Exemplo de Requisição (JSON Payload)

{
    "ano": 2026,
    "modelo": 55,
    "serie": 1,
    "numero_inicial": 105, // Falha começou na 105
    "numero_final": 110,  // Pulou até a 110
    "justificativa": "Pulo de numeração devido a falha de sinc do banco de dados local."
}

Envio Automático por E-mail

Aciona o nosso backend para empacotar o XML aprovado e o DANFE em PDF num e-mail transacional direcionado ao consumidor ou contador, eliminando esforços do seu servidor.

POST /api/nfe/{id}/email

Autenticação: Requer Bearer Token

Parâmetro	Tipo	Descrição
`email`	string	E-mail do recpetor (ex: [email protected]).

Eventos Avançados (Reforma Tributária e Logística)

A API conta com um endpoint universal para transmissão de Eventos Genéricos. Basta informar o código do Operador de Evento exigido e os parâmetros JSON. Nossa engine monta o XML do evento perfeitamente.

POST /api/nfe/{id}/event

Código do Evento	Nome do Evento e Casos de Uso
`110150`	EPEC - Evento Prévio em Contingência: Emissão rápida quando o emissor está sem internet ou com problemas técnicos na SEFAZ.
`110180`	Insucesso na Entrega: Registrar tentativas frustradas de entrega da mercadoria pelo motorista (CTe averbado).
`110181`	Cancelamento de Insucesso na Entrega: Estorna o evento de insucesso.
`112140`	Fornecimento Não Realizado: Reforma Tributária - mercadoria não foi entregue, apesar de paga.
`112150`	Atualização de Previsão: Reforma Tributária - atualizar/alterar a data combinada de entrega.

Impressão de DANFE (PDF)

Retorna o arquivo binário do PDF do DANFE (Documento Auxiliar da Nota Fiscal Eletrônica) para impressão ou envio ao cliente. A nota deve estar autorizada.

GET /api/nfe/{id}/danfe

Autenticação: Requer Bearer Token

Parâmetro de Rota	Tipo	Descrição
`id`	UUID	A Identificação da NFe.

A resposta desta requisição é um buffer binário de um arquivo .pdf. Portanto, seu sistema deve salvar a resposta diretamente em disco ou exibi-la em um visualizador PDF nativo no navegador (header Content-Type: application/pdf).

Download de XML (Protocolado)

Baixa ou exibe em String bruta o código-fonte XML Oficial de uma Nota Fiscal Eletrônica já contendo a tag de assinatura e a tag do Protocolo de Autorização de Uso.

GET /api/nfe/{id}/xml

Autenticação: Requer Bearer Token

O Content-Type do retorno será application/xml ou text/xml puro.

Consultar Notas Recebidas (DistDFe)

Varre a base de dados nacional da SEFAZ e retorna um lote de Resumos ou XMLs completos de todas as Notas Fiscais que fornecedores emitiram contra o CNPJ da sua empresa. O sistema guarda inteligentemente o último NSU consultado (cursor) para que sua próxima chamada traga apenas notas novas automaticamente.

GET /api/nfe/recebidas/distribuicao

Autenticação: Requer Bearer Token

Query Param	Tipo	Descrição
`ult_nsu`	string	(Opcional) Traz a partir de um NSU específico se você quiser forçar a reconsulta. Se omitido, usa o do banco.

Imprimir DANFE de Nota Recebida

Gera o PDF do DANFE para uma nota que foi baixada via DistDFe. Como a SEFAZ Nacional retorna o XML em string, você deve enviar esse conteúdo para este endpoint para obter o PDF pronto para impressão.

POST /api/nfe/recebidas/danfe

Autenticação: Requer Bearer Token

Parâmetro	Tipo	Descrição
`xml`	string	Conteúdo XML completo da nota recebida.

Referência da API

Autenticação

Cadastrar Empresa (Tenant)

Configurar Certificado A1 (.pfx)

Configurar Logomarca (DANFE)

Emitir NFe (Simplificado)

Consultar Status Sefaz

Status do Serviço SEFAZ

Emitir NFCe (Consumidor Final)

Cancelamento de NFe/NFCe (Evento 110111)

Carta de Correção Eletrônica (Evento 110110)

Inutilização de Numeração (Evento 110110)

Envio Automático por E-mail

Eventos Avançados (Reforma Tributária e Logística)

Impressão de DANFE (PDF)

Download de XML (Protocolado)

Consultar Notas Recebidas (DistDFe)

Imprimir DANFE de Nota Recebida