API de integração

Emita NF-e, NFC-e e NFS-e a partir do seu sistema. Você envia os dados da venda em JSON; a API monta, assina com o certificado em custódia, transmite e responde na mesma chamada. A especificação em formato OpenAPI 3.1 está em /api/v1/openapi.json.

URL base: https://fiscal.theordem.com.br/api/v1. Não há ambiente de testes separado: o campo ambiente de cada chamada decide (1 produção, 2 homologação), e a produção de cada emitente precisa ser liberada antes.

Autenticação

Toda chamada leva Authorization: Bearer tof_live_…. A chave é criada no painel, em Chaves de API, por um administrador da conta, e aparece uma única vez. Ela pertence a uma conta: a conta vem sempre da chave, nunca do corpo da requisição.

Chame a API a partir de um servidor. Não há CORS para integradores, e a chave nunca deve ir em código de navegador ou de aplicativo instalado.

Escopos

A chave só faz o que os escopos dela permitem, e nenhum escopo implica outro. Fora do escopo a rota responde 403 escopo_insuficiente. Criar ou revogar chaves, gerir a equipe e alterar a alçada são ações só do painel.

Escopo	Permite
`ingestao`	Registrar notas emitidas fora da nuvem
`leitura`	Consultar notas, baixar XML e DANFE
`emissao`	Emitir NF-e, NFC-e e NFS-e; enviar a nota por e-mail; consultar alçada e cota
`eventos`	Cancelar, corrigir e inutilizar
`emitentes`	Cadastrar e consultar emitentes e numeração
`certificado`	Enviar o certificado A1
`producao`	Liberar o ambiente de produção de um emitente
`dfe`	Buscar as notas recebidas de fornecedores e manifestar ciência

Idempotência

Envie uma idempotencyKey sua em cada emissão (obrigatória na NF-e e na NFC-e). A mesma chave nunca gera duas notas para o mesmo emitente: a repetição devolve ja_emitida com a nota original.

Se a resposta for 202, a API continua conciliando a nota com a SEFAZ sozinha; para saber o desfecho, repita a chamada com a mesma chave ou consulte a nota. Se a conexão cair antes da resposta, repita com a mesma chave. Nunca troque a chave para tentar de novo.

Erros

Todo erro vem em JSON com erro (texto para pessoas) e, quase sempre, codigo (estável, para o seu sistema tratar).

Status	Quando	Corpo
400	Validação da API	{ erro, codigo } — `codigo` é o nome do campo (ex.: `itens[0].ncm`)
401	Chave inválida ou revogada	{ erro }
403	Escopo, licença ou produção não liberada	{ erro, codigo } — `escopo_insuficiente`, `licenca_…`, `PRODUCAO_NAO_LIBERADA`
404	O recurso não existe nesta conta	{ erro }
409	Operação em andamento ou conflito de estado	{ erro, codigo }
422	Rejeição da SEFAZ/SEFIN ou regra fiscal	{ erro, codigo?, cStat?, xMotivo? }
429	Limite por minuto ou cota mensal	{ erro, codigo, tentarEmSegundos } e cabeçalho `Retry-After`
500	Erro interno	{ erro: "Erro interno", ref } — informe a `ref` ao suporte

Limites

Os limites valem por chave de API. Ao estourar, a resposta é 429 com Retry-After. Nota rejeitada não gasta a cota mensal.

Leitura (GET)	300 por minuto
Escrita	60 por minuto
Emissão	600 por minuto, e 30 por minuto por emitente
Eventos e inutilização	20 por minuto

Webhooks

Cadastre no painel, em Webhooks, um endereço https:// do seu sistema para ser avisado quando uma nota for autorizada, rejeitada, cancelada ou corrigida. O aviso vale para o que acontece por qualquer caminho: pela API, pelo painel ou pela conciliação automática.

Evento	Quando
`nota.autorizada`	A SEFAZ ou a SEFIN autorizou a nota.
`nota.rejeitada`	A nota foi rejeitada ou denegada.
`nota.cancelada`	O cancelamento foi registrado.
`nota.corrigida`	Uma carta de correção foi registrada.

O corpo leva só referências. Para os dados da nota, consulte GET /documentos/:id com a sua chave.

POST https://seu-sistema.com.br/fiscal/avisos
Content-Type: application/json
X-TheOrdem-Evento: nota.autorizada
X-TheOrdem-Entrega: 5f0c2b1e-8a3d-4f6e-9b7a-2c1d0e9f8a7b
X-TheOrdem-Assinatura: t=1791979200,v1=9f2c…

{
  "id": "5f0c2b1e-8a3d-4f6e-9b7a-2c1d0e9f8a7b",
  "evento": "nota.autorizada",
  "criadoEm": "2026-10-14T12:00:00.000Z",
  "dados": { "documentoId": "0b9f6d3e-…", "clienteId": "…", "modelo": "nfce", "ambiente": 1 }
}

Confira a assinatura antes de confiar no aviso: calcule o HMAC-SHA256 de <t>.<corpo exato recebido> com o segredo do webhook e compare com v1; recuse se t for mais velho que cinco minutos.

import { createHmac, timingSafeEqual } from "node:crypto";

function avisoValido(segredo, corpoBruto, cabecalho) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(cabecalho);
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const esperado = createHmac("sha256", segredo).update(m[1] + "." + corpoBruto).digest();
  return timingSafeEqual(esperado, Buffer.from(m[2], "hex"));
}

Responda 2xx em até 8 segundos. Qualquer outra resposta, inclusive redirecionamento, conta como falha e o aviso é tentado de novo com espera crescente, por até sete vezes. O mesmo aviso pode chegar mais de uma vez: use o id para ignorar repetição. Depois de 20 falhas seguidas o endereço é desativado.

Emitentes

GET/emitentesListar emitentesemitentes

Chave com o escopo emitentes. No painel, papel mínimo: leitor.

Parâmetros de consulta

`documento`	CNPJ ou CPF completo, com ou sem máscara. Filtra pela igualdade.
`busca`	Trecho da razão social, do nome fantasia ou início do documento.
`limite`	Itens por página (padrão 50).
`cursor`	`proximoCursor` da página anterior.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/emitentes" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — Página de emitentes.

{
  "emitentes": [
    {
      "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
      "documento": "39543895000146",
      "razaoSocial": "Empresa Exemplo LTDA",
      "nomeFantasia": null,
      "codigoMunicipio": "4314407",
      "status": "ativo",
      "certificado": {
        "situacao": "ativo",
        "naoDepois": "2027-09-15T18:40:13+00:00"
      }
    }
  ],
  "proximoCursor": null
}

POST/emitentesCadastrar emitenteemitentes

O dígito verificador do CNPJ/CPF é validado. A produção nunca é liberada no cadastro.

Chave com o escopo emitentes. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/emitentes" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "documento": "39543895000146",
  "razaoSocial": "Empresa Exemplo LTDA",
  "nomeFantasia": "Exemplo",
  "codigoMunicipio": "4314407",
  "config": {
    "nfe": {
      "ie": "0960000000",
      "crt": 1,
      "endereco": {
        "uf": "RS",
        "codigoMunicipio": "4314407",
        "cep": "96020152",
        "logradouro": "Avenida Exemplo",
        "numero": "130",
        "bairro": "Centro",
        "municipio": "Pelotas"
      },
      "series": {
        "nfe": 1,
        "nfce": 1
      }
    }
  }
}'

Respostas

201 — Criado.

{
  "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11"
}

409 — Documento já cadastrado na conta (traz o id do existente) ou limite de emitentes do plano.

{
  "erro": "Já existe um emitente com este documento nesta conta.",
  "codigo": "documento_ja_cadastrado",
  "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11"
}

POST/emitentes/importacaoCadastrar emitentes em loteemitentes

Até 200 linhas por chamada; cada linha tem o seu resultado.

Chave com o escopo emitentes. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/emitentes/importacao" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "emitentes": [
    {
      "documento": "39543895000146",
      "razaoSocial": "Empresa Exemplo LTDA"
    }
  ]
}'

Respostas

200 — Resultado por linha.

{
  "resumo": {
    "total": 1,
    "criados": 1,
    "jaExistentes": 0,
    "erros": 0
  },
  "resultados": [
    {
      "indice": 0,
      "status": "criado",
      "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11"
    }
  ]
}

GET/emitentes/:idDetalhe do emitenteemitentes

Chave com o escopo emitentes. No painel, papel mínimo: leitor.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/emitentes/<id>" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — Cadastro e config.

{
  "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "tipoDoc": "CNPJ",
  "documento": "39543895000146",
  "inscricaoMunicipal": null,
  "razaoSocial": "Empresa Exemplo LTDA",
  "nomeFantasia": null,
  "codigoMunicipio": "4314407",
  "status": "ativo",
  "config": {
    "nfe": {
      "ie": "0960000000",
      "crt": 1,
      "producao": false
    }
  }
}

PATCH/emitentes/:idAtualizar emitenteemitentes

config entra por merge: mande só o que mudou. documento e tipoDoc são imutáveis. Mudar config.nfe.producao ou config.nfse.producao exige o escopo producao (na sessão: admin com código de e-mail recente).

Chave com o escopo emitentes. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X PATCH "https://fiscal.theordem.com.br/api/v1/emitentes/<id>" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "config": {
    "nfe": {
      "producao": true
    }
  }
}'

Respostas

200 — Atualizado.

{
  "atualizado": true
}

POST/emitentes/:id/certificadoEnviar o certificado A1certificado

Chave privada e certificado em PEM; a API nunca recebe .pfx nem senha. O CNPJ/CPF do certificado precisa ser o do emitente (CNPJ confere pela raiz). Na sessão exige código de e-mail recente.

Chave com o escopo certificado. No painel, papel mínimo: admin.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/certificado" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "chavePem": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----",
  "certPem": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----"
}'

Respostas

201 — Guardado em custódia; só metadados voltam.

{
  "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "fingerprintSha256": "06:42:56:…",
  "titularCn": "EMPRESA EXEMPLO LTDA:39543895000146",
  "naoDepois": "2027-09-15T18:40:13+00:00"
}

422 — Recusado: chave_invalida, certificado_invalido, par_invalido, certificado_vencido, titular_nao_identificado ou titular_divergente.

{
  "erro": "O certificado é de outro CNPJ.",
  "codigo": "titular_divergente"
}

GET/emitentes/:id/certificadoSituação do certificadoemitentes

Chave com o escopo emitentes. No painel, papel mínimo: leitor.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/certificado" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — Metadados do A1 ativo.

{
  "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "fingerprintSha256": "06:42:56:…",
  "titularCn": "EMPRESA EXEMPLO LTDA:39543895000146",
  "naoAntes": "2026-09-15T18:40:13+00:00",
  "naoDepois": "2027-09-15T18:40:13+00:00",
  "status": "ativo",
  "vencido": false,
  "diasParaVencer": 337
}

404 — Emitente sem certificado ativo.

GET/emitentes/:id/numeracaoConsultar a numeração de uma sérieemitentes

Chave com o escopo emitentes. No painel, papel mínimo: leitor.

Parâmetros de consulta

`modelo` (obrigatório)	55 (NF-e) ou 65 (NFC-e).
`serie` (obrigatório)	1 a 889.
`ambiente` (obrigatório)	1 produção, 2 homologação.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/numeracao" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — Contador atual.

{
  "modelo": 65,
  "serie": 1,
  "ambiente": 1,
  "ultimoNumero": 482,
  "proximoNumero": 483
}

PUT/emitentes/:id/numeracaoInformar a numeração inicial de uma sérieemitentes

Para quem já emite por outro sistema. O contador só anda para a frente; a próxima nota sai com ultimoNumero + 1. Repetir o mesmo valor responde 200.

Chave com o escopo emitentes. No painel, papel mínimo: admin.

Exemplo de chamada

curl -X PUT "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/numeracao" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "modelo": 65,
  "serie": 1,
  "ambiente": 1,
  "ultimoNumero": 482
}'

Respostas

200 — Contador posicionado.

{
  "modelo": 65,
  "serie": 1,
  "ambiente": 1,
  "ultimoNumero": 482,
  "proximoNumero": 483
}

409 — O contador já passou do valor pedido.

{
  "erro": "A numeração desta série já está em 500.",
  "codigo": "numeracao_menor",
  "modelo": 65,
  "serie": 1,
  "ambiente": 1,
  "ultimoNumero": 500,
  "proximoNumero": 501
}

Emissão

POST/documentos/nfeEmitir NF-e (modelo 55)emissao

A API monta, assina e transmite o XML e responde na mesma chamada. Dados do emitente (IE, regime, endereço, série) vêm do cadastro. idempotencyKey é obrigatória e vale por emitente. Acima da alçada da conta, envie confirmacaoValor igual ao total.

Chave com o escopo emissao. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/documentos/nfe" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "clienteId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "idempotencyKey": "venda-123",
  "ambiente": 2,
  "presenca": 1,
  "naturezaOperacao": "Venda de mercadoria",
  "destinatario": {
    "documento": "12345678000195",
    "nome": "Cliente Exemplo LTDA",
    "indIEDest": 9,
    "endereco": {
      "uf": "RS",
      "codigoMunicipio": "4314902",
      "cep": "90000000",
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "municipio": "Porto Alegre"
    }
  },
  "itens": [
    {
      "codigo": "1",
      "descricao": "Produto exemplo",
      "ncm": "61091000",
      "cfop": "5102",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 19.9
    }
  ],
  "pagamentos": [
    {
      "meio": "01",
      "valor": 19.9
    }
  ],
  "informacoesComplementares": "Texto livre opcional"
}'

Respostas

200 — Autorizada, ou ja_emitida quando a idempotencyKey já gerou esta nota.

{
  "tipo": "autorizada",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chaveAcesso": "43261039543895000146550010000001231123456789",
  "numero": 123,
  "protocolo": "143260000012345",
  "autorizadaEm": "2026-10-13T14:30:07-03:00"
}

202 — Sem resposta da SEFAZ. Não é erro: a API segue conciliando a nota sozinha, e repetir com a mesma idempotencyKey devolve o desfecho.

{
  "status": "em_processamento",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chaveAcesso": "43261039543895000146550010000001231123456789",
  "numero": 123,
  "mensagem": "A SEFAZ não respondeu. Repita a chamada com a mesma idempotencyKey."
}

409 — Outra chamada com a mesma idempotencyKey está em andamento.

{
  "erro": "Já existe uma emissão em andamento para esta chave.",
  "codigo": "EMISSAO_EM_ANDAMENTO"
}

422 — Rejeição ou denegação da SEFAZ, ou regra fiscal da API (NFE_NAO_CONFIGURADO, UF_NAO_SUPORTADA).

{
  "erro": "Rejeitada pela SEFAZ.",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chaveAcesso": "43261039543895000146550010000001231123456789",
  "numero": 123,
  "cStat": "539",
  "xMotivo": "Rejeição: Duplicidade de NF-e, com diferença na Chave de Acesso"
}

POST/documentos/nfceEmitir NFC-e (modelo 65)emissao

Mesmo corpo da NF-e; o destinatário é opcional. A resposta traz também qrCode e urlChave, para o cupom.

Chave com o escopo emissao. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/documentos/nfce" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "clienteId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "idempotencyKey": "venda-123",
  "ambiente": 2,
  "presenca": 1,
  "naturezaOperacao": "Venda de mercadoria",
  "itens": [
    {
      "codigo": "1",
      "descricao": "Produto exemplo",
      "ncm": "61091000",
      "cfop": "5102",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 19.9
    }
  ],
  "pagamentos": [
    {
      "meio": "01",
      "valor": 19.9
    }
  ],
  "informacoesComplementares": "Texto livre opcional"
}'

Respostas

200 — Autorizada, ou ja_emitida quando a idempotencyKey já gerou esta nota.

{
  "tipo": "autorizada",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chaveAcesso": "43261039543895000146550010000001231123456789",
  "numero": 123,
  "protocolo": "143260000012345",
  "autorizadaEm": "2026-10-13T14:30:07-03:00",
  "qrCode": "https://www.sefaz.rs.gov.br/NFCE/NFCE-COM.aspx?p=…",
  "urlChave": "www.sefaz.rs.gov.br/nfce/consulta"
}

202 — Sem resposta da SEFAZ. Não é erro: a API segue conciliando a nota sozinha, e repetir com a mesma idempotencyKey devolve o desfecho.

{
  "status": "em_processamento",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chaveAcesso": "43261039543895000146550010000001231123456789",
  "numero": 123,
  "mensagem": "A SEFAZ não respondeu. Repita a chamada com a mesma idempotencyKey."
}

409 — Outra chamada com a mesma idempotencyKey está em andamento.

{
  "erro": "Já existe uma emissão em andamento para esta chave.",
  "codigo": "EMISSAO_EM_ANDAMENTO"
}

422 — Rejeição ou denegação da SEFAZ, ou regra fiscal da API (NFE_NAO_CONFIGURADO, UF_NAO_SUPORTADA).

{
  "erro": "Rejeitada pela SEFAZ.",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chaveAcesso": "43261039543895000146550010000001231123456789",
  "numero": 123,
  "cStat": "539",
  "xMotivo": "Rejeição: Duplicidade de NF-e, com diferença na Chave de Acesso"
}

POST/documentos/nfseEmitir NFS-e (padrão nacional)emissao

Vale para municípios aderentes ao padrão nacional. idempotencyKey é recomendada e vale por emitente. Desde a competência 10/2026 a SEFIN exige o IBS/CBS (servico.ibscbs: cIndOp, cst, cClassTrib, pela correlação oficial do item da LC 116 e da NBS); sem ele, vale o padrão do cadastro do emitente. Quando o IBS/CBS incide no domicílio do tomador, tomador.endereco é obrigatório.

Chave com o escopo emissao. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/documentos/nfse" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "clienteId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "ambiente": 2,
  "idempotencyKey": "os-987",
  "tomador": {
    "documento": "11122233344",
    "tipo": "CPF",
    "nome": "Fulano de Tal",
    "endereco": {
      "codigoMunicipio": "4314407",
      "cep": "96010140",
      "logradouro": "Rua Andrade Neves",
      "numero": "100",
      "complemento": "Sala 2",
      "bairro": "Centro"
    }
  },
  "servico": {
    "cTribNac": "170101",
    "descricao": "Serviço prestado",
    "cNBS": "114011900",
    "codMunicipio": "4314407",
    "valor": 150,
    "ibscbs": {
      "cIndOp": "100301",
      "cst": "000",
      "cClassTrib": "000001"
    }
  }
}'

Respostas

200 — Autorizada, ou ja_emitida.

{
  "tipo": "autorizada",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chaveAcesso": "4314407239543895000146000000000000126101234567890",
  "numeroNfse": "12"
}

202 — Sem resposta da SEFIN: repita com a mesma idempotencyKey.

{
  "status": "em_recuperacao",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "mensagem": "A SEFIN não respondeu."
}

422 — Rejeitada pela SEFIN.

{
  "erro": "Rejeitada pela SEFIN.",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "codigos": [
    {
      "codigo": "E0001",
      "descricao": "…"
    }
  ]
}

Depois da emissão

POST/documentos/:id/eventosCancelar ou corrigir NF-e/NFC-eeventos

tipo: "cancelamento" com justificativa, ou tipo: "cce" com correcao (15 a 255 caracteres; a NFC-e não tem carta de correção). Só para notas emitidas pela nuvem.

Chave com o escopo eventos. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/documentos/<id>/eventos" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "tipo": "cancelamento",
  "justificativa": "Cliente desistiu da compra antes da entrega"
}'

Respostas

200 — cancelada, ja_cancelada ou corrigida (com sequencia).

{
  "tipo": "cancelada",
  "chave": "43261039543895000146550010000001231123456789",
  "protocolo": "243260000000001"
}

409 — Já há um evento em andamento para a nota.

{
  "erro": "Já existe uma operação em andamento.",
  "codigo": "OPERACAO_EM_ANDAMENTO"
}

422 — Recusa da SEFAZ, com cStat e xMotivo.

{
  "erro": "A SEFAZ recusou o evento (501): Rejeição: Prazo de Cancelamento Superior ao Previsto",
  "codigo": "SEFAZ_501",
  "cStat": "501",
  "xMotivo": "Rejeição: Prazo de Cancelamento Superior ao Previsto"
}

POST/documentos/:id/cancelamentoCancelar NFS-eeventos

Chave com o escopo eventos. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/documentos/<id>/cancelamento" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "motivo": 1,
  "justificativa": "Serviço não prestado conforme combinado",
  "tipo": "101101"
}'

Respostas

200 — cancelada, ou em_analise quando o pedido vai à análise da prefeitura (tipo: "101103").

{
  "tipo": "cancelada",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11"
}

POST/emitentes/:id/inutilizacaoInutilizar uma faixa de númeroseventos

Irreversível. A faixa não pode começar depois do próximo número da série; se passa do contador, o contador avança junto. ambiente: 1 exige a produção liberada.

Chave com o escopo eventos. No painel, papel mínimo: admin.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/inutilizacao" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "modelo": 55,
  "serie": 1,
  "ambiente": 2,
  "inicio": 483,
  "fim": 485,
  "justificativa": "Numeracao pulada por falha no sistema de origem"
}'

Respostas

200 — inutilizada, ou ja_inutilizada na repetição do mesmo pedido.

{
  "tipo": "inutilizada",
  "modelo": 55,
  "serie": 1,
  "ambiente": 2,
  "inicio": 483,
  "fim": 485,
  "protocolo": "143260000000100"
}

409 — Já há um pedido em andamento para a série.

{
  "erro": "Já existe uma inutilização em andamento para esta série.",
  "codigo": "OPERACAO_EM_ANDAMENTO"
}

422 — FAIXA_ALEM_DA_NUMERACAO, NFE_NAO_CONFIGURADO ou recusa da SEFAZ com cStat/xMotivo.

{
  "erro": "A numeração desta série está em 480: a faixa não pode começar depois de 481.",
  "codigo": "FAIXA_ALEM_DA_NUMERACAO"
}

GET/documentos/:id/xmlBaixar o XML autorizado ou o XML de um eventoleitura

Sem parâmetros: o nfeProc (NF-e/NFC-e) ou o XML da SEFIN (NFS-e). Com evento: o procEventoNFe.

Chave com o escopo leitura. No painel, papel mínimo: leitor.

Parâmetros de consulta

`evento`	`cancelamento` ou `cce`.
`sequencia`	Sequência da carta de correção, 1 a 20 (padrão 1).

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/documentos/<id>/xml" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — O XML, exatamente como foi guardado.

404 — Nota sem XML autorizado ou sem o evento pedido.

{
  "erro": "Nota sem XML autorizado.",
  "codigo": "xml_indisponivel"
}

GET/documentos/:id/danfeDANFE em PDF (NF-e e NFC-e)leitura

A4 para a NF-e, bobina de 80 mm para a NFC-e, desenhado a partir do XML autorizado. Nota cancelada sai marcada.

Chave com o escopo leitura. No painel, papel mínimo: leitor.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/documentos/<id>/danfe" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — O PDF.

422 — A nota é NFS-e: use /danfse.

{
  "erro": "O DANFE existe para NF-e e NFC-e.",
  "codigo": "modelo_sem_danfe"
}

POST/documentos/:id/envioEnviar a nota por e-mail ao destinatárioemissao

Um destinatário por chamada. O e-mail tem texto fixo e leva o XML em anexo e, na NF-e e na NFC-e, o DANFE em PDF. Só nota autorizada e emitida pela API (nota de ingestão responde 422 nota_de_ingestao). Conta no limite de eventos.

Chave com o escopo emissao. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/documentos/<id>/envio" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "cliente@exemplo.com.br"
}'

Respostas

200 — Aceito pelo provedor de e-mail.

{
  "enviado": true,
  "email": "cliente@exemplo.com.br",
  "anexos": [
    "nfe-43261039543895000146550010000001231123456789.xml",
    "nfe-43261039543895000146550010000001231123456789.pdf"
  ]
}

502 — O provedor de e-mail não aceitou o envio. Pode repetir.

{
  "erro": "O e-mail não pôde ser enviado agora. Tente novamente em instantes.",
  "codigo": "email_nao_enviado"
}

GET/documentos/:id/danfseDados do DANFSe (NFS-e)leitura

Dados estruturados para desenhar o DANFSe; não é PDF.

Chave com o escopo leitura. No painel, papel mínimo: leitor.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/documentos/<id>/danfse" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — Campos do DANFSe lidos do XML.

{
  "danfse": {
    "numero": "12",
    "chaveAcesso": "…"
  }
}

Consultas

GET/documentosListar e localizar notasleitura

Para localizar uma nota: chave (44 posições, ou 50 dígitos na NFS-e), ou idempotencyKey junto de clienteId e modelo. Lista vazia na consulta por idempotência significa que a chave nunca foi usada por esse emitente.

Chave com o escopo leitura. No painel, papel mínimo: leitor.

Parâmetros de consulta

`chave`	Chave de acesso.
`idempotencyKey`	Exige `clienteId` e `modelo`.
`clienteId`	Emitente.
`modelo`	`nfe`, `nfce` ou `nfse`.
`status`	`rascunho`, `assinada`, `transmitida`, `autorizada`, `rejeitada`, `cancelada` ou `erro`.
`origem`	`cloud` (emitida pela API) ou `ingestao`.
`de`	Data inicial, AAAA-MM-DD.
`ate`	Data final, AAAA-MM-DD.
`limite`	Itens por página (padrão 50).
`cursor`	`proximoCursor` da página anterior.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/documentos" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — Página de notas.

{
  "documentos": [
    {
      "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
      "modelo": "nfce",
      "origem": "cloud",
      "numero": "123",
      "serie": "1",
      "status": "autorizada",
      "valorTotal": 19.9,
      "emitidaEm": "2026-10-13T17:30:05+00:00",
      "createdAt": "2026-10-13T17:30:04+00:00",
      "chave": "43261039543895000146550010000001231123456789"
    }
  ],
  "proximoCursor": null
}

GET/documentos/:idDetalhe da notaleitura

Inclui a linha do tempo dos eventos. Não devolve XML.

Chave com o escopo leitura. No painel, papel mínimo: leitor.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/documentos/<id>" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — A nota.

{
  "id": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "clienteId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "modelo": "nfe",
  "origem": "cloud",
  "ambiente": 1,
  "numero": "123",
  "serie": "1",
  "status": "autorizada",
  "valorTotal": 19.9,
  "emitidaEm": "2026-10-13T17:30:05+00:00",
  "createdAt": "2026-10-13T17:30:04+00:00",
  "chave": "43261039543895000146550010000001231123456789",
  "protocolo": "143260000012345",
  "motivoRejeicao": null,
  "eventos": []
}

Notas recebidas

POST/emitentes/:id/dfe/buscaBuscar na SEFAZ as notas emitidas contra o CNPJdfe

Consulta a distribuição de DF-e do Ambiente Nacional (só produção) com o A1 do emitente e guarda o que veio. Não altera nada na SEFAZ. Ao chegar ao fim da fila, a SEFAZ só aceita nova busca em 1 hora: antes disso a rota responde 429 DFE_AGUARDE sem consultar.

Chave com o escopo dfe. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/dfe/busca" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — Busca feita. novas é quantas notas entraram na caixa.

{
  "novas": 3,
  "proximaConsulta": "2026-10-13T19:00:00.000Z"
}

409 — Já há uma busca em andamento para o emitente.

{
  "erro": "Já existe uma busca em andamento para este emitente.",
  "codigo": "OPERACAO_EM_ANDAMENTO"
}

429 — Dentro da espera imposta pela SEFAZ.

{
  "erro": "A SEFAZ só aceita uma nova busca depois deste horário.",
  "codigo": "DFE_AGUARDE",
  "proximaConsulta": "2026-10-13T19:00:00.000Z",
  "tentarEmSegundos": 1800
}

GET/emitentes/:id/dfeListar as notas recebidasdfe

O que já está na caixa, mais recentes primeiro; não fala com a SEFAZ. estado: resumo (só o cabeçalho), ciencia (manifestada, XML ainda não veio) ou completa (XML disponível).

Chave com o escopo dfe. No painel, papel mínimo: leitor.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/dfe" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — Notas e horários de consulta.

{
  "notas": [
    {
      "chave": "43261039543895000146550010000001231123456789",
      "emitente": {
        "documento": "12345678000190",
        "nome": "Fornecedor Exemplo LTDA"
      },
      "emissao": "2026-10-10",
      "valor": 350.9,
      "situacao": "autorizada",
      "estado": "resumo"
    }
  ],
  "ultimaConsulta": "2026-10-13T18:00:00.000Z",
  "proximaConsulta": "2026-10-13T19:00:00.000Z"
}

POST/emitentes/:id/dfe/cienciaManifestar ciência de uma nota e trazer o XMLdfe

Registra na SEFAZ a Ciência da Operação (evento 210210) e pede o XML completo. É um ato fiscal em nome do emitente; não confirma a compra. A nota precisa estar na lista.

Chave com o escopo dfe. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/dfe/ciencia" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "chave": "43261039543895000146550010000001231123456789"
}'

Respostas

200 — XML disponível em /dfe/xml.

{
  "tipo": "completa",
  "chave": "43261039543895000146550010000001231123456789"
}

202 — Ciência registrada, mas a SEFAZ ainda não liberou o XML. Repita mais tarde.

{
  "tipo": "aguardando",
  "chave": "43261039543895000146550010000001231123456789"
}

422 — NOTA_DESCONHECIDA, NOTA_SEM_VALOR (cancelada ou denegada) ou recusa da SEFAZ com cStat/xMotivo.

{
  "erro": "Essa nota não está na lista. Busque as notas de novo.",
  "codigo": "NOTA_DESCONHECIDA"
}

GET/emitentes/:id/dfe/xmlBaixar o XML de uma nota recebidadfe

Chave com o escopo dfe. No painel, papel mínimo: leitor.

Parâmetros de consulta

chave (obrigatório) Chave de acesso, 44 dígitos.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/emitentes/<id>/dfe/xml" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — O nfeProc da nota do fornecedor.

404 — A nota ainda não tem XML na caixa: manifeste a ciência antes.

{
  "erro": "O XML desta nota ainda não está disponível.",
  "codigo": "xml_indisponivel"
}

Ingestão

POST/documentos/ingestaoRegistrar uma nota emitida fora da nuvemingestao

Para o sistema que emite localmente e quer a nota na conta. A chave de acesso impede duplicar; série e número são lidos dela. protocolo é obrigatório quando status é autorizada. O XML vai até 1 MB e precisa conter a chave.

Chave com o escopo ingestao. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/documentos/ingestao" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "clienteId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "modelo": "nfce",
  "ambiente": 1,
  "status": "autorizada",
  "chave": "43261039543895000146650010000001231123456789",
  "protocolo": "143260000012345",
  "emitidaEm": "2026-10-13T14:30:00-03:00",
  "valorTotal": 19.9,
  "xmlAutorizado": "<nfeProc …>…</nfeProc>"
}'

Respostas

201 — Registrada.

{
  "tipo": "registrada",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chave": "43261039543895000146550010000001231123456789"
}

200 — ja_registrada (mesma chave, mesmo status) ou atualizada (autorizada que chega como cancelada).

{
  "tipo": "ja_registrada",
  "documentoId": "0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11",
  "chave": "43261039543895000146550010000001231123456789"
}

409 — Mudança de status não permitida.

{
  "erro": "Transição de status não permitida para esta nota.",
  "codigo": "transicao_invalida"
}

POST/documentos/ingestao/loteRegistrar notas em loteingestao

Até 50 notas e 4 MB por chamada. Uma nota ruim não derruba as outras; reenviar o lote inteiro é seguro.

Chave com o escopo ingestao. No painel, papel mínimo: operador.

Exemplo de chamada

curl -X POST "https://fiscal.theordem.com.br/api/v1/documentos/ingestao/lote" \
  -H "Authorization: Bearer $TOF_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "documentos": [
    "(mesmo corpo da rota unitária)"
  ]
}'

Respostas

200 — resumo e resultados por índice.

{
  "resumo": {
    "total": 2,
    "registradas": 1,
    "jaRegistradas": 1,
    "atualizadas": 0,
    "erros": 0
  },
  "resultados": [
    "(um resultado por nota, na ordem enviada)"
  ]
}

Conta

GET/contaPlano, alçada e saldo da cotaemissao

Chave com o escopo emissao. No painel, papel mínimo: leitor.

Exemplo de chamada

curl -X GET "https://fiscal.theordem.com.br/api/v1/conta" \
  -H "Authorization: Bearer $TOF_CHAVE"

Respostas

200 — uso.saldoMensal é quanto ainda cabe na cota do mês (null = plano sem cota).

{
  "nome": "Conta Exemplo",
  "slug": "conta-exemplo",
  "alcadaValor": 100000,
  "plano": {
    "estado": "ativa",
    "validade": "2026-12-31",
    "maxEmitentes": 300,
    "maxUsuarios": 5,
    "cotaMensal": 10000
  },
  "uso": {
    "emitentes": 42,
    "usuarios": 3,
    "emissoesNoMes": 1730,
    "saldoMensal": 8270
  }
}