{ "openapi": "3.1.0", "info": { "title": "TenzanNFE API", "version": "v1", "summary": "Emissão e gestão de documentos fiscais eletrônicos brasileiros por API REST.", "description": "API REST para emitir e gerenciar documentos fiscais eletrônicos brasileiros (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e e NFCom), sem lidar com XML, certificado digital ou a Sefaz diretamente.\n\n## Autenticação\nToda chamada envia duas credenciais em conjunto: `X-Access-Key` (a sua conta) e `Authorization: Bearer ` (a empresa e o ambiente). Sem as duas, a resposta é `401`. A gestão de clientes usa só a Chave de Acesso; obter tokens exige também a Chave Restrita (`X-Restricted-Key`).\n\n## Ambientes\nO prefixo do token define o ambiente da Sefaz: `nfe_test_...` é homologação (sandbox) e `nfe_live_...` é produção. Não existe parâmetro de ambiente na requisição.\n\n## Processamento assíncrono\n`emit`, `cancel` e `correct` respondem `202 Accepted` assim que o documento entra na fila; isso não significa autorização. Consulte `GET /v1/{tipo}/{id}` até o `status` deixar de ser `PENDENTE`. Uma rejeição da Sefaz aparece nessa consulta (`rejectionReason`), não como erro HTTP. Inutilização e os demais eventos são síncronos.\n\n## Créditos\nSó a emissão consome crédito (NF-e 1, NFC-e 0,5, CT-e 1,5). Consultas, DANFE, cancelamento, inutilização e eventos não consomem.\n\nDocumentação completa: https://nfe.tenzanlabs.com/getting-started/introducao/", "termsOfService": "https://nfe.tenzanlabs.com/terms/", "contact": { "name": "Tenzan Labs", "url": "https://nfe.tenzanlabs.com/contact/", "email": "admin@tenzanlabs.com" } }, "servers": [ { "url": "https://app.nfe.tenzanlabs.com", "description": "API (o ambiente de homologação ou produção é definido pelo prefixo do token)" } ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "tags": [ { "name": "NF-e e NFC-e", "description": "Nota Fiscal Eletrônica (modelo 55) e Nota Fiscal de Consumidor Eletrônica (modelo 65)." }, { "name": "CT-e", "description": "Conhecimento de Transporte Eletrônico." }, { "name": "MDF-e", "description": "Manifesto Eletrônico de Documentos Fiscais." }, { "name": "NFCom", "description": "Nota Fiscal Fatura de Serviço de Comunicação Eletrônica." }, { "name": "DC-e", "description": "Declaração de Conteúdo Eletrônica." }, { "name": "NFS-e", "description": "Nota Fiscal de Serviço Eletrônica (padrão nacional)." }, { "name": "Clientes", "description": "Gestão dos clientes (tenants) de uma conta de desenvolvedor: certificado digital, configuração fiscal e tokens." }, { "name": "Geral", "description": "Operações comuns a todos os tipos de documento." } ], "externalDocs": { "description": "Documentação da API", "url": "https://nfe.tenzanlabs.com/getting-started/introducao/" }, "paths": { "/v1/nfe/emit": { "post": { "operationId": "nfeEmitir", "summary": "Emitir NFe / NFCe", "description": "`POST /v1/nfe/emit` emite uma NF-e (`mod: \"55\"`). Os dois modelos compartilham exatamente o mesmo schema de campos.\n\n> **Emitindo NFC-e.** Para emitir uma NFC-e, use `POST /v1/nfc-e/emit` com `mod: \"65\"` em vez de `/v1/nfe/emit`. O endpoint valida que o `mod` do corpo bate com o tipo da rota — enviar `mod: \"65\"` para `/v1/nfe/emit` (ou vice-versa) retorna `400 Bad Request`.\n\n> **Endpoint assíncrono.** Esta chamada retorna `202 Accepted` assim que o documento entra na fila de processamento — não espera pela SEFAZ. Uma rejeição da SEFAZ (schema inválido, duplicidade, regra de negócio, etc.) **não** vira erro HTTP nesta chamada: ela só aparece depois, consultando [`GET /v1/nfe/{id}`](https://nfe.tenzanlabs.com/reference/nfe/consultar/) com o `invoiceId` retornado aqui. Use esse endpoint para fazer polling até o `status` deixar de ser `PENDENTE`.\n\n> **Campos pouco óbvios sempre obrigatórios.** Além dos campos de identificação, o schema hoje também exige `modalidade_frete`, `veiculo_placa` e `agropecuario_tipo_guia` mesmo quando a operação não envolve transporte de carga própria ou produto agropecuário — nesses casos, envie `modalidade_frete: \"9\"` (sem frete) e os outros dois como string vazia.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/emitir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mod": { "type": "string", "enum": [ "55" ], "description": "Modelo do documento: `55` para NF-e, `65` para NFC-e." }, "natureza_operacao": { "type": "string", "description": "Descrição da natureza da operação." }, "data_emissao": { "type": "string", "description": "Data e hora de emissão (ISO 8601)." }, "tipo_documento": { "type": "string", "enum": [ "0", "1" ], "description": "0: Nota de entrada · 1: Nota de saída." }, "local_destino": { "type": "string", "enum": [ "1", "2", "3" ], "description": "1: Operação interna · 2: Interestadual · 3: Com o exterior." }, "finalidade_emissao": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6" ], "description": "1: Normal · 2: Complementar · 3: Ajuste · 4: Devolução · 5/6: Nota de crédito/débito (Reforma Tributária)." }, "consumidor_final": { "type": "string", "enum": [ "0", "1" ], "description": "0: Normal · 1: Consumidor final." }, "presenca_comprador": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "9" ], "description": "Indicador de presença do comprador — ver listagem completa de campos para o significado de cada código." }, "cnpj_emitente": { "type": [ "string", "number" ], "description": "CNPJ da empresa emitente." }, "inscricao_estadual_emitente": { "type": "string", "description": "Inscrição Estadual da empresa emitente." }, "itens": { "type": "array", "description": "Lista de itens da nota.", "items": { "type": "object", "properties": { "codigo_produto": { "type": "string", "description": "Código interno do produto." }, "descricao": { "type": "string", "description": "Descrição do produto." }, "cfop": { "type": [ "string", "number" ], "description": "CFOP do produto." }, "unidade_comercial": { "type": "string", "description": "Unidade comercial (ex: `UN`, `KG`)." }, "quantidade_comercial": { "type": [ "string", "number" ], "description": "Quantidade comercial." }, "valor_unitario_comercial": { "type": [ "string", "number" ], "description": "Valor unitário comercial." }, "icms_origem": { "type": "string", "description": "Origem da mercadoria — ver listagem completa de campos." }, "icms_situacao_tributaria": { "type": "string", "description": "Situação tributária do ICMS (CST/CSOSN) — ver listagem completa de campos." } }, "required": [ "codigo_produto", "descricao", "cfop", "unidade_comercial", "quantidade_comercial", "valor_unitario_comercial", "icms_origem", "icms_situacao_tributaria" ] } } }, "additionalProperties": true, "required": [ "mod", "natureza_operacao", "data_emissao", "tipo_documento", "local_destino", "finalidade_emissao", "consumidor_final", "presenca_comprador", "cnpj_emitente", "inscricao_estadual_emitente", "itens" ] }, "example": { "mod": "55", "natureza_operacao": "Venda de Mercadoria", "data_emissao": "2026-08-19T12:00:00-03:00", "tipo_documento": "1", "local_destino": "1", "finalidade_emissao": "1", "consumidor_final": "1", "presenca_comprador": "1", "modalidade_frete": "9", "veiculo_placa": "", "agropecuario_tipo_guia": "", "cnpj_emitente": "12345678000199", "inscricao_estadual_emitente": "123456789", "nome_destinatario": "João da Silva", "cpf_destinatario": "11122233344", "itens": [ { "codigo_produto": "123", "descricao": "Caneta Azul", "codigo_ncm": "96081000", "cfop": "5102", "unidade_comercial": "UN", "quantidade_comercial": 10, "valor_unitario_comercial": 2.5, "icms_origem": "0", "icms_situacao_tributaria": "102", "pis_situacao_tributaria": "07", "cofins_situacao_tributaria": "07" } ] } } }, "description": "Só os campos essenciais estão descritos aqui; os demais campos opcionais aceitos estão na [listagem completa](https://nfe.tenzanlabs.com/reference/nfe/campos/)." }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que o documento entrou na fila de processamento." }, "invoiceId": { "type": "string", "description": "UUID interno do documento — use nas chamadas de [consulta](https://nfe.tenzanlabs.com/reference/nfe/consultar/), [cancelamento](https://nfe.tenzanlabs.com/reference/nfe/cancelar/) e [correção](https://nfe.tenzanlabs.com/reference/nfe/corrigir/)." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal, quando já pode ser calculada no momento do enfileiramento." } } }, "example": { "message": "Documento enfileirado para processamento", "invoiceId": "35f0a1b2-...", "accessKey": "35260812345678000199550010000000011000000018" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfc-e/emit": { "post": { "operationId": "nfceEmitir", "summary": "Emitir NFC-e", "description": "Mesmo contrato de `POST /v1/nfe/emit`, para NFC-e (`mod` 65): mesmos parâmetros, mesmas respostas e mesmos erros.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/emitir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mod": { "type": "string", "enum": [ "65" ], "description": "Modelo do documento: `55` para NF-e, `65` para NFC-e." }, "natureza_operacao": { "type": "string", "description": "Descrição da natureza da operação." }, "data_emissao": { "type": "string", "description": "Data e hora de emissão (ISO 8601)." }, "tipo_documento": { "type": "string", "enum": [ "0", "1" ], "description": "0: Nota de entrada · 1: Nota de saída." }, "local_destino": { "type": "string", "enum": [ "1", "2", "3" ], "description": "1: Operação interna · 2: Interestadual · 3: Com o exterior." }, "finalidade_emissao": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6" ], "description": "1: Normal · 2: Complementar · 3: Ajuste · 4: Devolução · 5/6: Nota de crédito/débito (Reforma Tributária)." }, "consumidor_final": { "type": "string", "enum": [ "0", "1" ], "description": "0: Normal · 1: Consumidor final." }, "presenca_comprador": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "9" ], "description": "Indicador de presença do comprador — ver listagem completa de campos para o significado de cada código." }, "cnpj_emitente": { "type": [ "string", "number" ], "description": "CNPJ da empresa emitente." }, "inscricao_estadual_emitente": { "type": "string", "description": "Inscrição Estadual da empresa emitente." }, "itens": { "type": "array", "description": "Lista de itens da nota.", "items": { "type": "object", "properties": { "codigo_produto": { "type": "string", "description": "Código interno do produto." }, "descricao": { "type": "string", "description": "Descrição do produto." }, "cfop": { "type": [ "string", "number" ], "description": "CFOP do produto." }, "unidade_comercial": { "type": "string", "description": "Unidade comercial (ex: `UN`, `KG`)." }, "quantidade_comercial": { "type": [ "string", "number" ], "description": "Quantidade comercial." }, "valor_unitario_comercial": { "type": [ "string", "number" ], "description": "Valor unitário comercial." }, "icms_origem": { "type": "string", "description": "Origem da mercadoria — ver listagem completa de campos." }, "icms_situacao_tributaria": { "type": "string", "description": "Situação tributária do ICMS (CST/CSOSN) — ver listagem completa de campos." } }, "required": [ "codigo_produto", "descricao", "cfop", "unidade_comercial", "quantidade_comercial", "valor_unitario_comercial", "icms_origem", "icms_situacao_tributaria" ] } } }, "additionalProperties": true, "required": [ "mod", "natureza_operacao", "data_emissao", "tipo_documento", "local_destino", "finalidade_emissao", "consumidor_final", "presenca_comprador", "cnpj_emitente", "inscricao_estadual_emitente", "itens" ] }, "example": { "mod": "65", "natureza_operacao": "Venda de Mercadoria", "data_emissao": "2026-08-19T12:00:00-03:00", "tipo_documento": "1", "local_destino": "1", "finalidade_emissao": "1", "consumidor_final": "1", "presenca_comprador": "1", "modalidade_frete": "9", "veiculo_placa": "", "agropecuario_tipo_guia": "", "cnpj_emitente": "12345678000199", "inscricao_estadual_emitente": "123456789", "nome_destinatario": "João da Silva", "cpf_destinatario": "11122233344", "itens": [ { "codigo_produto": "123", "descricao": "Caneta Azul", "codigo_ncm": "96081000", "cfop": "5102", "unidade_comercial": "UN", "quantidade_comercial": 10, "valor_unitario_comercial": 2.5, "icms_origem": "0", "icms_situacao_tributaria": "102", "pis_situacao_tributaria": "07", "cofins_situacao_tributaria": "07" } ] } } }, "description": "Só os campos essenciais estão descritos aqui; os demais campos opcionais aceitos estão na [listagem completa](https://nfe.tenzanlabs.com/reference/nfe/campos/)." }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que o documento entrou na fila de processamento." }, "invoiceId": { "type": "string", "description": "UUID interno do documento — use nas chamadas de [consulta](https://nfe.tenzanlabs.com/reference/nfe/consultar/), [cancelamento](https://nfe.tenzanlabs.com/reference/nfe/cancelar/) e [correção](https://nfe.tenzanlabs.com/reference/nfe/corrigir/)." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal, quando já pode ser calculada no momento do enfileiramento." } } }, "example": { "message": "Documento enfileirado para processamento", "invoiceId": "35f0a1b2-...", "accessKey": "35260812345678000199550010000000011000000018" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/{id}": { "get": { "operationId": "nfeConsultar", "summary": "Consultar NFe / NFCe", "description": "Consulta o status atual de um documento fiscal a partir do seu `invoiceId` (o UUID retornado em `invoiceId` na [emissão](https://nfe.tenzanlabs.com/reference/nfe/emitir/)). Não recebe corpo nem query string — o único parâmetro é o `id` na própria URL.\n\nUse este endpoint para fazer **polling** depois de [emitir](https://nfe.tenzanlabs.com/reference/nfe/emitir/), [cancelar](https://nfe.tenzanlabs.com/reference/nfe/cancelar/) ou [corrigir](https://nfe.tenzanlabs.com/reference/nfe/corrigir/) um documento: essas três operações são assíncronas (retornam `202 Accepted` antes de qualquer confirmação da SEFAZ), então é aqui que você descobre se o documento foi de fato autorizado, cancelado ou rejeitado.\n\n> **Consultando NFC-e.** Se o documento for uma NFC-e, use `GET /v1/nfc-e/{id}` em vez de `/v1/nfe/{id}` — a resposta é idêntica. O mesmo endpoint de consulta existe em todos os namespaces (`/v1/cte/{id}`, `/v1/mdfe/{id}`, etc.).", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/consultar/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID do documento." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal." }, "status": { "type": "string", "enum": [ "PENDENTE", "AUTORIZADA", "REJEITADA", "CANCELADA", "ENCERRADA", "ERRO_TECNICO" ], "description": "Status atual do processamento." }, "protocolNumber": { "type": "string", "description": "Número de protocolo de autorização retornado pela SEFAZ. Presente quando `status` é `AUTORIZADA` (ou posterior)." }, "rejectionReason": { "type": "string", "description": "Motivo da rejeição, quando `status` é `REJEITADA`." }, "updatedAt": { "type": "string", "description": "Data/hora da última atualização do status (ISO 8601)." }, "qrCodeUrl": { "type": "string", "description": "URL do QR Code (NFC-e/NFCom, quando aplicável)." }, "events": { "type": "array", "description": "Histórico de eventos síncronos já registrados no documento (encerramento de MDF-e, CC-e, cancelamentos, etc)." } } }, "example": { "id": "35f0a1b2-...", "accessKey": "35260812345678000199550010000000011000000018", "status": "AUTORIZADA", "protocolNumber": "135260000123456", "updatedAt": "2026-08-19T15:04:32.000Z", "qrCodeUrl": "https://www.homologacao.nfce.fazenda.sp.gov.br/...", "events": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfc-e/{id}": { "get": { "operationId": "nfceConsultar", "summary": "Consultar NFC-e", "description": "Mesmo contrato de `GET /v1/nfe/{id}`, para NFC-e (`mod` 65): mesmos parâmetros, mesmas respostas e mesmos erros.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/consultar/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID do documento." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal." }, "status": { "type": "string", "enum": [ "PENDENTE", "AUTORIZADA", "REJEITADA", "CANCELADA", "ENCERRADA", "ERRO_TECNICO" ], "description": "Status atual do processamento." }, "protocolNumber": { "type": "string", "description": "Número de protocolo de autorização retornado pela SEFAZ. Presente quando `status` é `AUTORIZADA` (ou posterior)." }, "rejectionReason": { "type": "string", "description": "Motivo da rejeição, quando `status` é `REJEITADA`." }, "updatedAt": { "type": "string", "description": "Data/hora da última atualização do status (ISO 8601)." }, "qrCodeUrl": { "type": "string", "description": "URL do QR Code (NFC-e/NFCom, quando aplicável)." }, "events": { "type": "array", "description": "Histórico de eventos síncronos já registrados no documento (encerramento de MDF-e, CC-e, cancelamentos, etc)." } } }, "example": { "id": "35f0a1b2-...", "accessKey": "35260812345678000199550010000000011000000018", "status": "AUTORIZADA", "protocolNumber": "135260000123456", "updatedAt": "2026-08-19T15:04:32.000Z", "qrCodeUrl": "https://www.homologacao.nfce.fazenda.sp.gov.br/...", "events": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/{id}/cancel": { "post": { "operationId": "nfeCancelar", "summary": "Cancelar NFe / NFCe", "description": "Cancela um documento fiscal já **autorizado**. Assim como a emissão, o cancelamento é **assíncrono**: a resposta `202 Accepted` só confirma que a solicitação entrou na fila, não que a SEFAZ já aceitou o cancelamento. Consulte [`GET /v1/nfe/{id}`](https://nfe.tenzanlabs.com/reference/nfe/consultar/) até o `status` mudar para `CANCELADA` (ou permanecer `AUTORIZADA`, se a SEFAZ rejeitar o cancelamento).\n\n> **Cancelando NFC-e.** Se o documento for uma NFC-e, use `POST /v1/nfc-e/{id}/cancel` em vez de `/v1/nfe/{id}/cancel` — o restante do contrato é idêntico. O mesmo endpoint de cancelamento existe em todos os namespaces (`/v1/cte/{id}/cancel`, `/v1/mdfe/{id}/cancel`, etc.).\n\n> **Prazo legal.** O cancelamento de NF-e/NFC-e/CT-e/MDF-e só é aceito pela SEFAZ dentro do prazo legal — normalmente **24 horas** após a autorização (o prazo exato varia por UF e modelo de documento). Fora desse prazo, use a [Carta de Correção](https://nfe.tenzanlabs.com/reference/nfe/corrigir/) para ajustes que não alterem valores, tributação, dados cadastrais das partes ou a data de emissão.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/cancelar/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Justificativa do cancelamento (mínimo de caracteres exigido pela SEFAZ, geralmente 15)." } }, "required": [ "reason" ] }, "example": { "reason": "Erro na descrição do produto" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que a solicitação de cancelamento entrou na fila de processamento." } } }, "example": { "message": "Cancelamento enfileirado para processamento" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfc-e/{id}/cancel": { "post": { "operationId": "nfceCancelar", "summary": "Cancelar NFC-e", "description": "Mesmo contrato de `POST /v1/nfe/{id}/cancel`, para NFC-e (`mod` 65): mesmos parâmetros, mesmas respostas e mesmos erros.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/cancelar/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Justificativa do cancelamento (mínimo de caracteres exigido pela SEFAZ, geralmente 15)." } }, "required": [ "reason" ] }, "example": { "reason": "Erro na descrição do produto" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que a solicitação de cancelamento entrou na fila de processamento." } } }, "example": { "message": "Cancelamento enfileirado para processamento" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/{id}/correct": { "post": { "operationId": "nfeCorrigir", "summary": "Corrigir NFe / NFCe", "description": "Emite uma **Carta de Correção Eletrônica (CC-e)** para um documento **autorizado**, registrando um ajuste que não altere valores da operação, tributação, dados cadastrais que impliquem mudança do remetente/destinatário, data de emissão ou de saída/entrada da mercadoria. Assim como emissão e cancelamento, é uma operação **assíncrona**: a resposta `202 Accepted` apenas confirma o enfileiramento — consulte [`GET /v1/nfe/{id}`](https://nfe.tenzanlabs.com/reference/nfe/consultar/) e o campo `events` para acompanhar o resultado.\n\nSó se aplica a documentos com `mod` **55** (NF-e) ou **65** (NFC-e) que já estejam `AUTORIZADA`.\n\n> **Corrigindo NFC-e.** Se o documento for uma NFC-e, use `POST /v1/nfc-e/{id}/correct` em vez de `/v1/nfe/{id}/correct` — o restante do contrato é idêntico.\n\n> **O que a CC-e não pode corrigir.** A SEFAZ rejeita CC-e que altere valores de itens/impostos, CFOP, dados que identifiquem o emitente ou destinatário, ou a data de emissão. Para esses casos, o caminho é [cancelar](https://nfe.tenzanlabs.com/reference/nfe/cancelar/) (dentro do prazo legal) e emitir um novo documento.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/corrigir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "correctionText": { "type": "string", "description": "Texto da correção. Deve ser objetivo e descrever exatamente o que está sendo corrigido (mínimo de caracteres exigido pela SEFAZ, geralmente 15)." } }, "required": [ "correctionText" ] }, "example": { "correctionText": "Correção do endereço de entrega do destinatário para Rua das Flores, 123" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que a CC-e entrou na fila de processamento." } } }, "example": { "message": "Correção enfileirada para processamento" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfc-e/{id}/correct": { "post": { "operationId": "nfceCorrigir", "summary": "Corrigir NFC-e", "description": "Mesmo contrato de `POST /v1/nfe/{id}/correct`, para NFC-e (`mod` 65): mesmos parâmetros, mesmas respostas e mesmos erros.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/corrigir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "correctionText": { "type": "string", "description": "Texto da correção. Deve ser objetivo e descrever exatamente o que está sendo corrigido (mínimo de caracteres exigido pela SEFAZ, geralmente 15)." } }, "required": [ "correctionText" ] }, "example": { "correctionText": "Correção do endereço de entrega do destinatário para Rua das Flores, 123" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que a CC-e entrou na fila de processamento." } } }, "example": { "message": "Correção enfileirada para processamento" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/{id}/ator-interessado": { "post": { "operationId": "nfeAtorInteressado", "summary": "Registrar Ator Interessado", "description": "Registra o **Ator Interessado** (evento **110150**) em um documento autorizado, indicando uma pessoa física ou jurídica com interesse no documento fiscal (por exemplo, uma transportadora ou intermediador de negociação) além do emitente e do destinatário. O evento é roteado via **Ambiente Nacional**.\n\nSó se aplica a documentos com `mod` **55** (NF-e) ou **65** (NFC-e) que já estejam `AUTORIZADA`. O registro pode ser feito em até **6 meses** após a autorização do documento.\n\n> **Registrando em NFC-e.** Se o documento for uma NFC-e, use `POST /v1/nfc-e/{id}/ator-interessado` em vez de `/v1/nfe/{id}/ator-interessado` — o restante do contrato é idêntico.\n\nEsse é um evento **síncrono** — a resposta HTTP já traz o resultado da SEFAZ, sem necessidade de polling.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/ator-interessado/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cpf": { "type": "string", "description": "CPF do ator interessado. Informe `cpf` ou `cnpj`, nunca os dois." }, "cnpj": { "type": "string", "description": "CNPJ do ator interessado. Informe `cpf` ou `cnpj`, nunca os dois." }, "permite_autorizacao_terceiros": { "type": "boolean", "description": "Indica se o ator interessado tem permissão para autorizar terceiros a acessar o documento fiscal." } } }, "example": { "cnpj": "12345678000199", "permite_autorizacao_terceiros": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "autorizado", "erro_autorizacao" ], "description": "Resultado do registro junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml_evento_ator_interessado": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." }, "numero_evento_ator_interessado": { "type": "number", "description": "Número sequencial do evento de Ator Interessado registrado para este documento." } } }, "example": { "status": "autorizado", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao documento fiscal eletrônico", "caminho_xml_evento_ator_interessado": "https://storage.../evento-ator-interessado.xml", "numero_evento_ator_interessado": 1 } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "autorizado", "erro_autorizacao" ], "description": "Resultado do registro junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml_evento_ator_interessado": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." }, "numero_evento_ator_interessado": { "type": "number", "description": "Número sequencial do evento de Ator Interessado registrado para este documento." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/{id}/insucesso-entrega": { "post": { "operationId": "nfeInsucessoEntrega", "summary": "Insucesso na Entrega", "description": "Registra o evento de **Insucesso na Entrega** (evento **110192**) de uma NF-e, quando a mercadoria não pôde ser entregue ao destinatário. O evento é roteado via **SVRS** (`cOrgao=92`).\n\nSó se aplica a documentos com `mod` **55** (NF-e) que já estejam `AUTORIZADA`.\n\nEsse é um evento **síncrono** — a resposta HTTP já traz o resultado da SEFAZ, sem necessidade de polling.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/insucesso-entrega/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data_tentativa_entrega": { "type": "string", "description": "Data e hora da tentativa de entrega (formato ISO 8601, com timezone)." }, "numero_tentativas": { "type": "number", "description": "Número de tentativas de entrega já realizadas." }, "motivo_insucesso": { "type": "number", "enum": [ 1, 2, 3, 4 ], "description": "Motivo do insucesso: `1` Destinatário ausente, `2` Recusado, `3` Endereço não localizado, `4` Outros." }, "justificativa_insucesso": { "type": "string", "description": "Justificativa do insucesso. Obrigatório quando `motivo_insucesso` for `4`." }, "latitude_entrega": { "type": [ "string", "number" ], "description": "Latitude do local da tentativa de entrega." }, "longitude_entrega": { "type": [ "string", "number" ], "description": "Longitude do local da tentativa de entrega." }, "hash_tentativa_entrega": { "type": "string", "description": "Hash que identifica unicamente a tentativa de entrega." }, "data_hash_tentativa": { "type": "string", "description": "Data de geração do `hash_tentativa_entrega`." } }, "required": [ "data_tentativa_entrega", "motivo_insucesso", "hash_tentativa_entrega" ] }, "example": { "data_tentativa_entrega": "2026-08-19T14:30:00-03:00", "numero_tentativas": 1, "motivo_insucesso": 1, "hash_tentativa_entrega": "a1b2c3d4e5f6" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "autorizado", "erro_autorizacao" ], "description": "Resultado do registro junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml_insucesso_entrega": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." }, "numero_insucesso_entrega": { "type": "number", "description": "Número sequencial do evento de Insucesso na Entrega registrado para este documento." } } }, "example": { "status": "autorizado", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao documento fiscal eletrônico", "caminho_xml_insucesso_entrega": "https://storage.../evento-insucesso-entrega.xml", "numero_insucesso_entrega": 1 } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "autorizado", "erro_autorizacao" ], "description": "Resultado do registro junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml_insucesso_entrega": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." }, "numero_insucesso_entrega": { "type": "number", "description": "Número sequencial do evento de Insucesso na Entrega registrado para este documento." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "nfeInsucessoEntregaDelete", "summary": "Cancelar insucesso de entrega", "description": "Cancela o evento de Insucesso na Entrega (evento **110193**) autorizado mais recentemente para este documento.\n\n> **Sem parâmetros.** Esta chamada não recebe corpo nem número de evento: ela cancela automaticamente o **último** Insucesso na Entrega autorizado registrado neste documento.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/insucesso-entrega/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "autorizado", "erro_autorizacao" ], "description": "Resultado do cancelamento junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml_cancelamento_insucesso_entrega": { "type": "string", "description": "URL pública do XML do evento de cancelamento, quando autorizado." }, "numero_cancelamento_insucesso_entrega": { "type": "number", "description": "Número sequencial do evento de cancelamento registrado para este documento." } } }, "example": { "status": "autorizado", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao documento fiscal eletrônico", "caminho_xml_cancelamento_insucesso_entrega": "https://storage.../evento-cancelamento-insucesso-entrega.xml", "numero_cancelamento_insucesso_entrega": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/{id}/econf": { "post": { "operationId": "nfeEconf", "summary": "Conciliação Financeira (e-CONF)", "description": "Registra o evento de **Conciliação Financeira / e-CONF** (Nota Técnica 2024.002) de uma NF-e, detalhando os pagamentos efetivamente recebidos pelo emitente para o documento. O evento é roteado via **SVRS** (`cOrgao=92`).\n\nSó se aplica a documentos com `mod` **55** (NF-e) que já estejam `AUTORIZADA`.\n\nEsse é um evento **síncrono** — a resposta HTTP já traz o resultado da SEFAZ, sem necessidade de polling.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/econf/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "detalhes_pagamento": { "type": "array", "description": "Lista dos pagamentos recebidos referentes ao documento fiscal.", "items": { "type": "object", "properties": { "indicador_pagamento": { "type": [ "string", "number" ], "description": "Indicador da forma de integração do pagamento (à vista, financiado, etc.)." }, "forma_pagamento": { "type": [ "string", "number" ], "description": "Código da forma de pagamento (tabela SEFAZ, ex.: `17` para pagamento eletrônico não informado)." }, "descricao_pagamento": { "type": "string", "description": "Descrição livre da forma de pagamento." }, "valor_pagamento": { "type": [ "string", "number" ], "description": "Valor do pagamento." }, "data_pagamento": { "type": "string", "description": "Data do pagamento (formato `AAAA-MM-DD`)." }, "cnpj_transacional": { "type": "string", "description": "CNPJ da instituição transacional (adquirente/subadquirente)." }, "uf_transacional": { "type": "string", "description": "UF da instituição transacional." }, "cnpj_instituicao_financeira": { "type": "string", "description": "CNPJ da instituição financeira responsável pelo pagamento." }, "bandeira_operadora": { "type": "string", "description": "Bandeira da operadora do cartão, quando aplicável." }, "numero_autorizacao": { "type": "string", "description": "Número de autorização da transação." }, "cnpj_beneficiario": { "type": "string", "description": "CNPJ do beneficiário do pagamento." }, "uf_beneficiario": { "type": "string", "description": "UF do beneficiário do pagamento." } }, "required": [ "forma_pagamento", "valor_pagamento", "data_pagamento" ] } } }, "required": [ "detalhes_pagamento" ] }, "example": { "detalhes_pagamento": [ { "forma_pagamento": "17", "valor_pagamento": "150.00", "data_pagamento": "2026-08-19" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "autorizado", "erro_autorizacao" ], "description": "Resultado do registro junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml_conciliacao_financeira": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." }, "numero_conciliacao_financeira": { "type": "number", "description": "Número sequencial do evento de e-CONF registrado para este documento." }, "numero_protocolo": { "type": "string", "description": "Número de protocolo do e-CONF, usado para consultá-lo ou cancelá-lo depois." } } }, "example": { "status": "autorizado", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao documento fiscal eletrônico", "caminho_xml_conciliacao_financeira": "https://storage.../evento-econf.xml", "numero_conciliacao_financeira": 1, "numero_protocolo": "192260000012345" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "autorizado", "erro_autorizacao" ], "description": "Resultado do registro junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml_conciliacao_financeira": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." }, "numero_conciliacao_financeira": { "type": "number", "description": "Número sequencial do evento de e-CONF registrado para este documento." }, "numero_protocolo": { "type": "string", "description": "Número de protocolo do e-CONF, usado para consultá-lo ou cancelá-lo depois." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/{id}/econf/{numeroProtocolo}": { "get": { "operationId": "nfeEconfGet", "summary": "Consultar e-CONF", "description": "Consulta um e-CONF já registrado a partir do seu número de protocolo.\n\n> **Consulta local.** Esta chamada não bate novamente na SEFAZ — ela apenas busca, na sua base local, o evento de e-CONF já registrado com o `numeroProtocolo` informado.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." }, { "name": "numeroProtocolo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Número de protocolo do e-CONF (`numero_protocolo` retornado no registro)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/econf/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status do e-CONF registrado." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`) no momento do registro." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`) no momento do registro." }, "numero_protocolo": { "type": "string", "description": "Número de protocolo do e-CONF consultado." } } }, "example": { "status": "autorizado", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao documento fiscal eletrônico", "numero_protocolo": "192260000012345" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "nfeEconfDelete", "summary": "Cancelar e-CONF", "description": "Cancela o e-CONF (evento **110751**) identificado pelo `numeroProtocolo`.\n\n> **Sem corpo.** Esta chamada não recebe corpo — o `numeroProtocolo` na URL já identifica de forma única qual e-CONF será cancelado.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." }, { "name": "numeroProtocolo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Número de protocolo do e-CONF (`numero_protocolo` retornado no registro)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/econf/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "autorizado", "erro_autorizacao" ], "description": "Resultado do cancelamento junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml_cancelamento_conciliacao_financeira": { "type": "string", "description": "URL pública do XML do evento de cancelamento, quando autorizado." }, "numero_cancelamento_conciliacao_financeira": { "type": "number", "description": "Número sequencial do evento de cancelamento registrado para este documento." } } }, "example": { "status": "autorizado", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao documento fiscal eletrônico", "caminho_xml_cancelamento_conciliacao_financeira": "https://storage.../evento-cancelamento-econf.xml", "numero_cancelamento_conciliacao_financeira": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/inutilize": { "post": { "operationId": "nfeInutilizar", "summary": "Inutilizar Numeração", "description": "Inutiliza uma faixa de numeração de documentos fiscais junto à SEFAZ. Use este endpoint quando o sistema emissor pulou numeração (por exemplo, por uma falha antes da emissão) — inutilizar a faixa evita autuação por numeração sem justificativa.\n\nDiferente dos demais eventos deste catálogo, este endpoint é **síncrono desde sempre**: a chamada só retorna depois que a SEFAZ processa o pedido.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/inutilizar/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ano": { "type": "number", "description": "Ano de emissão da faixa a inutilizar (4 dígitos)." }, "serie": { "type": "number", "description": "Série do documento fiscal." }, "inicio": { "type": "number", "description": "Número inicial da faixa a inutilizar." }, "fim": { "type": "number", "description": "Número final da faixa a inutilizar." }, "justificativa": { "type": "string", "description": "Justificativa da inutilização. Mínimo de **15 caracteres**." }, "mod": { "type": "string", "default": "55", "description": "Modelo do documento fiscal." }, "cnpj": { "type": "string", "description": "CNPJ do emitente. Quando omitido, usa o CNPJ configurado no tenant." } }, "required": [ "ano", "serie", "inicio", "fim", "justificativa" ] }, "example": { "ano": 2026, "serie": 1, "inicio": 101, "fim": 105, "justificativa": "Numeração pulada por falha no sistema emissor", "mod": "55" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cStat": { "type": "string", "description": "Código de status retornado pela SEFAZ." }, "xMotivo": { "type": "string", "description": "Mensagem retornada pela SEFAZ descrevendo o resultado." }, "nProt": { "type": "string", "description": "Número de protocolo da inutilização, quando homologada." }, "xml": { "type": "string", "description": "XML de retorno (`procInutNFe`) da SEFAZ, quando disponível." } } }, "example": { "cStat": "102", "xMotivo": "Inutilização de número homologado", "nProt": "135260000123456", "xml": "..." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/inutilizacoes": { "get": { "operationId": "nfeConsultarInutilizacoes", "summary": "Consultar Inutilizações", "description": "Consulta as faixas de numeração já inutilizadas (via [Inutilizar Numeração](https://nfe.tenzanlabs.com/reference/nfe/inutilizar/)). Diferente da maioria dos endpoints de consulta, esta é uma consulta **100% local** — os dados vêm do que já foi registrado pelo motor fiscal, sem uma nova chamada à SEFAZ.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "cnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CNPJ do emitente. Um dos dois — `cnpj` ou `cpf` — é obrigatório." }, { "name": "cpf", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CPF do emitente. Um dos dois — `cnpj` ou `cpf` — é obrigatório." }, { "name": "data_recebimento_inicial", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela data de recebimento inicial (formato `AAAA-MM-DD`)." }, { "name": "data_recebimento_final", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela data de recebimento final (formato `AAAA-MM-DD`)." }, { "name": "numero_inicial", "in": "query", "required": false, "schema": { "type": [ "string", "number" ] }, "description": "Filtra por número inicial da faixa inutilizada." }, { "name": "numero_final", "in": "query", "required": false, "schema": { "type": [ "string", "number" ] }, "description": "Filtra por número final da faixa inutilizada." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/consultar-inutilizacoes/" }, "responses": { "200": { "description": "OK: array de faixas inutilizadas", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "Status da inutilização." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "serie": { "type": "string", "description": "Série do documento fiscal." }, "numero_inicial": { "type": "string", "description": "Número inicial da faixa inutilizada." }, "numero_final": { "type": "string", "description": "Número final da faixa inutilizada." }, "modelo": { "type": "string", "description": "Modelo do documento fiscal." }, "cnpj": { "type": "string", "description": "CNPJ do emitente." }, "caminho_xml": { "type": "string", "description": "URL pública do XML de inutilização, quando disponível." }, "protocolo_sefaz": { "type": "string", "description": "Número de protocolo da inutilização, quando disponível." } } } }, "example": [ { "status": "inutilizado", "status_sefaz": "102", "mensagem_sefaz": "Inutilização de número homologado", "serie": "1", "numero_inicial": "101", "numero_final": "105", "modelo": "55", "cnpj": "12345678000199", "caminho_xml": "https://storage.../inutilizacao.xml", "protocolo_sefaz": "135260000123456" } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfe/{id}/danfe-etiqueta": { "get": { "operationId": "nfeDanfeEtiqueta", "summary": "DANFE Etiqueta", "description": "Gera uma etiqueta de envio em base64 (PDF) a partir de um documento fiscal autorizado, no formato **100x150mm**, contendo o código de barras da chave de acesso — pensada para impressão em impressoras de etiqueta usadas em logística e expedição.\n\nSó se aplica a documentos com `mod` **55** (NF-e) ou **65** (NFC-e) que já estejam `AUTORIZADA`.\n\n> **Gerando etiqueta de NFC-e.** Se o documento for uma NFC-e, use `GET /v1/nfc-e/{id}/danfe-etiqueta` em vez de `/v1/nfe/{id}/danfe-etiqueta` — o restante do contrato é idêntico.\n\n> **Não é o DANFE completo.** Esta etiqueta usa um **layout próprio**, pensado para envio/logística — ela **não** é o DANFE completo regulado pela SEFAZ (que segue o layout do Manual de Orientação do Contribuinte). Para o DANFE completo, use os canais habituais de impressão do documento fiscal.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/danfe-etiqueta/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status atual do documento fiscal." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "chave_nfe": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal." }, "numero": { "type": [ "string", "number" ], "description": "Número do documento fiscal." }, "serie": { "type": [ "string", "number" ], "description": "Série do documento fiscal." }, "danfe_etiqueta_base64": { "type": "string", "description": "Etiqueta 100x150mm em base64 (PDF), pronta para impressão." } } }, "example": { "status": "AUTORIZADA", "status_sefaz": "100", "mensagem_sefaz": "Autorizado o uso da NF-e", "chave_nfe": "35260812345678000199550010000000011000000018", "numero": 11, "serie": 1, "danfe_etiqueta_base64": "JVBERi0xLjQKJdPr6eEK..." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfc-e/{id}/danfe-etiqueta": { "get": { "operationId": "nfceDanfeEtiqueta", "summary": "DANFE Etiqueta (NFC-e)", "description": "Mesmo contrato de `GET /v1/nfe/{id}/danfe-etiqueta`, para NFC-e (`mod` 65): mesmos parâmetros, mesmas respostas e mesmos erros.", "tags": [ "NF-e e NFC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfe/danfe-etiqueta/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status atual do documento fiscal." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "chave_nfe": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal." }, "numero": { "type": [ "string", "number" ], "description": "Número do documento fiscal." }, "serie": { "type": [ "string", "number" ], "description": "Série do documento fiscal." }, "danfe_etiqueta_base64": { "type": "string", "description": "Etiqueta 100x150mm em base64 (PDF), pronta para impressão." } } }, "example": { "status": "AUTORIZADA", "status_sefaz": "100", "mensagem_sefaz": "Autorizado o uso da NF-e", "chave_nfe": "35260812345678000199550010000000011000000018", "numero": 11, "serie": 1, "danfe_etiqueta_base64": "JVBERi0xLjQKJdPr6eEK..." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/cte/emit": { "post": { "operationId": "cteEmitir", "summary": "Emitir CTe", "description": "`POST /v1/cte/emit` emite um CT-e (`mod: \"57\"`).\n\n> **Endpoint assíncrono.** Esta chamada retorna `202 Accepted` assim que o documento entra na fila de processamento — não espera pela SEFAZ. Uma rejeição da SEFAZ (schema inválido, duplicidade, regra de negócio, etc.) **não** vira erro HTTP nesta chamada: ela só aparece depois, consultando [`GET /v1/cte/{id}`](https://nfe.tenzanlabs.com/reference/cte/consultar/) com o `invoiceId` retornado aqui. Use esse endpoint para fazer polling até o `status` deixar de ser `PENDENTE`.", "tags": [ "CT-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/cte/emitir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mod": { "type": "string", "enum": [ "57" ], "description": "Modelo do documento: `57` para CT-e." }, "cfop": { "type": [ "string", "number" ], "description": "CFOP da CT-e." }, "natureza_operacao": { "type": "string", "description": "Descrição da natureza da operação." }, "modal": { "type": [ "string", "number" ], "enum": [ "01", "02", "03", "04", "05", "06" ], "description": "Modal de transporte. 01: Rodoviário · 02: Aéreo · 03: Aquaviário · 04: Ferroviário · 05: Dutoviário · 06: Multimodal." }, "tomador": { "type": [ "string", "number" ], "enum": [ "0", "1", "2", "3", "4" ], "description": "Tomador do serviço. 0: Remetente · 1: Expedidor · 2: Recebedor · 3: Destinatário · 4: Outros." }, "cnpj_emitente": { "type": "string", "description": "CNPJ da empresa emitente." }, "inscricao_estadual_emitente": { "type": [ "string", "number" ], "description": "Inscrição Estadual da empresa emitente." }, "municipio_inicio": { "type": "string", "description": "Nome do município de início da prestação." }, "uf_inicio": { "type": "string", "description": "Sigla da UF de início da prestação." }, "municipio_fim": { "type": "string", "description": "Nome do município de término da prestação." }, "uf_fim": { "type": "string", "description": "Sigla da UF de término da prestação." }, "valor_total": { "type": [ "string", "number" ], "description": "Valor total da prestação de serviço." } }, "additionalProperties": true, "required": [ "mod", "cfop", "natureza_operacao" ] }, "example": { "mod": "57", "cfop": "5353", "natureza_operacao": "Prestação de Serviço de Transporte" } } }, "description": "Só os campos essenciais estão descritos aqui; os demais campos opcionais aceitos estão na [listagem completa](https://nfe.tenzanlabs.com/reference/cte/campos/)." }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que o documento entrou na fila de processamento." }, "invoiceId": { "type": "string", "description": "UUID interno do documento — use na chamada de [consulta](https://nfe.tenzanlabs.com/reference/cte/consultar/)." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal, quando já pode ser calculada no momento do enfileiramento." } } }, "example": { "message": "Documento enfileirado para processamento", "invoiceId": "35f0a1b2-...", "accessKey": "35260812345678000199570010000000011000000018" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/cte/{id}": { "get": { "operationId": "cteConsultar", "summary": "Consultar CTe", "description": "Consulta o status atual de um CT-e a partir do seu `invoiceId` (o UUID retornado em `invoiceId` na [emissão](https://nfe.tenzanlabs.com/reference/cte/emitir/)). Não recebe corpo nem query string — o único parâmetro é o `id` na própria URL.\n\nUse este endpoint para fazer **polling** depois de [emitir](https://nfe.tenzanlabs.com/reference/cte/emitir/) um CT-e: a emissão é assíncrona (retorna `202 Accepted` antes de qualquer confirmação da SEFAZ), então é aqui que você descobre se o documento foi de fato autorizado ou rejeitado.", "tags": [ "CT-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/cte/consultar/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID do documento." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal." }, "status": { "type": "string", "enum": [ "PENDENTE", "AUTORIZADA", "REJEITADA", "CANCELADA", "ENCERRADA", "ERRO_TECNICO" ], "description": "Status atual do processamento." }, "protocolNumber": { "type": "string", "description": "Número de protocolo de autorização retornado pela SEFAZ. Presente quando `status` é `AUTORIZADA` (ou posterior)." }, "rejectionReason": { "type": "string", "description": "Motivo da rejeição, quando `status` é `REJEITADA`." }, "updatedAt": { "type": "string", "description": "Data/hora da última atualização do status (ISO 8601)." }, "qrCodeUrl": { "type": "string", "description": "URL do QR Code (NFC-e/NFCom, quando aplicável)." }, "events": { "type": "array", "description": "Histórico de eventos síncronos já registrados no documento (encerramento de MDF-e, CC-e, cancelamentos, etc)." } } }, "example": { "id": "35f0a1b2-...", "accessKey": "35260812345678000199570010000000011000000018", "status": "AUTORIZADA", "protocolNumber": "135260000123456", "updatedAt": "2026-08-19T15:04:32.000Z", "qrCodeUrl": "https://www.homologacao.nfce.fazenda.sp.gov.br/...", "events": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mdfe/emit": { "post": { "operationId": "mdfeEmitir", "summary": "Emitir MDFe", "description": "`POST /v1/mdfe/emit` emite um MDF-e (`mod: \"58\"`) — o Manifesto Eletrônico de Documentos Fiscais que agrupa os DF-e (NF-e, CT-e) transportados em uma viagem.\n\n> **Endpoint assíncrono.** Esta chamada retorna `202 Accepted` assim que o documento entra na fila de processamento — não espera pela SEFAZ. Uma rejeição da SEFAZ (schema inválido, duplicidade, regra de negócio, etc.) **não** vira erro HTTP nesta chamada: ela só aparece depois, consultando [`GET /v1/mdfe/{id}`](https://nfe.tenzanlabs.com/reference/mdfe/consultar/) com o `invoiceId` retornado aqui. Use esse endpoint para fazer polling até o `status` deixar de ser `PENDENTE`.\n\n> **Numeração automática.** Os campos `serie` e `numero` podem ficar em branco — nesse caso a API se responsabiliza pela numeração automática do MDF-e, o que é o comportamento recomendado.", "tags": [ "MDF-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/mdfe/emitir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mod": { "type": "string", "enum": [ "58" ], "description": "Modelo do documento: `58` para MDF-e." }, "tipo_transporte": { "type": [ "string", "number" ], "enum": [ "1", "2", "3" ], "description": "Tipo do Transportador. 1: ETC · 2: TAC · 3: CTC." }, "uf_inicio": { "type": "string", "description": "Sigla da UF de carregamento. Informar `EX` para operações com o exterior." }, "uf_fim": { "type": "string", "description": "Sigla da UF de descarregamento. Informar `EX` para operações com o exterior." }, "cnpj_emitente": { "type": "string", "description": "CNPJ do emitente." }, "inscricao_estadual_emitente": { "type": [ "string", "number" ], "description": "Inscrição Estadual da empresa emitente." }, "nome_emitente": { "type": "string", "description": "Razão Social ou nome da empresa emitente." }, "municipios_carregamento": { "type": "array", "description": "Municípios de carregamento da carga.", "items": { "type": "object", "properties": { "codigo": { "type": [ "string", "number" ], "description": "Código IBGE do município de carregamento." }, "nome": { "type": "string", "description": "Nome do município de carregamento." } } } }, "municipios_descarregamento": { "type": "array", "description": "Municípios de descarregamento, com os documentos fiscais vinculados.", "items": { "type": "object", "properties": { "codigo": { "type": [ "string", "number" ], "description": "Código IBGE do município de descarregamento." }, "nome": { "type": "string", "description": "Nome do município de descarregamento." }, "notas_fiscais": { "type": "array", "description": "NF-e transportadas até este município.", "items": { "type": "object", "properties": { "chave_nfe": { "type": "string", "description": "Chave de acesso de 44 dígitos da NF-e." } } } } } } }, "valor_total_carga": { "type": [ "string", "number" ], "description": "Valor total da carga/mercadorias transportadas." }, "peso_bruto": { "type": [ "string", "number" ], "description": "Peso Bruto Total da carga/mercadorias transportadas." } }, "additionalProperties": true, "required": [ "mod" ] }, "example": { "mod": "58", "tipo_transporte": "1", "uf_inicio": "SP", "uf_fim": "RJ", "municipios_carregamento": [ { "codigo": "3550308", "nome": "São Paulo" } ], "cnpj_emitente": "12345678000199", "inscricao_estadual_emitente": "123456789", "nome_emitente": "Transportadora Exemplo LTDA", "municipios_descarregamento": [ { "codigo": "3304557", "nome": "Rio de Janeiro", "notas_fiscais": [ { "chave_nfe": "35260812345678000199550010000000011000000018" } ] } ], "valor_total_carga": 15000, "peso_bruto": 1200.5, "codigo_unidade_medida_peso_bruto": "01" } } }, "description": "Só os campos essenciais estão descritos aqui; os demais campos opcionais aceitos estão na [listagem completa](https://nfe.tenzanlabs.com/reference/mdfe/campos/)." }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que o documento entrou na fila de processamento." }, "invoiceId": { "type": "string", "description": "UUID interno do documento — use nas chamadas de [consulta](https://nfe.tenzanlabs.com/reference/mdfe/consultar/) e nos [eventos de MDF-e](https://nfe.tenzanlabs.com/reference/mdfe/encerrar/) (encerramento, inclusão de condutor, inclusão de DF-e)." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal, quando já pode ser calculada no momento do enfileiramento." } } }, "example": { "message": "Documento enfileirado para processamento", "invoiceId": "35f0a1b2-...", "accessKey": "35260812345678000199580010000000011000000018" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mdfe/{id}": { "get": { "operationId": "mdfeConsultar", "summary": "Consultar MDFe", "description": "Consulta o status atual de um documento fiscal a partir do seu `invoiceId` (o UUID retornado em `invoiceId` na [emissão](https://nfe.tenzanlabs.com/reference/mdfe/emitir/)). Não recebe corpo nem query string — o único parâmetro é o `id` na própria URL.\n\nUse este endpoint para fazer **polling** depois de [emitir](https://nfe.tenzanlabs.com/reference/mdfe/emitir/) um MDF-e: a emissão é assíncrona (retorna `202 Accepted` antes de qualquer confirmação da SEFAZ), então é aqui que você descobre se o documento foi de fato autorizado ou rejeitado. Já os eventos de MDF-e — [encerramento](https://nfe.tenzanlabs.com/reference/mdfe/encerrar/), [inclusão de condutor](https://nfe.tenzanlabs.com/reference/mdfe/incluir-condutor/) e [inclusão de DF-e](https://nfe.tenzanlabs.com/reference/mdfe/incluir-dfe/) — são síncronos e retornam o resultado da SEFAZ diretamente na resposta, sem necessidade de consulta adicional.", "tags": [ "MDF-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/mdfe/consultar/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID do documento." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal." }, "status": { "type": "string", "enum": [ "PENDENTE", "AUTORIZADA", "REJEITADA", "CANCELADA", "ENCERRADA", "ERRO_TECNICO" ], "description": "Status atual do processamento." }, "protocolNumber": { "type": "string", "description": "Número de protocolo de autorização retornado pela SEFAZ. Presente quando `status` é `AUTORIZADA` (ou posterior)." }, "rejectionReason": { "type": "string", "description": "Motivo da rejeição, quando `status` é `REJEITADA`." }, "updatedAt": { "type": "string", "description": "Data/hora da última atualização do status (ISO 8601)." }, "qrCodeUrl": { "type": "string", "description": "URL do QR Code (NFC-e/NFCom, quando aplicável) — não se aplica a MDF-e." }, "events": { "type": "array", "description": "Histórico de eventos síncronos já registrados no documento (encerramento, inclusão de condutor, inclusão de DF-e, etc)." } } }, "example": { "id": "35f0a1b2-...", "accessKey": "35260812345678000199580010000000011000000018", "status": "AUTORIZADA", "protocolNumber": "135260000123456", "updatedAt": "2026-08-19T15:04:32.000Z", "qrCodeUrl": null, "events": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mdfe/{id}/inclusao-condutor": { "post": { "operationId": "mdfeIncluirCondutor", "summary": "Incluir Condutor", "description": "Inclui um condutor adicional no MDF-e (evento **110114**), além do(s) condutor(es) já informado(s) na emissão. Útil quando o motorista responsável pelo veículo muda ao longo do percurso.\n\nSó se aplica a documentos com `mod` **58** (MDF-e) que já estejam `AUTORIZADA` e ainda não tenham sido encerrados.\n\nEsse é um evento **síncrono** — a resposta HTTP já traz o resultado da SEFAZ, sem necessidade de polling.", "tags": [ "MDF-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/mdfe/incluir-condutor/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome completo do condutor." }, "cpf": { "type": "string", "description": "CPF do condutor (somente dígitos)." } }, "required": [ "nome", "cpf" ] }, "example": { "nome": "João da Silva", "cpf": "12345678900" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "incluido", "erro_inclusao" ], "description": "Resultado da inclusão junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." } } }, "example": { "status": "incluido", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao MDF-e", "caminho_xml": "https://storage.../evento-inclusao-condutor.xml" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mdfe/{id}/inclusao-dfe": { "post": { "operationId": "mdfeIncluirDfe", "summary": "Incluir DF-e", "description": "Inclui um Documento Fiscal Eletrônico (DF-e, por exemplo uma NF-e) vinculado ao MDF-e (evento **110115**), para casos em que o documento de transporte precisa ser agregado depois da emissão original do manifesto.\n\nSó se aplica a documentos com `mod` **58** (MDF-e) que já estejam `AUTORIZADA` e ainda não tenham sido encerrados.\n\nEsse é um evento **síncrono** — a resposta HTTP já traz o resultado da SEFAZ, sem necessidade de polling.", "tags": [ "MDF-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/mdfe/incluir-dfe/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "protocolo": { "type": "string", "description": "Número de protocolo a ser referenciado no evento. Se omitido, usa o protocolo de autorização do próprio MDF-e. Padrão: protocolo de autorização do MDF-e." }, "codigo_municipio_carregamento": { "type": [ "string", "number" ], "description": "Código IBGE do município de carregamento." }, "nome_municipio_carregamento": { "type": "string", "description": "Nome do município de carregamento." }, "documentos": { "type": "array", "description": "Lista de documentos fiscais eletrônicos a incluir no MDF-e.", "items": { "type": "object", "properties": { "codigo_municipio_descarregamento": { "type": [ "string", "number" ], "description": "Código IBGE do município de descarregamento deste documento." }, "nome_municipio_descarregamento": { "type": "string", "description": "Nome do município de descarregamento." }, "chave_nfe": { "type": "string", "description": "Chave de acesso de 44 dígitos da NF-e (ou outro DF-e) vinculada." } }, "required": [ "codigo_municipio_descarregamento", "chave_nfe" ] } } }, "required": [ "codigo_municipio_carregamento", "documentos" ] }, "example": { "codigo_municipio_carregamento": "3550308", "nome_municipio_carregamento": "São Paulo", "documentos": [ { "codigo_municipio_descarregamento": "3304557", "nome_municipio_descarregamento": "Rio de Janeiro", "chave_nfe": "35260812345678000199550010000000011000000018" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "incluido", "erro_inclusao" ], "description": "Resultado da inclusão junto à SEFAZ." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." } } }, "example": { "status": "incluido", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao MDF-e", "caminho_xml": "https://storage.../evento-inclusao-dfe.xml" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/mdfe/{id}/encerrar": { "post": { "operationId": "mdfeEncerrar", "summary": "Encerrar MDF-e", "description": "Encerra um MDF-e autorizado (evento **110112**), marcando o fim do transporte. Depois de encerrado, o status do documento muda para `ENCERRADA` e nenhum novo DF-e/condutor pode ser incluído nele.\n\nSó se aplica a documentos com `mod` **58** (MDF-e) que já estejam `AUTORIZADA`.", "tags": [ "MDF-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/mdfe/encerrar/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "Data do encerramento (formato `AAAA-MM-DD`)." }, "sigla_uf": { "type": "string", "description": "UF onde ocorreu o encerramento." }, "nome_municipio": { "type": "string", "description": "Nome do município onde ocorreu o encerramento." }, "codigo_municipio": { "type": "string", "description": "Código IBGE do município. Recomendado para evitar ambiguidade entre municípios de mesmo nome." } }, "required": [ "data", "sigla_uf", "nome_municipio" ] }, "example": { "data": "2026-08-19", "sigla_uf": "SP", "nome_municipio": "São Paulo", "codigo_municipio": "3550308" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`\"encerrado\"` ou `\"erro_encerramento\"`." }, "status_sefaz": { "type": "string", "description": "Código de status retornado pela SEFAZ (`cStat`)." }, "mensagem_sefaz": { "type": "string", "description": "Mensagem retornada pela SEFAZ (`xMotivo`)." }, "caminho_xml": { "type": "string", "description": "URL pública do XML do evento, quando autorizado." } } }, "example": { "status": "encerrado", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado ao MDF-e", "caminho_xml": "https://storage.../evento-encerramento.xml" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfcom/emit": { "post": { "operationId": "nfcomEmitir", "summary": "Emitir NFCom", "description": "`POST /v1/nfcom/emit` emite uma NFCom (`mod: \"62\"`) — Nota Fiscal de Serviços de Comunicação Eletrônica, usada por prestadoras de telefonia, TV por assinatura, internet e outros serviços de telecomunicação.\n\n> **Endpoint assíncrono.** Esta chamada retorna `202 Accepted` assim que o documento entra na fila de processamento — não espera pela SEFAZ. Uma rejeição da SEFAZ (schema inválido, duplicidade, regra de negócio, etc.) **não** vira erro HTTP nesta chamada: ela só aparece depois, consultando [`GET /v1/nfcom/{id}`](https://nfe.tenzanlabs.com/reference/nfcom/consultar/) com o `invoiceId` retornado aqui. Use esse endpoint para fazer polling até o `status` deixar de ser `PENDENTE`.", "tags": [ "NFCom" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfcom/emitir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mod": { "type": "string", "enum": [ "62" ], "description": "Modelo do documento: fixo `62` para NFCom." }, "data_emissao": { "type": "string", "description": "Data e hora de emissão do documento fiscal (ISO 8601)." }, "cnpj_emitente": { "type": "string", "description": "CNPJ da emitente. Utiliza os dados do cadastro da empresa quando omitido." }, "nome_destinatario": { "type": "string", "description": "Nome ou razão social do destinatário/assinante." }, "cnpj_destinatario": { "type": "string", "description": "CNPJ do destinatário/assinante. Obrigatório informar CNPJ, CPF ou outra identificação do destinatário/assinante." }, "cpf_destinatario": { "type": "string", "description": "CPF do destinatário/assinante. Obrigatório informar CNPJ, CPF ou outra identificação do destinatário/assinante." }, "tipo_assinante": { "type": [ "string", "number" ], "description": "Tipo de assinante — ver listagem completa de campos para o significado de cada código." }, "tipo_servico": { "type": [ "string", "number" ], "description": "Tipo de serviço utilizado (telefonia, dados, TV por assinatura, internet, etc) — ver listagem completa de campos." }, "itens": { "type": "array", "description": "Itens da nota fiscal.", "items": { "type": "object", "properties": { "numero_item": { "type": "string", "description": "Número do item da NFCom, começando por 1." }, "codigo_produto": { "type": "string", "description": "Código do produto ou serviço." }, "descricao": { "type": "string", "description": "Descrição do produto." }, "cfop": { "type": [ "string", "number" ], "description": "CFOP." }, "unidade_medida": { "type": [ "string", "number" ], "description": "Unidade Básica de Medida — ver listagem completa de campos." }, "quantidade_faturada": { "type": [ "string", "number" ], "description": "Quantidade faturada." }, "valor_item": { "type": [ "string", "number" ], "description": "Valor unitário do item." }, "valor_total_item": { "type": [ "string", "number" ], "description": "Valor total do item." } }, "required": [ "numero_item", "codigo_produto", "descricao" ] } } }, "additionalProperties": true, "required": [ "mod", "data_emissao" ] }, "example": { "mod": "62", "data_emissao": "2026-08-19T12:00:00-03:00", "cnpj_emitente": "12345678000199", "nome_destinatario": "João da Silva", "cpf_destinatario": "11122233344", "tipo_assinante": "3", "tipo_servico": "4", "itens": [ { "numero_item": "1", "codigo_produto": "PLANO-FIBRA-500", "descricao": "Assinatura mensal - Internet Fibra 500MB", "cfop": "5307", "unidade_medida": "4", "quantidade_faturada": 1, "valor_item": 99.9, "valor_total_item": 99.9 } ] } } }, "description": "Só os campos essenciais estão descritos aqui; os demais campos opcionais aceitos estão na [listagem completa](https://nfe.tenzanlabs.com/reference/nfcom/campos/)." }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que o documento entrou na fila de processamento." }, "invoiceId": { "type": "string", "description": "UUID interno do documento — use na chamada de [consulta](https://nfe.tenzanlabs.com/reference/nfcom/consultar/)." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal, quando já pode ser calculada no momento do enfileiramento." } } }, "example": { "message": "Documento enfileirado para processamento", "invoiceId": "62f0a1b2-...", "accessKey": "35260812345678000199620010000000011000000018" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfcom/{id}": { "get": { "operationId": "nfcomConsultar", "summary": "Consultar NFCom", "description": "Consulta o status atual de uma NFCom a partir do seu `invoiceId` (o UUID retornado em `invoiceId` na [emissão](https://nfe.tenzanlabs.com/reference/nfcom/emitir/)). Não recebe corpo nem query string — o único parâmetro é o `id` na própria URL.\n\nUse este endpoint para fazer **polling** depois de [emitir](https://nfe.tenzanlabs.com/reference/nfcom/emitir/) uma NFCom: a emissão é assíncrona (retorna `202 Accepted` antes de qualquer confirmação da SEFAZ), então é aqui que você descobre se o documento foi de fato autorizado ou rejeitado.", "tags": [ "NFCom" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfcom/consultar/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID do documento." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal." }, "status": { "type": "string", "enum": [ "PENDENTE", "AUTORIZADA", "REJEITADA", "CANCELADA", "ENCERRADA", "ERRO_TECNICO" ], "description": "Status atual do processamento." }, "protocolNumber": { "type": "string", "description": "Número de protocolo de autorização retornado pela SEFAZ. Presente quando `status` é `AUTORIZADA` (ou posterior)." }, "rejectionReason": { "type": "string", "description": "Motivo da rejeição, quando `status` é `REJEITADA`." }, "updatedAt": { "type": "string", "description": "Data/hora da última atualização do status (ISO 8601)." }, "qrCodeUrl": { "type": "string", "description": "URL do QR Code da NFCom, quando aplicável." }, "events": { "type": "array", "description": "Histórico de eventos síncronos já registrados no documento." } } }, "example": { "id": "62f0a1b2-...", "accessKey": "35260812345678000199620010000000011000000018", "status": "AUTORIZADA", "protocolNumber": "135260000123456", "updatedAt": "2026-08-19T15:04:32.000Z", "qrCodeUrl": "https://www.homologacao.nfcom.fazenda.sp.gov.br/...", "events": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/dce/emit": { "post": { "operationId": "dceEmitir", "summary": "Emitir DCe", "description": "`POST /v1/dce/emit` emite uma DC-e (`mod: \"59\"`) — Declaração de Conteúdo Eletrônica, usada para declarar o conteúdo de encomendas transportadas pelos Correios ou por transportadoras/marketplaces.\n\n> **Endpoint assíncrono.** Esta chamada retorna `202 Accepted` assim que o documento entra na fila de processamento — não espera pela SEFAZ. Uma rejeição da SEFAZ (schema inválido, duplicidade, regra de negócio, etc.) **não** vira erro HTTP nesta chamada: ela só aparece depois, consultando [`GET /v1/dce/{id}`](https://nfe.tenzanlabs.com/reference/dce/consultar/) com o `invoiceId` retornado aqui. Use esse endpoint para fazer polling até o `status` deixar de ser `PENDENTE`.", "tags": [ "DC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/dce/emitir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mod": { "type": "string", "enum": [ "59" ], "description": "Modelo do documento: fixo `59` para DC-e." }, "tipo_emitente": { "type": [ "string", "number" ], "enum": [ "0", "1", "2", "3", "4" ], "description": "Tipo do Emitente da DCe — ver listagem completa de campos." }, "cnpj_emitente": { "type": "string", "description": "CNPJ do emitente." }, "nome_emitente": { "type": "string", "description": "Razão social ou nome do emitente." }, "nome_destinatario": { "type": "string", "description": "Razão social ou nome do destinatário." }, "cnpj_destinatario": { "type": "string", "description": "CNPJ do destinatário." }, "cpf_destinatario": { "type": [ "string", "number" ], "description": "CPF do destinatário." }, "itens": { "type": "array", "description": "Detalhamento de itens da DCe.", "items": { "type": "object", "properties": { "numero": { "type": [ "string", "number" ], "description": "Número do item da DCe, começando por 1." }, "descricao_produto": { "type": "string", "description": "Descrição do produto, bem ou mercadoria." }, "codigo_ncm": { "type": "string", "description": "Código NCM (capítulo com 2 dígitos ou completo com 8 dígitos)." }, "quantidade": { "type": [ "string", "number" ], "description": "Quantidade." }, "valor_unitario": { "type": [ "string", "number" ], "description": "Valor unitário do item." }, "valor_produto": { "type": [ "string", "number" ], "description": "Valor total bruto do item." } }, "required": [ "descricao_produto", "codigo_ncm", "valor_unitario", "valor_produto" ] } }, "valor_total": { "type": [ "string", "number" ], "description": "Valor total da DCe." } }, "additionalProperties": true, "required": [ "mod" ] }, "example": { "mod": "59", "tipo_emitente": "2", "cnpj_emitente": "12345678000199", "nome_emitente": "Loja Exemplo LTDA", "nome_destinatario": "João da Silva", "cpf_destinatario": "11122233344", "itens": [ { "numero": "1", "descricao_produto": "Caneta Azul", "codigo_ncm": "96081000", "quantidade": 10, "valor_unitario": 2.5, "valor_produto": 25 } ], "valor_total": 25 } } }, "description": "Só os campos essenciais estão descritos aqui; os demais campos opcionais aceitos estão na [listagem completa](https://nfe.tenzanlabs.com/reference/dce/campos/)." }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que o documento entrou na fila de processamento." }, "invoiceId": { "type": "string", "description": "UUID interno do documento — use na chamada de [consulta](https://nfe.tenzanlabs.com/reference/dce/consultar/)." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal, quando já pode ser calculada no momento do enfileiramento." } } }, "example": { "message": "Documento enfileirado para processamento", "invoiceId": "59f0a1b2-...", "accessKey": "35260812345678000199590010000000011000000018" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/dce/{id}": { "get": { "operationId": "dceConsultar", "summary": "Consultar DCe", "description": "Consulta o status atual de uma DC-e a partir do seu `invoiceId` (o UUID retornado em `invoiceId` na [emissão](https://nfe.tenzanlabs.com/reference/dce/emitir/)). Não recebe corpo nem query string — o único parâmetro é o `id` na própria URL.\n\nUse este endpoint para fazer **polling** depois de [emitir](https://nfe.tenzanlabs.com/reference/dce/emitir/) uma DC-e: a emissão é assíncrona (retorna `202 Accepted` antes de qualquer confirmação da SEFAZ), então é aqui que você descobre se o documento foi de fato autorizado ou rejeitado.", "tags": [ "DC-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/dce/consultar/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID do documento." }, "accessKey": { "type": "string", "description": "Chave de acesso de 44 dígitos do documento fiscal." }, "status": { "type": "string", "enum": [ "PENDENTE", "AUTORIZADA", "REJEITADA", "CANCELADA", "ENCERRADA", "ERRO_TECNICO" ], "description": "Status atual do processamento." }, "protocolNumber": { "type": "string", "description": "Número de protocolo de autorização retornado pela SEFAZ. Presente quando `status` é `AUTORIZADA` (ou posterior)." }, "rejectionReason": { "type": "string", "description": "Motivo da rejeição, quando `status` é `REJEITADA`." }, "updatedAt": { "type": "string", "description": "Data/hora da última atualização do status (ISO 8601)." }, "qrCodeUrl": { "type": "string", "description": "URL do QR Code, quando aplicável." }, "events": { "type": "array", "description": "Histórico de eventos síncronos já registrados no documento." } } }, "example": { "id": "59f0a1b2-...", "accessKey": "35260812345678000199590010000000011000000018", "status": "AUTORIZADA", "protocolNumber": "135260000123456", "updatedAt": "2026-08-19T15:04:32.000Z", "qrCodeUrl": null, "events": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfse/emit": { "post": { "operationId": "nfseEmitir", "summary": "Emitir NFSe Nacional", "description": "`POST /v1/nfse/emit` emite uma NFS-e Nacional (`mod: \"NFSE\"`) — Nota Fiscal de Serviços Eletrônica no padrão instituído pelo Comitê Gestor da NFS-e (Convênio NFS-e), que substitui gradualmente os sistemas municipais de nota fiscal de serviço.\n\n> **Validação síncrona, processamento assíncrono.** Esta chamada retorna `202 Accepted` assim que o documento entra na fila — não espera pela confirmação do ambiente nacional; rejeições de regra de negócio do ambiente nacional só aparecem depois, consultando [`GET /v1/nfse/{id}`](https://nfe.tenzanlabs.com/reference/nfse/consultar/) com o `invoiceId`. Já os erros de **formato e consistência do payload** são devolvidos na hora, com `400` e `status: \"ERRO_VALIDACAO\"`, listando cada campo em `campos: [{ campo, mensagem }]` (endereço incompleto, CNPJ com dígito verificador inválido, grupo IBS/CBS incompleto etc.). Nenhum valor fiscal é inventado pelo motor: o que o XSD exige e não foi informado é erro.\n\n> **Numeração da DPS.** Omita `numero_dps` para o motor alocar o próximo número por (CNPJ do prestador, série, ambiente) — o número usado volta em `numero_dps` e `serie_dps` na resposta. Se você informar o número e ele já tiver sido usado na série, a resposta é `409` com `status: \"ERRO_VALIDACAO\"`. `serie_dps` deve estar entre `1` e `49999`.\n\n> **CNPJ alfanumérico.** `cnpj_prestador`, `cnpj_tomador`, `cnpj_intermediario` e `cnpj_destinatario` aceitam o CNPJ alfanumérico (`[0-9A-Z]{12}[0-9]{2}`, maiúsculo, sem máscara) com conferência do dígito verificador. CPF continua numérico.", "tags": [ "NFS-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfse/emitir/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mod": { "type": "string", "enum": [ "NFSE" ], "description": "Modelo do documento: fixo `NFSE` para NFS-e Nacional." }, "data_emissao": { "type": "string", "description": "Data e hora de emissão do documento (ISO 8601)." }, "cnpj_prestador": { "type": "string", "description": "CNPJ do prestador do serviço. Informe `cnpj_prestador` ou `cpf_prestador`." }, "razao_social_prestador": { "type": "string", "description": "Razão social ou nome do prestador." }, "codigo_municipio_prestador": { "type": "string", "description": "Código do município do prestador (tabela IBGE). Usado como município emissor quando `codigo_municipio_emissora` não é enviado. Não gera `` sozinho: para informar o endereço do prestador, envie também `cep_prestador`, `logradouro_prestador`, `numero_prestador` e `bairro_prestador`." }, "codigo_municipio_prestacao": { "type": "string", "description": "Município da prestação do serviço (tabela IBGE). Obrigatório (ou `codigo_pais_prestacao`, para serviço no exterior)." }, "cnpj_tomador": { "type": "string", "description": "CNPJ do tomador do serviço. Informe `cnpj_tomador` ou `cpf_tomador`." }, "razao_social_tomador": { "type": "string", "description": "Razão social ou nome do tomador. Obrigatória quando o tomador é informado; para não identificar o tomador, omita todos os campos dele." }, "descricao_servico": { "type": "string", "description": "Descrição do serviço prestado (obrigatória)." }, "codigo_tributacao_nacional_iss": { "type": "string", "description": "Código de tributação nacional do ISS, 6 dígitos (obrigatório)." }, "valor_servico": { "type": "number", "description": "Valor do serviço prestado (obrigatório, maior que zero)." } }, "additionalProperties": true }, "example": { "mod": "NFSE", "data_emissao": "2026-08-19T12:00:00-03:00", "cnpj_prestador": "11222333000181", "razao_social_prestador": "Consultoria Exemplo LTDA", "codigo_municipio_prestador": "3550308", "codigo_municipio_prestacao": "3550308", "cnpj_tomador": "98765432000198", "razao_social_tomador": "Cliente Exemplo LTDA", "descricao_servico": "Consultoria em tecnologia da informação", "codigo_tributacao_nacional_iss": "010701", "valor_servico": 1500 } } }, "description": "Só os campos essenciais estão descritos aqui; os demais campos opcionais aceitos estão na [listagem completa](https://nfe.tenzanlabs.com/reference/nfse/campos/)." }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmação de que o documento entrou na fila de processamento." }, "invoiceId": { "type": "string", "description": "UUID interno do documento — use na chamada de [consulta](https://nfe.tenzanlabs.com/reference/nfse/consultar/)." }, "accessKey": { "type": "string", "description": "Identificador (Id) da DPS calculado no enfileiramento." }, "numero_dps": { "type": "string", "description": "Número da DPS efetivamente usado (o informado, ou o alocado pelo motor quando `numero_dps` veio vazio)." }, "serie_dps": { "type": "string", "description": "Série da DPS efetivamente usada." } } }, "example": { "message": "Documento enfileirado para processamento", "invoiceId": "e5f0a1b2-...", "accessKey": "35260811222333000181NFSE10000000011000000018" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/nfse/{id}": { "get": { "operationId": "nfseConsultar", "summary": "Consultar NFSe Nacional", "description": "Consulta o status atual de uma NFS-e Nacional a partir do seu `invoiceId` (o UUID retornado em `invoiceId` na [emissão](https://nfe.tenzanlabs.com/reference/nfse/emitir/)). Não recebe corpo nem query string — o único parâmetro é o `id` na própria URL.\n\nUse este endpoint para fazer **polling** depois de [emitir](https://nfe.tenzanlabs.com/reference/nfse/emitir/) uma NFS-e: a emissão é assíncrona (retorna `202 Accepted` antes de qualquer confirmação do ambiente nacional), então é aqui que você descobre se o documento foi de fato autorizado ou rejeitado.", "tags": [ "NFS-e" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do documento (`invoiceId` retornado na emissão)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/nfse/consultar/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID do documento." }, "accessKey": { "type": "string", "description": "Chave de acesso do documento fiscal." }, "status": { "type": "string", "enum": [ "PENDENTE", "AUTORIZADA", "REJEITADA", "CANCELADA", "ENCERRADA", "ERRO_TECNICO" ], "description": "Status atual do processamento." }, "protocolNumber": { "type": "string", "description": "Número de protocolo de autorização. Presente quando `status` é `AUTORIZADA` (ou posterior)." }, "rejectionReason": { "type": "string", "description": "Motivo da rejeição, quando `status` é `REJEITADA`." }, "updatedAt": { "type": "string", "description": "Data/hora da última atualização do status (ISO 8601)." }, "qrCodeUrl": { "type": "string", "description": "URL do QR Code, quando aplicável." }, "events": { "type": "array", "description": "Histórico de eventos síncronos já registrados no documento." } } }, "example": { "id": "e5f0a1b2-...", "accessKey": "35260812345678000199NFSE10000000011000000018", "status": "AUTORIZADA", "protocolNumber": "135260000123456", "updatedAt": "2026-08-19T15:04:32.000Z", "qrCodeUrl": null, "events": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/clients": { "post": { "operationId": "clientsCriar", "summary": "Criar cliente", "description": "Cadastra um novo cliente (tenant) na sua conta — é nele que ficam o certificado digital e a configuração fiscal (UF, CSC/CSC ID, ambiente) usados em toda emissão feita em nome dele. Ao criar o cliente, a API já gera automaticamente os tokens `nfe_test_...`/`nfe_live_...` usados no header `Authorization: Bearer` das chamadas de emissão — veja [Obter os tokens de um cliente](https://nfe.tenzanlabs.com/reference/clients/tokens/) para recuperá-los.\n\n**Autorização:** só a [Chave de Acesso](https://nfe.tenzanlabs.com/getting-started/autenticacao/) (`X-Access-Key`) — não exige a Chave Restrita.\n\n> **Nada sensível volta na resposta.** IE, CSC, CSC ID, certificado e senha do certificado nunca são retornados por nenhum endpoint — tudo é criptografado (AES-256-GCM) antes de ser salvo. A resposta desta chamada também **não** traz os tokens do cliente; consulte-os separadamente em [`GET /v1/clients/{cnpj}/tokens`](https://nfe.tenzanlabs.com/reference/clients/tokens/).", "tags": [ "Clientes" ], "security": [ { "AccessKey": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/clients/criar/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Razão social do cliente. Não vazio, até 255 caracteres." }, "cnpj": { "type": "string", "description": "CNPJ do cliente, com ou sem máscara. O dígito verificador é validado." }, "ie": { "type": "string", "description": "Inscrição Estadual. Não vazia, até 255 caracteres." }, "uf": { "type": "string", "description": "Uma das 27 UFs válidas." }, "csc": { "type": "string", "description": "Código de Segurança do Contribuinte (CSC), usado nas NFC-e. Não vazio, até 255 caracteres." }, "cscId": { "type": "string", "description": "Identificador do CSC. Não vazio, até 255 caracteres." }, "certificateBase64": { "type": "string", "description": "Certificado digital A1 (`.pfx`/`.p12`) codificado em base64. Até ~512KB decodificado." }, "certificatePassword": { "type": "string", "description": "Senha do certificado digital. Não vazia, até 255 caracteres." }, "environment": { "type": "number", "enum": [ 1, 2 ], "default": 2, "description": "Ambiente da SEFAZ para as emissões deste cliente. `1`: Produção · `2`: Homologação." } }, "required": [ "name", "cnpj", "ie", "uf", "csc", "cscId", "certificateBase64", "certificatePassword" ] }, "example": { "name": "Empresa Exemplo LTDA", "cnpj": "11.222.333/0001-81", "ie": "123456789", "uf": "SP", "csc": "meu-csc-secreto", "cscId": "1", "certificateBase64": "", "certificatePassword": "senha-do-certificado", "environment": 2 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID interno do cliente — use nas demais chamadas de gestão de clientes." }, "name": { "type": "string", "description": "Razão social cadastrada." }, "cnpj": { "type": "string", "description": "CNPJ normalizado (somente dígitos)." }, "uf": { "type": "string", "description": "UF cadastrada." }, "environment": { "type": "number", "description": "Ambiente configurado (`1` ou `2`)." }, "createdAt": { "type": "string", "description": "Data e hora de criação do cliente (ISO 8601)." } } }, "example": { "id": "183e2c79-7c26-4a9e-b20d-63ce5645497b", "name": "Empresa Exemplo LTDA", "cnpj": "11222333000181", "uf": "SP", "environment": 2, "createdAt": "2026-08-29T17:31:38.694Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "clientsListar", "summary": "Listar clientes", "description": "Lista os clientes (tenants) cadastrados na sua conta. Retorna só o essencial para identificação — nunca dados fiscais ou credenciais. Não recebe corpo nem query string.\n\n**Autorização:** só a [Chave de Acesso](https://nfe.tenzanlabs.com/getting-started/autenticacao/) (`X-Access-Key`).", "tags": [ "Clientes" ], "security": [ { "AccessKey": [] } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/clients/listar/" }, "responses": { "200": { "description": "OK: array de", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID interno do cliente." }, "name": { "type": "string", "description": "Razão social cadastrada." }, "cnpj": { "type": "string", "description": "CNPJ normalizado (somente dígitos)." } } } }, "example": [ { "id": "183e2c79-...", "name": "Empresa Exemplo LTDA", "cnpj": "11222333000181" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/clients/{id}": { "get": { "operationId": "clientsConsultar", "summary": "Consultar cliente", "description": "Consulta um cliente específico da sua conta pelo `id`. Mesmo formato minimalista do item da [listagem](https://nfe.tenzanlabs.com/reference/clients/listar/) — nunca dados fiscais ou credenciais.\n\n**Autorização:** só a [Chave de Acesso](https://nfe.tenzanlabs.com/getting-started/autenticacao/) (`X-Access-Key`).", "tags": [ "Clientes" ], "security": [ { "AccessKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID do cliente." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/clients/consultar/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID interno do cliente." }, "name": { "type": "string", "description": "Razão social cadastrada." }, "cnpj": { "type": "string", "description": "CNPJ normalizado (somente dígitos)." } } }, "example": { "id": "183e2c79-...", "name": "Empresa Exemplo LTDA", "cnpj": "11222333000181" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/clients/{cnpj}/tokens": { "get": { "operationId": "clientsTokens", "summary": "Obter tokens do cliente", "description": "Recupera os tokens (`nfe_test_...`/`nfe_live_...`) de um cliente a partir do CNPJ — os mesmos tokens usados no header `Authorization: Bearer` das chamadas de emissão. É a forma programática de obter o token de um cliente logo após [criá-lo](https://nfe.tenzanlabs.com/reference/clients/criar/), sem precisar copiá-lo manualmente do painel.\n\n> **Endpoint privilegiado.** Exige **as duas** — [Chave de Acesso](https://nfe.tenzanlabs.com/getting-started/autenticacao/) **e** [Chave Restrita](https://nfe.tenzanlabs.com/reference/clients/chave-restrita/) — sempre juntas. Retorna o token de **produção** sem pedir a senha da conta, então trate a Chave Restrita com o mesmo cuidado que a senha da conta. Veja [O que é a Chave Restrita](https://nfe.tenzanlabs.com/reference/clients/chave-restrita/) antes de usar este endpoint.\n\n**Autorização:** `X-Access-Key` **+** `X-Restricted-Key`.\n\n**Rate limit:** 20 requisições/minuto por IP, além do limite global de 60/min.", "tags": [ "Clientes" ], "security": [ { "AccessKey": [], "RestrictedKey": [] } ], "parameters": [ { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CNPJ do cliente (com ou sem máscara)." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/clients/tokens/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID interno do cliente." }, "name": { "type": "string", "description": "Razão social cadastrada." }, "cnpj": { "type": "string", "description": "CNPJ normalizado (somente dígitos)." }, "tokens": { "type": "array", "description": "Lista de tokens do cliente.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID do token." }, "name": { "type": "string", "description": "Nome descritivo do token (ex: \"Chave de Produção\")." }, "type": { "type": "string", "enum": [ "PROD", "HOMOLOG" ], "description": "Ambiente ao qual o token pertence." }, "token": { "type": "string", "description": "O token em si (`nfe_live_...` ou `nfe_test_...`), usado no header `Authorization: Bearer`." } } } } } }, "example": { "id": "183e2c79-7c26-4a9e-b20d-63ce5645497b", "name": "Empresa Exemplo LTDA", "cnpj": "11222333000181", "tokens": [ { "id": "...", "name": "Chave de Produção", "type": "PROD", "token": "nfe_live_..." }, { "id": "...", "name": "Chave de Homologação", "type": "HOMOLOG", "token": "nfe_test_..." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/{tipo}/status": { "post": { "operationId": "geralStatus", "summary": "Status do Serviço", "description": "Verifica se o serviço da SEFAZ configurado para o ambiente e a UF do tenant está online. Útil para checar disponibilidade antes de disparar um lote grande de emissões, evitando tentativas desnecessárias durante uma instabilidade conhecida da SEFAZ.\n\nEste endpoint existe em cada namespace de documento — troque `{tipo}` por `nfe`, `nfc-e`, `cte`, `mdfe`, `dce`, `nfcom` ou `nfse` conforme o documento que você está emitindo.\n\nNão recebe corpo nem parâmetros.", "tags": [ "Geral" ], "security": [ { "AccessKey": [], "BearerToken": [] } ], "parameters": [ { "name": "tipo", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "nfe", "nfc-e", "cte", "mdfe", "dce", "nfcom", "nfse" ] }, "description": "Tipo de documento do namespace: `nfe`, `nfc-e`, `cte`, `mdfe`, `dce`, `nfcom` ou `nfse`." } ], "externalDocs": { "description": "Documentação desta operação", "url": "https://nfe.tenzanlabs.com/reference/geral/status/" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "online": { "type": "boolean", "description": "`true` se o serviço da SEFAZ está respondendo normalmente." }, "message": { "type": "string", "description": "Mensagem descritiva do status do serviço." } } }, "example": { "online": true, "message": "Serviço em operação" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "AccessKey": { "type": "apiKey", "in": "header", "name": "X-Access-Key", "description": "Chave de Acesso: identifica a sua conta (`nfe_access_...`). Gere e regenere no painel do desenvolvedor." }, "BearerToken": { "type": "http", "scheme": "bearer", "description": "Token do cliente (empresa): `nfe_test_...` para homologação ou `nfe_live_...` para produção." }, "RestrictedKey": { "type": "apiKey", "in": "header", "name": "X-Restricted-Key", "description": "Chave Restrita: privilégio alto, exigida somente para obter os tokens de um cliente. Trate como a senha da conta." } }, "schemas": { "ApiError": { "type": "object", "description": "Formato 1 (padrão): erros de autenticação, limite de plano, parâmetro ausente e afins. `message` é uma string.", "properties": { "statusCode": { "type": "integer", "examples": [ 401 ] }, "message": { "type": "string", "examples": [ "Chave de Acesso (header X-Access-Key) ausente ou inválida." ] }, "error": { "type": "string", "examples": [ "Unauthorized" ] } }, "required": [ "statusCode", "message" ] }, "ValidationError": { "type": "object", "description": "Formato 2: o corpo não bate com o schema do documento fiscal. `message` é um objeto com o detalhe dos campos.", "properties": { "statusCode": { "type": "integer", "examples": [ 400 ] }, "message": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Dados inválidos" ] }, "errors": { "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "natureza_operacao": "Required" } ] } } }, "error": { "type": "string", "examples": [ "Bad Request" ] } }, "required": [ "statusCode", "message" ] }, "InternalError": { "type": "object", "description": "Formato 3: erro de negócio sem formatador. Chega como 500 genérico, sem o motivo original.", "properties": { "statusCode": { "type": "integer", "examples": [ 500 ] }, "message": { "type": "string", "examples": [ "Internal server error" ] } }, "required": [ "statusCode", "message" ] } }, "responses": { "BadRequest": { "description": "Requisição inválida: campo ausente ou fora do formato. Há dois formatos de corpo (veja `ApiError` e `ValidationError`).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "Unauthorized": { "description": "Chave de Acesso (`X-Access-Key`) ou token (`Authorization: Bearer`) ausente, inválido ou revogado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Nenhum recurso com esse identificador pertence à conta/empresa da chave usada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "InternalError": { "description": "Erro interno. Tente de novo com backoff e, se persistir, abra um chamado informando o `invoiceId` e o horário.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }