Documentacao da API | API Fiscal

Autenticacao

Envie sua API Key no cabecalho (metodo principal):

Authorization: Bearer SUA_API_KEY

Alternativa aceita:

X-API-Key: SUA_API_KEY

Formato: fiscal_live_<40 hex> (producao) ou fiscal_test_<40 hex> (sandbox: sempre homologacao). Crie e gerencie chaves em Minhas API Keys.

Formato das respostas

Toda resposta JSON inclui request_id (tambem no cabecalho X-Request-Id). Informe-o ao suporte.

Sucesso

{
  "success": true,
  "request_id": "req_a1b2...",
  "...": "dados do recurso"
}

Erro

{
  "success": false,
  "request_id": "req_a1b2...",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Requisicao invalida."
  }
}

Rate limit e ambientes

Limite por minuto e por API Key. Ao exceder: HTTP 429, RATE_LIMITED e cabecalho Retry-After (segundos).
Sandbox: chaves fiscal_test_* emitem sempre em homologacao SEFAZ e so enxergam documentos de homologacao.
Producao: chaves fiscal_live_* usam o ambiente configurado da empresa.

API Keys e escopos

Cada chave tem escopos por modulo; um escopo nunca da acesso a outro modulo (403 FORBIDDEN).

emitir, consultar, cancelar, cce, inutilizar, download, preview, configurar: NF-e/NFC-e, Motor (/fiscal/*), cadastros e webhooks.
nfse:read|write, cte:read|write, cteos:read|write, mdfe:read|write, rural:read|write: leitura ou escrita por modulo.
override: substituir valores calculados pelo Motor (auditado, com motivo) e aceitar revisao fiscal.

Multiempresa

Informe empresa_id (id) ou empresa (codigo); com uma unica empresa na conta o campo e opcional. Empresa inexistente, inativa ou de outra conta responde 403 EMPRESA_NAO_AUTORIZADA; documentos de outra empresa respondem 404. Cada empresa tem certificado, series, ambiente e modulos (MODULO_NAO_HABILITADO) proprios. Produtor rural PF usa CPF + IE e certificado e-CPF.

Motor Tributario Central

Um unico nucleo calcula e classifica NFS-e, CT-e, CT-e OS, MDF-e e NF-e rural; NF-e/NFC-e o consultam quando ha contexto rural. Fluxo: JSON simples → empresa → TaxContext → regras especializadas → TaxResult → documento → snapshot.

Vigencia: a regra aplicada e a vigente na data da operacao; empate de regras e erro de ambiguidade.
Resultado: taxes, classifications, rules_used (fonte e versao), warnings, confidence_score (0 a 1) e requires_review. Com requires_review a emissao automatica e bloqueada.
Explain: ?explain=true detalha cada decisao (base, aliquota, valor, regra, fonte, versao, motivo).
Sem tributacao inventada: sem regra cadastrada o motor avisa ou recusa; nao ha aliquota padrao.
Snapshot e override: cada emissao grava um snapshot imutavel (SHA-256); substituir um valor calculado exige permissao override e override_motivo.

Idempotencia

Vale para NF-e, NFC-e, NFS-e, CT-e, CT-e OS e MDF-e. Chaves: header Idempotency-Key (opcional) e sempre empresa + modulo + pedido. Mesmo pedido e conteudo: replay (Idempotent-Replay: true), sem nova transmissao nem cobranca. Conteudo diferente: 422 IDEMPOTENCY_KEY_REUSED. Em processamento: 409 REQUEST_IN_PROGRESS. Resposta incerta: 202, consulte o documento (nunca reemita).

Preview e dry-run

POST /nfse/preview, /cte/preview, /cteos/preview, /mdfe/preview e /fiscal/preview validam sem transmitir, cobrar ou consumir numeracao. POST /fiscal/calcular e /fiscal/validate executam apenas o Motor (e a validacao do leiaute) para qualquer documento, sem SEFAZ nem Sistema Nacional. data_operacao simula a legislacao de outra data (so nesses modos). NFF: 501 NFF_NAO_DISPONIVEL.

Webhooks

Eventos nfe.*, nfce.*, nfse.*, cte.*, cteos.* e mdfe.* (processing, authorized, rejected, cancelled; mdfe.closed). Produtor rural usa nfe.* com context: PRODUTOR_RURAL.

X-Webhook-Signature = "sha256=" + HMAC_SHA256(segredo, X-Webhook-Timestamp + "." + corpo)

Retry com backoff (1 min, 5 min, 15 min, 1 h, 6 h), timeout de 8 s, URL https obrigatoria e bloqueio de enderecos privados (SSRF). Rejeite timestamps com mais de 5 minutos.

Fila assincrona, retentativas e consulta antes de reenviar

Receber ou enfileirar nao significa transmitir nem autorizar. POST /fiscal/solicitacoes (ou Prefer: respond-async em POST /nfe|/nfce|/nfse|/cte|/cteos|/mdfe) grava uma tarefa persistente e devolve solicitacao_id (202). O worker transmite quando possivel; em falha temporaria repete com intervalo progressivo; com resultado desconhecido consulta a situacao (nunca reenvia as cegas); so marca AUTORIZADA/REJEITADA com o resultado oficial.

Status: RECEBIDA, AGUARDANDO_TRANSMISSAO, TRANSMITINDO, AGUARDANDO_RETORNO, AUTORIZADA, REJEITADA, FALHA_TEMPORARIA, ACAO_NECESSARIA, CANCELADA (tarefa; nunca cancelamento fiscal).
Duplicidade: uma tarefa por empresa + documento + pedido; reenviar devolve a mesma solicitacao (Idempotent-Replay); "nao recebido" (cStat 217 / DPS 404) so e confirmado por consulta, depois do prazo de tolerancia.
Creditos: saldo validado ao aceitar (402 SALDO_INSUFICIENTE); debito unico na emissao, estorno em falha; ilimitados respeitados.
Eventos de webhook: fiscal.document.queued, pending, authorized (so apos o resultado oficial), rejected, action_required, cancelled.
Workers: php database/worker_fiscal.php (cron/Agendador a cada minuto) e php database/worker_notificacoes.php. Detalhes no guia (PDF) e em docs/FILA_FISCAL.md.

Notificacoes por e-mail

Enviadas pelo PHPMailer 7.1.1 a partir de uma outbox persistente (separada da fila fiscal; a confirmacao fiscal nao depende do SMTP): autorizada (somente apos o resultado oficial), rejeitada com o motivo, acao necessaria e aviso opcional de pendencia. HTML responsivo + texto simples, sem XML, certificados ou credenciais (apenas link autenticado para o painel). Sem e-mail por tentativa, deduplicacao, retentativas progressivas e preferencias por usuario/empresa (GET|PUT /fiscal/notificacoes/preferencias). SMTP por variaveis de ambiente (MAIL_*); sem configuracao o envio fica desativado.

POST /nfe permissao: emitir

Emitir NF-e (modelo 55)

Recebe o JSON minimo (pedido, cliente, itens e pagamento). A API obtem emitente, certificado, natureza, serie e numeracao da configuracao da empresa; o Motor Tributario resolve CFOP, CST/CSOSN, ICMS, PIS, COFINS e IBS/CBS; valida, assina e transmite a SEFAZ. Sem regra suficiente NAO emite: responde 422 FISCAL_CONFIGURATION_REQUIRED dizendo o que configurar.

Autenticacao: Bearer API Key · Idempotency-Key (opcional): evita emissao duplicada em reenvios.

Obrigatorios

pedido
cliente
itens[].codigo
itens[].quantidade
pagamento

Opcionais

empresa (obrigatorio so se sua conta tem mais de uma)
itens[].valor (padrao: preco do produto)
itens[].desconto
natureza
observacoes
presenca (presencial|internet|telefone|entrega|outros)
intermediador {cnpj,id} (presenca diferente de presencial; padrao: sem intermediador)
consumidor_final
frete.modalidade

JSON minimo

{
    "pedido": "PED-12345",
    "cliente": "CLI001",
    "itens": [
        {
            "codigo": "PROD001",
            "quantidade": 2
        }
    ],
    "pagamento": "pix"
}

JSON completo

{
    "empresa": "EMPRESA_001",
    "pedido": "PED-12345",
    "cliente": {
        "cpf_cnpj": "12345678909",
        "nome": "Joao da Silva",
        "email": "joao@exemplo.com",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "10",
            "bairro": "Centro",
            "cod_municipio": "3550308",
            "municipio": "Sao Paulo",
            "uf": "SP",
            "cep": "01001000"
        }
    },
    "itens": [
        {
            "codigo": "PROD001",
            "quantidade": 2,
            "valor": 100,
            "desconto": 0
        }
    ],
    "pagamento": [
        {
            "forma": "pix",
            "valor": 200
        }
    ],
    "natureza": "VENDA",
    "observacoes": "Pedido online",
    "presenca": "internet",
    "frete": {
        "modalidade": 9
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/nfe" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pedido":"PED-12345","cliente":"CLI001","itens":[{"codigo":"PROD001","quantidade":2}],"pagamento":"pix"}'

Exemplo de response

{
    "success": true,
    "status": "AUTORIZADA",
    "id": "43",
    "numero": 1,
    "serie": 1,
    "chave": "3524...",
    "protocolo": "135240000000001",
    "xml": "/api/v1/nfe/43/xml",
    "danfe": "/api/v1/nfe/43/danfe",
    "request_id": "req_a1b2c3d4e5f6a7b8c9d0"
}

Erros possiveis

422 SEFAZ_REJECTION — Documento rejeitado pela SEFAZ (sefaz_code e mensagem originais).
422 FISCAL_CONFIGURATION_REQUIRED — Produto sem NCM, operacao sem regra tributaria, cliente sem endereco (NF-e)...
202 SEFAZ_UNAVAILABLE — Situacao incerta por falha de comunicacao; consulte GET /nfe/{id}.

POST /nfce permissao: emitir

Emitir NFC-e (modelo 65)

Mesmo JSON da NF-e; o cliente e opcional e nao exige endereco.

Autenticacao: Bearer API Key

Obrigatorios

pedido
itens[].codigo
itens[].quantidade
pagamento

Opcionais

empresa
cliente
itens[].valor
natureza
observacoes

JSON minimo

{
    "pedido": "PED-9",
    "itens": [
        {
            "codigo": "PROD001",
            "quantidade": 1
        }
    ],
    "pagamento": "dinheiro"
}

JSON completo

{
    "empresa": "EMPRESA_001",
    "pedido": "PED-12345",
    "cliente": {
        "cpf_cnpj": "12345678909",
        "nome": "Joao da Silva",
        "email": "joao@exemplo.com",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "10",
            "bairro": "Centro",
            "cod_municipio": "3550308",
            "municipio": "Sao Paulo",
            "uf": "SP",
            "cep": "01001000"
        }
    },
    "itens": [
        {
            "codigo": "PROD001",
            "quantidade": 2,
            "valor": 100,
            "desconto": 0
        }
    ],
    "pagamento": [
        {
            "forma": "pix",
            "valor": 200
        }
    ],
    "natureza": "VENDA",
    "observacoes": "Pedido online",
    "presenca": "internet",
    "frete": {
        "modalidade": 9
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/nfce" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pedido":"PED-9","itens":[{"codigo":"PROD001","quantidade":1}],"pagamento":"dinheiro"}'

Exemplo de response

{
    "success": true,
    "status": "AUTORIZADA",
    "id": "44",
    "numero": 1,
    "serie": 1,
    "danfe": "/api/v1/nfce/44/danfce",
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_REJECTION — Documento rejeitado pela SEFAZ (sefaz_code e mensagem originais).
422 FISCAL_CONFIGURATION_REQUIRED — Produto sem NCM, operacao sem regra tributaria, cliente sem endereco (NF-e)...
202 SEFAZ_UNAVAILABLE — Situacao incerta por falha de comunicacao; consulte GET /nfe/{id}.

POST /fiscal/preview permissao: preview

Pre-visualizar calculo (nao emite)

Enriquece, aplica regras, valida e calcula tributos sem transmitir nada.

Autenticacao: Bearer API Key

Obrigatorios

itens[]
pagamento

Opcionais

modelo (55|65, padrao 55)
demais campos da emissao

JSON minimo

{
    "pedido": "PED-12345",
    "cliente": "CLI001",
    "itens": [
        {
            "codigo": "PROD001",
            "quantidade": 2
        }
    ],
    "pagamento": "pix",
    "modelo": 55
}

JSON completo

{
    "empresa": "EMPRESA_001",
    "pedido": "PED-12345",
    "cliente": {
        "cpf_cnpj": "12345678909",
        "nome": "Joao da Silva",
        "email": "joao@exemplo.com",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "10",
            "bairro": "Centro",
            "cod_municipio": "3550308",
            "municipio": "Sao Paulo",
            "uf": "SP",
            "cep": "01001000"
        }
    },
    "itens": [
        {
            "codigo": "PROD001",
            "quantidade": 2,
            "valor": 100,
            "desconto": 0
        }
    ],
    "pagamento": [
        {
            "forma": "pix",
            "valor": 200
        }
    ],
    "natureza": "VENDA",
    "observacoes": "Pedido online",
    "presenca": "internet",
    "frete": {
        "modalidade": 9
    },
    "modelo": 55
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/fiscal/preview" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pedido":"PED-12345","cliente":"CLI001","itens":[{"codigo":"PROD001","quantidade":2}],"pagamento":"pix","modelo":55}'

Exemplo de response

{
    "success": true,
    "ready_to_issue": true,
    "document": {
        "modelo": 55,
        "itens": [
            {
                "codigo": "PROD001",
                "cfop": "5102",
                "regra_tributaria_id": 12,
                "regra_iva_id": null,
                "decisao_tributaria": {
                    "data_operacao": "2026-09-29",
                    "regra_tributaria": {
                        "regra_id": 12,
                        "tipo_regra": "tributaria",
                        "prioridade": 100,
                        "criterios_correspondentes": [
                            "crt",
                            "operacao",
                            "ncm"
                        ]
                    }
                }
            }
        ],
        "totais": {
            "vProd": 200,
            "vNF": 200
        }
    },
    "request_id": "req_..."
}

Erros possiveis

422 FISCAL_CONFIGURATION_REQUIRED — ready_to_issue=false com a lista error.missing e os codigos em error.motivos.

GET /nfe/{id} permissao: consultar

Consultar NF-e / NFC-e

Status, numero, serie, chave, protocolo e eventos. Documentos PENDENTE sao reconciliados com a SEFAZ. Use /nfce/{id} para NFC-e.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/nfe/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": "43",
    "status": "AUTORIZADA",
    "chave": "3524...",
    "request_id": "req_..."
}

Erros possiveis

404 DOCUMENTO_NAO_ENCONTRADO — Documento inexistente ou de outra conta.

GET /nfe/{id}/eventos permissao: consultar

Historico de eventos

Cancelamentos e cartas de correcao do documento (tambem /nfce/{id}/eventos).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/nfe/43/eventos" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "eventos": [
        {
            "tipo": "CANCELAMENTO",
            "status": "REGISTRADO"
        }
    ],
    "request_id": "req_..."
}

GET /nfe/{id}/xml permissao: download

Baixar XML

XML autorizado (application/xml). Tambem /nfce/{id}/xml.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/nfe/43/xml" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

<nfeProc>...</nfeProc>

GET /nfe/{id}/danfe permissao: download

Baixar DANFE / DANFCE (PDF)

PDF do DANFE (NF-e) em /nfe/{id}/danfe ou do DANFCE (NFC-e) em /nfce/{id}/danfce.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/nfe/43/danfe" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

(application/pdf)

POST /nfe/{id}/cancelamento permissao: cancelar

Cancelar documento

Cancela NF-e ou NFC-e (/nfce/{id}/cancelamento).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

justificativa (15 a 255 caracteres)

Opcionais

nenhum

JSON minimo

{
    "justificativa": "Erro na digitacao do pedido"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/nfe/43/cancelamento" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"justificativa":"Erro na digitacao do pedido"}'

Exemplo de response

{
    "success": true,
    "status": "CANCELADA",
    "protocolo": "135...",
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Justificativa fora do tamanho permitido.
422 SEFAZ_REJECTION — Prazo ou situacao nao permite cancelar.

POST /nfe/{id}/cce permissao: cce

Carta de correcao (CC-e)

A sequencia (1..20) e controlada pela API.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

correcao (15 a 1000 caracteres)

Opcionais

nenhum

JSON minimo

{
    "correcao": "Corrigir endereco de entrega para Rua B, 20"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/nfe/43/cce" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"correcao":"Corrigir endereco de entrega para Rua B, 20"}'

Exemplo de response

{
    "success": true,
    "sequencia": 1,
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_REJECTION — Correcao nao aceita pela SEFAZ.

POST /inutilizacao permissao: inutilizar

Inutilizar numeracao

Inutiliza uma faixa de numeros nao utilizados.

Autenticacao: Bearer API Key

Obrigatorios

modelo (55|65)
numero_inicial
justificativa

Opcionais

empresa
serie
numero_final

JSON minimo

{
    "empresa": "EMPRESA_001",
    "modelo": 55,
    "numero_inicial": 10,
    "justificativa": "Numeracao pulada por falha de sistema"
}

JSON completo

{
    "empresa": "EMPRESA_001",
    "modelo": 55,
    "serie": 1,
    "numero_inicial": 10,
    "numero_final": 12,
    "justificativa": "Numeracao pulada por falha de sistema"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/inutilizacao" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa":"EMPRESA_001","modelo":55,"numero_inicial":10,"justificativa":"Numeracao pulada por falha de sistema"}'

Exemplo de response

{
    "success": true,
    "status": "HOMOLOGADA",
    "protocolo": "135...",
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_REJECTION — Faixa ja utilizada ou invalida.

GET /configuracao-fiscal permissao: consultar

Visao geral da configuracao fiscal

Status das 5 etapas (Emitente, Certificado, Natureza, Tributacao, IBS/CBS), percentual, pendencias, emitente e certificado (sem segredos). Query opcional: ?empresa=CODIGO (so entre as empresas da sua conta). Sem empresa cadastrada devolve 0% com a pendencia de emitente. Status por etapa: nao_configurado, incompleto, configurado, requer_atencao.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa (query)

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "empresa": "EMPRESA_001",
    "configuracao_fiscal_percentual": 75,
    "pronta_para_emitir": false,
    "etapas": {
        "emitente": {
            "ordem": 1,
            "rotulo": "Emitente",
            "status": "configurado",
            "obrigatoria": true
        },
        "certificado": {
            "ordem": 2,
            "status": "nao_configurado"
        },
        "natureza": {
            "ordem": 3,
            "status": "configurado"
        },
        "tributacao": {
            "ordem": 4,
            "status": "configurado"
        },
        "iva": {
            "ordem": 5,
            "status": "nao_configurado",
            "obrigatoria": false
        }
    },
    "pendencias": [
        "Certificado: certificado digital A1 da empresa nao cadastrado."
    ],
    "emitente": {
        "cnpj": "12345678000195",
        "razao_social": "EMPRESA EXEMPLO LTDA",
        "crt": 3
    },
    "certificado": {
        "status": "ausente",
        "valido": false
    },
    "totais": {
        "naturezas": 1,
        "regras_tributacao": 3,
        "regras_iva": 0
    },
    "request_id": "req_..."
}

Erros possiveis

403 EMPRESA_NAO_AUTORIZADA — Empresa informada nao pertence a sua conta.

GET /configuracao-fiscal/validar permissao: consultar

Validar se a empresa esta pronta para emitir

Executa o validador fiscal da configuracao. 200 quando pronta; 422 CONFIG_FISCAL_INCOMPLETA com a lista de pendencias em error.details.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa (query)

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/validar" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": false,
    "error": {
        "code": "CONFIG_FISCAL_INCOMPLETA",
        "message": "A configuracao fiscal esta incompleta.",
        "details": [
            "Certificado: certificado digital A1 da empresa nao cadastrado."
        ]
    },
    "configuracao_fiscal_percentual": 75,
    "pronta_para_emitir": false,
    "request_id": "req_..."
}

Erros possiveis

422 CONFIG_FISCAL_INCOMPLETA — Ha etapas pendentes.

POST /configuracao-fiscal/cnpj/consultar permissao: consultar

Consultar dados do CNPJ

Busca razao social, fantasia, situacao cadastral, data de abertura, CNAE principal/secundarios, endereco, IBGE, UF (e cUF), telefone e e-mail (BrasilAPI e publica.cnpj.ws). NAO grava nada: o usuario revisa e confirma em POST/PUT /configuracao-fiscal/emitente. Cada campo vem com sua origem (AUTOMATICO, CALCULADO, SUGERIDO, CONFIRMACAO_OBRIGATORIA); o CRT e apenas sugestao e exige confirmacao. CFOP, CST, ICMS, PIS, COFINS, IBS, CBS e cClassTrib nunca sao inferidos do CNPJ.

Autenticacao: Bearer API Key

Obrigatorios

cnpj (14 digitos, com ou sem mascara)

Opcionais

nenhum

JSON minimo

{
    "cnpj": "12345678000195"
}

JSON completo

{
    "cnpj": "12.345.678/0001-95"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/cnpj/consultar" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpj":"12345678000195"}'

Exemplo de response

{
    "success": true,
    "dados": {
        "cnpj": "12345678000195",
        "razao_social": "EMPRESA EXEMPLO LTDA",
        "nome_fantasia": "EXEMPLO",
        "situacao_cadastral": "ATIVA",
        "data_abertura": "2015-03-10",
        "cnae": "4751201",
        "cnaes_secundarios": [
            "4753900"
        ],
        "cep": "38700000",
        "logradouro": "RUA DAS FLORES",
        "numero": "100",
        "bairro": "CENTRO",
        "municipio": "PATOS DE MINAS",
        "cod_municipio": "3148004",
        "uf": "MG",
        "cod_uf": 31,
        "telefone": "3433334444",
        "email": "contato@exemplo.com.br",
        "crt": 1
    },
    "origem": {
        "razao_social": "AUTOMATICO",
        "cod_uf": "CALCULADO",
        "crt": "CONFIRMACAO_OBRIGATORIA"
    },
    "fonte": "BrasilAPI / publica.cnpj.ws",
    "avisos": [
        "Inscricao estadual nao encontrada: informe-a manualmente (obrigatoria para emitir NF-e)."
    ],
    "request_id": "req_..."
}

Erros possiveis

422 CNPJ_INVALIDO — Digitos verificadores invalidos.
422 VALIDATION_ERROR — CNPJ nao informado.
502 CNPJ_CONSULTA_INDISPONIVEL — Servicos de consulta indisponiveis; preencha manualmente.

POST /configuracao-fiscal/automatica permissao: configurar

Gerar configuracao fiscal automatica

A partir do CNPJ/UF e do CRT do emitente gera naturezas (VENDA, VENDA_CONSUMIDOR), regras de tributacao (CFOP, CSOSN/CST ICMS, PIS/COFINS, ICMS interno/interestadual) e a regra IBS/CBS de 2026. Sao sugestoes marcadas com [Auto] e prioridade 50: regras suas sempre prevalecem; nada e apagado nem duplicado. Tambem roda sozinha ao salvar o emitente (desligue com "config_automatica": false).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa (query)
apuracao (presumido|real: so CRT 3, define PIS/COFINS 0,65/3,00 ou 1,65/7,60)

JSON minimo

{}

JSON completo

{
    "apuracao": "presumido"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/automatica" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Exemplo de response

{
    "success": true,
    "crt": 1,
    "regime": "Simples Nacional",
    "criados": {
        "naturezas": 2,
        "tributacao": 3,
        "iva": 1
    },
    "regras_automaticas_desativadas": 0,
    "avisos": [
        "IBS/CBS: gerada a regra de 2026 (ano de teste). Para 2027 em diante revise as aliquotas."
    ],
    "configuracao_fiscal_percentual": 80,
    "pronta_para_emitir": false,
    "request_id": "req_..."
}

Erros possiveis

403 FORBIDDEN — A chave nao possui a permissao "configurar".

GET /configuracao-fiscal/emitente permissao: consultar

Consultar o emitente

Dados do emitente da empresa (sem CSC, tokens ou senha do certificado).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa (query)

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/emitente" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "emitente": {
        "codigo": "EMPRESA_001",
        "cnpj": "12345678000195",
        "razao_social": "EMPRESA EXEMPLO LTDA",
        "crt": 3,
        "regime_tributario": "Regime Normal (Lucro Presumido/Real)",
        "uf": "MG",
        "cod_uf": 31,
        "origem_dados": {
            "razao_social": "AUTOMATICO"
        },
        "confirmado_em": "2026-09-29 16:06:00"
    },
    "request_id": "req_..."
}

POST /configuracao-fiscal/emitente permissao: configurar

Criar o emitente (empresa da conta)

Cria a empresa vinculada ao usuario da API Key (NUNCA a um usuario_id enviado no corpo). A empresa nasce em HOMOLOGACAO. O envio equivale a confirmar os dados; se o CRT veio da consulta de CNPJ (origem CONFIRMACAO_OBRIGATORIA), envie "confirmar": true. Resposta 201.

Autenticacao: Bearer API Key

Obrigatorios

cnpj
razao_social
uf

Opcionais

nome_fantasia
ie
iest
im
crt (1|2|3|4)
cnae
cnaes_secundarios[]
cep
logradouro
numero
complemento
bairro
municipio
cod_municipio
telefone
email
serie_nfe
serie_nfce
csc_id
csc
exige_ibs_cbs
origem {campo: ORIGEM}
confirmar

JSON minimo

{
    "cnpj": "12345678000195",
    "razao_social": "EMPRESA EXEMPLO LTDA",
    "uf": "MG"
}

JSON completo

{
    "cnpj": "12345678000195",
    "razao_social": "EMPRESA EXEMPLO LTDA",
    "nome_fantasia": "EXEMPLO",
    "ie": "0011223340000",
    "crt": 3,
    "cnae": "4751201",
    "cep": "38700000",
    "logradouro": "RUA DAS FLORES",
    "numero": "100",
    "bairro": "CENTRO",
    "municipio": "PATOS DE MINAS",
    "cod_municipio": "3148004",
    "uf": "MG",
    "telefone": "3433334444",
    "email": "contato@exemplo.com.br",
    "serie_nfe": 1,
    "serie_nfce": 1,
    "origem": {
        "razao_social": "AUTOMATICO",
        "crt": "CONFIRMACAO_OBRIGATORIA"
    },
    "confirmar": true
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/emitente" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpj":"12345678000195","razao_social":"EMPRESA EXEMPLO LTDA","uf":"MG"}'

Exemplo de response

{
    "success": true,
    "empresa": "EMPRESA_002",
    "emitente": {
        "cnpj": "12345678000195",
        "razao_social": "EMPRESA EXEMPLO LTDA"
    },
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Campos invalidos (error.errors[].field).
403 EMITENTE_NAO_CONFIGURADO — Credencial sem usuario da plataforma: peca ao administrador.
409 LIMITE_EMPRESAS — Limite de empresas atingido.

PUT /configuracao-fiscal/emitente permissao: configurar

Atualizar / confirmar o emitente

Atualizacao parcial: so os campos enviados mudam. Registra valor anterior e novo na auditoria. O campo opcional "empresa" escolhe entre as empresas da sua conta.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

mesmos campos de POST /configuracao-fiscal/emitente
empresa

JSON minimo

{
    "ie": "0011223340000",
    "crt": 3
}

JSON completo

{
    "ie": "0011223340000",
    "crt": 3,
    "exige_ibs_cbs": true
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/emitente" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ie":"0011223340000","crt":3}'

Exemplo de response

{
    "success": true,
    "emitente": {
        "razao_social": "EMPRESA EXEMPLO LTDA",
        "ie": "0011223340000"
    },
    "status": {
        "status": "configurado"
    },
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Campos invalidos.
403 EMPRESA_NAO_AUTORIZADA — Empresa de outra conta.

GET /configuracao-fiscal/certificado permissao: consultar

Situacao do certificado digital

Status (ausente, ok, vence_em_breve <= 30 dias, vencido, invalido), titular, emissor, numero de serie, CNPJ, validade e dias restantes. Nunca devolve a senha.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa (query)

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/certificado" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "certificado": {
        "status": "ok",
        "valido": true,
        "titular": "EMPRESA EXEMPLO LTDA:12345678000195",
        "emissor": "AC Certisign RFB G5",
        "numero_serie": "1274...",
        "cnpj": "12345678000195",
        "cnpj_confere_com_emitente": true,
        "validade": "2027-03-01",
        "dias_restantes": 153,
        "problemas": [],
        "codigos": []
    },
    "request_id": "req_..."
}

POST /configuracao-fiscal/certificado permissao: configurar

Enviar certificado digital A1 (.pfx/.p12)

JSON com o arquivo em base64 e a senha (ou multipart: campo "arquivo" e "senha"). Valida senha, validade e CNPJ (raiz do CNPJ do certificado = raiz do emitente). A senha e criptografada (AES-256-GCM) e nunca e devolvida nem registrada em log.

Autenticacao: Bearer API Key

Obrigatorios

arquivo_base64
senha

Opcionais

empresa

JSON minimo

{
    "arquivo_base64": "MIIK...(.pfx em base64)",
    "senha": "SENHA_DO_CERTIFICADO"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/certificado" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arquivo_base64":"MIIK...(.pfx em base64)","senha":"SENHA_DO_CERTIFICADO"}'

Exemplo de response

{
    "success": true,
    "certificado": {
        "status": "ok",
        "valido": true,
        "validade": "2027-03-01"
    },
    "aviso": null,
    "request_id": "req_..."
}

Erros possiveis

422 CERTIFICADO_INVALIDO — Arquivo invalido ou senha incorreta.
422 CERTIFICADO_VENCIDO — Certificado vencido.
422 CERTIFICADO_DIVERGENTE — Certificado de outro CNPJ.
422 VALIDATION_ERROR — Arquivo ou senha ausentes.

GET /configuracao-fiscal/logs permissao: consultar

Historico de alteracoes da configuracao

Auditoria de emitente, certificado, natureza, tributacao e iva: usuario, acao, registro, valor anterior/novo, IP e data. Query: entidade, page, limit (max 100).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

entidade
page
limit
empresa

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/logs" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "items": [
        {
            "id": 10,
            "acao": "atualizado",
            "entidade": "natureza",
            "registro_id": "3",
            "valor_anterior": {
                "descricao": "VENDA"
            },
            "valor_novo": {
                "descricao": "VENDA DE MERCADORIA"
            },
            "ip": "203.0.113.10",
            "criado_em": "2026-09-29 16:07:00"
        }
    ],
    "request_id": "req_..."
}

GET /configuracao-fiscal/naturezas permissao: consultar

Listar naturezas de operacao

Naturezas da sua empresa. Query: ativo=1|0, empresa.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

ativo
empresa

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/naturezas" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "items": [
        {
            "id": 3,
            "codigo": "VENDA",
            "descricao": "VENDA DE MERCADORIA",
            "tipo_operacao": 1,
            "finalidade": 1,
            "padrao_nfe": 1,
            "ativo": 1
        }
    ],
    "request_id": "req_..."
}

POST /configuracao-fiscal/naturezas permissao: configurar

Criar natureza de operacao

Varias naturezas por empresa (venda, devolucao, remessa, bonificacao, transferencia...). Apenas uma natureza e a padrao por modelo (padrao_nfe / padrao_nfce). O CFOP da natureza e informativo: quem decide o CFOP e a regra tributaria. Resposta 201.

Autenticacao: Bearer API Key

Obrigatorios

codigo
descricao (natOp, ate 60)

Opcionais

tipo_operacao (1 saida | 0 entrada)
finalidade (1..4)
operacao_interna
operacao_interestadual
consumidor_final
contribuinte
cfop
observacoes
padrao_nfe
padrao_nfce
ativo

JSON minimo

{
    "codigo": "VENDA",
    "descricao": "VENDA DE MERCADORIA"
}

JSON completo

{
    "codigo": "DEVOL",
    "descricao": "DEVOLUCAO DE VENDA",
    "tipo_operacao": 0,
    "finalidade": 4,
    "cfop": "1202",
    "padrao_nfe": false
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/naturezas" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codigo":"VENDA","descricao":"VENDA DE MERCADORIA"}'

Exemplo de response

{
    "success": true,
    "item": {
        "id": 3,
        "codigo": "VENDA",
        "descricao": "VENDA DE MERCADORIA"
    },
    "avisos": [],
    "request_id": "req_..."
}

Erros possiveis

409 REGISTRO_DUPLICADO — Codigo ja existe na empresa.
422 VALIDATION_ERROR — Campos invalidos.

GET /configuracao-fiscal/naturezas/{id} permissao: consultar

Consultar natureza (PUT atualiza, DELETE desativa)

GET consulta; PUT /configuracao-fiscal/naturezas/{id} atualiza parcialmente (mesmos campos do POST, permissao configurar); DELETE apenas desativa (dados e historico preservados). Registro de outra empresa responde 404.

Autenticacao: Bearer API Key

Parametros de URL: {id} ID da natureza

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/naturezas/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "item": {
        "id": 3,
        "codigo": "VENDA"
    },
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Inexistente ou de outra empresa.

GET /configuracao-fiscal/tributacao permissao: consultar

Listar regras de tributacao

Regras da empresa, da mais prioritaria para a menos. Query: ativo, empresa.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

ativo
empresa

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/tributacao" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "items": [
        {
            "id": 12,
            "descricao": "Interna geral",
            "crt": 3,
            "operacao": "interna",
            "cfop": "5102",
            "cst_icms": "00",
            "aliq_icms": "18.0000",
            "prioridade": 100,
            "vigencia_inicio": null,
            "vigencia_fim": null
        }
    ],
    "request_id": "req_..."
}

POST /configuracao-fiscal/tributacao permissao: configurar

Criar regra de tributacao

Define CFOP e a tributacao (CSOSN ou CST de ICMS, aliquota, reducao de BC, PIS, COFINS) para os criterios informados; criterio em branco = qualquer. O Motor Tributario escolhe a regra vigente MAIS ESPECIFICA (mais criterios que casam), desempata por prioridade e devolve conflito se duas empatarem. A resposta traz avisos quando a regra conflita com outra ativa. Resposta 201.

Autenticacao: Bearer API Key

Obrigatorios

cfop

Opcionais

descricao
prioridade
vigencia_inicio
vigencia_fim
modelo (55|65)
crt (1..4)
natureza_id
produto_id
ncm (prefixo)
cest
categoria
origem (0..8)
uf_origem
uf_destino
operacao (interna|interestadual|exterior)
tipo_destinatario (PF|PJ)
consumidor_final
contribuinte
csosn
cst_icms
aliq_icms
red_bc
aliq_cred_sn
cst_pis
aliq_pis
cst_cofins
aliq_cofins
inf_cpl
ativo

JSON minimo

{
    "cfop": "5102",
    "crt": 3,
    "operacao": "interna",
    "cst_icms": "00",
    "aliq_icms": 18,
    "cst_pis": "01",
    "aliq_pis": 1.65,
    "cst_cofins": "01",
    "aliq_cofins": 7.6
}

JSON completo

{
    "descricao": "Camisetas - venda interna",
    "prioridade": 100,
    "vigencia_inicio": "2026-01-01",
    "crt": 3,
    "ncm": "6109",
    "operacao": "interna",
    "tipo_destinatario": "PF",
    "cfop": "5102",
    "cst_icms": "00",
    "aliq_icms": 12,
    "cst_pis": "01",
    "aliq_pis": 1.65,
    "cst_cofins": "01",
    "aliq_cofins": 7.6
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/tributacao" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cfop":"5102","crt":3,"operacao":"interna","cst_icms":"00","aliq_icms":18,"cst_pis":"01","aliq_pis":1.65,"cst_cofins":"01","aliq_cofins":7.6}'

Exemplo de response

{
    "success": true,
    "item": {
        "id": 12,
        "cfop": "5102"
    },
    "avisos": [],
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — CFOP ausente, aliquota fora de 0-100, UF/data invalida, natureza_id/produto_id de outra empresa...

GET /configuracao-fiscal/tributacao/{id} permissao: consultar

Consultar regra (PUT atualiza, DELETE desativa)

GET consulta; PUT atualiza parcialmente; DELETE desativa (nunca apaga: documentos emitidos guardam a regra usada). Para mudar aliquotas ao longo do tempo, encerre a vigencia da regra antiga e crie outra.

Autenticacao: Bearer API Key

Parametros de URL: {id} ID da regra

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/tributacao/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "item": {
        "id": 12
    },
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Inexistente ou de outra empresa.

GET /configuracao-fiscal/iva permissao: consultar

Listar regras IVA (IBS/CBS)

Regras de IBS/CBS/cClassTrib da empresa. Query: ativo, empresa.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

ativo
empresa

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/iva" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "items": [
        {
            "id": 5,
            "ncm": "4444",
            "cst": "000",
            "cclasstrib": "000001",
            "ibs_p_uf": "0.1000",
            "ibs_p_mun": "0.0000",
            "cbs_p": "0.9000",
            "ativo": 1
        }
    ],
    "request_id": "req_..."
}

POST /configuracao-fiscal/iva permissao: configurar

Criar regra IVA (IBS/CBS)

Define CST (3 digitos), cClassTrib (6 digitos) e aliquotas de IBS (UF e municipio) e CBS, com reducao de aliquota (gRed), diferimento (gDif), vigencia e criterios (produto, NCM, NBS, natureza, destinatario, UF, municipio, operacao). Integrada ao Motor Tributario: e resolvida junto com a tributacao tradicional pela data da operacao. Credito presumido e informativo (nao e emitido no XML). Resposta 201.

Autenticacao: Bearer API Key

Obrigatorios

cst
cclasstrib

Opcionais

descricao
prioridade
vigencia_inicio
vigencia_fim
modelo
natureza_id
produto_id
ncm
nbs
categoria
uf_destino
cod_municipio_destino
operacao
consumidor_final
contribuinte
tipo_destinatario
classificacao
regime (regular|regime_especifico|tratamento_diferenciado)
ibs_p_uf
ibs_p_mun
cbs_p
red_aliq_ibs_uf
red_aliq_ibs_mun
red_aliq_cbs
dif_p_ibs_uf
dif_p_ibs_mun
dif_p_cbs
cred_presumido_p
inf_cpl
ativo

JSON minimo

{
    "cst": "000",
    "cclasstrib": "000001",
    "ibs_p_uf": 0.1,
    "ibs_p_mun": 0,
    "cbs_p": 0.9
}

JSON completo

{
    "descricao": "IBS/CBS - NCM 4444",
    "vigencia_inicio": "2026-01-01",
    "ncm": "4444",
    "operacao": "interna",
    "cst": "000",
    "cclasstrib": "000001",
    "classificacao": "Tributacao integral",
    "regime": "regular",
    "ibs_p_uf": 0.1,
    "ibs_p_mun": 0,
    "cbs_p": 0.9,
    "red_aliq_cbs": 0,
    "dif_p_cbs": 0
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/iva" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cst":"000","cclasstrib":"000001","ibs_p_uf":0.1,"ibs_p_mun":0,"cbs_p":0.9}'

Exemplo de response

{
    "success": true,
    "item": {
        "id": 5,
        "cst": "000",
        "cclasstrib": "000001"
    },
    "avisos": [],
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — CST/cClassTrib com tamanho invalido, aliquotas fora de 0-100, vigencia invalida.

GET /configuracao-fiscal/iva/{id} permissao: consultar

Consultar regra IVA (PUT atualiza, DELETE desativa)

GET consulta; PUT atualiza parcialmente; DELETE desativa. Documentos ja emitidos mantem a regra IVA usada (snapshot).

Autenticacao: Bearer API Key

Parametros de URL: {id} ID da regra IVA

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/iva/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "item": {
        "id": 5
    },
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Inexistente ou de outra empresa.

GET /financeiro/status permissao: consultar

Situacao financeira

Saldo, precos por emissao e se ha creditos ilimitados ativos (concessao do administrador). Sempre da carteira do proprio usuario da chave.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/financeiro/status" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "credito_ilimitado": false,
    "saldo": "37.50",
    "saldo_baixo": false,
    "alerta_saldo": "10.00",
    "precos": {
        "NFE": "1.50",
        "NFCE": "0.75"
    },
    "moeda": "BRL",
    "request_id": "req_..."
}

Erros possiveis

403 CARTEIRA_INDISPONIVEL — Credencial sem carteira.

GET /financeiro/saldo permissao: consultar

Saldo

Saldo atual da carteira (valores em BRL, string decimal). Com creditos ilimitados o saldo e preservado, mas nao e consumido.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/financeiro/saldo" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "saldo": "37.50",
    "credito_ilimitado": false,
    "moeda": "BRL",
    "request_id": "req_..."
}

GET /financeiro/extrato permissao: consultar

Extrato

Movimentacoes da carteira (ledger), da mais recente para a mais antiga. Query: pagina, por_pagina (ate 100), de/ate (AAAA-MM-DD), tipo (CREDITO_COMPRA, CREDITO_ADMIN, DEBITO_EMISSAO, ESTORNO, AJUSTE_ADMIN, REEMBOLSO). valor negativo = saida.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

pagina
por_pagina
de
ate
tipo

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/financeiro/extrato" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "saldo": "37.50",
    "pagina": 1,
    "por_pagina": 20,
    "total": 1,
    "movimentacoes": [
        {
            "id": 10,
            "tipo": "DEBITO_EMISSAO",
            "valor": "-1.50",
            "saldo_anterior": "39.00",
            "saldo_posterior": "37.50",
            "tipo_documento": "NFE",
            "documento_id": 43,
            "pagamento_id": null,
            "referencia": "emissao:...",
            "descricao": "Emissao NFE - pedido PED-1",
            "data": "2026-01-01 10:00:00"
        }
    ],
    "request_id": "req_..."
}

POST /fiscal/calcular permissao: preview

Calcular (Motor Tributario, sem emitir)

Executa o Motor Tributario Central para qualquer documento (NFE, NFCE, NFSE, CTE, MDFE) e contexto, SEM emitir, cobrar ou falar com SEFAZ/Sistema Nacional. "operacao" e o mesmo JSON minimo da emissao (NF-e/NFC-e dispensam o pagamento). Devolve taxes, classifications, rules_used (fonte/versao/vigencia), warnings, confidence_score e requires_review. A legislacao e escolhida pela data da operacao (data_operacao, apenas para simulacao). Query ?explain=true devolve o passo a passo de cada decisao (tributo, base, aliquota, valor, regra, fonte, versao, motivo).

Autenticacao: Bearer API Key

Obrigatorios

documento (NFE|NFCE|NFSE|CTE|CTEOS|MDFE)
operacao {}

Opcionais

empresa_id | empresa
contexto (PRODUTOR_RURAL)
operacao.data_operacao (simulacao)

JSON minimo

{
    "empresa_id": 25,
    "documento": "NFSE",
    "operacao": {
        "empresa_id": 25,
        "pedido": "SERV-0001",
        "tomador": {
            "cpf_cnpj": "12345678909",
            "nome": "Joao da Silva",
            "email": "joao@exemplo.com",
            "endereco": {
                "logradouro": "Rua A",
                "numero": "10",
                "bairro": "Centro",
                "cod_municipio": "3148004",
                "municipio": "Patos de Minas",
                "uf": "MG",
                "cep": "38700000"
            }
        },
        "servico": {
            "codigo": "CONS01",
            "valor": 1500
        }
    }
}

JSON completo

{
    "empresa_id": 25,
    "documento": "NFE",
    "contexto": "PRODUTOR_RURAL",
    "operacao": {
        "pedido": "RURAL-0001",
        "operacao": "venda",
        "propriedade": "FAZ01",
        "cliente": "CLIMG",
        "itens": [
            {
                "codigo": "CAFE01",
                "quantidade": 100
            }
        ]
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/fiscal/calcular" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"documento":"NFSE","operacao":{"empresa_id":25,"pedido":"SERV-0001","tomador":{"cpf_cnpj":"12345678909","nome":"Joao da Silva","email":"joao@exemplo.com","endereco":{"logradouro":"Rua A","numero":"10","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"servico":{"codigo":"CONS01","valor":1500}}}'

Exemplo de response

{
    "success": true,
    "document": "NFSE",
    "taxes": {
        "iss": {
            "tipo": "tributavel",
            "base": 1500,
            "rate": 2.5,
            "valor": 37.5
        }
    },
    "classifications": {
        "cTribNac": "010701",
        "municipio_incidencia": "3148004",
        "tpRetISSQN": 1
    },
    "rules_used": [
        {
            "rule_id": 81,
            "tipo": "ISS",
            "versao": "2026.1",
            "fonte": "Lei Complementar Municipal ...",
            "vigencia_inicio": "2026-01-01"
        }
    ],
    "warnings": [],
    "confidence_score": 0.95,
    "requires_review": false,
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Dados invalidos da operacao.
501 NFF_NAO_DISPONIVEL — documento NFF: arquitetura preparada, integracao oficial ainda nao implementada.

POST /fiscal/validate permissao: preview

Validar (dry-run)

Dry-run completo: o mesmo calculo de /fiscal/calcular + validacao do documento (DPS/XML no leiaute oficial) + consistencia. Sem SEFAZ/Sistema Nacional, sem cobranca, sem emissao. Retorna valid e ready_to_issue (false quando requires_review ou o leiaute reprova).

Autenticacao: Bearer API Key

Obrigatorios

documento
operacao {}

Opcionais

empresa_id | empresa
contexto

JSON minimo

{
    "empresa_id": 25,
    "documento": "CTE",
    "operacao": {
        "empresa_id": 25,
        "pedido": "FRETE-0001",
        "tomador": "destinatario",
        "remetente": {
            "cpf_cnpj": "33000167000101",
            "nome": "Remetente Industria Ltda",
            "ie": "9057800426",
            "endereco": {
                "logradouro": "Rua A",
                "numero": "1",
                "bairro": "Centro",
                "cod_municipio": "3148004",
                "municipio": "Patos de Minas",
                "uf": "MG",
                "cep": "38700000"
            }
        },
        "destinatario": {
            "cpf_cnpj": "00000000000191",
            "nome": "Destinatario Comercio SA",
            "ie": "110042490114",
            "endereco": {
                "logradouro": "Av. B",
                "numero": "200",
                "bairro": "Se",
                "cod_municipio": "3550308",
                "municipio": "Sao Paulo",
                "uf": "SP",
                "cep": "01001000"
            }
        },
        "valor_prestacao": 1000,
        "carga": {
            "valor": 50000,
            "produto": "Tubos plasticos",
            "peso_kg": 18145
        },
        "documentos": [
            "31260960701190000104550010000001231123456789"
        ],
        "fiscal": {
            "tipo_estabelecimento_tomador": "comercial"
        }
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/fiscal/validate" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"documento":"CTE","operacao":{"empresa_id":25,"pedido":"FRETE-0001","tomador":"destinatario","remetente":{"cpf_cnpj":"33000167000101","nome":"Remetente Industria Ltda","ie":"9057800426","endereco":{"logradouro":"Rua A","numero":"1","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"destinatario":{"cpf_cnpj":"00000000000191","nome":"Destinatario Comercio SA","ie":"110042490114","endereco":{"logradouro":"Av. B","numero":"200","bairro":"Se","cod_municipio":"3550308","municipio":"Sao Paulo","uf":"SP","cep":"01001000"}},"valor_prestacao":1000,"carga":{"valor":50000,"produto":"Tubos plasticos","peso_kg":18145},"documentos":["31260960701190000104550010000001231123456789"],"fiscal":{"tipo_estabelecimento_tomador":"comercial"}}}'

Exemplo de response

{
    "success": true,
    "document": "CTE",
    "valid": true,
    "ready_to_issue": true,
    "xml_validado": true,
    "leiaute": "PL_CTe_400",
    "taxes": {
        "icms": {
            "cst": "00",
            "rate": 12,
            "valor": 120
        }
    },
    "confidence_score": 0.9,
    "requires_review": false,
    "request_id": "req_..."
}

Erros possiveis

422 FISCAL_CONFIGURATION_REQUIRED — Configuracao pendente: error.missing.

GET /configuracao-fiscal/regras-base permissao: consultar

Listar regras da base tributaria versionada

Regras da empresa e globais da plataforma (somente leitura). Query: tipo (ISS, ISS_RETENCAO, RETENCAO_FEDERAL, MUNICIPIO_INCIDENCIA, ICMS_TRANSPORTE, RURAL_ICMS, RURAL_BENEFICIO, CFOP_OPERACAO, IBS_CBS), empresa.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

tipo
empresa (query)

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/regras-base" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "itens": [
        {
            "id": 81,
            "config_id": 25,
            "tipo": "ISS",
            "criterios": {
                "municipio_ibge": "3148004"
            },
            "resultado": {
                "aliquota": 2.5
            },
            "vigencia_inicio": "2026-01-01",
            "vigencia_fim": null,
            "versao": "2026.1",
            "fonte": "Lei Complementar Municipal ..."
        }
    ],
    "request_id": "req_..."
}

POST /configuracao-fiscal/regras-base permissao: configurar

Cadastrar regra da base tributaria

Toda regra exige tipo, criterios (casamento: igualdade, *_prefixo, *_in), resultado, vigencia_inicio, versao e FONTE (norma/fundamento). Beneficios (RURAL_ICMS diferente de NORMAL, RURAL_BENEFICIO) exigem resultado.fundamento. A aliquota/beneficio nunca e presumido pela plataforma. Alteracoes sao auditadas.

Autenticacao: Bearer API Key

Obrigatorios

tipo
criterios {}
resultado {}
vigencia_inicio
versao
fonte

Opcionais

vigencia_fim
descricao
referencia
prioridade
confianca (0..1)
empresa_id

JSON minimo

{
    "empresa_id": 25,
    "tipo": "ISS",
    "criterios": {
        "municipio_ibge": "3148004",
        "lc116_prefixo": "01"
    },
    "resultado": {
        "aliquota": 2.5
    },
    "vigencia_inicio": "2026-01-01",
    "versao": "2026.1",
    "fonte": "Lei Complementar Municipal ..."
}

JSON completo

{
    "empresa_id": 25,
    "tipo": "RURAL_ICMS",
    "criterios": {
        "uf_origem": "MG",
        "produto_classe": "cafe",
        "operacao": "venda",
        "operacao_geo": "interna"
    },
    "resultado": {
        "situacao": "DIFERIMENTO",
        "cst": "51",
        "p_dif": 100,
        "fundamento": "Art. ... do RICMS/MG"
    },
    "vigencia_inicio": "2026-01-01",
    "versao": "2026.1",
    "fonte": "RICMS/MG",
    "referencia": "URL ou citacao"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/regras-base" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"tipo":"ISS","criterios":{"municipio_ibge":"3148004","lc116_prefixo":"01"},"resultado":{"aliquota":2.5},"vigencia_inicio":"2026-01-01","versao":"2026.1","fonte":"Lei Complementar Municipal ..."}'

Exemplo de response

{
    "success": true,
    "id": 81,
    "tipo": "ISS",
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Fonte/vigencia/criterio/resultado invalidos.

GET /configuracao-fiscal/regras-base/{id} permissao: consultar

Consultar regra

Regra da empresa ou global.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/regras-base/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 81,
    "tipo": "ISS",
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Regra inexistente.

PUT /configuracao-fiscal/regras-base/{id} permissao: configurar

Alterar regra da empresa

Somente regras da propria empresa (as globais sao da plataforma). Emissoes ja feitas NAO mudam (snapshot imutavel).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

campos da criacao

JSON minimo

{
    "resultado": {
        "aliquota": 3
    },
    "fonte": "Lei Complementar Municipal ..."
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/regras-base/43" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resultado":{"aliquota":3},"fonte":"Lei Complementar Municipal ..."}'

Exemplo de response

{
    "success": true,
    "id": 81,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Regra da empresa inexistente.

DELETE /configuracao-fiscal/regras-base/{id} permissao: configurar

Desativar regra da empresa

Desativacao logica (auditada).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X DELETE "https://www.fiscal.versianecode.com.br/api/v1/configuracao-fiscal/regras-base/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 81,
    "ativo": false,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Regra da empresa inexistente.

POST /nfse permissao: nfse:write

Emitir NFS-e Nacional

JSON minimo: pedido, tomador e servico (cadastrado em /servicos ou inline com descricao, c_trib_nac e valor). A API monta a DPS, o Motor Tributario determina ISS (aliquota pela base versionada da data da operacao), retencoes, municipio de incidencia e classificacao, assina e envia ao Sistema Nacional da NFS-e (mTLS com o certificado A1 da empresa). Sem aliquota/regra vigente NAO emite (422). Idempotente (pedido e Idempotency-Key). Dependencias externas: certificado ICP-Brasil valido, convenio do municipio com o Sistema Nacional e XSD oficial (opcional) em storage/schemas/nfse.

Autenticacao: Bearer API Key · Idempotency-Key (opcional): evita emissao duplicada em reenvios.

Obrigatorios

pedido
servico.codigo OU (servico.descricao + servico.c_trib_nac + servico.valor)

Opcionais

empresa_id | empresa
tomador {cpf_cnpj, nome, email, endereco}
competencia
desconto
observacoes
servico.valor/lc116/nbs/cnae/local_prestacao
servico.aliquota_iss e servico.iss_retido (OVERRIDE: exigem permissao override + override_motivo)
aceitar_revisao (requer override)

JSON minimo

{
    "empresa_id": 25,
    "pedido": "SERV-0001",
    "tomador": {
        "cpf_cnpj": "12345678909",
        "nome": "Joao da Silva",
        "email": "joao@exemplo.com",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "10",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "servico": {
        "codigo": "CONS01",
        "valor": 1500
    }
}

JSON completo

{
    "empresa_id": 25,
    "pedido": "SERV-0001",
    "tomador": {
        "cpf_cnpj": "12345678909",
        "nome": "Joao da Silva",
        "email": "joao@exemplo.com",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "10",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "servico": {
        "codigo": "CONS01",
        "valor": 1500
    },
    "competencia": "2026-03-10",
    "observacoes": "Referente ao contrato 123"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/nfse" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"SERV-0001","tomador":{"cpf_cnpj":"12345678909","nome":"Joao da Silva","email":"joao@exemplo.com","endereco":{"logradouro":"Rua A","numero":"10","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"servico":{"codigo":"CONS01","valor":1500}}'

Exemplo de response

{
    "success": true,
    "id": "12",
    "status": "AUTORIZADA",
    "chave_acesso": "3148004221...(50 posicoes)",
    "numero_nfse": "1",
    "valor_servicos": 1500,
    "valor_iss": 37.5,
    "links": {
        "xml": "/api/v1/nfse/12/xml",
        "danfse": "/api/v1/nfse/12/danfse"
    },
    "request_id": "req_..."
}

Erros possiveis

422 FISCAL_CONFIGURATION_REQUIRED — Falta configuracao fiscal (regra, certificado, emitente...): error.missing e error.motivos.
422 REVISAO_FISCAL_NECESSARIA — A tributacao nao pode ser determinada com seguranca (confidence_score baixo / requires_review).
422 IDEMPOTENCY_KEY_REUSED — Mesmo pedido/Idempotency-Key com conteudo diferente.
402 SALDO_INSUFICIENTE — Saldo de creditos insuficiente.

POST /nfse/preview permissao: nfse:write

Preview da NFS-e (nao emite, nao cobra)

Mesmo JSON da emissao. Calcula, classifica, valida a DPS e explica. Nao transmite, nao cobra, nao gera documento. Query ?explain=true devolve o passo a passo de cada decisao (tributo, base, aliquota, valor, regra, fonte, versao, motivo).

Autenticacao: Bearer API Key

Obrigatorios

pedido (opcional no preview)
servico
tomador

Opcionais

data_operacao (simulacao)

JSON minimo

{
    "empresa_id": 25,
    "pedido": "SERV-0001",
    "tomador": {
        "cpf_cnpj": "12345678909",
        "nome": "Joao da Silva",
        "email": "joao@exemplo.com",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "10",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "servico": {
        "codigo": "CONS01",
        "valor": 1500
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/nfse/preview" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"SERV-0001","tomador":{"cpf_cnpj":"12345678909","nome":"Joao da Silva","email":"joao@exemplo.com","endereco":{"logradouro":"Rua A","numero":"10","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"servico":{"codigo":"CONS01","valor":1500}}'

Exemplo de response

{
    "success": true,
    "ready_to_issue": true,
    "document": "NFSE",
    "taxes": {
        "iss": {
            "valor": 37.5,
            "rate": 2.5
        }
    },
    "classifications": {
        "cTribNac": "010701"
    },
    "confidence_score": 0.95,
    "requires_review": false,
    "dps_validacao": [],
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Servico/tomador invalidos.

GET /nfse permissao: nfse:read

Listar NFS-e

Query: status, pedido, empresa_id, pagina, por_pagina (ate 100). Somente documentos das empresas da credencial.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

status
pedido
empresa_id
pagina
por_pagina

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/nfse" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "pagina": 1,
    "por_pagina": 20,
    "itens": [
        {
            "id": "12",
            "status": "AUTORIZADA",
            "chave_acesso": "...",
            "valor_servicos": 1500
        }
    ],
    "request_id": "req_..."
}

GET /nfse/{id} permissao: nfse:read

Consultar NFS-e

Status, chave de acesso, valores, eventos e links. NFS-e PROCESSANDO (resposta incerta) e reconciliada consultando a DPS no Sistema Nacional.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/nfse/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": "12",
    "status": "AUTORIZADA",
    "chave_acesso": "3148004221...(50 posicoes)",
    "numero_nfse": "1",
    "valor_servicos": 1500,
    "valor_iss": 37.5,
    "links": {
        "xml": "/api/v1/nfse/12/xml",
        "danfse": "/api/v1/nfse/12/danfse"
    },
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Documento inexistente ou de outra empresa.

POST /nfse/{id}/cancelar permissao: nfse:write

Cancelar NFS-e

Registra o evento de cancelamento (e101101) no Sistema Nacional. Prazos e regras sao do municipio/Sistema Nacional.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

justificativa (15 a 255 caracteres)

Opcionais

codigo_motivo (1 erro na emissao, 2 servico nao prestado, 9 outros; padrao 9)

JSON minimo

{
    "justificativa": "Cancelamento por erro na emissao do servico",
    "codigo_motivo": 1
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/nfse/43/cancelar" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"justificativa":"Cancelamento por erro na emissao do servico","codigo_motivo":1}'

Exemplo de response

{
    "success": true,
    "id": "12",
    "status": "CANCELADA",
    "request_id": "req_..."
}

Erros possiveis

422 NFSE_CANCEL_REJECTION — Cancelamento rejeitado pelo Sistema Nacional.
409 STATUS_INVALIDO — Somente NFS-e AUTORIZADA pode ser cancelada.

GET /nfse/{id}/xml permissao: nfse:read

Baixar XML da NFS-e

XML da NFS-e autorizada devolvido pelo Sistema Nacional (referencia principal, armazenado como recebido).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/nfse/43/xml" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

<NFSe>...</NFSe>

Erros possiveis

409 XML_INDISPONIVEL — NFS-e ainda sem XML autorizado.

GET /nfse/{id}/danfse permissao: nfse:read

Baixar DANFSe (PDF)

DANFSe nacional gerado localmente a partir do XML autorizado armazenado (sped-da, NT 008). O PDF nao substitui o documento eletronico.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/nfse/43/danfse" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

(application/pdf)

Erros possiveis

409 DOCUMENTO_NAO_AUTORIZADO — So existe para NFS-e autorizada.

GET /servicos permissao: nfse:read

Listar servicos cadastrados

Servicos fiscais da empresa (LC 116, cTribNac, NBS, CNAE, preco e, opcionalmente, aliquota/retencao de ISS).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/servicos" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "itens": [
        {
            "id": 1,
            "codigo": "CONS01",
            "c_trib_nac": "010701"
        }
    ],
    "request_id": "req_..."
}

POST /servicos permissao: nfse:write

Cadastrar servico

c_trib_nac (6 digitos) identifica o servico no padrao nacional. aliquota_iss/iss_retido sao CONFIGURACAO (cadastro); sem eles o Motor usa a base versionada.

Autenticacao: Bearer API Key

Obrigatorios

codigo
descricao

Opcionais

empresa_id
lc116 (NN.NN)
c_trib_nac
c_trib_mun
nbs
cnae
preco
aliquota_iss
iss_retido
municipio_incidencia

JSON minimo

{
    "empresa_id": 25,
    "codigo": "CONS01",
    "descricao": "Consultoria em tecnologia da informacao",
    "lc116": "01.07",
    "c_trib_nac": "010701",
    "nbs": "115090000",
    "preco": 1500
}

JSON completo

{
    "empresa_id": 25,
    "codigo": "CONS01",
    "descricao": "Consultoria em tecnologia da informacao",
    "lc116": "01.07",
    "c_trib_nac": "010701",
    "nbs": "115090000",
    "cnae": "6204000",
    "preco": 1500,
    "iss_retido": 0
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/servicos" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"codigo":"CONS01","descricao":"Consultoria em tecnologia da informacao","lc116":"01.07","c_trib_nac":"010701","nbs":"115090000","preco":1500}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "codigo": "CONS01",
    "request_id": "req_..."
}

Erros possiveis

409 REGISTRO_DUPLICADO — Codigo ja existe.

GET /servicos/{id} permissao: nfse:read

Consultar servico

Servico da empresa.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/servicos/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "codigo": "CONS01",
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Servico inexistente.

PUT /servicos/{id} permissao: nfse:write

Alterar servico

Atualiza campos informados (auditado).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

campos do cadastro

JSON minimo

{
    "preco": 1600
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/servicos/43" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preco":1600}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Servico inexistente.

DELETE /servicos/{id} permissao: nfse:write

Desativar servico

Desativacao logica (auditada).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X DELETE "https://www.fiscal.versianecode.com.br/api/v1/servicos/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "ativo": false,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Servico inexistente.

POST /cte permissao: cte:write

Emitir CT-e (modelo 57, rodoviario)

JSON simplificado: tomador (papel ou terceiro), remetente, destinatario (codigo de cliente cadastrado ou dados), valor da prestacao, carga e chaves das NF-e transportadas. O Motor Tributario determina o ICMS do transporte (base ICMS_TRANSPORTE da data da operacao; Simples Nacional usa ICMSSN), o CFOP e, se ha regra vigente, o IBS/CBS (leiaute 4.00 com IBS/CBS). O CFOP sai da base pelo tipo de estabelecimento do tomador (fiscal.tipo_estabelecimento_tomador) ou e declarado em fiscal.cfop. XML gerado com sped-cte, validado no XSD 4.00, enviado a SEFAZ; o XML autorizado (cteProc) e a referencia. Pre-requisitos: RNTRC e IE do emitente, certificado A1, credenciamento do emitente como transportador na SEFAZ da UF.

Autenticacao: Bearer API Key · Idempotency-Key (opcional): evita emissao duplicada em reenvios.

Obrigatorios

pedido
tomador (remetente|expedidor|recebedor|destinatario ou objeto)
remetente
destinatario
valor_prestacao
carga {valor, produto, peso_kg|quantidades}
documentos [chaves NF-e]

Opcionais

empresa_id | empresa
expedidor
recebedor
origem/destino {cod_municipio, municipio, uf} (padrao: enderecos de remetente/destinatario)
componentes [{nome, valor}]
fiscal {tipo_estabelecimento_tomador: mesma_natureza|industrial|comercial|comunicacao|energia|produtor_rural, cfop}
natureza_operacao
observacoes
data_operacao

JSON minimo

{
    "empresa_id": 25,
    "pedido": "FRETE-0001",
    "tomador": "destinatario",
    "remetente": {
        "cpf_cnpj": "33000167000101",
        "nome": "Remetente Industria Ltda",
        "ie": "9057800426",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "1",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "destinatario": {
        "cpf_cnpj": "00000000000191",
        "nome": "Destinatario Comercio SA",
        "ie": "110042490114",
        "endereco": {
            "logradouro": "Av. B",
            "numero": "200",
            "bairro": "Se",
            "cod_municipio": "3550308",
            "municipio": "Sao Paulo",
            "uf": "SP",
            "cep": "01001000"
        }
    },
    "valor_prestacao": 1000,
    "carga": {
        "valor": 50000,
        "produto": "Tubos plasticos",
        "peso_kg": 18145
    },
    "documentos": [
        "31260960701190000104550010000001231123456789"
    ],
    "fiscal": {
        "tipo_estabelecimento_tomador": "comercial"
    }
}

JSON completo

{
    "empresa_id": 25,
    "pedido": "FRETE-0001",
    "tomador": "destinatario",
    "remetente": {
        "cpf_cnpj": "33000167000101",
        "nome": "Remetente Industria Ltda",
        "ie": "9057800426",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "1",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "destinatario": {
        "cpf_cnpj": "00000000000191",
        "nome": "Destinatario Comercio SA",
        "ie": "110042490114",
        "endereco": {
            "logradouro": "Av. B",
            "numero": "200",
            "bairro": "Se",
            "cod_municipio": "3550308",
            "municipio": "Sao Paulo",
            "uf": "SP",
            "cep": "01001000"
        }
    },
    "valor_prestacao": 1000,
    "carga": {
        "valor": 50000,
        "produto": "Tubos plasticos",
        "peso_kg": 18145
    },
    "documentos": [
        "31260960701190000104550010000001231123456789"
    ],
    "fiscal": {
        "tipo_estabelecimento_tomador": "comercial"
    },
    "componentes": [
        {
            "nome": "FRETE VALOR",
            "valor": 1000
        }
    ],
    "observacoes": "Entrega agendada"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cte" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"FRETE-0001","tomador":"destinatario","remetente":{"cpf_cnpj":"33000167000101","nome":"Remetente Industria Ltda","ie":"9057800426","endereco":{"logradouro":"Rua A","numero":"1","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"destinatario":{"cpf_cnpj":"00000000000191","nome":"Destinatario Comercio SA","ie":"110042490114","endereco":{"logradouro":"Av. B","numero":"200","bairro":"Se","cod_municipio":"3550308","municipio":"Sao Paulo","uf":"SP","cep":"01001000"}},"valor_prestacao":1000,"carga":{"valor":50000,"produto":"Tubos plasticos","peso_kg":18145},"documentos":["31260960701190000104550010000001231123456789"],"fiscal":{"tipo_estabelecimento_tomador":"comercial"}}'

Exemplo de response

{
    "success": true,
    "id": "7",
    "status": "AUTORIZADA",
    "chave": "31260...57...(44)",
    "protocolo": "131000000000001",
    "cfop": "6353",
    "valor_prestacao": 1000,
    "links": {
        "xml": "/api/v1/cte/7/xml",
        "dacte": "/api/v1/cte/7/dacte"
    },
    "request_id": "req_..."
}

Erros possiveis

422 FISCAL_CONFIGURATION_REQUIRED — Falta configuracao fiscal (regra, certificado, emitente...): error.missing e error.motivos.
422 REVISAO_FISCAL_NECESSARIA — A tributacao nao pode ser determinada com seguranca (confidence_score baixo / requires_review).
422 IDEMPOTENCY_KEY_REUSED — Mesmo pedido/Idempotency-Key com conteudo diferente.
402 SALDO_INSUFICIENTE — Saldo de creditos insuficiente.

POST /cte/preview permissao: cte:write

Preview do CT-e (nao emite, nao cobra)

Calcula ICMS/CFOP/IBS-CBS, valida o XML no leiaute oficial e explica. Nao transmite nem cobra. Query ?explain=true devolve o passo a passo de cada decisao (tributo, base, aliquota, valor, regra, fonte, versao, motivo).

Autenticacao: Bearer API Key

Obrigatorios

(mesmos da emissao)

Opcionais

nenhum

JSON minimo

{
    "empresa_id": 25,
    "pedido": "FRETE-0001",
    "tomador": "destinatario",
    "remetente": {
        "cpf_cnpj": "33000167000101",
        "nome": "Remetente Industria Ltda",
        "ie": "9057800426",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "1",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "destinatario": {
        "cpf_cnpj": "00000000000191",
        "nome": "Destinatario Comercio SA",
        "ie": "110042490114",
        "endereco": {
            "logradouro": "Av. B",
            "numero": "200",
            "bairro": "Se",
            "cod_municipio": "3550308",
            "municipio": "Sao Paulo",
            "uf": "SP",
            "cep": "01001000"
        }
    },
    "valor_prestacao": 1000,
    "carga": {
        "valor": 50000,
        "produto": "Tubos plasticos",
        "peso_kg": 18145
    },
    "documentos": [
        "31260960701190000104550010000001231123456789"
    ],
    "fiscal": {
        "tipo_estabelecimento_tomador": "comercial"
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cte/preview" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"FRETE-0001","tomador":"destinatario","remetente":{"cpf_cnpj":"33000167000101","nome":"Remetente Industria Ltda","ie":"9057800426","endereco":{"logradouro":"Rua A","numero":"1","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"destinatario":{"cpf_cnpj":"00000000000191","nome":"Destinatario Comercio SA","ie":"110042490114","endereco":{"logradouro":"Av. B","numero":"200","bairro":"Se","cod_municipio":"3550308","municipio":"Sao Paulo","uf":"SP","cep":"01001000"}},"valor_prestacao":1000,"carga":{"valor":50000,"produto":"Tubos plasticos","peso_kg":18145},"documentos":["31260960701190000104550010000001231123456789"],"fiscal":{"tipo_estabelecimento_tomador":"comercial"}}'

Exemplo de response

{
    "success": true,
    "ready_to_issue": true,
    "document": "CTE",
    "taxes": {
        "icms": {
            "cst": "00",
            "valor": 120
        }
    },
    "classifications": {
        "cfop": "6353",
        "cst": "00"
    },
    "xml_validado": true,
    "leiaute": "PL_CTe_400",
    "confidence_score": 0.9,
    "requires_review": false,
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Dados invalidos.

GET /cte permissao: cte:read

Listar CT-e

Query: status, pedido, empresa_id, pagina, por_pagina.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

status
pedido
empresa_id
pagina
por_pagina

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/cte" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "pagina": 1,
    "por_pagina": 20,
    "itens": [
        {
            "id": "7",
            "status": "AUTORIZADA"
        }
    ],
    "request_id": "req_..."
}

GET /cte/{id} permissao: cte:read

Consultar CT-e

Status, chave, protocolo, eventos e links. CT-e PENDENTE e reconciliado por consulta da chave na SEFAZ.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/cte/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": "7",
    "status": "AUTORIZADA",
    "chave": "31260...57...(44)",
    "protocolo": "131000000000001",
    "cfop": "6353",
    "valor_prestacao": 1000,
    "links": {
        "xml": "/api/v1/cte/7/xml",
        "dacte": "/api/v1/cte/7/dacte"
    },
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Documento inexistente ou de outra empresa.

POST /cte/{id}/cancelar permissao: cte:write

Cancelar CT-e

Evento de cancelamento (110111).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

justificativa (15 a 255)

Opcionais

nenhum

JSON minimo

{
    "justificativa": "Cancelamento por erro de digitacao no valor"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cte/43/cancelar" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"justificativa":"Cancelamento por erro de digitacao no valor"}'

Exemplo de response

{
    "success": true,
    "status": "CANCELADA",
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_EVENT_REJECTION — Evento rejeitado pela SEFAZ.
409 STATUS_INVALIDO — Somente CT-e AUTORIZADO.

POST /cte/{id}/cce permissao: cte:write

Carta de Correcao (CC-e)

Evento 110110 com correcoes [{grupo, campo, valor}]. Nao pode alterar valores, tomador, CFOP etc. (regra da SEFAZ). Sequencia controlada pela API.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

correcoes [{grupo, campo, valor, numero_item?}]

Opcionais

nenhum

JSON minimo

{
    "correcoes": [
        {
            "grupo": "compl",
            "campo": "xObs",
            "valor": "Observacao corrigida"
        }
    ]
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cte/43/cce" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"correcoes":[{"grupo":"compl","campo":"xObs","valor":"Observacao corrigida"}]}'

Exemplo de response

{
    "success": true,
    "eventos": [
        {
            "tipo": "CCE",
            "sequencia": 1,
            "status": "REGISTRADO"
        }
    ],
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_EVENT_REJECTION — Correcao nao aceita.

POST /cte/{id}/desacordo permissao: cte:write

Prestacao de servico em desacordo

Evento 610110 (desacordo do tomador).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

observacao (15 a 255)

Opcionais

nenhum

JSON minimo

{
    "observacao": "Prestacao do servico em desacordo com o contratado"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cte/43/desacordo" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"observacao":"Prestacao do servico em desacordo com o contratado"}'

Exemplo de response

{
    "success": true,
    "eventos": [
        {
            "tipo": "DESACORDO",
            "status": "REGISTRADO"
        }
    ],
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_EVENT_REJECTION — Evento nao aceito.

GET /cte/{id}/xml permissao: cte:read

Baixar XML do CT-e

cteProc (XML autorizado + protocolo + eventos de cancelamento), referencia principal.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/cte/43/xml" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

<cteProc>...</cteProc>

Erros possiveis

409 XML_INDISPONIVEL — Sem XML autorizado.

GET /cte/{id}/dacte permissao: cte:read

Baixar DACTE (PDF)

DACTE gerado a partir do XML autorizado armazenado (sped-da).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/cte/43/dacte" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

(application/pdf)

Erros possiveis

409 DOCUMENTO_SEM_PROTOCOLO — CT-e sem protocolo.

POST /cteos permissao: cteos:write

Emitir CT-e OS (modelo 67, transporte de pessoas, valores e excesso de bagagem)

JSON simplificado: tomador (codigo de cliente cadastrado ou dados), servico {tipo: transporte_pessoas | transporte_valores | excesso_bagagem, descricao, quantidade}, origem e destino {cod_municipio, municipio, uf}, valor da prestacao e, opcionalmente, percurso (UFs), veiculo, fretamento e documentos referenciados. O Motor Tributario determina o ICMS do transporte (base ICMS_TRANSPORTE da data da operacao; criterio documento = CTEOS restringe a regra ao CT-e OS; Simples Nacional usa ICMSSN) e, se ha regra vigente, o IBS/CBS (leiaute 4.00 com IBS/CBS). O CFOP NAO e adivinhado: vem de regra CFOP_OPERACAO cadastrada para o documento CTEOS ou e declarado em fiscal.cfop. XML gerado com sped-cte (CTeOS), validado no XSD cteOS 4.00, enviado a SEFAZ SEMPRE de forma unitaria; o XML autorizado (cteOSProc) e a referencia. Modal rodoviario OS: TAF (12 digitos) ou numero do Registro Estadual (25 digitos) do transportador, configurado na empresa (taf_cteos | reg_estadual_cteos) ou informado em transporte. Pre-requisitos: IE e endereco do emitente, certificado A1, modulo cteos habilitado e autorizacao do emitente para transporte de passageiros/valores.

Autenticacao: Bearer API Key · Idempotency-Key (opcional): evita emissao duplicada em reenvios. Prefer: respond-async: processa pela fila fiscal.

Obrigatorios

pedido
tomador (codigo de cliente ou {cpf_cnpj, nome, endereco})
servico {tipo, descricao (ate 30 caracteres), quantidade?}
origem {cod_municipio, municipio, uf}
destino {cod_municipio, municipio, uf}
valor_prestacao

Opcionais

empresa_id | empresa
percurso [UFs] (ate 25)
veiculo (placa ou {placa, renavam, uf, proprietario {cpf_cnpj, nome, tipo 0|1|2, taf|nro_reg_estadual, ie, uf}})
fretamento {tipo: eventual|continuo, data_viagem}
transporte {taf | nro_reg_estadual} (substitui o padrao da empresa)
documentos_referenciados [{numero, serie, subserie, data, valor} | {chave_bpe}]
componentes [{nome, valor}]
fiscal {cfop, tipo_estabelecimento_tomador}
natureza_operacao
observacoes
data_operacao

JSON minimo

{
    "empresa_id": 25,
    "pedido": "OS-0001",
    "tomador": {
        "cpf_cnpj": "33000167000101",
        "nome": "Empresa de Turismo Ltda",
        "ie": "9057800426",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "1",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "servico": {
        "tipo": "transporte_pessoas",
        "descricao": "Fretamento para evento",
        "quantidade": 40
    },
    "origem": {
        "cod_municipio": "3148004",
        "municipio": "Patos de Minas",
        "uf": "MG"
    },
    "destino": {
        "cod_municipio": "3550308",
        "municipio": "Sao Paulo",
        "uf": "SP"
    },
    "valor_prestacao": 1500,
    "fiscal": {
        "cfop": "6357"
    }
}

JSON completo

{
    "empresa_id": 25,
    "pedido": "OS-0001",
    "tomador": {
        "cpf_cnpj": "33000167000101",
        "nome": "Empresa de Turismo Ltda",
        "ie": "9057800426",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "1",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "servico": {
        "tipo": "transporte_pessoas",
        "descricao": "Fretamento para evento",
        "quantidade": 40
    },
    "origem": {
        "cod_municipio": "3148004",
        "municipio": "Patos de Minas",
        "uf": "MG"
    },
    "destino": {
        "cod_municipio": "3550308",
        "municipio": "Sao Paulo",
        "uf": "SP"
    },
    "valor_prestacao": 1500,
    "fiscal": {
        "cfop": "6357"
    },
    "percurso": [
        "MG",
        "SP"
    ],
    "veiculo": {
        "placa": "ABC1D23",
        "renavam": "01093538977",
        "uf": "MG"
    },
    "fretamento": {
        "tipo": "eventual",
        "data_viagem": "2026-11-10T08:00:00"
    },
    "documentos_referenciados": [
        {
            "numero": "123",
            "serie": "1",
            "data": "2026-10-01",
            "valor": 1500
        }
    ],
    "observacoes": "Viagem de ida e volta"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cteos" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"OS-0001","tomador":{"cpf_cnpj":"33000167000101","nome":"Empresa de Turismo Ltda","ie":"9057800426","endereco":{"logradouro":"Rua A","numero":"1","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"servico":{"tipo":"transporte_pessoas","descricao":"Fretamento para evento","quantidade":40},"origem":{"cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG"},"destino":{"cod_municipio":"3550308","municipio":"Sao Paulo","uf":"SP"},"valor_prestacao":1500,"fiscal":{"cfop":"6357"}}'

Exemplo de response

{
    "success": true,
    "id": "5",
    "status": "AUTORIZADA",
    "chave": "31261...67...(44)",
    "protocolo": "131000000000003",
    "cfop": "6357",
    "tipo_servico": "transporte_pessoas",
    "valor_prestacao": 1500,
    "links": {
        "xml": "/api/v1/cteos/5/xml",
        "dacte": "/api/v1/cteos/5/dacte"
    },
    "request_id": "req_..."
}

Erros possiveis

422 FISCAL_CONFIGURATION_REQUIRED — Falta configuracao fiscal (regra, certificado, emitente...): error.missing e error.motivos.
422 REVISAO_FISCAL_NECESSARIA — A tributacao nao pode ser determinada com seguranca (confidence_score baixo / requires_review).
422 IDEMPOTENCY_KEY_REUSED — Mesmo pedido/Idempotency-Key com conteudo diferente.
402 SALDO_INSUFICIENTE — Saldo de creditos insuficiente.

POST /cteos/preview permissao: cteos:write

Preview do CT-e OS (nao emite, nao cobra)

Calcula ICMS/CFOP/IBS-CBS, valida o XML no leiaute oficial e explica. Nao transmite nem cobra. Query ?explain=true devolve o passo a passo de cada decisao (tributo, base, aliquota, valor, regra, fonte, versao, motivo).

Autenticacao: Bearer API Key

Obrigatorios

(mesmos da emissao)

Opcionais

nenhum

JSON minimo

{
    "empresa_id": 25,
    "pedido": "OS-0001",
    "tomador": {
        "cpf_cnpj": "33000167000101",
        "nome": "Empresa de Turismo Ltda",
        "ie": "9057800426",
        "endereco": {
            "logradouro": "Rua A",
            "numero": "1",
            "bairro": "Centro",
            "cod_municipio": "3148004",
            "municipio": "Patos de Minas",
            "uf": "MG",
            "cep": "38700000"
        }
    },
    "servico": {
        "tipo": "transporte_pessoas",
        "descricao": "Fretamento para evento",
        "quantidade": 40
    },
    "origem": {
        "cod_municipio": "3148004",
        "municipio": "Patos de Minas",
        "uf": "MG"
    },
    "destino": {
        "cod_municipio": "3550308",
        "municipio": "Sao Paulo",
        "uf": "SP"
    },
    "valor_prestacao": 1500,
    "fiscal": {
        "cfop": "6357"
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cteos/preview" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"OS-0001","tomador":{"cpf_cnpj":"33000167000101","nome":"Empresa de Turismo Ltda","ie":"9057800426","endereco":{"logradouro":"Rua A","numero":"1","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"servico":{"tipo":"transporte_pessoas","descricao":"Fretamento para evento","quantidade":40},"origem":{"cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG"},"destino":{"cod_municipio":"3550308","municipio":"Sao Paulo","uf":"SP"},"valor_prestacao":1500,"fiscal":{"cfop":"6357"}}'

Exemplo de response

{
    "success": true,
    "ready_to_issue": true,
    "document": "CTEOS",
    "taxes": {
        "icms": {
            "cst": "00",
            "valor": 180
        }
    },
    "classifications": {
        "cfop": "6357",
        "cst": "00"
    },
    "xml_validado": true,
    "leiaute": "PL_CTe_400",
    "confidence_score": 0.9,
    "requires_review": false,
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Dados invalidos.

GET /cteos permissao: cteos:read

Listar CT-e OS

Query: status, pedido, empresa_id, pagina, por_pagina.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

status
pedido
empresa_id
pagina
por_pagina

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/cteos" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "pagina": 1,
    "por_pagina": 20,
    "itens": [
        {
            "id": "5",
            "status": "AUTORIZADA"
        }
    ],
    "request_id": "req_..."
}

GET /cteos/{id} permissao: cteos:read

Consultar CT-e OS

Status, chave, protocolo, eventos e links. CT-e OS PENDENTE e reconciliado por consulta da chave na SEFAZ.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/cteos/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": "5",
    "status": "AUTORIZADA",
    "chave": "31261...67...(44)",
    "protocolo": "131000000000003",
    "cfop": "6357",
    "tipo_servico": "transporte_pessoas",
    "valor_prestacao": 1500,
    "links": {
        "xml": "/api/v1/cteos/5/xml",
        "dacte": "/api/v1/cteos/5/dacte"
    },
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Documento inexistente ou de outra empresa.

POST /cteos/{id}/cancelar permissao: cteos:write

Cancelar CT-e OS

Evento de cancelamento (110111).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

justificativa (15 a 255)

Opcionais

nenhum

JSON minimo

{
    "justificativa": "Cancelamento por erro de digitacao no valor"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cteos/43/cancelar" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"justificativa":"Cancelamento por erro de digitacao no valor"}'

Exemplo de response

{
    "success": true,
    "status": "CANCELADA",
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_EVENT_REJECTION — Evento rejeitado pela SEFAZ.
409 STATUS_INVALIDO — Somente CT-e OS AUTORIZADO.

POST /cteos/{id}/cce permissao: cteos:write

Carta de Correcao (CC-e)

Evento 110110 com correcoes [{grupo, campo, valor}]. Nao pode alterar valores, tomador, CFOP etc. (regra da SEFAZ). Sequencia controlada pela API.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

correcoes [{grupo, campo, valor, numero_item?}]

Opcionais

nenhum

JSON minimo

{
    "correcoes": [
        {
            "grupo": "compl",
            "campo": "xObs",
            "valor": "Observacao corrigida"
        }
    ]
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/cteos/43/cce" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"correcoes":[{"grupo":"compl","campo":"xObs","valor":"Observacao corrigida"}]}'

Exemplo de response

{
    "success": true,
    "eventos": [
        {
            "tipo": "CCE",
            "sequencia": 1,
            "status": "REGISTRADO"
        }
    ],
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_EVENT_REJECTION — Correcao nao aceita.

GET /cteos/{id}/xml permissao: cteos:read

Baixar XML do CT-e OS

cteOSProc (XML autorizado + protocolo + eventos de cancelamento), referencia principal.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/cteos/43/xml" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

<cteOSProc>...</cteOSProc>

Erros possiveis

409 XML_INDISPONIVEL — Sem XML autorizado.

GET /cteos/{id}/dacte permissao: cteos:read

Baixar DACTE OS (PDF)

DACTE OS gerado a partir do XML autorizado armazenado (sped-da).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/cteos/43/dacte" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

(application/pdf)

Erros possiveis

409 DOCUMENTO_SEM_PROTOCOLO — CT-e OS sem protocolo.

POST /mdfe permissao: mdfe:write

Emitir MDF-e (modelo 58, rodoviario)

Dados simplificados: veiculo (placa cadastrada em /veiculos), condutores (CPF cadastrado em /condutores), percurso e documentos vinculados: CT-es ja emitidos por cte_id (sem redigitar chave/municipio/valor) ou chaves de CT-e/NF-e. O MDF-e nao tem tributacao (o Motor registra o contexto no snapshot). Validado no XSD 3.00 (sped-mdfe). Regras de leiaute aplicadas: um unico documento exige CEP de carga/descarga (infLotacao); tipo_emitente 1/3 exige produto predominante.

Autenticacao: Bearer API Key · Idempotency-Key (opcional): evita emissao duplicada em reenvios.

Obrigatorios

pedido
veiculo
condutores [CPF ou {nome,cpf}]
documentos [{cte_id | chave_cte | chave_nfe (+municipio_descarga)}]
carga.peso_kg

Opcionais

empresa_id | empresa
reboques [placas]
percurso {uf_inicio, uf_fim, ufs_percurso, carregamento{cod_municipio, municipio, cep}, inicio_viagem}
carga {valor, tipo 01-11, produto, ncm}
tipo_emitente (1 prestador, 2 carga propria, 3 CT-e globalizado)
tipo_transportador (1 ETC, 2 TAC, 3 CTC)
seguro
observacoes

JSON minimo

{
    "empresa_id": 25,
    "pedido": "MANIF-0001",
    "veiculo": "ABC1D23",
    "condutores": [
        "11144477735"
    ],
    "percurso": {
        "uf_inicio": "MG",
        "uf_fim": "SP"
    },
    "documentos": [
        {
            "cte_id": 7
        },
        {
            "cte_id": 8
        }
    ],
    "carga": {
        "peso_kg": 36290
    }
}

JSON completo

{
    "empresa_id": 25,
    "pedido": "MANIF-0001",
    "veiculo": "ABC1D23",
    "condutores": [
        "11144477735"
    ],
    "percurso": {
        "uf_inicio": "MG",
        "uf_fim": "SP"
    },
    "documentos": [
        {
            "cte_id": 7
        },
        {
            "cte_id": 8
        }
    ],
    "carga": {
        "peso_kg": 36290
    },
    "reboques": [
        "XYZ2E34"
    ],
    "observacoes": "Viagem MG-SP"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/mdfe" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"MANIF-0001","veiculo":"ABC1D23","condutores":["11144477735"],"percurso":{"uf_inicio":"MG","uf_fim":"SP"},"documentos":[{"cte_id":7},{"cte_id":8}],"carga":{"peso_kg":36290}}'

Exemplo de response

{
    "success": true,
    "id": "3",
    "status": "AUTORIZADA",
    "chave": "31260...58...(44)",
    "protocolo": "131000000000002",
    "qtd_documentos": 2,
    "links": {
        "xml": "/api/v1/mdfe/3/xml",
        "damdfe": "/api/v1/mdfe/3/damdfe"
    },
    "request_id": "req_..."
}

Erros possiveis

422 FISCAL_CONFIGURATION_REQUIRED — Falta configuracao fiscal (regra, certificado, emitente...): error.missing e error.motivos.
422 REVISAO_FISCAL_NECESSARIA — A tributacao nao pode ser determinada com seguranca (confidence_score baixo / requires_review).
422 IDEMPOTENCY_KEY_REUSED — Mesmo pedido/Idempotency-Key com conteudo diferente.
402 SALDO_INSUFICIENTE — Saldo de creditos insuficiente.
422 VALIDATION_ERROR — CT-e ja vinculado a outro MDF-e ativo, condutor/veiculo nao cadastrado, etc.

POST /mdfe/preview permissao: mdfe:write

Preview do MDF-e (nao emite, nao cobra)

Valida veiculo, condutores, CT-es e o XML no leiaute oficial. Nao transmite nem cobra.

Autenticacao: Bearer API Key

Obrigatorios

(mesmos da emissao)

Opcionais

nenhum

JSON minimo

{
    "empresa_id": 25,
    "pedido": "MANIF-0001",
    "veiculo": "ABC1D23",
    "condutores": [
        "11144477735"
    ],
    "percurso": {
        "uf_inicio": "MG",
        "uf_fim": "SP"
    },
    "documentos": [
        {
            "cte_id": 7
        },
        {
            "cte_id": 8
        }
    ],
    "carga": {
        "peso_kg": 36290
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/mdfe/preview" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"MANIF-0001","veiculo":"ABC1D23","condutores":["11144477735"],"percurso":{"uf_inicio":"MG","uf_fim":"SP"},"documentos":[{"cte_id":7},{"cte_id":8}],"carga":{"peso_kg":36290}}'

Exemplo de response

{
    "success": true,
    "ready_to_issue": true,
    "document": "MDFE",
    "qtd_documentos": 2,
    "xml_validado": true,
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — Dados invalidos.

GET /mdfe permissao: mdfe:read

Listar MDF-e

Query: status, pedido, empresa_id, pagina, por_pagina.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

status
pedido
empresa_id
pagina
por_pagina

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/mdfe" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "pagina": 1,
    "por_pagina": 20,
    "itens": [
        {
            "id": "3",
            "status": "AUTORIZADA"
        }
    ],
    "request_id": "req_..."
}

GET /mdfe/{id} permissao: mdfe:read

Consultar MDF-e

Status, chave, protocolo, documentos, condutores, eventos e links.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/mdfe/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": "3",
    "status": "AUTORIZADA",
    "chave": "31260...58...(44)",
    "protocolo": "131000000000002",
    "qtd_documentos": 2,
    "links": {
        "xml": "/api/v1/mdfe/3/xml",
        "damdfe": "/api/v1/mdfe/3/damdfe"
    },
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Documento inexistente ou de outra empresa.

POST /mdfe/{id}/encerrar permissao: mdfe:write

Encerrar MDF-e

Evento de encerramento (110112) com o municipio de encerramento (IBGE, 7 digitos).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

cod_municipio

Opcionais

data (AAAA-MM-DD)

JSON minimo

{
    "cod_municipio": "3550308"
}

JSON completo

{
    "cod_municipio": "3550308",
    "data": "2026-03-11"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/mdfe/43/encerrar" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cod_municipio":"3550308"}'

Exemplo de response

{
    "success": true,
    "status": "ENCERRADA",
    "request_id": "req_..."
}

Erros possiveis

409 STATUS_INVALIDO — Somente MDF-e AUTORIZADO.

POST /mdfe/{id}/cancelar permissao: mdfe:write

Cancelar MDF-e

Evento de cancelamento (110111).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

justificativa (15 a 255)

Opcionais

nenhum

JSON minimo

{
    "justificativa": "Cancelamento do manifesto por engano do emissor"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/mdfe/43/cancelar" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"justificativa":"Cancelamento do manifesto por engano do emissor"}'

Exemplo de response

{
    "success": true,
    "status": "CANCELADA",
    "request_id": "req_..."
}

Erros possiveis

422 SEFAZ_EVENT_REJECTION — Evento rejeitado.

POST /mdfe/{id}/condutor permissao: mdfe:write

Incluir condutor

Evento de inclusao de condutor (110114). O condutor nao pode repetir.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

cpf

Opcionais

nome (quando o CPF nao esta cadastrado)

JSON minimo

{
    "cpf": "52998224725",
    "nome": "Maria Souza"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/mdfe/43/condutor" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cpf":"52998224725","nome":"Maria Souza"}'

Exemplo de response

{
    "success": true,
    "condutores": [
        {
            "nome": "Joao da Silva"
        },
        {
            "nome": "Maria Souza"
        }
    ],
    "request_id": "req_..."
}

Erros possiveis

409 CONDUTOR_JA_INCLUIDO — Condutor ja consta.

GET /mdfe/{id}/xml permissao: mdfe:read

Baixar XML do MDF-e

mdfeProc (XML autorizado + protocolo + eventos), referencia principal.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/mdfe/43/xml" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

<mdfeProc>...</mdfeProc>

Erros possiveis

409 XML_INDISPONIVEL — Sem XML autorizado.

GET /mdfe/{id}/damdfe permissao: mdfe:read

Baixar DAMDFE (PDF)

DAMDFE gerado a partir do XML autorizado armazenado (sped-da).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/mdfe/43/damdfe" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

(application/pdf)

Erros possiveis

409 DOCUMENTO_SEM_PROTOCOLO — MDF-e sem protocolo.

GET /veiculos permissao: mdfe:read

Listar veiculos

Veiculos de tracao e reboques cadastrados.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/veiculos" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "itens": [
        {
            "id": 1,
            "placa": "ABC1D23",
            "tipo": "TRACAO"
        }
    ],
    "request_id": "req_..."
}

POST /veiculos permissao: mdfe:write

Cadastrar veiculo

Placa (AAA0A00/AAA0000), tara e UF de licenciamento. Proprietario de terceiros: proprietario_*.

Autenticacao: Bearer API Key

Obrigatorios

placa
tara (kg)
uf_licenciamento

Opcionais

empresa_id
renavam
cap_kg
cap_m3
tp_rod
tp_car
tipo (TRACAO|REBOQUE)
proprietario_doc
proprietario_nome
proprietario_rntrc
proprietario_ie
proprietario_uf
proprietario_tp_prop

JSON minimo

{
    "empresa_id": 25,
    "placa": "ABC1D23",
    "tara": 8350,
    "uf_licenciamento": "MG"
}

JSON completo

{
    "empresa_id": 25,
    "placa": "ABC1D23",
    "tara": 8350,
    "cap_kg": 15000,
    "tp_rod": "03",
    "tp_car": "02",
    "uf_licenciamento": "MG",
    "tipo": "TRACAO"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/veiculos" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"placa":"ABC1D23","tara":8350,"uf_licenciamento":"MG"}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "placa": "ABC1D23",
    "request_id": "req_..."
}

Erros possiveis

409 REGISTRO_DUPLICADO — Placa ja cadastrada.

GET /veiculos/{id} permissao: mdfe:read

Consultar veiculo

Veiculo da empresa.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/veiculos/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "placa": "ABC1D23",
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Veiculo inexistente.

PUT /veiculos/{id} permissao: mdfe:write

Alterar veiculo

Atualiza campos informados (auditado).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

campos do cadastro

JSON minimo

{
    "cap_kg": 16000
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/veiculos/43" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cap_kg":16000}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Veiculo inexistente.

DELETE /veiculos/{id} permissao: mdfe:write

Desativar veiculo

Desativacao logica (auditada).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X DELETE "https://www.fiscal.versianecode.com.br/api/v1/veiculos/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "ativo": false,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Veiculo inexistente.

GET /condutores permissao: mdfe:read

Listar condutores

Condutores cadastrados.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/condutores" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "itens": [
        {
            "id": 1,
            "nome": "JOAO DA SILVA",
            "cpf": "11144477735"
        }
    ],
    "request_id": "req_..."
}

POST /condutores permissao: mdfe:write

Cadastrar condutor

Nome (ate 60) e CPF valido.

Autenticacao: Bearer API Key

Obrigatorios

nome
cpf

Opcionais

empresa_id

JSON minimo

{
    "empresa_id": 25,
    "nome": "JOAO DA SILVA",
    "cpf": "111.444.777-35"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/condutores" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"nome":"JOAO DA SILVA","cpf":"111.444.777-35"}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "cpf": "11144477735",
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — CPF invalido.

GET /condutores/{id} permissao: mdfe:read

Consultar condutor

Condutor da empresa.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/condutores/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "nome": "JOAO DA SILVA",
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Condutor inexistente.

PUT /condutores/{id} permissao: mdfe:write

Alterar condutor

Atualiza campos informados (auditado).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nome
cpf

JSON minimo

{
    "nome": "JOAO P. DA SILVA"
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/condutores/43" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nome":"JOAO P. DA SILVA"}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Condutor inexistente.

DELETE /condutores/{id} permissao: mdfe:write

Desativar condutor

Desativacao logica (auditada).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X DELETE "https://www.fiscal.versianecode.com.br/api/v1/condutores/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "ativo": false,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Condutor inexistente.

GET /rural/produtor permissao: rural:read

Consultar produtor rural

Dados do produtor (PF por CPF ou PJ por CNPJ), contexto fiscal, propriedades e situacao do certificado.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id (query)

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/rural/produtor" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "empresa_id": 25,
    "tipo": "PF",
    "documento": "11144477735",
    "contexto_fiscal": "PRODUTOR_RURAL",
    "propriedades": 1,
    "certificado": {
        "status": "ok",
        "validade": "2027-01-01"
    },
    "request_id": "req_..."
}

Erros possiveis

403 EMPRESA_NAO_AUTORIZADA — Empresa alheia ou inexistente.

POST /rural/produtor permissao: rural:write

Cadastrar produtor rural PF

Cria a empresa emitente do produtor pessoa fisica (CPF + IE, sem CNPJ), com o contexto PRODUTOR_RURAL. Exige API Key de usuario. O CRT e informado por voce (o motor nao presume o enquadramento). O certificado e-CPF do produtor e enviado em /configuracao-fiscal/certificado. Produtor PJ: cadastre a empresa normalmente e ative o contexto com PUT.

Autenticacao: Bearer API Key

Obrigatorios

cpf
nome
uf
ie
crt
logradouro
numero
bairro
cod_municipio
municipio
cep
fone

Opcionais

nome_fantasia
cnae

JSON minimo

{
    "cpf": "111.444.777-35",
    "nome": "Jose Produtor Rural",
    "uf": "MG",
    "ie": "PR0123456780123",
    "crt": 3,
    "logradouro": "Fazenda Boa Vista",
    "numero": "S/N",
    "bairro": "Zona Rural",
    "cod_municipio": "3148004",
    "municipio": "Patos de Minas",
    "cep": "38700000",
    "fone": "34999998888"
}

JSON completo

{
    "cpf": "111.444.777-35",
    "nome": "Jose Produtor Rural",
    "uf": "MG",
    "ie": "PR0123456780123",
    "crt": 3,
    "logradouro": "Fazenda Boa Vista",
    "numero": "S/N",
    "bairro": "Zona Rural",
    "cod_municipio": "3148004",
    "municipio": "Patos de Minas",
    "cep": "38700000",
    "fone": "34999998888",
    "cnae": "0134200"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/rural/produtor" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cpf":"111.444.777-35","nome":"Jose Produtor Rural","uf":"MG","ie":"PR0123456780123","crt":3,"logradouro":"Fazenda Boa Vista","numero":"S/N","bairro":"Zona Rural","cod_municipio":"3148004","municipio":"Patos de Minas","cep":"38700000","fone":"34999998888"}'

Exemplo de response

{
    "success": true,
    "empresa_id": 25,
    "tipo": "PF",
    "contexto_fiscal": "PRODUTOR_RURAL",
    "request_id": "req_..."
}

Erros possiveis

409 REGISTRO_DUPLICADO — CPF+IE ja cadastrados.
403 USUARIO_OBRIGATORIO — Exige API Key de usuario.

PUT /rural/produtor permissao: rural:write

Ligar/desligar o contexto rural da empresa

Ativa (true) ou desativa (false) o contexto PRODUTOR_RURAL de uma empresa existente. Produtor PF nao pode desativar. Com o contexto ativo, a NF-e existente detecta o contexto pelo cadastro (sem enviar "contexto").

Autenticacao: Bearer API Key

Obrigatorios

ativo (boolean)

Opcionais

empresa_id

JSON minimo

{
    "empresa_id": 25,
    "ativo": true
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/rural/produtor" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"ativo":true}'

Exemplo de response

{
    "success": true,
    "empresa_id": 25,
    "tipo": "PJ",
    "contexto_fiscal": "PRODUTOR_RURAL",
    "request_id": "req_..."
}

Erros possiveis

409 CONTEXTO_OBRIGATORIO — Produtor PF nao desativa o contexto.

POST /nfe permissao: emitir

Emitir NF-e do produtor rural (endpoint NF-e existente)

NAO ha endpoint paralelo: use POST /nfe com "contexto": "PRODUTOR_RURAL" (ou deixe a empresa com o contexto ativo) e "operacao" (venda, transferencia, remessa, retorno, devolucao, industrializacao, armazenagem...). O Motor aplica as regras rurais: CFOP da operacao (base versionada), situacao do ICMS (normal, diferimento, reducao, isencao, suspensao) SOMENTE por regra RURAL_ICMS vigente com fundamento, cBenef por RURAL_BENEFICIO, IBS/CBS por regra vigente. Tributacao incerta (requires_review) bloqueia a emissao. Identificacao do emitente por CPF (PF) ou CNPJ (PJ). A chave do webhook nfe.* traz "context".

Autenticacao: Bearer API Key · Idempotency-Key (opcional): evita emissao duplicada em reenvios.

Obrigatorios

pedido
contexto (PRODUTOR_RURAL) OU empresa com contexto ativo
operacao
cliente
itens
pagamento

Opcionais

propriedade (codigo cadastrado)
itens[].origem_operacao (producao_propria|adquirida; padrao producao_propria com aviso)

JSON minimo

{
    "empresa_id": 25,
    "pedido": "RURAL-0001",
    "contexto": "PRODUTOR_RURAL",
    "operacao": "venda",
    "propriedade": "FAZ01",
    "cliente": "CLIMG",
    "itens": [
        {
            "codigo": "CAFE01",
            "quantidade": 100
        }
    ],
    "pagamento": "pix"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/nfe" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"pedido":"RURAL-0001","contexto":"PRODUTOR_RURAL","operacao":"venda","propriedade":"FAZ01","cliente":"CLIMG","itens":[{"codigo":"CAFE01","quantidade":100}],"pagamento":"pix"}'

Exemplo de response

{
    "success": true,
    "status": "AUTORIZADA",
    "id": "43",
    "chave": "3524...",
    "request_id": "req_..."
}

Erros possiveis

422 FISCAL_CONFIGURATION_REQUIRED — Operacao/propriedade/NCM/regra ausentes ou requires_review (codigos REVISAO_FISCAL_NECESSARIA, OPERACAO_RURAL_NAO_INFORMADA, RURAL_ICMS_SEM_FUNDAMENTO, RURAL_BENEFICIO_INCOMPATIVEL_CRT).

GET /rural/propriedades permissao: rural:read

Listar propriedades rurais

Propriedades do produtor (multiplas).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/rural/propriedades" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "itens": [
        {
            "id": 1,
            "codigo": "FAZ01",
            "nome": "Fazenda Boa Vista"
        }
    ],
    "request_id": "req_..."
}

POST /rural/propriedades permissao: rural:write

Cadastrar propriedade rural

Somente dados fiscais/operacionais necessarios.

Autenticacao: Bearer API Key

Obrigatorios

codigo
nome
uf
cod_municipio
municipio

Opcionais

empresa_id
ie
logradouro
numero
bairro
cep
atividade
cnae
car

JSON minimo

{
    "empresa_id": 25,
    "codigo": "FAZ01",
    "nome": "Fazenda Boa Vista",
    "uf": "MG",
    "cod_municipio": "3148004",
    "municipio": "Patos de Minas"
}

JSON completo

{
    "empresa_id": 25,
    "codigo": "FAZ01",
    "nome": "Fazenda Boa Vista",
    "uf": "MG",
    "cod_municipio": "3148004",
    "municipio": "Patos de Minas",
    "atividade": "Cafeicultura",
    "car": "MG-123"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/rural/propriedades" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"codigo":"FAZ01","nome":"Fazenda Boa Vista","uf":"MG","cod_municipio":"3148004","municipio":"Patos de Minas"}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "codigo": "FAZ01",
    "request_id": "req_..."
}

Erros possiveis

409 REGISTRO_DUPLICADO — Codigo ja existe.

GET /rural/propriedades/{id} permissao: rural:read

Consultar propriedade

Propriedade da empresa.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/rural/propriedades/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "codigo": "FAZ01",
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Propriedade inexistente.

PUT /rural/propriedades/{id} permissao: rural:write

Alterar propriedade

Atualiza campos informados (auditado).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

campos do cadastro

JSON minimo

{
    "atividade": "Cafeicultura"
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/rural/propriedades/43" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"atividade":"Cafeicultura"}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Propriedade inexistente.

DELETE /rural/propriedades/{id} permissao: rural:write

Desativar propriedade

Desativacao logica (auditada).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X DELETE "https://www.fiscal.versianecode.com.br/api/v1/rural/propriedades/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "ativo": false,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Propriedade inexistente.

GET /produtos permissao: consultar

Listar produtos

Produtos fiscais da empresa (qualquer produto agropecuario ou nao).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/produtos" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "itens": [
        {
            "id": 1,
            "codigo": "CAFE01",
            "ncm": "09011110",
            "classificacao_rural": "cafe"
        }
    ],
    "request_id": "req_..."
}

POST /produtos permissao: configurar

Cadastrar produto

NCM (8 digitos), origem, unidade e, para o contexto rural, classificacao_rural (livre: cafe, soja, milho, leite, gado, hortifruti...), usada nos criterios das regras. O motor NAO deduz NCM pela descricao.

Autenticacao: Bearer API Key

Obrigatorios

codigo
descricao
ncm
origem (0-8)
unidade

Opcionais

empresa_id
cest
gtin
preco
categoria
classificacao_rural

JSON minimo

{
    "empresa_id": 25,
    "codigo": "CAFE01",
    "descricao": "Cafe arabica em grao cru",
    "ncm": "09011110",
    "origem": 0,
    "unidade": "SC",
    "classificacao_rural": "cafe",
    "preco": 1200
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/produtos" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"codigo":"CAFE01","descricao":"Cafe arabica em grao cru","ncm":"09011110","origem":0,"unidade":"SC","classificacao_rural":"cafe","preco":1200}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "codigo": "CAFE01",
    "request_id": "req_..."
}

Erros possiveis

409 REGISTRO_DUPLICADO — Codigo ja existe.

GET /produtos/{id} permissao: consultar

Consultar produto

Produto da empresa.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/produtos/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "codigo": "CAFE01",
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Produto inexistente.

PUT /produtos/{id} permissao: configurar

Alterar produto

Atualiza campos informados (auditado).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

campos do cadastro

JSON minimo

{
    "preco": 1300
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/produtos/43" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preco":1300}'

Exemplo de response

{
    "success": true,
    "id": 1,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Produto inexistente.

DELETE /produtos/{id} permissao: configurar

Desativar produto

Desativacao logica (auditada).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X DELETE "https://www.fiscal.versianecode.com.br/api/v1/produtos/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 1,
    "ativo": false,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Produto inexistente.

POST /dfe/sincronizar permissao: dfe:write

Sincronizar documentos recebidos

Busca na SEFAZ (Ambiente Nacional) os documentos emitidos CONTRA o CNPJ da empresa e grava o XML recebido. Incremental: usa o ultimo NSU de cada empresa/ambiente/tipo; chame de novo enquanto status = PARCIAL. Tipos: NFE (resumos, NF-e completas e eventos), CTE e MDFE (documentos em que a empresa e envolvida) ou TODOS. A SEFAZ exige aguardar 1 hora quando nao ha documentos novos (cStat 137) ou ao consumir indevidamente (656): a API respeita isso e responde AGUARDANDO com aguardar_ate. Sem cobranca de creditos. Para receber o XML COMPLETO de uma NF-e que veio como RESUMO, registre a manifestacao (POST /dfe/manifestacoes) e sincronize novamente. NFS-e: distribuicao do Sistema Nacional NAO implementada.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id | empresa
tipo (NFE | CTE | MDFE | TODOS; padrao NFE)
max_lotes (1 a 20; padrao 5; cada lote ate 50 documentos)

JSON minimo

{
    "empresa_id": 25,
    "tipo": "NFE"
}

JSON completo

{
    "empresa_id": 25,
    "tipo": "TODOS",
    "max_lotes": 10
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/dfe/sincronizar" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"tipo":"NFE"}'

Exemplo de response

{
    "success": true,
    "empresa_id": 25,
    "ambiente": "homologacao",
    "resultados": [
        {
            "tipo": "NFE",
            "status": "CONCLUIDO",
            "lotes": 2,
            "novos": 37,
            "ult_nsu": 1520,
            "max_nsu": 1520,
            "cstat": "138",
            "motivo": "Documento(s) localizado(s)",
            "aguardar_ate": null
        }
    ],
    "request_id": "req_..."
}

Erros possiveis

403 MODULO_NAO_HABILITADO — Modulo dfe desabilitado para a empresa.
422 FISCAL_CONFIGURATION_REQUIRED — Certificado digital pendente.
422 VALIDATION_ERROR — tipo invalido (produtor PF consulta apenas NFE).

POST /dfe/baixar-chave permissao: dfe:write

Baixar NF-e pela chave

Consulta de distribuicao por chave de acesso (somente NF-e em que a empresa e interessada). Grava o que a SEFAZ devolver (resumo ou XML completo) sem alterar o cursor de NSU.

Autenticacao: Bearer API Key

Obrigatorios

chave (44 digitos)

Opcionais

empresa_id | empresa

JSON minimo

{
    "empresa_id": 25,
    "chave": "31260960701190000104550010000001231123456789"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/dfe/baixar-chave" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"chave":"31260960701190000104550010000001231123456789"}'

Exemplo de response

{
    "success": true,
    "chave": "31260960701190000104550010000001231123456789",
    "cstat": "138",
    "novos": 1,
    "documentos": [
        {
            "id": 91,
            "nsu": 1498,
            "natureza": "RESUMO",
            "schema_nome": "resNFe_v1.01"
        }
    ],
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — chave invalida.
502 SEFAZ_UNAVAILABLE — SEFAZ indisponivel.

GET /dfe/status permissao: dfe:read

Situacao da sincronizacao

Ultimo NSU, maximo NSU, ultima sincronizacao, ultimo cStat e bloqueio da SEFAZ por tipo, alem do total de documentos recebidos por tipo e natureza.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id | empresa

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/dfe/status" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "empresa_id": 25,
    "ambiente": "homologacao",
    "sincronizacao_automatica": false,
    "cursores": {
        "NFE": {
            "ult_nsu": 1520,
            "max_nsu": 1520,
            "ultima_sync": "2026-10-01 10:00:00",
            "ultimo_cstat": "137",
            "aguardando_sefaz": true,
            "aguardar_ate": "2026-10-01 11:00:00"
        }
    },
    "totais": {
        "NFE": {
            "RESUMO": 20,
            "COMPLETO": 15,
            "EVENTO": 2
        }
    },
    "request_id": "req_..."
}

GET /dfe/documentos permissao: dfe:read

Listar documentos recebidos

Lista os documentos recebidos (metadados; o XML vem em /dfe/documentos/{id}/xml). Para importar incrementalmente no seu sistema, guarde o maior nsu recebido e use nsu_apos (ordem crescente de NSU). natureza: RESUMO (resNFe), COMPLETO (XML completo), EVENTO.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id
tipo (NFE|CTE|MDFE)
natureza (RESUMO|COMPLETO|EVENTO|OUTRO)
chave
emitente (CNPJ/CPF)
tp_evento
nsu_apos
de (YYYY-MM-DD)
ate (YYYY-MM-DD)
pagina
por_pagina (max 100)

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/dfe/documentos" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 37,
    "pagina": 1,
    "por_pagina": 20,
    "itens": [
        {
            "id": 91,
            "tipo": "NFE",
            "nsu": 1498,
            "natureza": "COMPLETO",
            "chave": "3126...(44)",
            "emitente": {
                "documento": "60701190000104",
                "nome": "FORNECEDOR LTDA",
                "ie": "110042490114"
            },
            "valor": 1520.5,
            "data_emissao": "2026-09-28 10:15:00",
            "xml_completo": true,
            "xml": "/api/v1/dfe/documentos/91/xml"
        }
    ],
    "request_id": "req_..."
}

GET /dfe/documentos/{id} permissao: dfe:read

Consultar documento recebido

Metadados de um documento recebido.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/dfe/documentos/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 91,
    "tipo": "NFE",
    "nsu": 1498,
    "natureza": "COMPLETO",
    "chave": "3126...(44)",
    "xml": "/api/v1/dfe/documentos/91/xml",
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Documento inexistente ou de outra empresa.

GET /dfe/documentos/{id}/xml permissao: dfe:read

XML do documento recebido

XML exatamente como recebido da SEFAZ (nfeProc, resNFe, evento...).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/dfe/documentos/43/xml" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

<nfeProc xmlns="http://www.portalfiscal.inf.br/nfe" versao="4.00">...</nfeProc>

Erros possiveis

404 NAO_ENCONTRADO — Documento inexistente ou de outra empresa.

POST /dfe/manifestacoes permissao: dfe:write

Manifestacao do Destinatario (NF-e)

Registra na SEFAZ a manifestacao da empresa destinataria sobre uma NF-e ja recebida: ciencia (210210), confirmacao (210200), desconhecimento (210220) ou nao_realizada (210240, exige justificativa de 15 a 255 caracteres). A ciencia/confirmacao libera o XML completo na proxima sincronizacao. Idempotente por chave + evento.

Autenticacao: Bearer API Key

Obrigatorios

chave
evento (ciencia | confirmacao | desconhecimento | nao_realizada)

Opcionais

empresa_id | empresa
justificativa (obrigatoria em nao_realizada)

JSON minimo

{
    "empresa_id": 25,
    "chave": "31260960701190000104550010000001231123456789",
    "evento": "ciencia"
}

JSON completo

{
    "empresa_id": 25,
    "chave": "31260960701190000104550010000001231123456789",
    "evento": "nao_realizada",
    "justificativa": "Mercadoria nao foi entregue ao destinatario"
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/dfe/manifestacoes" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":25,"chave":"31260960701190000104550010000001231123456789","evento":"ciencia"}'

Exemplo de response

{
    "success": true,
    "id": 5,
    "chave": "31260960701190000104550010000001231123456789",
    "evento": "ciencia",
    "tp_evento": "210210",
    "status": "REGISTRADO",
    "cstat": "135",
    "protocolo": "891260000000001",
    "request_id": "req_..."
}

Erros possiveis

404 DOCUMENTO_NAO_RECEBIDO — NF-e ainda nao consta nos documentos recebidos.
422 VALIDATION_ERROR — chave/evento/justificativa invalidos ou evento rejeitado pela SEFAZ.

GET /dfe/manifestacoes permissao: dfe:read

Listar manifestacoes

Ultimas 100 manifestacoes registradas.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id
chave

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/dfe/manifestacoes" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "itens": [
        {
            "id": 5,
            "chave": "3126...(44)",
            "evento": "ciencia",
            "status": "REGISTRADO",
            "cstat": "135"
        }
    ],
    "request_id": "req_..."
}

GET /sefaz/status permissao: consultar

Status dos servicos fiscais

Status em tempo real de todos os documentos para a UF e o ambiente da empresa: NF-e (55), NFC-e (65), CT-e (57), CT-e OS (67) e MDF-e (58) pela consulta oficial de status de servico da SEFAZ (cStat 107 = em operacao) e NFS-e Nacional por sonda de conectividade (o Sistema Nacional nao publica status oficial). Cache de 20 s por servico. situacao: online, instavel, offline, erro, desabilitado (modulo nao habilitado na empresa).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id | empresa

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/sefaz/status" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "empresa_id": 25,
    "uf": "MG",
    "ambiente": "homologacao",
    "situacao_geral": "online",
    "consultado_em": "2026-10-01T10:00:00-03:00",
    "servicos": {
        "nfe": {
            "modelo": "55",
            "situacao": "online",
            "rotulo": "Em operação",
            "cstat": "107",
            "tempo_ms": 310
        },
        "nfce": {
            "modelo": "65",
            "situacao": "online",
            "rotulo": "Em operação",
            "cstat": "107",
            "tempo_ms": 290
        },
        "cte": {
            "modelo": "57",
            "situacao": "online",
            "rotulo": "Em operação",
            "cstat": "107",
            "tempo_ms": 420
        },
        "cteos": {
            "modelo": "67",
            "situacao": "online",
            "rotulo": "Em operação",
            "cstat": "107",
            "tempo_ms": 410
        },
        "mdfe": {
            "modelo": "58",
            "situacao": "instavel",
            "rotulo": "Paralisado momentaneamente",
            "cstat": "108"
        },
        "nfse": {
            "modelo": "nfse",
            "situacao": "online",
            "rotulo": "Sistema Nacional acessível",
            "tempo_ms": 180
        }
    },
    "request_id": "req_..."
}

Erros possiveis

422 FISCAL_CONFIGURATION_REQUIRED — Certificado digital pendente (a consulta usa o certificado da empresa).

POST /fiscal/solicitacoes permissao: consultar

Solicitar emissao assincrona

Recebe a solicitacao de emissao (NF-e, NFC-e, NFS-e, CT-e, CT-e OS ou MDF-e), valida permissao do documento (emitir | nfse:write | cte:write | cteos:write | mdfe:write), empresa, modulo e SALDO de creditos, registra uma tarefa PERSISTENTE (MySQL) e devolve o solicitacao_id. Receber/enfileirar NAO significa transmitir nem autorizar: o worker transmite quando possivel e repete automaticamente em falhas temporarias (intervalo progressivo com variacao aleatoria), CONSULTA a situacao antes de qualquer reenvio (nunca retransmite as cegas), e so marca AUTORIZADA/REJEITADA com o resultado oficial. Idempotente por empresa + documento + pedido: reenviar o mesmo pedido devolve a mesma solicitacao (200 + Idempotent-Replay); conteudo diferente = 422 IDEMPOTENCY_KEY_REUSED. Equivalente: POST /nfe|/nfce|/nfse|/cte|/mdfe com o header Prefer: respond-async, ?async=true ou "async": true. Status: RECEBIDA, AGUARDANDO_TRANSMISSAO, TRANSMITINDO, AGUARDANDO_RETORNO, AUTORIZADA, REJEITADA, FALHA_TEMPORARIA, ACAO_NECESSARIA, CANCELADA (tarefa).

Autenticacao: Bearer API Key

Obrigatorios

documento (NFE | NFCE | NFSE | CTE | CTEOS | MDFE)
dados {} (o mesmo JSON da emissao, com pedido)

Opcionais

empresa_id | empresa (tambem aceito dentro de dados)
Idempotency-Key (header)

JSON minimo

{
    "documento": "NFSE",
    "dados": {
        "empresa_id": 25,
        "pedido": "SERV-0001",
        "tomador": {
            "cpf_cnpj": "12345678909",
            "nome": "Joao da Silva",
            "endereco": {
                "logradouro": "Rua A",
                "numero": "10",
                "bairro": "Centro",
                "cod_municipio": "3148004",
                "municipio": "Patos de Minas",
                "uf": "MG",
                "cep": "38700000"
            }
        },
        "servico": {
            "codigo": "CONS01",
            "valor": 1500
        }
    }
}

JSON completo

{
    "documento": "NFE",
    "dados": {
        "empresa_id": 25,
        "pedido": "PED-12345",
        "cliente": "CLI001",
        "itens": [
            {
                "codigo": "PROD001",
                "quantidade": 2
            }
        ],
        "pagamento": "pix"
    }
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/fiscal/solicitacoes" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"documento":"NFSE","dados":{"empresa_id":25,"pedido":"SERV-0001","tomador":{"cpf_cnpj":"12345678909","nome":"Joao da Silva","endereco":{"logradouro":"Rua A","numero":"10","bairro":"Centro","cod_municipio":"3148004","municipio":"Patos de Minas","uf":"MG","cep":"38700000"}},"servico":{"codigo":"CONS01","valor":1500}}}'

Exemplo de response

{
    "success": true,
    "solicitacao_id": "sol_9f2c41aa07be13d5c8e1",
    "status": "AGUARDANDO_TRANSMISSAO",
    "mensagem": "Solicitacao recebida e aguardando processamento. Receber nao significa transmitir nem autorizar: acompanhe o resultado.",
    "consulta_url": "/api/v1/fiscal/solicitacoes/sol_9f2c41aa07be13d5c8e1",
    "request_id": "req_..."
}

Erros possiveis

402 SALDO_INSUFICIENTE — Saldo insuficiente (validado na aceitacao; o debito ocorre uma unica vez na emissao).
403 FORBIDDEN — A credencial nao tem a permissao do documento.
403 MODULO_NAO_HABILITADO — Modulo desabilitado na empresa.
422 IDEMPOTENCY_KEY_REUSED — Pedido ja usado com conteudo diferente (use /reprocessar com "dados").
422 VALIDATION_ERROR — documento/dados/pedido invalidos.

GET /fiscal/solicitacoes permissao: consultar

Listar solicitacoes

Solicitacoes das empresas da credencial (isolamento multiempresa; chave de teste enxerga somente homologacao).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

status
documento (NFE|NFCE|NFSE|CTE|CTEOS|MDFE)
empresa_id
pedido
ambiente (homologacao|producao)
origem (API_ASSINCRONA|SINCRONA)
de (YYYY-MM-DD)
ate (YYYY-MM-DD)
travadas=1
pagina
por_pagina (max 100)

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/fiscal/solicitacoes" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "total": 1,
    "pagina": 1,
    "por_pagina": 20,
    "itens": [
        {
            "solicitacao_id": "sol_9f2c41aa07be13d5c8e1",
            "documento": "NFSE",
            "pedido": "SERV-0001",
            "empresa_id": 25,
            "ambiente": "homologacao",
            "status": "AGUARDANDO_RETORNO",
            "tentativas": 1,
            "proxima_tentativa": "2026-10-01 11:03:00"
        }
    ],
    "request_id": "req_..."
}

GET /fiscal/solicitacoes/{id} permissao: consultar

Consultar solicitacao

Situacao, historico de processamento (data, tentativa, mensagem e ator de cada transicao), proxima tentativa, resultado fiscal (documento_id, chave, protocolo, cStat) e links de XML/PDF quando autorizada. resultado_oficial_confirmado = true somente em AUTORIZADA ou REJEITADA. Solicitacao de outra empresa responde 404.

Autenticacao: Bearer API Key

Parametros de URL: {id} solicitacao_id (sol_ + 20 hex)

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/fiscal/solicitacoes/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "solicitacao_id": "sol_9f2c41aa07be13d5c8e1",
    "documento": "NFSE",
    "pedido": "SERV-0001",
    "status": "AUTORIZADA",
    "descricao_status": "Documento autorizado (resultado oficial confirmado).",
    "resultado_oficial_confirmado": true,
    "tentativas": 2,
    "consultas": 1,
    "documento_id": 12,
    "chave": "3148004...",
    "protocolo": "131260000000001",
    "links": {
        "xml": "/api/v1/nfse/12/xml",
        "danfse": "/api/v1/nfse/12/danfse"
    },
    "historico": [
        {
            "de": null,
            "para": "RECEBIDA",
            "tentativa": 0,
            "mensagem": "Solicitacao recebida pela API.",
            "ator": "api",
            "em": "2026-10-01 10:00:00"
        },
        {
            "de": "AGUARDANDO_RETORNO",
            "para": "AUTORIZADA",
            "tentativa": 2,
            "mensagem": "Documento autorizado (protocolo 131260000000001).",
            "ator": "worker:srv1:4120",
            "em": "2026-10-01 10:04:11"
        }
    ],
    "request_id": "req_..."
}

Erros possiveis

404 SOLICITACAO_NAO_ENCONTRADA — Inexistente ou de outra empresa.

DELETE /fiscal/solicitacoes/{id} permissao: consultar

Cancelar a TAREFA (antes da transmissao)

Remove somente uma tarefa AINDA NAO TRANSMITIDA (nao e cancelamento fiscal). Exige a permissao do documento. Se o documento ja foi transmitido ou esta autorizado, responde 409 e orienta o cancelamento fiscal oficial (POST /{documento}/{id}/cancelamento | cancelar).

Autenticacao: Bearer API Key

Parametros de URL: {id} solicitacao_id (sol_ + 20 hex)

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X DELETE "https://www.fiscal.versianecode.com.br/api/v1/fiscal/solicitacoes/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "aviso": "Foi cancelada a TAREFA ainda nao transmitida. Isto nao e o cancelamento fiscal de um documento.",
    "solicitacao_id": "sol_9f2c41aa07be13d5c8e1",
    "status": "CANCELADA",
    "request_id": "req_..."
}

Erros possiveis

409 DOCUMENTO_JA_TRANSMITIDO — Documento transmitido/autorizado: use o cancelamento fiscal oficial.
409 SOLICITACAO_CONCLUIDA — Solicitacao ja concluida.
409 SOLICITACAO_EM_TRANSMISSAO — Em transmissao agora.

POST /fiscal/solicitacoes/{id}/reprocessar permissao: consultar

Reprocessar (acao necessaria / rejeitada)

Devolve a solicitacao a fila quando estiver em ACAO_NECESSARIA (ex.: apos adicionar creditos ou corrigir a configuracao) ou REJEITADA (exige "dados" corrigidos). Com "dados", o pedido deve continuar o mesmo. NUNCA ignora a idempotencia nem as regras fiscais: passa pelo mesmo emitir() e pela consulta de situacao. Documento autorizado ou cancelado nao e reprocessavel. Auditado.

Autenticacao: Bearer API Key

Parametros de URL: {id} solicitacao_id (sol_ + 20 hex)

Obrigatorios

nenhum

Opcionais

dados {} (JSON da emissao corrigido; obrigatorio para REJEITADA)

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/fiscal/solicitacoes/43/reprocessar" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "solicitacao_id": "sol_9f2c41aa07be13d5c8e1",
    "status": "AGUARDANDO_TRANSMISSAO",
    "tentativas": 0,
    "request_id": "req_..."
}

Erros possiveis

409 TRANSICAO_INVALIDA — Estado atual nao permite reprocessar.
409 DOCUMENTO_JA_AUTORIZADO — Nada a reprocessar.
422 VALIDATION_ERROR — REJEITADA exige dados corrigidos; pedido diferente.

GET /fiscal/notificacoes/preferencias permissao: consultar

Preferencias de notificacao

Preferencias de e-mail/painel do usuario dono da API Key (geral ou por empresa com ?empresa_id). Chaves sem usuario da plataforma respondem 403.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/fiscal/notificacoes/preferencias" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "empresa_id": 0,
    "preferencias": {
        "email_destino": null,
        "email_ativo": 1,
        "painel_ativo": 1,
        "ev_autorizada": 1,
        "ev_rejeitada": 1,
        "ev_acao": 1,
        "ev_falha": 1,
        "pendente_minutos": null
    },
    "request_id": "req_..."
}

Erros possiveis

403 USUARIO_NAO_IDENTIFICADO — Use uma API Key criada no painel.

PUT /fiscal/notificacoes/preferencias permissao: configurar

Salvar preferencias de notificacao

Define o e-mail de destino, eventos que geram aviso (autorizada, rejeitada, acao necessaria, falha) e o aviso opcional de pendencia (pendente_minutos, 5 a 10080; envia UM e-mail). empresa_id restringe a uma empresa do usuario e prevalece sobre a preferencia geral.

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

empresa_id
email_destino
email_ativo
painel_ativo
ev_autorizada
ev_rejeitada
ev_acao
ev_falha
pendente_minutos

JSON minimo

{
    "email_destino": "financeiro@empresa.com",
    "pendente_minutos": 30
}

JSON completo

{
    "empresa_id": 25,
    "email_destino": "fiscal@empresa.com",
    "email_ativo": true,
    "painel_ativo": true,
    "ev_autorizada": true,
    "ev_rejeitada": true,
    "ev_acao": true,
    "ev_falha": true,
    "pendente_minutos": 30
}

Exemplo de request

curl -X PUT "https://www.fiscal.versianecode.com.br/api/v1/fiscal/notificacoes/preferencias" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_destino":"financeiro@empresa.com","pendente_minutos":30}'

Exemplo de response

{
    "success": true,
    "empresa_id": 25,
    "preferencias": {
        "email_destino": "fiscal@empresa.com",
        "email_ativo": 1,
        "pendente_minutos": 30
    },
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — E-mail invalido, minutos fora do limite ou empresa nao autorizada.

POST /webhooks permissao: configurar

Cadastrar webhook

Recebe eventos nfe.*, nfce.*, nfse.*, cte.*, mdfe.* (authorized, rejected, cancelled, processing, closed) dfe.documentos_recebidos (novos documentos da Distribuicao DF-e) e fiscal.document.queued | pending | authorized | rejected | action_required | cancelled (solicitacoes assincronas; payload com solicitacao_id, documento, status, empresa_id, pedido e dados do resultado; deduplicados e com historico de entregas). URL https obrigatoria (http so para localhost em desenvolvimento), sem enderecos privados. O segredo HMAC e exibido UMA vez. Cada entrega envia X-Webhook-Event, X-Webhook-Id, X-Webhook-Timestamp e X-Webhook-Signature = "sha256=" + HMAC-SHA256(segredo, timestamp + "." + corpo). Rejeite timestamps antigos (protecao contra replay) e trate eventos repetidos pelo id. Retentativas com backoff (1m, 5m, 15m, 1h, 6h).

Autenticacao: Bearer API Key

Obrigatorios

url

Opcionais

eventos (lista ou ["*"])
empresa_id (restringe a uma empresa)

JSON minimo

{
    "url": "https://seu-sistema.com/webhooks/fiscal",
    "eventos": [
        "nfse.authorized",
        "cte.authorized",
        "cteos.authorized",
        "mdfe.closed"
    ]
}

JSON completo

{
    "url": "https://seu-sistema.com/webhooks/fiscal",
    "eventos": [
        "nfe.authorized",
        "nfe.rejected",
        "nfse.authorized",
        "nfse.rejected",
        "cte.authorized",
        "mdfe.authorized"
    ],
    "empresa_id": 25
}

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://seu-sistema.com/webhooks/fiscal","eventos":["nfse.authorized","cte.authorized","cteos.authorized","mdfe.closed"]}'

Exemplo de response

{
    "success": true,
    "id": 4,
    "url": "https://seu-sistema.com/webhooks/fiscal",
    "eventos": [
        "nfse.authorized"
    ],
    "ativo": true,
    "segredo": "whsec_...(exibido uma vez)",
    "request_id": "req_..."
}

Erros possiveis

422 VALIDATION_ERROR — URL/evento invalidos.

GET /webhooks permissao: consultar

Listar webhooks

Webhooks da sua credencial (sem o segredo).

Autenticacao: Bearer API Key

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "itens": [
        {
            "id": 4,
            "url": "https://...",
            "eventos": [
                "nfse.authorized"
            ],
            "ativo": true,
            "falhas_seguidas": 0
        }
    ],
    "request_id": "req_..."
}

GET /webhooks/{id} permissao: consultar

Consultar webhook

Webhook da sua credencial.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/webhooks/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 4,
    "url": "https://...",
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Webhook inexistente ou de outra credencial.

DELETE /webhooks/{id} permissao: configurar

Desativar webhook

Desativacao logica (auditada).

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X DELETE "https://www.fiscal.versianecode.com.br/api/v1/webhooks/43" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "id": 4,
    "ativo": false,
    "request_id": "req_..."
}

Erros possiveis

404 NAO_ENCONTRADO — Webhook inexistente.

GET /webhooks/{id}/entregas permissao: consultar

Historico de entregas

Ultimas 100 entregas: evento, status (PENDENTE, ENTREGUE, FALHA, ESGOTADO), tentativas, HTTP status e proxima tentativa.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X GET "https://www.fiscal.versianecode.com.br/api/v1/webhooks/43/entregas" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "itens": [
        {
            "evento": "nfse.authorized",
            "status": "ENTREGUE",
            "tentativas": 1,
            "http_status": 200
        }
    ],
    "request_id": "req_..."
}

POST /webhooks/{id}/testar permissao: configurar

Enviar evento de teste

Envia o evento webhook.test assinado para a URL e devolve o resultado da entrega.

Autenticacao: Bearer API Key

Parametros de URL: {id} Identificador devolvido na emissao

Obrigatorios

nenhum

Opcionais

nenhum

Exemplo de request

curl -X POST "https://www.fiscal.versianecode.com.br/api/v1/webhooks/43/testar" \
  -H "Authorization: Bearer SUA_API_KEY"

Exemplo de response

{
    "success": true,
    "status": "ENTREGUE",
    "http_status": 200,
    "duracao_ms": 120,
    "request_id": "req_..."
}

Erros possiveis

502 FALHA — Receptor nao respondeu 2xx.

Erros comuns a todos os endpoints

HTTP	code	Descricao
401	`UNAUTHORIZED`	Chave ausente, mal formada ou invalida.
401	`API_KEY_REVOKED`	A chave foi revogada.
403	`API_KEY_BLOCKED`	A chave esta bloqueada.
403	`USER_INACTIVE`	Usuario inativo ou bloqueado.
403	`FORBIDDEN`	A chave nao possui a permissao necessaria.
403	`EMPRESA_NAO_AUTORIZADA`	Empresa inexistente ou nao vinculada a sua conta.
400	`JSON_INVALIDO`	Corpo da requisicao nao e um JSON valido.
413	`PAYLOAD_TOO_LARGE`	Corpo acima do limite permitido.
422	`VALIDATION_ERROR`	Dados invalidos (lista em error.errors).
422	`FISCAL_CONFIGURATION_REQUIRED`	Falta configuracao fiscal: pendencias em error.missing/details e codigos estaveis em error.motivos (ex.: CERTIFICADO_VENCIDO, NATUREZA_NAO_CONFIGURADA, REGRA_TRIBUTARIA_NAO_ENCONTRADA).
422	`CONFIG_FISCAL_INCOMPLETA`	GET /configuracao-fiscal/validar: configuracao incompleta (pendencias em error.details).
404	`NAO_ENCONTRADO`	Registro inexistente ou pertencente a outra empresa (mesma resposta, nao revela existencia).
404	`ROTA_NAO_ENCONTRADA`	Rota inexistente.
405	`METODO_NAO_PERMITIDO`	Metodo HTTP nao permitido para o recurso.
409	`REGISTRO_DUPLICADO`	Ja existe registro com o mesmo codigo na empresa.
409	`LIMITE_EMPRESAS`	Limite de empresas por usuario atingido.
422	`CNPJ_INVALIDO`	CNPJ com digitos verificadores invalidos.
422	`CERTIFICADO_INVALIDO`	Arquivo do certificado invalido ou senha incorreta.
422	`CERTIFICADO_VENCIDO`	Certificado digital vencido.
422	`CERTIFICADO_DIVERGENTE`	Certificado pertence a outro CNPJ (raiz diferente da empresa).
502	`CNPJ_CONSULTA_INDISPONIVEL`	Servico de consulta de CNPJ indisponivel: preencha manualmente.
402	`SALDO_INSUFICIENTE`	Saldo de creditos insuficiente para a emissao (usuarios sem creditos ilimitados). Adicione creditos no painel (Financeiro) e tente novamente. Emissoes nao autorizadas pela SEFAZ sao estornadas automaticamente.
403	`CARTEIRA_INDISPONIVEL`	GET /financeiro/*: a credencial nao esta associada a uma carteira de creditos.
422	`REVISAO_FISCAL_NECESSARIA`	A tributacao nao pode ser determinada com seguranca (confidence_score baixo / requires_review=true): a emissao automatica e bloqueada. Use /fiscal/validate para ver o que falta.
422	`IDEMPOTENCY_KEY_REUSED`	Mesmo pedido/Idempotency-Key reenviado com conteudo diferente.
409	`REQUEST_IN_PROGRESS`	Requisicao identica ainda em processamento: aguarde e consulte o documento.
422	`OVERRIDE_NAO_PERMITIDO`	Override fiscal exige a permissao override.
422	`OVERRIDE_SEM_MOTIVO`	Override fiscal exige override_motivo (minimo 10 caracteres).
403	`MODULO_NAO_HABILITADO`	Modulo (nfse, cte, cteos, mdfe, rural) nao habilitado para a empresa.
422	`SEFAZ_EVENT_REJECTION`	Evento (cancelamento, CC-e, encerramento...) rejeitado pela SEFAZ.
422	`NFSE_REJECTION`	DPS rejeitada pelo Sistema Nacional da NFS-e (codigos em error.erros).
501	`NFF_NAO_DISPONIVEL`	Nota Fiscal Facil: arquitetura preparada, integracao oficial ainda nao implementada.
429	`RATE_LIMITED`	Limite de requisicoes por minuto excedido. Veja o header Retry-After.
500	`INTERNAL_ERROR`	Erro interno. Informe o request_id ao suporte.

Autenticacao

Formato das respostas

Rate limit e ambientes

API Keys e escopos

Multiempresa

Motor Tributario Central

Idempotencia

Preview e dry-run

Webhooks

Fila assincrona, retentativas e consulta antes de reenviar

Notificacoes por e-mail

NF-e

Emitir NF-e (modelo 55)

NFC-e

Emitir NFC-e (modelo 65)

Fiscal

Pre-visualizar calculo (nao emite)

Consulta

Consultar NF-e / NFC-e

Historico de eventos

Baixar XML

Baixar DANFE / DANFCE (PDF)

Eventos

Cancelar documento

Carta de correcao (CC-e)

Inutilizar numeracao

Configuracao Fiscal

Visao geral da configuracao fiscal

Validar se a empresa esta pronta para emitir

Consultar dados do CNPJ

Gerar configuracao fiscal automatica

Consultar o emitente

Criar o emitente (empresa da conta)

Atualizar / confirmar o emitente

Situacao do certificado digital

Enviar certificado digital A1 (.pfx/.p12)

Historico de alteracoes da configuracao

Naturezas de Operacao

Listar naturezas de operacao

Criar natureza de operacao

Consultar natureza (PUT atualiza, DELETE desativa)

Regras de Tributacao

Listar regras de tributacao

Criar regra de tributacao

Consultar regra (PUT atualiza, DELETE desativa)

Regras IVA (IBS/CBS)

Listar regras IVA (IBS/CBS)

Criar regra IVA (IBS/CBS)

Consultar regra IVA (PUT atualiza, DELETE desativa)

Financeiro (creditos)

Situacao financeira

Saldo

Extrato

Fiscal Engine

Calcular (Motor Tributario, sem emitir)

Validar (dry-run)

Listar regras da base tributaria versionada

Cadastrar regra da base tributaria

Consultar regra

Alterar regra da empresa

Desativar regra da empresa

NFS-e

Emitir NFS-e Nacional

Preview da NFS-e (nao emite, nao cobra)

Listar NFS-e

Consultar NFS-e

Cancelar NFS-e

Baixar XML da NFS-e

Baixar DANFSe (PDF)

Listar servicos cadastrados

Cadastrar servico

Consultar servico

Alterar servico

Desativar servico

CT-e

Emitir CT-e (modelo 57, rodoviario)

Preview do CT-e (nao emite, nao cobra)

Listar CT-e

Consultar CT-e

Cancelar CT-e