Documentação da API

Emita NF-e, NFC-e e NFS-e (Padrão Nacional), faça a manifestação de DF-e e baixe PDFs e XMLs — tudo via API REST. Multiempresa, com isolamento por chave.

Introdução

A API do SpeedNF é REST e usa JSON. Toda requisição precisa do cabeçalho X-Api-Key. As respostas seguem um formato único de sucesso/erro.

Item	Valor
Base URL	`https://www.speednf.rcssoftware.com.br/api/v1`
Formato	JSON (exceto downloads de PDF/XML/ZIP)
Autenticação	Header `X-Api-Key`
Documentos	NF-e (55), NFC-e (65), NFS-e Nacional, DF-e

Autenticação

Envie sua chave em todas as requisições:

curl https://www.speednf.rcssoftware.com.br/api/v1/emitentes \
  -H "X-Api-Key: sua_chave_aqui"

Dois tipos de chave

Tipo	Alcance
Chave-mestra (integrador)	Enxerga todos os emitentes. Pode cadastrar empresas e gerar chaves de empresa.
Chave-de-empresa	Acesso somente aos dados de um emitente. Ideal para o lojista ou contador.

Com a chave-de-empresa, todas as consultas e emissões ficam automaticamente restritas àquela empresa — não é possível acessar dados de outra.

Chaves & Token

Consultar a chave atual

GET /token

{
  "sucesso": true,
  "dados": {
    "nome": "Integração externa",
    "ativo": true,
    "rate_limit": 60,
    "prefixo_chave": "sn_3wUW..."
  }
}

Gerar nova chave (rotação)

POST /token/rotacionar

Invalida a chave atual imediatamente e retorna a nova. É exibida uma única vez.

Após rotacionar, atualize a chave em todos os sistemas antes da próxima requisição.

Cadastro completo do emitente

O emitente é a empresa que emite as notas. Fluxo recomendado: 1) cadastrar → 2) enviar o certificado A1 → 3) enviar a logo → 4) testar a SEFAZ → 5) emitir.

1. Criar o emitente

POST /emitentes

curl -X POST https://www.speednf.rcssoftware.com.br/api/v1/emitentes \
  -H "X-Api-Key: sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "razao_social": "KALU SPORTS LTDA",
    "nome_fantasia": "Kalu Sports",
    "cnpj": "61810791000100",
    "ie": "233461254",
    "inscricao_municipal": "0102853800195",
    "crt": 1,
    "mei": false,

    "logradouro": "Rua Hilton Rodrigues",
    "numero": "167",
    "bairro": "Pituba",
    "codigo_municipio": "2927408",
    "municipio": "Salvador",
    "uf": "BA",
    "cep": "41830630",
    "telefone": "7133334444",

    "ambiente_nfe": 2,
    "ambiente_nfse": 2,
    "serie_nfe": 1,
    "serie_nfce": 1,
    "serie_nfse": 1
  }'

Campo	Descrição
`cnpj`	14 posições. Aceita CNPJ alfanumérico.
`crt`	`1` Simples Nacional · `2` Simples (excesso) · `3` Regime Normal.
`mei`	`true` se é MEI (muda a tributação da NFS-e).
`codigo_municipio`	Código IBGE, 7 dígitos.
`ambiente_nfe` / `ambiente_nfse`	`1` produção · `2` homologação. Por empresa.
`serie_*`	Série de cada modelo (NF-e, NFC-e, NFS-e).

Listar / detalhar / atualizar

GET /emitentes

GET /emitentes/{id}

PUT /emitentes/{id}

Testar a conexão com a SEFAZ

GET /emitentes/{id}/sefaz/status

Faz um "ping" na SEFAZ do estado (requer certificado). Use antes de emitir.

Certificado Digital A1

Obrigatório para emitir. Envie o arquivo .pfx/.p12 e a senha. A senha é criptografada e o arquivo fica fora da área pública — nunca é retornado pela API.

POST /emitentes/{id}/certificado multipart/form-data

curl -X POST https://www.speednf.rcssoftware.com.br/api/v1/emitentes/1/certificado \
  -H "X-Api-Key: sua_chave" \
  -F "certificado=@/caminho/certificado.pfx" \
  -F "senha=senhaDoCertificado"

{
  "sucesso": true,
  "mensagem": "Certificado validado e armazenado com seguranca.",
  "dados": { "cn": "KALU SPORTS LTDA:61810791000100", "validade": "31/12/2026" }
}

Apenas certificado A1 (arquivo). O A3 (token/cartão) não funciona em servidor.

Logomarca

Logo que aparece no topo da DANFE e da DANFCE. PNG ou JPG, até 2 MB.

POST /emitentes/{id}/logo multipart/form-data

curl -X POST https://www.speednf.rcssoftware.com.br/api/v1/emitentes/1/logo \
  -H "X-Api-Key: sua_chave" \
  -F "logo=@/caminho/logo.png"

Chave de API por empresa

Gere uma chave exclusiva de um emitente — dá acesso somente aos dados dele. Só a chave-mestra pode gerar/revogar. Útil para entregar ao lojista ou contador sem expor as outras empresas.

POST /emitentes/{id}/chave

DELETE /emitentes/{id}/chave

{
  "sucesso": true,
  "mensagem": "Chave da empresa gerada.",
  "dados": {
    "emitente_id": 1,
    "razao_social": "KALU SPORTS LTDA",
    "api_key": "emp_ChaveExclusivaDaEmpresa..."
  }
}

NF-e (55) e NFC-e (65)

POST /notas

NF-e — exemplo

curl -X POST https://www.speednf.rcssoftware.com.br/api/v1/notas \
  -H "X-Api-Key: sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "emitente_id": 1,
    "modelo": 55,
    "natureza_operacao": "VENDA",
    "destinatario": {
      "cnpj": "12345678000199",
      "nome": "CLIENTE EXEMPLO LTDA",
      "ie": "1234567",
      "endereco": {
        "logradouro": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista",
        "codigo_municipio": "3550308", "municipio": "São Paulo", "uf": "SP", "cep": "01310100"
      }
    },
    "itens": [{
      "codigo": "P001", "descricao": "PRODUTO EXEMPLO", "ncm": "61091000",
      "cfop": "5102", "unidade": "UN", "quantidade": 2,
      "valor_unitario": 50.00, "valor_total": 100.00, "origem": 0, "csosn": "102"
    }],
    "pagamentos": [{ "forma": "01", "valor": 100.00 }]
  }'

NFC-e (65)

Mesma estrutura com "modelo": 65. Requer CSC e CSC ID no emitente (obtidos na SEFAZ estadual). O destinatário é opcional.

A NFC-e usa o mesmo leiaute da NF-e — todos os grupos abaixo, inclusive IBS/CBS da Reforma, funcionam de forma idêntica no modelo 65. O QR Code (infNFeSupl) é gerado automaticamente a partir do CSC.

Tributação (ICMS, PIS, COFINS, IPI, FCP, DIFAL, ST)

Modelo híbrido: envie o valor já calculado (a API repassa fielmente) ou apenas base + aliquota (a API calcula). A escolha é por imposto. Recomendamos o bloco tributos por item:

"itens": [{
  "codigo": "P1", "descricao": "PRODUTO", "ncm": "22021000",
  "cfop": "5405", "quantidade": 1, "valor_unitario": 100, "valor_total": 100,
  "cest": "0300100",          // produtos sujeitos a ST
  "cbenef": "BA830001",       // benefício fiscal estadual (opcional)

  "tributos": {
    "icms": {
      "origem": 0, "cst": "10",
      "base": 100, "aliquota": 18, "valor": 18,
      "fcp": { "aliquota": 2 },
      "st": {
        "mva": 40, "aliquota": 18,
        "fcp": { "aliquota": 2 }
      }
    },
    "difal": {                 // venda interestadual a consumidor final
      "base": 100, "aliquota_interna": 18, "aliquota_interestadual": 12,
      "valor_uf_destino": 6, "valor_uf_origem": 0
    },
    "pis":    { "cst": "01", "aliquota": 1.65 },
    "cofins": { "cst": "01", "aliquota": 7.6 },
    "ipi":    { "cst": "50", "aliquota": 5, "enquadramento": "999" }
  }
}]

Grupo	Campos
`icms`	`origem`, `cst`/`csosn`, `base`, `aliquota`, `valor`. Redução: `reducao_base`. Diferimento: `diferimento`.
`icms.fcp`	Fundo de Combate à Pobreza: `base`, `aliquota`, `valor`.
`icms.st`	Substituição tributária: `mva` (ou `base`), `aliquota`, `valor`, e `fcp` da ST.
`icms.st_retido`	ST cobrado antes (CST 60 / CSOSN 500): `base`, `aliquota`, `valor`.
`difal`	EC 87/2015: `aliquota_interna`, `aliquota_interestadual`, `valor_uf_destino`, `valor_uf_origem`.
`pis` / `cofins` / `ipi`	`cst`, `base`, `aliquota`, `valor`.
`ii`	Imposto de Importação: `base`, `despesas_aduaneiras`, `valor`, `iof`.

O modelo cobre todos os estados: como a tributação vem pronta do integrador (ou é calculada por base+alíquota), a API monta o XML fielmente. Os totais da nota são somados automaticamente dos itens.

Compatibilidade: os campos soltos no item (cst, aliquota_icms, valor_icms...) continuam funcionando para quem já integrou.

Nota de veículo

Adicione o grupo veiculo ao item (chassi, RENAVAM, cor DENATRAN, combustível, ano fab./modelo, km, tipo de operação).

"itens": [{
  "codigo": "V001", "descricao": "VEICULO XYZ", "ncm": "87032100",
  "cfop": "5102", "unidade": "UN", "quantidade": 1,
  "valor_unitario": 50000.00, "valor_total": 50000.00, "origem": 0, "csosn": "102",
  "veiculo": {
    "chassi": "9BWZZZ377VT004251", "renavam": "12345678901",
    "cor": "PRETA", "cor_denatran": "01", "combustivel": "01",
    "ano_fabricacao": 2025, "ano_modelo": 2026, "km": "0", "tipo_operacao": 1
  }
}]

Produto importado (II + Declaração de Importação)

Para revenda de importados, informe o Imposto de Importação e a(s) DI(s) com suas adições:

"itens": [{
  "...": "...",
  "tributos": {
    "ii": { "base": 1000, "despesas_aduaneiras": 50, "valor": 120, "iof": 10 }
  },
  "importacao": {
    "declaracoes": [{
      "numero": "1234567890",
      "data_registro": "2026-07-01",
      "local_desembaraco": "PORTO DE SALVADOR",
      "uf_desembaraco": "BA",
      "data_desembaraco": "2026-07-03",
      "via_transporte": 1,
      "adicoes": [{ "numero": "1", "sequencial": "1", "codigo_fabricante": "FAB01" }]
    }]
  }
}]

Nota de devolução (NF referenciada)

Para devolução, complemento ou estorno, referencie a(s) nota(s) de origem pela chave de 44 dígitos:

{
  "emitente_id": 1, "modelo": 55,
  "natureza_operacao": "DEVOLUCAO DE VENDA",
  "notas_referenciadas": [
    "29260761810791000100550010000001231000001234"
  ],
  "destinatario": { "...": "..." },
  "itens": [{ "cfop": "5202", "...": "..." }]
}

Use o CFOP de devolução adequado (ex.: 5202/6202/1202/2202) e informe o mesmo produto da nota original.

Venda a prazo (fatura e duplicatas)

Para venda parcelada com boleto — habilita a antecipação de recebíveis:

{
  "...": "...",
  "cobranca": {
    "numero": "FAT001",
    "valor_original": 300.00,
    "valor_desconto": 0,
    "valor_liquido": 300.00,
    "duplicatas": [
      { "numero": "001", "vencimento": "2026-08-30", "valor": 150.00 },
      { "numero": "002", "vencimento": "2026-09-30", "valor": 150.00 }
    ]
  }
}

Reforma Tributária — IBS / CBS / Imposto Seletivo

Válido para NF-e (55) e NFC-e (65). Os grupos IBS/CBS e o Imposto Seletivo são enviados por item, no grupo ibs_cbs. A API repassa os campos fielmente ao XML (conforme a NT 2025.002) e os totais vão em totais_ibs_cbs. Os campos dos subgrupos usam o padrão subgrupo_campo (ex.: gIBSUF_vIBSUF).

CST e cClassTrib devem formar um par válido da tabela oficial (IT 2025.002). Ex.: CST 000 (tributação integral) usa cClassTrib 000001. A API valida os pares mais comuns e retorna erro com o código correto antes de transmitir; a lista completa está em TabelaClassificacaoTributaria (SVRS). Em caso de dúvida sobre o código do seu produto, consulte o contador. Obrigatório para CRT 3 (Regime Normal) desde 03/08/2026; Simples Nacional e MEI a partir de 04/01/2027.

"itens": [{
  "...": "...",
  "ibs_cbs": {
    "CST": "000",
    "cClassTrib": "000001",
    "vBC": "100.00",
    "gIBSUF_pIBSUF": "0.1000", "gIBSUF_vIBSUF": "0.10",
    "gIBSMun_pIBSMun": "0.0000", "gIBSMun_vIBSMun": "0.00",
    "gCBS_pCBS": "0.9000", "gCBS_vCBS": "0.90"
  },
  "imposto_seletivo": {
    // campos do IS quando aplicavel ao produto
  }
}]

A Reforma está em implantação. Os campos aceitos acompanham a versão da biblioteca fiscal e as Notas Técnicas vigentes. Consulte seu contador sobre CST e cClassTrib corretos por produto.

Transporte (transportadora e volumes)

Frete com transportadora, veículo e volumes (peso, espécie):

{
  "...": "...",
  "transporte": {
    "modalidade_frete": 1,
    "transportadora": {
      "cnpj": "12345678000199", "nome": "TRANSPORTES XYZ",
      "ie": "1234567", "endereco": "Rod. BR-101 km 10",
      "municipio": "Salvador", "uf": "BA"
    },
    "veiculo": { "placa": "ABC1D23", "uf": "BA" },
    "volumes": [
      { "quantidade": 2, "especie": "CAIXA",
        "peso_liquido": 10.5, "peso_bruto": 11.2 }
    ]
  }
}

Modalidade do frete: 0=emitente, 1=destinatário, 2=terceiros, 3/4=próprio, 9=sem frete.

Venda via marketplace (intermediador)

Para vendas em plataformas de terceiros (Mercado Livre, Shopee, Amazon...):

{
  "...": "...",
  "intermediador": {
    "cnpj": "03361252000134",
    "identificador": "conta_do_lojista_no_marketplace"
  }
}

A API marca automaticamente o indicador de intermediador na nota quando este grupo é enviado.

Ações

GET /notas filtros: modelo, status, emitente_id

GET /notas/{id}

POST /notas/{id}/cancelar

POST /notas/{id}/carta-correcao

NFS-e (Padrão Nacional)

POST /nfse

Com serviço avulso

curl -X POST https://www.speednf.rcssoftware.com.br/api/v1/nfse \
  -H "X-Api-Key: sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "emitente_id": 1,
    "tomador": {
      "cpf": "02059284554",
      "nome": "CLIENTE TESTE",
      "endereco": {
        "codigo_municipio": "2927408", "cep": "41830630",
        "logradouro": "Rua Hilton Rodrigues", "numero": "167", "bairro": "Pituba"
      }
    },
    "servico": {
      "codigo_tributacao_nacional": "010302",
      "codigo_nbs": "115061000",
      "descricao": "SERVICO DE HOSPEDAGEM",
      "valor": 50.00
    }
  }'

Com serviço do catálogo

{
  "emitente_id": 1,
  "tomador": { "cpf": "02059284554", "nome": "CLIENTE TESTE", "endereco": { } },
  "servico_id": 5,
  "servico": { "valor": 50.00 }
}

Tributação automática por regime

Regime	opSimpNac	Total de tributos
MEI	2	`indTotTrib` (ISS fixo no DAS)
ME/EPP (Simples)	3	`pTotTribSN` + `regApTribSN`
Regime Normal	1	`pTotTrib` (fed/est/mun)

tomador.endereco é obrigatório quando o ISSQN incide no domicílio do tomador. O codigo_nbs é obrigatório desde 2026. O grupo IBS/CBS da Reforma é montado automaticamente no XML da NFS-e (finNFSe, CST, cClassTrib) conforme o leiaute nacional 1.01; valores padrão podem ser ajustados via ibscbs no payload.

Ações e distribuição

GET /nfse/{id}

POST /nfse/{id}/cancelar

POST /nfse/sincronizar baixa NFS-e recebidas do ADN

Catálogo de serviços (NFS-e)

Serviços pré-cadastrados por emitente. Na emissão, referencie por servico_id.

GET /emitentes/{id}/servicos

POST /emitentes/{id}/servicos

PUT /emitentes/{id}/servicos/{sid}

DELETE /emitentes/{id}/servicos/{sid}

{
  "codigo": "HOSPEDAGEM",
  "descricao": "Hospedagem de sistemas",
  "ctrib_nac": "010302",
  "codigo_nbs": "115061000",
  "aliquota_iss": 2.00,
  "padrao": true
}

Manifestação de Destinatário (DF-e)

Baixa os documentos emitidos contra o CNPJ do emitente e permite manifestar.

POST /emitentes/{id}/dfe/sincronizar

GET /emitentes/{id}/dfe

GET /dfe/{id}/xml

POST /dfe/{id}/manifestar

tipo	Evento
210200	Confirmação da Operação
210210	Ciência da Operação seguro
210220	Desconhecimento da Operação
210240	Operação não Realizada (exige justificativa)

Baixar PDF (DANFE / DANFCE)

Gera o PDF da nota (com a logo do emitente). Retorna o arquivo diretamente.

GET /notas/{id}/danfe

curl https://www.speednf.rcssoftware.com.br/api/v1/notas/123/danfe \
  -H "X-Api-Key: sua_chave" \
  -o danfe.pdf

Para a Carta de Correção (DACCE):

GET /notas/{id}/carta-correcao/pdf

Baixar XML de uma nota

XML autorizado, com protocolo da SEFAZ.

GET /notas/{id}/xml NF-e / NFC-e

GET /nfse/{id}/xml NFS-e

curl https://www.speednf.rcssoftware.com.br/api/v1/notas/123/xml \
  -H "X-Api-Key: sua_chave" \
  -o nota.xml

Exportar XMLs em lote (ZIP)

Baixa um ZIP com os XMLs de um período, filtrando por tipo e empresa. Ideal para a guarda fiscal (5 anos) e a contabilidade. As pastas do ZIP são organizadas por tipo (nfe/, nfce/, nfse/, nfse-recebidas/).

GET /exportar/xmls

Parâmetro	Obrig.	Descrição
`data_inicio`	sim	`AAAA-MM-DD`
`data_fim`	sim	`AAAA-MM-DD`
`tipo`	não	`nfe`, `nfce`, `nfse`, `nfse_recebida` ou `todos`
`emitente_id`	não	Restringe a uma empresa
`status`	não	`autorizada` (padrão), `cancelada`, `todas`

curl -G https://www.speednf.rcssoftware.com.br/api/v1/exportar/xmls \
  -H "X-Api-Key: sua_chave" \
  -d data_inicio=2026-07-01 \
  -d data_fim=2026-07-31 \
  -d tipo=todos \
  -d emitente_id=1 \
  -o xmls_julho.zip

Tabelas de códigos fiscais

Referência rápida dos códigos aceitos nos campos da API. Em caso de dúvida sobre qual código usar, consulte o contador da empresa.

Origem da mercadoria (`origem`)

Código	Descrição
`0`	Nacional, exceto as indicadas nos códigos 3, 4, 5 e 8
`1`	Estrangeira — importação direta, exceto a indicada no código 6
`2`	Estrangeira — adquirida no mercado interno, exceto a indicada no código 7
`3`	Nacional, com Conteúdo de Importação superior a 40% e até 70%
`4`	Nacional, produção conforme processos produtivos básicos
`5`	Nacional, com Conteúdo de Importação até 40%
`6`	Estrangeira — importação direta, sem similar nacional (lista CAMEX) e gás natural
`7`	Estrangeira — mercado interno, sem similar nacional (lista CAMEX) e gás natural
`8`	Nacional, com Conteúdo de Importação superior a 70%

CST ICMS (`tributos.icms.cst`) — Regime Normal

CST	Descrição	Campos que acompanham
`00`	Tributada integralmente	`base`, `aliquota`, `valor`
`10`	Tributada com cobrança de ICMS por ST	ICMS próprio + grupo `st`
`20`	Com redução da base de cálculo	`reducao_base` (%) + ICMS
`30`	Isenta/não tributada com cobrança por ST	grupo `st`
`40`	Isenta	apenas `origem` (desoneração opcional)
`41`	Não tributada	apenas `origem`
`50`	Suspensão	apenas `origem`
`51`	Diferimento	`diferimento` (%) + ICMS da operação
`60`	ICMS cobrado anteriormente por ST	grupo `st_retido`
`70`	Redução de base + cobrança por ST	`reducao_base` + ICMS + grupo `st`
`90`	Outras	conforme a operação

CSOSN (`tributos.icms.csosn`) — Simples Nacional

CSOSN	Descrição	Campos que acompanham
`101`	Tributada com permissão de crédito	`aliquota_credito_sn`, `valor_credito_sn`
`102`	Tributada sem permissão de crédito	apenas `origem`
`103`	Isenção do ICMS para faixa de receita	apenas `origem`
`201`	Com permissão de crédito e cobrança por ST	crédito SN + grupo `st`
`202`	Sem permissão de crédito e com ST	grupo `st`
`203`	Isenção para faixa de receita e com ST	grupo `st`
`300`	Imune	apenas `origem`
`400`	Não tributada pelo Simples (ex.: devolução, bonificação)	apenas `origem`
`500`	ICMS cobrado anteriormente por ST	grupo `st_retido` (quando exigido)
`900`	Outros	conforme a operação

CST PIS / COFINS (`tributos.pis.cst` / `tributos.cofins.cst`)

CST	Descrição	Comportamento na API
`01`	Tributável — alíquota básica	calcula/aceita `base`+`aliquota`+`valor`
`02`	Tributável — alíquota diferenciada	calcula/aceita valores
`04`	Tributação monofásica (alíquota zero na revenda)	sem valores
`05`	Tributável por ST	sem valores
`06`	Alíquota zero	sem valores
`07`	Isenta da contribuição	sem valores (padrão da API)
`08`	Sem incidência	sem valores
`09`	Com suspensão	sem valores
`49`–`99`	Outras operações (saída/entrada/crédito)	aceita valores quando informados

CST IPI (`tributos.ipi.cst`)

CST	Descrição
`00`	Entrada com recuperação de crédito
`01`–`03`	Entrada tributada zero / isenta / não tributada
`04`/`05`	Entrada imune / com suspensão
`49`	Outras entradas
`50`	Saída tributada
`51`–`53`	Saída tributada zero / isenta / não tributada
`54`/`55`	Saída imune / com suspensão
`99`	Outras saídas

CST IBS/CBS (`ibs_cbs.CST`) — Reforma Tributária

CST	Descrição
`000`	Tributação integral
`010`/`011`	Alíquotas uniformes (setor financeiro) / uniformes reduzidas
`200`	Alíquota zero ou reduzida (conforme cClassTrib)
`210`	Alíquota reduzida com redutor de base de cálculo
`220`/`221`/`222`	Alíquota fixa / fixa proporcional / redução de base
`400`	Isenção
`410`	Imunidade e não incidência
`510`/`515`	Diferimento / diferimento com redução de alíquota
`550`	Suspensão
`620`	Tributação monofásica
`800`/`810`/`811`	Transferência de crédito / ajustes
`820`/`830`	Regime específico / exclusão de base de cálculo

O cClassTrib (6 dígitos) detalha a situação dentro do CST — a tabela oficial tem centenas de códigos e é atualizada por versão do Informe Técnico RT 2025.002. A API valida o formato do cClassTrib e o CST contra a tabela; a combinação exata é validada pelo ambiente autorizador. Em caso de dúvida sobre o código do seu produto, consulte o contador.

Modalidade do frete (`transporte.modalidade_frete`)

Código	Descrição
`0`	Contratação por conta do remetente (CIF)
`1`	Contratação por conta do destinatário (FOB)
`2`	Contratação por conta de terceiros
`3`	Transporte próprio por conta do remetente
`4`	Transporte próprio por conta do destinatário
`9`	Sem ocorrência de transporte

Forma de pagamento (`pagamentos[].forma`)

Código	Descrição
`01`	Dinheiro
`02`	Cheque
`03`	Cartão de crédito
`04`	Cartão de débito
`05`	Crédito loja
`10`/`11`/`12`/`13`	Vale alimentação / refeição / presente / combustível
`14`	Duplicata mercantil
`15`	Boleto bancário
`16`/`17`	Depósito bancário / PIX
`18`/`19`	Transferência / Programa de fidelidade
`90`	Sem pagamento (ex.: remessa, devolução)
`99`	Outros

Consulta via API

Todas as tabelas também estão disponíveis por endpoint, para popular selects ou conferir códigos no seu sistema:

GET /tabelas lista as tabelas

GET /tabelas/{nome} csosn, cst-icms, cst-pis-cofins, cst-ipi, cst-ibs-cbs, origem, formas-pagamento, modalidades-frete, motivos-desoneracao

curl https://www.speednf.rcssoftware.com.br/api/v1/tabelas/csosn -H "X-Api-Key: sua_chave"

{
  "sucesso": true,
  "dados": {
    "nome": "csosn",
    "titulo": "CSOSN (Simples Nacional)",
    "codigos": [
      { "codigo": "101", "descricao": "Tributada pelo Simples Nacional com permissão de crédito",
        "campos_aceitos": ["aliquota_credito_sn", "valor_credito_sn"] },
      { "codigo": "102", "descricao": "Tributada pelo Simples Nacional sem permissão de crédito",
        "campos_aceitos": [] }
    ]
  }
}

Validação prévia na emissão

Antes de reservar número e transmitir à SEFAZ, a API valida os códigos fiscais do payload. Código inexistente ou campo incoerente com o CST/CSOSN retorna 422 imediato, apontando o caminho exato do campo — sem gastar uma rejeição na SEFAZ:

{
  "sucesso": false,
  "mensagem": "Payload com códigos fiscais inválidos ou incoerentes. Nada foi transmitido à SEFAZ.",
  "erros": [
    { "campo": "itens[0].tributos.icms.csosn",
      "mensagem": "CSOSN: código '105' inválido. Aceitos: 101, 102, 103, 201, 202, 203, 300, 400, 500, 900. Consulte GET /api/v1/tabelas/csosn para as descrições." },
    { "campo": "itens[0].tributos.icms.reducao_base",
      "mensagem": "Campo 'reducao_base' não é esperado para o CST 00. Campos aceitos com esse código: base, aliquota, valor, modalidade_base, fcp." }
  ]
}

A validação também confere o regime: emitente do Simples (CRT 1/2) deve usar csosn; Regime Normal (CRT 3) usa cst. A escolha errada retorna erro orientando a troca.

Origem × Tributação: como se combinam

Na NF-e, a situação tributária do ICMS é composta por origem + código: a origem (1 dígito, tabela acima) informa a procedência da mercadoria, e o cst (2 dígitos, Regime Normal) ou csosn (3 dígitos, Simples) informa a tributação. A API monta essa combinação automaticamente — você envia os dois campos separados.

Respostas & Erros

Sucesso

{ "sucesso": true, "mensagem": "OK", "dados": { } }

Erro

{ "sucesso": false, "mensagem": "Descrição do erro.", "detalhe": { } }

HTTP	Significado
200 / 201	OK / Criado
401	Chave ausente ou inválida
403	Sem permissão (ex.: chave-de-empresa acessando outra)
404	Não encontrado
422	Dados inválidos ou rejeição fiscal (a mensagem traz o motivo)
429	Limite de requisições excedido

Rejeições da SEFAZ ou do Ambiente Nacional retornam 422 com a mensagem oficial (ex.: E0234, E1235). Toda comunicação fica registrada para auditoria.

SpeedNF · Documentação da API — atualizada em 01/08/2026
Base URL: https://www.speednf.rcssoftware.com.br/api/v1