Como ativar o serviço de Web API

Teste de funcionamento

Após criar a integração, aguarde até 5 minutos, acesse seu navegador de preferência e informe o [nome ou endereço do servidor] + [porta de rede] onde o servidor ativado conforme exemplo abaixo. Lembrando que estas duas informações [servidor] e [porta] são encontradas na tela acima.

Ao acessar a Web API via navegador, deverá aparecer uma tela conforme exemplo abaixo.

Endpoints disponíveis

Endpoints Get : Consulta de Dados

⚠️ IMPORTANTE: Os exemplos de resposta abaixo são apenas amostras com alguns campos principais. Para obter todos os campos disponíveis e suas estruturas completas, realize consultas reais aos endpoints com dados de produção.

GET / - Welcome/Status

Descrição: Endpoint de boas-vindas e verificação de status do servidor.

curl --location 'http://localhost:8000/'

Resposta:

{
  "Object": "Seja bem vindo ao Fiscal.io Server\nutilize este endereço para comunicar com o Fiscal.io Monitor\nA comunicação deve ser feita utizando JSON.\nPara mais informações consulte nossa documentação em\nhttps://docs.fiscal.io/integracoes"
}

GET /DOC/{chave} - Obter Documentos Fiscais e Eventos Relacionados

Descrição: Obter documentos fiscais e eventos relacionados.

Exemplo de Uso:

curl --location 'http://localhost:8000/DOC/{chave de acesso}'

Parâmetros:

• {chave}: Chave de acesso do documento fiscal (44 dígitos)

Resposta:

{
  "Object": {
    // AMOSTRA: Este é apenas um exemplo com alguns campos principais
    // Para obter todos os campos disponíveis, realize uma consulta real
    "DocList": [
      {
        "Chave": "35250432722095000143550010000028791105593659", // Chave de acesso do documento fiscal
        "Filial": "12345678000199", // CNPJ da filial
        "Model": "55", // Modelo do documento (55=NFe, 57=CTe, etc.)
        "Serie": "1", // Série do documento
        "Numero": "28791", // Número do documento
        "DhEmi": "2024-12-15T10:30:00", // Data e hora de emissão
        "Status": "Autorizada" // Status do documento
      }
    ],
    // AMOSTRA: Este é apenas um exemplo com alguns campos principais do DocItem
    // Para obter todos os campos disponíveis, realize uma consulta real
    "ItemList": [
      {
        "Chave": "35250432722095000143550010000028791105593659", // Chave de acesso do documento fiscal
        "nItem": "1", // Número sequencial do item
        "cProd": "123456789", // Código do produto
        "cEAN": "7891234567890", // Código de barras EAN
        "xProd": "Produto Exemplo", // Descrição do produto
        "NCM": "12345678", // Código NCM do produto
        "CFOP": "5102", // Código fiscal de operações e prestações
        "uCom": "UN", // Unidade comercial
        "qCom": "1.0000", // Quantidade comercial
        "vUnCom": "100.00", // Valor unitário comercial
        "vProd": "100.00", // Valor total do produto
        "uTrib": "UN", // Unidade tributável
        "qTrib": "1.0000", // Quantidade tributável
        "vUnTrib": "100.00", // Valor unitário tributável
        "vFrete": "0.00", // Valor do frete
        "vSeg": "0.00", // Valor do seguro
        "vDesc": "0.00", // Valor do desconto
        "vOutro": "0.00", // Outros valores
        "indTot": "1", // Indicador de total
        "ICMSBase": "100.00", // Base de cálculo do ICMS
        "ICMSTaxa": "18.00", // Alíquota do ICMS
        "ICMSValor": "18.00", // Valor do ICMS
        "ICMSCdCst": "00", // Código de situação tributária do ICMS
        "ICMSOrig": "0" // Origem da mercadoria
      }
    ],
    // AMOSTRA: Este é apenas um exemplo com alguns campos principais
    // Para obter todos os campos disponíveis, realize uma consulta real
    "EventList": [
      {
        "Chave": "35250432722095000143550010000028791105593659", // Chave de acesso do documento fiscal
        "tpEvento": "110111", // Tipo do evento (110111=Cancelamento, 110140=Carta de Correção, etc.)
        "nSeqEvento": 1, // Número sequencial do evento
        "dhEvento": "2024-12-15T10:35:00" // Data e hora do evento
      }
    ]
  }
}

Campos de Resposta:

• DocList: Lista de documentos encontrados
• ItemList: Lista de itens dos documentos com campos:
  • Chave: Chave de acesso do documento fiscal
  • nItem: Número sequencial do item
  • cProd: Código do produto
  • cEAN: Código de barras EAN
  • xProd: Descrição do produto
  • NCM: Código NCM do produto
  • CFOP: Código fiscal de operações e prestações
  • uCom: Unidade comercial
  • qCom: Quantidade comercial
  • vUnCom: Valor unitário comercial
  • vProd: Valor total do produto
  • uTrib: Unidade tributável
  • qTrib: Quantidade tributável
  • vUnTrib: Valor unitário tributável
  • vFrete: Valor do frete
  • vSeg: Valor do seguro
  • vDesc: Valor do desconto
  • vOutro: Outros valores
  • indTot: Indicador de total
  • ICMSBase: Base de cálculo do ICMS
  • ICMSTaxa: Alíquota do ICMS
  • ICMSValor: Valor do ICMS
  • ICMSCdCst: Código de situação tributária do ICMS
  • ICMSOrig: Origem da mercadoria
    
  • .....
• EventList: Lista de eventos relacionados aos documentos

GET /DOC/{chave}/{tipoEvento} - Obter Eventos Relacionados a Documentos Fiscais

Descrição: Obter eventos relacionados a documentos fiscais.

Exemplo de Uso:

curl --location 'http://localhost:8000/DOC/{chave de acesso do documento fiscal}/{código do tipo de evento conforme manual da sefaz}'

Parâmetros:

• {chave}: Chave de acesso do documento fiscal (44 dígitos)
• {tipoEvento}: Código do tipo de evento conforme manual da SEFAZ

Resposta:

{
  "Object": {
    // AMOSTRA: Este é apenas um exemplo com alguns campos principais
    // Para obter todos os campos disponíveis, realize uma consulta real
    "EventList": [
      {
        "Chave": "35250432722095000143550010000028791105593659", // Chave de acesso do documento fiscal
        "tpEvento": "110111", // Tipo do evento (110111=Cancelamento, 110140=Carta de Correção, etc.)
        "nSeqEvento": 1, // Número sequencial do evento
        "dhEvento": "2024-12-15T10:35:00", // Data e hora do evento
        "xJust": "Justificativa do evento" // Justificativa do evento (quando aplicável)
      }
    ]
  }
}

GET /DOC/PDF/{chave} - Obter PDF do Documento

Descrição: Obter PDF do documento fiscal.

Exemplo de Uso:

curl --location 'http://localhost:8000/DOC/PDF/{chave de acesso}'

Parâmetros:

• {chave}: Chave de acesso do documento fiscal (44 dígitos)

Resposta:

{
  "Object": {
    "ObjKey": "35250432722095000143550010000028791105593659",
    "ObjType": "PDF",
    "ObjGzip": "base64_encoded_gzip_content"
  }
}

Campos de Resposta:

• ObjKey: Chave do documento
• ObjType: Tipo do arquivo ("PDF")
• ObjGzip: Conteúdo do arquivo PDF comprimido em GZIP e codificado em Base64

2.5 GET /DOC/XML/{chave} - Download XML

Descrição: Download do arquivo XML de um documento fiscal.

curl --location 'http://localhost:8000/DOC/XML/{chave de acesso}'

Parâmetros:

• {chave}: Chave de acesso do documento fiscal (44 dígitos)

Resposta:

{
  "Object": {
    "ObjKey": "35250432722095000143550010000028791105593659",
    "ObjType": "XML",
    "ObjGzip": "base64_encoded_gzip_content"
  }
}

Campos de Resposta:

• ObjKey: Chave do documento
• ObjType: Tipo do arquivo ("XML")
• ObjGzip: Conteúdo do arquivo XML comprimido em GZIP e codificado em Base64

GET /DOC/EDINOTFIS/{chave} - Download EDI NotFis

Descrição: Download do arquivo EDI NotFis gerado a partir do XML.

curl --location 'http://localhost:8000/DOC/EDINOTFIS/{chave de acesso}'

Parâmetros:

• {chave}: Chave de acesso do documento fiscal (44 dígitos)

Resposta:

{
  "Object": {
    "ObjKey": "35250432722095000143550010000028791105593659",
    "ObjType": "EDI NotFis",
    "ObjGzip": "base64_encoded_gzip_content"
  }
}

GET /DOC/EDICONEMB/{chave} - Download EDI Conemb

Descrição: Download do arquivo EDI Conemb gerado a partir do XML.

curl --location 'http://localhost:8000/DOC/EDICONEMB/{chave de acesso}'

Parâmetros:

• {chave}: Chave de acesso do documento fiscal (44 dígitos)

Resposta:

{
  "Object": {
    "ObjKey": "35250432722095000143550010000028791105593659",
    "ObjType": "EDI Conemb",
    "ObjGzip": "base64_encoded_gzip_content"
  }
}

GET /COMPANY/{cnpj} - Informações da Empresa

Descrição: Consulta informações de uma empresa cadastrada.

curl --location 'http://localhost:8000/COMPANY/{cnpj}'

Parâmetros:

• {cnpj}: CNPJ da empresa (14 dígitos)

Resposta:

{
  "Object": {
    // AMOSTRA: Este é apenas um exemplo com alguns campos principais
    // Para obter todos os campos disponíveis, realize uma consulta real
    "CNPJ": "12345678000199", // CNPJ da empresa
    "Nome": "Empresa Exemplo Ltda", // Razão social da empresa
    "Estado": "SP", // Sigla do estado
    "Certificado": "1234567890123456789012345678901234567890", // Serial do certificado digital
    "Environment": "1", // Ambiente (1=Homologação, 2=Produção)
    "GetNFeAndEvent": "X", // Habilitar download automático de NFe
    "NFeDownAuto": "X" // Tipo de download automático
  }
}

EndPoints Post : Envio de Dados

POST /DOC/CERTIFICATE - Registrar Certificado Digital

Descrição: Registrar certificado digital A1.

Exemplo de Uso:

curl --location 'http://localhost:8000/DOC/CERTIFICATE' \
--header 'Content-Type: application/json' \
--data '{
    "GZipCert": "Certificado digital no formato GZip", 
    "Password": "Senha do certificado" 
}'

Modelo de Entrada:

{
  "GZipCert": "Certificado digital no formato GZip",
  "Password": "Senha do certificado"
}

Campos de Entrada:

• GZipCert (obrigatório): Certificado digital no formato GZip
• Password (obrigatório): Senha do certificado digital

Resposta de Sucesso:

{
  "Object": {
    "Serial": "1234567890123456789012345678901234567890"
  }
}

POST /COMPANY - Cadastrar CPF ou CNPJ

Descrição: Cadastrar CPF ou CNPJ no sistema.

Exemplo de Uso:

curl --location 'http://localhost:8000/COMPANY' \
--header 'Content-Type: application/json' \
--data '{
       "CNPJ" : "11111111111111",      
       "Nome": "Nome da empresa",      
       "Estado" : "31",                
       "Certificado" : "123123425234", 
       "DisableAutoScan" : "",         
       "Environment" : "1",            

       "GetNFeAndEvent" : "X",         
       "NFeDownAuto" : "X",            
       "GetCTeAndEvent" : "X",         
       "GetMDFeAndEvent" : "X",        

       "GetNFeOutAndEvent" : "X",      
       "NFeOutDownAuto" : "W",         
       "GetNFCeOutAndEvent" : "X",      
       "NFCeOutDownAuto" : "W",         
       "GetCTeOutAndEvent" : "X",      
       "CTeOutDownAuto" : "W"         
}'

Modelo de Entrada:

{
  "CNPJ": "11111111111111",
  "Nome": "Nome da empresa",
  "Estado": "31",
  "Certificado": "123123425234",
  "DisableAutoScan": "",
  "Environment": "1",
  "GetNFeAndEvent": "X",
  "NFeDownAuto": "X",
  "GetCTeAndEvent": "X",
  "GetMDFeAndEvent": "X",
  "GetNFeOutAndEvent": "X",
  "NFeOutDownAuto": "W",
  "GetNFCeOutAndEvent": "X",
  "NFCeOutDownAuto": "W",
  "GetCTeOutAndEvent": "X",
  "CTeOutDownAuto": "W"
}

Campos de Entrada:

• CNPJ (obrigatório): CNPJ ou CPF da empresa (14 ou 11 dígitos)
• Nome (obrigatório): Nome da empresa
• Estado (obrigatório): Código do estado (2 dígitos)
• Certificado (obrigatório): Serial do certificado digital
• DisableAutoScan (opcional): Desabilitar escaneamento automático
• Environment (obrigatório): Ambiente
  • 1: Homologação
  • 2: Produção

Campos de Configuração Inbound (Entrada):

• GetNFeAndEvent: "X" para habilitar download automático de NFe
• NFeDownAuto: Tipo de download automático
  • X: Ciência da Operação + Download de XML
  • W: SEM Manifestação + COM validade jurídica
  • N: SEM Manifestação + SEM validade jurídica
• GetCTeAndEvent: "X" para habilitar download automático de CTe
• GetMDFeAndEvent: "X" para habilitar download automático de MDFe

Campos de Configuração Outbound (Saída):

• GetNFeOutAndEvent: "X" para habilitar envio automático de NFe
• NFeOutDownAuto: Tipo de download automático para NFe de saída
• GetNFCeOutAndEvent: "X" para habilitar envio automático de NFCe
• NFCeOutDownAuto: Tipo de download automático para NFCe de saída
• GetCTeOutAndEvent: "X" para habilitar envio automático de CTe
• CTeOutDownAuto: Tipo de download automático para CTe de saída

Resposta de Sucesso:

{
  "Object": {
    "CNPJ": "11111111111111",
    "Nome": "Nome da empresa",
    "Estado": "31",
    "Certificado": "123123425234",
    "Environment": "1",
    "Status": "Empresa cadastrada com sucesso"
  }
}

POST /DOC/TAG - Atribuir Etiqueta a Documento

Descrição: Atribuir etiqueta a documento fiscal.

Exemplo de Uso:

curl --location 'http://localhost:8000/DOC/TAG' \
--header 'Content-Type: application/json' \
--data '{
    "Company": "{cnpj ou cpf}",
    "DocKey": "{chave de acesso}",
    "DocTag": "{código da etiqueta}" 
}'

Modelo de Entrada:

{
  "Company": "12345678000199",
  "DocKey": "35250432722095000143550010000028791105593659",
  "DocTag": "CODIGO_ETIQUETA"
}

Campos de Entrada:

• Company (obrigatório): CNPJ ou CPF da empresa
• DocKey (obrigatório): Chave de acesso do documento fiscal
• DocTag (obrigatório): Código da etiqueta a ser atribuída

Resposta de Sucesso:

{
  "Object": {
    "Chave": "35250432722095000143550010000028791105593659",
    "Tag": "CODIGO_ETIQUETA",
    "Status": "Etiqueta atribuída com sucesso"
  }
}

POST /EVENT - Registrar Evento

Descrição: Registrar evento em documento fiscal.

Exemplo de Uso:

curl --location 'http://localhost:8000/EVENT' \
--header 'Content-Type: application/json' \
--data '{
    "Company": "{cnpj ou cpf}",
    "DocKey": "{chave de acesso}",
    "EvtCode": "{código de evento conforme manual de documentos fiscais da SEFAZ}",
    "Reason": "{Somente informar este campo nos casos que o evento exigir uma justificativa}"
}'

Modelo de Entrada:

{
  "Company": "12345678000199",
  "DocKey": "35250432722095000143550010000028791105593659",
  "EvtCode": "110111",
  "Reason": "Justificativa do evento"
}

Campos de Entrada:

• Company (obrigatório): CNPJ ou CPF da empresa
• DocKey (obrigatório): Chave de acesso do documento fiscal
• EvtCode (obrigatório): Código de evento conforme manual de documentos fiscais da SEFAZ
• Reason (condicional): Somente informar este campo nos casos que o evento exigir uma justificativa

Códigos de Evento Comuns:

• 110111: Cancelamento
• 110140: Carta de Correção Eletrônica
• 949494: Ciência da Operação
• 848484: Confirmação da Operação
• 747474: Desconhecimento da Operação

Resposta de Sucesso:

{
  "Object": {
    "Chave": "35250432722095000143550010000028791105593659",
    "tpEvento": "110111",
    "nSeqEvento": 1,
    "dhEvento": "2024-12-15T10:35:00",
    "Status": "Processado com sucesso"
  }
}

POST /XML - Upload de XML

Descrição: Envio de arquivo XML para processamento.

Modelo de Entrada:

{
  "GzipXml": "base64_encoded_gzip_xml_content",
  "Socket": "IDENTIFICADOR_SOCKET"
}

Campos de Entrada:

• GzipXml (obrigatório): Conteúdo do XML comprimido em GZIP e codificado em Base64
• Socket (opcional): Identificador do socket/cliente

Resposta de Sucesso:

{
  "Object": {
    "Chave": "35250432722095000143550010000028791105593659",
    "Status": "Processado com sucesso",
    "Filial": "12345678000199"
  }
}

Exemplo de Uso:

// Comprimir XML
var varXmlContent = File.ReadAllText("documento.xml");
var varGzipXml = clsCompress.funcZipTextToString(varXmlContent);

// Criar modelo
var varclsObject = new clsApiPostDocItemModel
{
    GzipXml = varGzipXml,
    Socket = "ERP_SYSTEM_001"
};

// Serializar e enviar
var varJsonContent = JsonConvert.SerializeObject(varclsObject);

Códigos de Erro

Códigos de Status HTTP

• 200: Sucesso
• 400: Erro na requisição (conteúdo inválido)
• 404: Recurso não encontrado
• 500: Erro interno do servidor

Códigos de Erro Específicos

• INVALID: Conteúdo inválido na requisição
• NOTFOUND: Recurso não encontrado
• 9999: Erro interno do sistema

Exemplo de Resposta de Erro

{
  "HasError": true,
  "Messages": [
    {
      "Type": "E",
      "Code": "NOTFOUND",
      "Message": "Documento não encontrado."
    }
  ]
}

Exemplos Práticos

Envio de XML

// Preparar XML
var varXmlContent = File.ReadAllText("nfe.xml");
var varGzipXml = clsCompress.funcZipTextToString(varXmlContent);

// Criar requisição
var varclsObject = new clsApiPostDocItemModel
{
    GzipXml = varGzipXml,
    Socket = "ERP_SYSTEM_001"
};

// Serializar
var varJsonContent = JsonConvert.SerializeObject(varclsObject);

// Enviar via HTTP POST
var varHttpClient = new HttpClient();
var varContent = new StringContent(varJsonContent, Encoding.UTF8, "application/json");
var varResponse = await varHttpClient.PostAsync("http://localhost:8000/XML", varContent);
var varResponseContent = await varResponse.Content.ReadAsStringAsync();

Consulta de Documento

// Consultar documento
var varHttpClient = new HttpClient();
var varResponse = await varHttpClient.GetAsync("http://localhost:8000/DOC/35250432722095000143550010000028791105593659");
var varResponseContent = await varResponse.Content.ReadAsStringAsync();

// Deserializar resposta
var varclsResponse = JsonConvert.DeserializeObject<clsApiGetDocItemModel>(varResponseContent);

Download de PDF

// Download PDF
var varHttpClient = new HttpClient();
var varResponse = await varHttpClient.GetAsync("http://localhost:8000/DOC/PDF/35250432722095000143550010000028791105593659");
var varResponseContent = await varResponse.Content.ReadAsStringAsync();

// Deserializar e salvar
var varclsResponse = JsonConvert.DeserializeObject<clsApiGetDocFileModel>(varResponseContent);
var varPdfBytes = Convert.FromBase64String(varclsResponse.ObjGzip);
File.WriteAllBytes("documento.pdf", varPdfBytes);

Cadastro de Empresa

// Criar modelo de empresa
var varclsObject = new clsApiPostCompanyModel
{
    CNPJ = "11111111111111",
    Nome = "Nome da empresa",
    Estado = "31",
    Certificado = "123123425234",
    DisableAutoScan = "",
    Environment = "1",
    GetNFeAndEvent = "X",
    NFeDownAuto = "X",
    GetCTeAndEvent = "X",
    GetMDFeAndEvent = "X",
    GetNFeOutAndEvent = "X",
    NFeOutDownAuto = "W",
    GetNFCeOutAndEvent = "X",
    NFCeOutDownAuto = "W",
    GetCTeOutAndEvent = "X",
    CTeOutDownAuto = "W"
};

// Serializar e enviar
var varJsonContent = JsonConvert.SerializeObject(varclsObject);
var varHttpClient = new HttpClient();
var varContent = new StringContent(varJsonContent, Encoding.UTF8, "application/json");
var varResponse = await varHttpClient.PostAsync("http://localhost:8000/COMPANY", varContent);
var varResponseContent = await varResponse.Content.ReadAsStringAsync();

Registro de Evento

// Criar modelo de evento
var varclsObject = new clsApiPostEvtItemModel
{
    Company = "12345678000199",
    DocKey = "35250432722095000143550010000028791105593659",
    EvtCode = "110111",
    Reason = "Justificativa do cancelamento"
};

// Serializar e enviar
var varJsonContent = JsonConvert.SerializeObject(varclsObject);
var varHttpClient = new HttpClient();
var varContent = new StringContent(varJsonContent, Encoding.UTF8, "application/json");
var varResponse = await varHttpClient.PostAsync("http://localhost:8000/EVENT", varContent);
var varResponseContent = await varResponse.Content.ReadAsStringAsync();

Monitoramento e Logs

Níveis de Log

• Info: Operações normais
• Warning: Avisos e situações especiais
• Error: Erros que não impedem funcionamento
• Fatal: Erros críticos

Exemplo de Log

[INFO] Integração via Api Web -> Iniciando Fiscal.io Http Server
[INFO] Integração via Api Web -> Prefixo : http://*:8080/
[INFO] Integração via Api Web -> Http Request Method POST
[INFO] Integração via Api Web -> Http Request Router /XML
[INFO] Integração via Api Web -> Http Response Content {"Success":true}