{"openapi":"3.1.0","info":{"title":"TheOrdem Fiscal — API de integração","version":"1","description":"Emissão de NF-e, NFC-e e NFS-e por chave de API. A chave pertence a uma conta e só faz o que os escopos dela permitem; o tenant vem sempre da chave, nunca do corpo. As chamadas partem de servidor: a API não tem CORS para integradores."},"servers":[{"url":"https://fiscal.theordem.com.br/api/v1"}],"tags":[{"name":"Emitentes"},{"name":"Emissão"},{"name":"Depois da emissão"},{"name":"Consultas"},{"name":"Notas recebidas"},{"name":"Ingestão"},{"name":"Conta"}],"paths":{"/emitentes":{"get":{"operationId":"getEmitentes","tags":["Emitentes"],"summary":"Listar emitentes","description":"Escopo da chave: `emitentes`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["emitentes"]}],"x-escopo":"emitentes","parameters":[{"name":"documento","in":"query","required":false,"description":"CNPJ ou CPF completo, com ou sem máscara. Filtra pela igualdade.","schema":{"type":"string"}},{"name":"busca","in":"query","required":false,"description":"Trecho da razão social, do nome fantasia ou início do documento.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"Itens por página (padrão 50).","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"`proximoCursor` da página anterior.","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de emitentes.","content":{"application/json":{"schema":{"type":"object"},"example":{"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":{"operationId":"postEmitentes","tags":["Emitentes"],"summary":"Cadastrar emitente","description":"O dígito verificador do CNPJ/CPF é validado. A produção nunca é liberada no cadastro.\n\nEscopo da chave: `emitentes`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["emitentes"]}],"x-escopo":"emitentes","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"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}}}}}}},"responses":{"201":{"description":"Criado.","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11"}}}},"409":{"description":"Documento já cadastrado na conta (traz o `id` do existente) ou limite de emitentes do plano.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Já existe um emitente com este documento nesta conta.","codigo":"documento_ja_cadastrado","id":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11"}}}}}}},"/emitentes/importacao":{"post":{"operationId":"postEmitentesImportacao","tags":["Emitentes"],"summary":"Cadastrar emitentes em lote","description":"Até 200 linhas por chamada; cada linha tem o seu resultado.\n\nEscopo da chave: `emitentes`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["emitentes"]}],"x-escopo":"emitentes","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"emitentes":[{"documento":"39543895000146","razaoSocial":"Empresa Exemplo LTDA"}]}}}},"responses":{"200":{"description":"Resultado por linha.","content":{"application/json":{"schema":{"type":"object"},"example":{"resumo":{"total":1,"criados":1,"jaExistentes":0,"erros":0},"resultados":[{"indice":0,"status":"criado","id":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11"}]}}}}}}},"/emitentes/{id}":{"get":{"operationId":"getEmitentesId","tags":["Emitentes"],"summary":"Detalhe do emitente","description":"Escopo da chave: `emitentes`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["emitentes"]}],"x-escopo":"emitentes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cadastro e `config`.","content":{"application/json":{"schema":{"type":"object"},"example":{"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":{"operationId":"patchEmitentesId","tags":["Emitentes"],"summary":"Atualizar emitente","description":"`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).\n\nEscopo da chave: `emitentes`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["emitentes"]}],"x-escopo":"emitentes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"config":{"nfe":{"producao":true}}}}}},"responses":{"200":{"description":"Atualizado.","content":{"application/json":{"schema":{"type":"object"},"example":{"atualizado":true}}}}}}},"/emitentes/{id}/certificado":{"post":{"operationId":"postEmitentesIdCertificado","tags":["Emitentes"],"summary":"Enviar o certificado A1","description":"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.\n\nEscopo da chave: `certificado`. Papel mínimo na sessão: admin.","security":[{"chaveDeApi":["certificado"]}],"x-escopo":"certificado","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"chavePem":"-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----","certPem":"-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----"}}}},"responses":{"201":{"description":"Guardado em custódia; só metadados voltam.","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11","fingerprintSha256":"06:42:56:…","titularCn":"EMPRESA EXEMPLO LTDA:39543895000146","naoDepois":"2027-09-15T18:40:13+00:00"}}}},"422":{"description":"Recusado: `chave_invalida`, `certificado_invalido`, `par_invalido`, `certificado_vencido`, `titular_nao_identificado` ou `titular_divergente`.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"O certificado é de outro CNPJ.","codigo":"titular_divergente"}}}}}},"get":{"operationId":"getEmitentesIdCertificado","tags":["Emitentes"],"summary":"Situação do certificado","description":"Escopo da chave: `emitentes`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["emitentes"]}],"x-escopo":"emitentes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Metadados do A1 ativo.","content":{"application/json":{"schema":{"type":"object"},"example":{"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":{"description":"Emitente sem certificado ativo.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/emitentes/{id}/numeracao":{"get":{"operationId":"getEmitentesIdNumeracao","tags":["Emitentes"],"summary":"Consultar a numeração de uma série","description":"Escopo da chave: `emitentes`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["emitentes"]}],"x-escopo":"emitentes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"modelo","in":"query","required":true,"description":"55 (NF-e) ou 65 (NFC-e).","schema":{"type":"string"}},{"name":"serie","in":"query","required":true,"description":"1 a 889.","schema":{"type":"string"}},{"name":"ambiente","in":"query","required":true,"description":"1 produção, 2 homologação.","schema":{"type":"string"}}],"responses":{"200":{"description":"Contador atual.","content":{"application/json":{"schema":{"type":"object"},"example":{"modelo":65,"serie":1,"ambiente":1,"ultimoNumero":482,"proximoNumero":483}}}}}},"put":{"operationId":"putEmitentesIdNumeracao","tags":["Emitentes"],"summary":"Informar a numeração inicial de uma série","description":"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.\n\nEscopo da chave: `emitentes`. Papel mínimo na sessão: admin.","security":[{"chaveDeApi":["emitentes"]}],"x-escopo":"emitentes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"modelo":65,"serie":1,"ambiente":1,"ultimoNumero":482}}}},"responses":{"200":{"description":"Contador posicionado.","content":{"application/json":{"schema":{"type":"object"},"example":{"modelo":65,"serie":1,"ambiente":1,"ultimoNumero":482,"proximoNumero":483}}}},"409":{"description":"O contador já passou do valor pedido.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"A numeração desta série já está em 500.","codigo":"numeracao_menor","modelo":65,"serie":1,"ambiente":1,"ultimoNumero":500,"proximoNumero":501}}}}}}},"/documentos/nfe":{"post":{"operationId":"postDocumentosNfe","tags":["Emissão"],"summary":"Emitir NF-e (modelo 55)","description":"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.\n\nEscopo da chave: `emissao`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["emissao"]}],"x-escopo":"emissao","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}},"responses":{"200":{"description":"Autorizada, ou `ja_emitida` quando a `idempotencyKey` já gerou esta nota.","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"autorizada","documentoId":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11","chaveAcesso":"43261039543895000146550010000001231123456789","numero":123,"protocolo":"143260000012345","autorizadaEm":"2026-10-13T14:30:07-03:00"}}}},"202":{"description":"Sem resposta da SEFAZ. Não é erro: a API segue conciliando a nota sozinha, e repetir com a mesma `idempotencyKey` devolve o desfecho.","content":{"application/json":{"schema":{"type":"object"},"example":{"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":{"description":"Outra chamada com a mesma `idempotencyKey` está em andamento.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Já existe uma emissão em andamento para esta chave.","codigo":"EMISSAO_EM_ANDAMENTO"}}}},"422":{"description":"Rejeição ou denegação da SEFAZ, ou regra fiscal da API (`NFE_NAO_CONFIGURADO`, `UF_NAO_SUPORTADA`).","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}}}},"/documentos/nfce":{"post":{"operationId":"postDocumentosNfce","tags":["Emissão"],"summary":"Emitir NFC-e (modelo 65)","description":"Mesmo corpo da NF-e; o destinatário é opcional. A resposta traz também `qrCode` e `urlChave`, para o cupom.\n\nEscopo da chave: `emissao`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["emissao"]}],"x-escopo":"emissao","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}},"responses":{"200":{"description":"Autorizada, ou `ja_emitida` quando a `idempotencyKey` já gerou esta nota.","content":{"application/json":{"schema":{"type":"object"},"example":{"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":{"description":"Sem resposta da SEFAZ. Não é erro: a API segue conciliando a nota sozinha, e repetir com a mesma `idempotencyKey` devolve o desfecho.","content":{"application/json":{"schema":{"type":"object"},"example":{"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":{"description":"Outra chamada com a mesma `idempotencyKey` está em andamento.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Já existe uma emissão em andamento para esta chave.","codigo":"EMISSAO_EM_ANDAMENTO"}}}},"422":{"description":"Rejeição ou denegação da SEFAZ, ou regra fiscal da API (`NFE_NAO_CONFIGURADO`, `UF_NAO_SUPORTADA`).","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}}}},"/documentos/nfse":{"post":{"operationId":"postDocumentosNfse","tags":["Emissão"],"summary":"Emitir NFS-e (padrão nacional)","description":"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.\n\nEscopo da chave: `emissao`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["emissao"]}],"x-escopo":"emissao","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}}},"responses":{"200":{"description":"Autorizada, ou `ja_emitida`.","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"autorizada","documentoId":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11","chaveAcesso":"4314407239543895000146000000000000126101234567890","numeroNfse":"12"}}}},"202":{"description":"Sem resposta da SEFIN: repita com a mesma `idempotencyKey`.","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"em_recuperacao","documentoId":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11","mensagem":"A SEFIN não respondeu."}}}},"422":{"description":"Rejeitada pela SEFIN.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Rejeitada pela SEFIN.","documentoId":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11","codigos":[{"codigo":"E0001","descricao":"…"}]}}}}}}},"/documentos/{id}/eventos":{"post":{"operationId":"postDocumentosIdEventos","tags":["Depois da emissão"],"summary":"Cancelar ou corrigir NF-e/NFC-e","description":"`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.\n\nEscopo da chave: `eventos`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["eventos"]}],"x-escopo":"eventos","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"cancelamento","justificativa":"Cliente desistiu da compra antes da entrega"}}}},"responses":{"200":{"description":"`cancelada`, `ja_cancelada` ou `corrigida` (com `sequencia`).","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"cancelada","chave":"43261039543895000146550010000001231123456789","protocolo":"243260000000001"}}}},"409":{"description":"Já há um evento em andamento para a nota.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Já existe uma operação em andamento.","codigo":"OPERACAO_EM_ANDAMENTO"}}}},"422":{"description":"Recusa da SEFAZ, com `cStat` e `xMotivo`.","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}}}},"/documentos/{id}/cancelamento":{"post":{"operationId":"postDocumentosIdCancelamento","tags":["Depois da emissão"],"summary":"Cancelar NFS-e","description":"Escopo da chave: `eventos`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["eventos"]}],"x-escopo":"eventos","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"motivo":1,"justificativa":"Serviço não prestado conforme combinado","tipo":"101101"}}}},"responses":{"200":{"description":"`cancelada`, ou `em_analise` quando o pedido vai à análise da prefeitura (`tipo: \"101103\"`).","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"cancelada","documentoId":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11"}}}}}}},"/emitentes/{id}/inutilizacao":{"post":{"operationId":"postEmitentesIdInutilizacao","tags":["Depois da emissão"],"summary":"Inutilizar uma faixa de números","description":"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.\n\nEscopo da chave: `eventos`. Papel mínimo na sessão: admin.","security":[{"chaveDeApi":["eventos"]}],"x-escopo":"eventos","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"modelo":55,"serie":1,"ambiente":2,"inicio":483,"fim":485,"justificativa":"Numeracao pulada por falha no sistema de origem"}}}},"responses":{"200":{"description":"`inutilizada`, ou `ja_inutilizada` na repetição do mesmo pedido.","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"inutilizada","modelo":55,"serie":1,"ambiente":2,"inicio":483,"fim":485,"protocolo":"143260000000100"}}}},"409":{"description":"Já há um pedido em andamento para a série.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Já existe uma inutilização em andamento para esta série.","codigo":"OPERACAO_EM_ANDAMENTO"}}}},"422":{"description":"`FAIXA_ALEM_DA_NUMERACAO`, `NFE_NAO_CONFIGURADO` ou recusa da SEFAZ com `cStat`/`xMotivo`.","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}}}},"/documentos/{id}/xml":{"get":{"operationId":"getDocumentosIdXml","tags":["Depois da emissão"],"summary":"Baixar o XML autorizado ou o XML de um evento","description":"Sem parâmetros: o `nfeProc` (NF-e/NFC-e) ou o XML da SEFIN (NFS-e). Com `evento`: o `procEventoNFe`.\n\nEscopo da chave: `leitura`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["leitura"]}],"x-escopo":"leitura","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"evento","in":"query","required":false,"description":"`cancelamento` ou `cce`.","schema":{"type":"string"}},{"name":"sequencia","in":"query","required":false,"description":"Sequência da carta de correção, 1 a 20 (padrão 1).","schema":{"type":"string"}}],"responses":{"200":{"description":"O XML, exatamente como foi guardado.","content":{"application/xml":{"schema":{"type":"string"}}}},"404":{"description":"Nota sem XML autorizado ou sem o evento pedido.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Nota sem XML autorizado.","codigo":"xml_indisponivel"}}}}}}},"/documentos/{id}/danfe":{"get":{"operationId":"getDocumentosIdDanfe","tags":["Depois da emissão"],"summary":"DANFE em PDF (NF-e e NFC-e)","description":"A4 para a NF-e, bobina de 80 mm para a NFC-e, desenhado a partir do XML autorizado. Nota cancelada sai marcada.\n\nEscopo da chave: `leitura`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["leitura"]}],"x-escopo":"leitura","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"O PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"A nota é NFS-e: use `/danfse`.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"O DANFE existe para NF-e e NFC-e.","codigo":"modelo_sem_danfe"}}}}}}},"/documentos/{id}/envio":{"post":{"operationId":"postDocumentosIdEnvio","tags":["Depois da emissão"],"summary":"Enviar a nota por e-mail ao destinatário","description":"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.\n\nEscopo da chave: `emissao`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["emissao"]}],"x-escopo":"emissao","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"email":"cliente@exemplo.com.br"}}}},"responses":{"200":{"description":"Aceito pelo provedor de e-mail.","content":{"application/json":{"schema":{"type":"object"},"example":{"enviado":true,"email":"cliente@exemplo.com.br","anexos":["nfe-43261039543895000146550010000001231123456789.xml","nfe-43261039543895000146550010000001231123456789.pdf"]}}}},"502":{"description":"O provedor de e-mail não aceitou o envio. Pode repetir.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"O e-mail não pôde ser enviado agora. Tente novamente em instantes.","codigo":"email_nao_enviado"}}}}}}},"/documentos/{id}/danfse":{"get":{"operationId":"getDocumentosIdDanfse","tags":["Depois da emissão"],"summary":"Dados do DANFSe (NFS-e)","description":"Dados estruturados para desenhar o DANFSe; não é PDF.\n\nEscopo da chave: `leitura`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["leitura"]}],"x-escopo":"leitura","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campos do DANFSe lidos do XML.","content":{"application/json":{"schema":{"type":"object"},"example":{"danfse":{"numero":"12","chaveAcesso":"…"}}}}}}}},"/documentos":{"get":{"operationId":"getDocumentos","tags":["Consultas"],"summary":"Listar e localizar notas","description":"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.\n\nEscopo da chave: `leitura`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["leitura"]}],"x-escopo":"leitura","parameters":[{"name":"chave","in":"query","required":false,"description":"Chave de acesso.","schema":{"type":"string"}},{"name":"idempotencyKey","in":"query","required":false,"description":"Exige `clienteId` e `modelo`.","schema":{"type":"string"}},{"name":"clienteId","in":"query","required":false,"description":"Emitente.","schema":{"type":"string"}},{"name":"modelo","in":"query","required":false,"description":"`nfe`, `nfce` ou `nfse`.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"`rascunho`, `assinada`, `transmitida`, `autorizada`, `rejeitada`, `cancelada` ou `erro`.","schema":{"type":"string"}},{"name":"origem","in":"query","required":false,"description":"`cloud` (emitida pela API) ou `ingestao`.","schema":{"type":"string"}},{"name":"de","in":"query","required":false,"description":"Data inicial, AAAA-MM-DD.","schema":{"type":"string"}},{"name":"ate","in":"query","required":false,"description":"Data final, AAAA-MM-DD.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"Itens por página (padrão 50).","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"`proximoCursor` da página anterior.","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de notas.","content":{"application/json":{"schema":{"type":"object"},"example":{"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}}}}}}},"/documentos/{id}":{"get":{"operationId":"getDocumentosId","tags":["Consultas"],"summary":"Detalhe da nota","description":"Inclui a linha do tempo dos eventos. Não devolve XML.\n\nEscopo da chave: `leitura`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["leitura"]}],"x-escopo":"leitura","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A nota.","content":{"application/json":{"schema":{"type":"object"},"example":{"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":[]}}}}}}},"/emitentes/{id}/dfe/busca":{"post":{"operationId":"postEmitentesIdDfeBusca","tags":["Notas recebidas"],"summary":"Buscar na SEFAZ as notas emitidas contra o CNPJ","description":"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.\n\nEscopo da chave: `dfe`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["dfe"]}],"x-escopo":"dfe","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Busca feita. `novas` é quantas notas entraram na caixa.","content":{"application/json":{"schema":{"type":"object"},"example":{"novas":3,"proximaConsulta":"2026-10-13T19:00:00.000Z"}}}},"409":{"description":"Já há uma busca em andamento para o emitente.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Já existe uma busca em andamento para este emitente.","codigo":"OPERACAO_EM_ANDAMENTO"}}}},"429":{"description":"Dentro da espera imposta pela SEFAZ.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"A SEFAZ só aceita uma nova busca depois deste horário.","codigo":"DFE_AGUARDE","proximaConsulta":"2026-10-13T19:00:00.000Z","tentarEmSegundos":1800}}}}}}},"/emitentes/{id}/dfe":{"get":{"operationId":"getEmitentesIdDfe","tags":["Notas recebidas"],"summary":"Listar as notas recebidas","description":"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).\n\nEscopo da chave: `dfe`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["dfe"]}],"x-escopo":"dfe","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Notas e horários de consulta.","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}}}},"/emitentes/{id}/dfe/ciencia":{"post":{"operationId":"postEmitentesIdDfeCiencia","tags":["Notas recebidas"],"summary":"Manifestar ciência de uma nota e trazer o XML","description":"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.\n\nEscopo da chave: `dfe`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["dfe"]}],"x-escopo":"dfe","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"chave":"43261039543895000146550010000001231123456789"}}}},"responses":{"200":{"description":"XML disponível em `/dfe/xml`.","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"completa","chave":"43261039543895000146550010000001231123456789"}}}},"202":{"description":"Ciência registrada, mas a SEFAZ ainda não liberou o XML. Repita mais tarde.","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"aguardando","chave":"43261039543895000146550010000001231123456789"}}}},"422":{"description":"`NOTA_DESCONHECIDA`, `NOTA_SEM_VALOR` (cancelada ou denegada) ou recusa da SEFAZ com `cStat`/`xMotivo`.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Essa nota não está na lista. Busque as notas de novo.","codigo":"NOTA_DESCONHECIDA"}}}}}}},"/emitentes/{id}/dfe/xml":{"get":{"operationId":"getEmitentesIdDfeXml","tags":["Notas recebidas"],"summary":"Baixar o XML de uma nota recebida","description":"Escopo da chave: `dfe`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["dfe"]}],"x-escopo":"dfe","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"chave","in":"query","required":true,"description":"Chave de acesso, 44 dígitos.","schema":{"type":"string"}}],"responses":{"200":{"description":"O `nfeProc` da nota do fornecedor.","content":{"application/xml":{"schema":{"type":"string"}}}},"404":{"description":"A nota ainda não tem XML na caixa: manifeste a ciência antes.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"O XML desta nota ainda não está disponível.","codigo":"xml_indisponivel"}}}}}}},"/documentos/ingestao":{"post":{"operationId":"postDocumentosIngestao","tags":["Ingestão"],"summary":"Registrar uma nota emitida fora da nuvem","description":"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.\n\nEscopo da chave: `ingestao`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["ingestao"]}],"x-escopo":"ingestao","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"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>"}}}},"responses":{"200":{"description":"`ja_registrada` (mesma chave, mesmo status) ou `atualizada` (autorizada que chega como cancelada).","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"ja_registrada","documentoId":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11","chave":"43261039543895000146550010000001231123456789"}}}},"201":{"description":"Registrada.","content":{"application/json":{"schema":{"type":"object"},"example":{"tipo":"registrada","documentoId":"0b9f6d3e-6f6b-4c1e-9d55-1d6d8f3a2c11","chave":"43261039543895000146550010000001231123456789"}}}},"409":{"description":"Mudança de status não permitida.","content":{"application/json":{"schema":{"type":"object"},"example":{"erro":"Transição de status não permitida para esta nota.","codigo":"transicao_invalida"}}}}}}},"/documentos/ingestao/lote":{"post":{"operationId":"postDocumentosIngestaoLote","tags":["Ingestão"],"summary":"Registrar notas em lote","description":"Até 50 notas e 4 MB por chamada. Uma nota ruim não derruba as outras; reenviar o lote inteiro é seguro.\n\nEscopo da chave: `ingestao`. Papel mínimo na sessão: operador.","security":[{"chaveDeApi":["ingestao"]}],"x-escopo":"ingestao","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"documentos":["(mesmo corpo da rota unitária)"]}}}},"responses":{"200":{"description":"`resumo` e `resultados` por índice.","content":{"application/json":{"schema":{"type":"object"},"example":{"resumo":{"total":2,"registradas":1,"jaRegistradas":1,"atualizadas":0,"erros":0},"resultados":["(um resultado por nota, na ordem enviada)"]}}}}}}},"/conta":{"get":{"operationId":"getConta","tags":["Conta"],"summary":"Plano, alçada e saldo da cota","description":"Escopo da chave: `emissao`. Papel mínimo na sessão: leitor.","security":[{"chaveDeApi":["emissao"]}],"x-escopo":"emissao","responses":{"200":{"description":"`uso.saldoMensal` é quanto ainda cabe na cota do mês (`null` = plano sem cota).","content":{"application/json":{"schema":{"type":"object"},"example":{"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}}}}}}}}},"components":{"securitySchemes":{"chaveDeApi":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer tof_live_…`. Escopos: `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)."}}}}