{
"openapi": "3.0.4",
"info": {
"title": "NuvDocs - API de integração",
"description": "Emissão de documentos fiscais eletrônicos pela NuvTI. Toda chamada exige, ao mesmo tempo, o certificado ICP-Brasil com CNPJ na conexão TLS (TLS mútuo) e a chave de API no cabeçalho Authorization: Bearer. Com uma chave de teste (nd_test_) os documentos vão ao destino de teste da chave, sem efeito fiscal: o mesmo código funciona trocando só a chave. Erros vêm em application/problem+json, com código estável e críticas por campo. O envio é idempotente pela chave de idempotência: repetir depois de um 503 nunca duplica.",
"version": "v1"
},
"servers": [
{
"url": "http://api.nuvdocs.com.br/"
}
],
"paths": {
"/v1/documentos": {
"post": {
"tags": [
"Envio"
],
"summary": "Envia um documento",
"description": "Grava o documento de forma durável e responde 202 com o id. A validação fiscal vem depois, na preparação; a rejeição chega pela consulta ou pelo webhook (situação criticado). Faixa padrão: imediata. Repetir a mesma chave de idempotência devolve ja_recebido com o mesmo id. Se a conta ligar a aprovação na API e o emissor exigir aprovação, a situação é pendente_de_aprovacao, o id é o da pendência, e o documento só existe depois da aprovação; repetir a chave devolve a mesma pendência, e a pendência recusada volta com o código aprovacao_recusada. Se a conta ligar o aviso de possível duplicidade, a resposta de um documento novo pode trazer, em avisos, o código possivel_duplicidade (mesmo emissor, tomador e valor no período); o documento é aceito do mesmo jeito.",
"operationId": "EnviarDocumento",
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnvelopeNfse"
},
"example": {
"emissor": "12345678000195",
"chaveIdempotencia": "pedido-2026-000123",
"idCliente": "PED-000123",
"tipo": "nfse",
"conteudo": {
"servico": {
"codigoNacional": "01.07.01",
"descricao": "Suporte técnico em informática"
},
"valores": {
"valorServico": 1500.0
}
}
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Documento recebido (ou já recebido antes, com o mesmo id).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespostaDoDocumento"
},
"example": {
"chaveIdempotencia": "pedido-2026-000123",
"id": "4n8q2s6u0c8e4g6i2k0m6o4q2s",
"situacao": "recebido",
"faixa": "imediata",
"avisos": [ ],
"erros": [ ]
}
}
}
},
"400": {
"description": "O gzip do corpo está corrompido.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O gzip do corpo está corrompido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O gzip do corpo está corrompido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"413": {
"description": "O documento passa do tamanho máximo.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_excedido": {
"summary": "O documento passa do tamanho máximo.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_excedido",
"title": "Limite da requisição excedido",
"status": 413,
"detail": "O documento passa do tamanho máximo.",
"codigo": "limite_excedido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A conta da chave, ou a conta do emissor no envio por empresa de software habilitada, está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam. A conta do emissor não tem dados de cobrança (ou tem cobrança em atraso) e já usou as notas da faixa gratuita do mês. Cadastre os dados de cobrança no site. Consulta, download e cancelamento continuam. A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"conta_suspensa": {
"summary": "A conta da chave, ou a conta do emissor no envio por empresa de software habilitada, está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/conta_suspensa",
"title": "Conta sem emissão",
"status": 403,
"detail": "A conta da chave, ou a conta do emissor no envio por empresa de software habilitada, está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam.",
"codigo": "conta_suspensa",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"faixa_gratuita_esgotada": {
"summary": "A conta do emissor não tem dados de cobrança (ou tem cobrança em atraso) e já usou as notas da faixa gratuita do mês. Cadastre os dados de cobrança no site. Consulta, download e cancelamento continuam.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/faixa_gratuita_esgotada",
"title": "Faixa gratuita esgotada",
"status": 403,
"detail": "A conta do emissor não tem dados de cobrança (ou tem cobrança em atraso) e já usou as notas da faixa gratuita do mês. Cadastre os dados de cobrança no site. Consulta, download e cancelamento continuam.",
"codigo": "faixa_gratuita_esgotada",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"415": {
"description": "O corpo não é application/json. O Content-Encoding não é gzip.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"tipo_de_conteudo_nao_suportado": {
"summary": "O corpo não é application/json.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/tipo_de_conteudo_nao_suportado",
"title": "Tipo de conteúdo não suportado",
"status": 415,
"detail": "O corpo não é application/json.",
"codigo": "tipo_de_conteudo_nao_suportado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"codificacao_nao_suportada": {
"summary": "O Content-Encoding não é gzip.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/codificacao_nao_suportada",
"title": "Codificação não suportada",
"status": 415,
"detail": "O Content-Encoding não é gzip.",
"codigo": "codificacao_nao_suportada",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"409": {
"description": "A chave de idempotência já foi usada por este emissor em outra conta do NuvDocs. Gere outra chave e envie de novo.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"chave_em_uso_por_outra_conta": {
"summary": "A chave de idempotência já foi usada por este emissor em outra conta do NuvDocs. Gere outra chave e envie de novo.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/chave_em_uso_por_outra_conta",
"title": "Chave em uso por outra conta",
"status": 409,
"detail": "A chave de idempotência já foi usada por este emissor em outra conta do NuvDocs. Gere outra chave e envie de novo.",
"codigo": "chave_em_uso_por_outra_conta",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"422": {
"description": "O envelope foi recusado na recepção (JSON inválido, campo obrigatório, emissor não cadastrado, sem habilitação, número já usado...); as críticas dizem por quê.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"documento_recusado": {
"summary": "O envelope foi recusado na recepção (JSON inválido, campo obrigatório, emissor não cadastrado, sem habilitação, número já usado...); as críticas dizem por quê.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/documento_recusado",
"title": "Documento recusado",
"status": 422,
"detail": "O envelope foi recusado na recepção (JSON inválido, campo obrigatório, emissor não cadastrado, sem habilitação, número já usado...); as críticas dizem por quê.",
"codigo": "documento_recusado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "Banco ou armazenamento fora do ar; repita com a mesma chave depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "Banco ou armazenamento fora do ar; repita com a mesma chave depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "Banco ou armazenamento fora do ar; repita com a mesma chave depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
},
"get": {
"tags": [
"Consulta"
],
"summary": "Busca documentos por identificador do cliente, chave de acesso ou filtros",
"description": "Dois modos. (1) idCliente ou chaveAcesso, sozinhos: até 10 documentos do emissor, do mais novo para o mais antigo, com a mesma situação da consulta pelo id. (2) Filtros, por página: o período (de, inclusive; ate, exclusive; pela data de emissão) com um filtro, no máximo, entre situacao, numero, tomador (CNPJ ou CPF), nomeTomador (começo do nome, sem diferença de acento e maiúscula; ao menos 3 letras), valorMinimo e ou valorMaximo, e texto (palavras da descrição do serviço; exige de e ate com até 31 dias). Cada combinação usa um índice; outra combinação é recusada com combinacao_nao_suportada. A página vem do mais novo para o mais antigo, com até 100 resumos (padrão 50; sem rejeicao, criticas e eventosFiscais: consulte pelo id para o detalhe). Para a próxima página, repita o pedido com o cursor da resposta; sem cursor na resposta, não há mais documentos. Lista vazia quando nada é achado.",
"operationId": "BuscarDocumentos",
"parameters": [
{
"name": "emissor",
"in": "query",
"description": "CNPJ do emissor. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
},
{
"name": "idCliente",
"in": "query",
"description": "Identificador informado pelo cliente no envio.",
"schema": {
"type": "string"
}
},
{
"name": "chaveAcesso",
"in": "query",
"description": "Chave de acesso devolvida na autorização.",
"schema": {
"type": "string"
}
},
{
"name": "de",
"in": "query",
"description": "Início do período, inclusive, pela data de emissão (ISO 8601: 2026-10-01 ou 2026-10-01T12:00:00Z; sem fuso vale UTC).",
"schema": {
"type": "string"
}
},
{
"name": "ate",
"in": "query",
"description": "Fim do período, exclusive (ISO 8601).",
"schema": {
"type": "string"
}
},
{
"name": "situacao",
"in": "query",
"description": "Situação: recebido, pronto, autorizado, rejeitado, cancelado...",
"schema": {
"type": "string"
}
},
{
"name": "numero",
"in": "query",
"description": "Número do documento.",
"schema": {
"type": "string"
}
},
{
"name": "tomador",
"in": "query",
"description": "CNPJ ou CPF do tomador, com ou sem pontuação.",
"schema": {
"type": "string"
}
},
{
"name": "nomeTomador",
"in": "query",
"description": "Começo do nome do tomador, ao menos 3 letras; acento e maiúscula não contam.",
"schema": {
"type": "string"
}
},
{
"name": "valorMinimo",
"in": "query",
"description": "Menor valor do serviço, inclusive, com ponto decimal.",
"schema": {
"type": "string"
}
},
{
"name": "valorMaximo",
"in": "query",
"description": "Maior valor do serviço, inclusive, com ponto decimal.",
"schema": {
"type": "string"
}
},
{
"name": "texto",
"in": "query",
"description": "De 1 a 5 palavras da descrição do serviço (ao menos 3 letras cada); exige de e ate com até 31 dias.",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"in": "query",
"description": "Cursor da página anterior da busca por filtros.",
"schema": {
"type": "string"
}
},
{
"name": "quantidade",
"in": "query",
"description": "Tamanho da página da busca por filtros (1 a 100; padrão 50).",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Documentos achados.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespostaDaBusca"
},
"example": {
"documentos": [
{
"id": "4n8q2s6u0c8e4g6i2k0m6o4q2s",
"chaveIdempotencia": "pedido-2026-000123",
"idCliente": "PED-000123",
"emissor": "12345678000195",
"tipo": "nfse",
"recebedor": "simulado",
"ambiente": "simulacao",
"teste": true,
"faixa": "imediata",
"situacao": "autorizado",
"chaveAcesso": "35503082123456780001950000000000000000123456789012",
"serie": "1",
"numero": 123,
"datas": {
"recebido": "2026-10-22T13:05:21.417Z",
"emissao": "2026-10-22T13:05:21.417Z",
"autorizado": "2026-10-22T13:05:22.031Z"
},
"tomador": {
"documento": "98765432000110",
"nome": "Cliente Exemplo Ltda"
},
"valor": 1500.00
}
],
"cursor": "YjF8MTc5MjY3NDMyMTQxN3w0bjhxMnM2dTBjOGU0ZzZpMmswbTZvNHEycw"
}
}
}
},
"400": {
"description": "Nenhum filtro, ou idCliente e chaveAcesso ao mesmo tempo. Dois filtros além do período, idCliente ou chaveAcesso com outro filtro, ou texto sem período de até 31 dias. Data, número, tomador, nome, valor, texto, cursor ou quantidade inválidos. Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"filtro_obrigatorio": {
"summary": "Nenhum filtro, ou idCliente e chaveAcesso ao mesmo tempo.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/filtro_obrigatorio",
"title": "Filtro obrigatório",
"status": 400,
"detail": "Nenhum filtro, ou idCliente e chaveAcesso ao mesmo tempo.",
"codigo": "filtro_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"combinacao_nao_suportada": {
"summary": "Dois filtros além do período, idCliente ou chaveAcesso com outro filtro, ou texto sem período de até 31 dias.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/combinacao_nao_suportada",
"title": "Combinação de filtros não suportada",
"status": 400,
"detail": "Dois filtros além do período, idCliente ou chaveAcesso com outro filtro, ou texto sem período de até 31 dias.",
"codigo": "combinacao_nao_suportada",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"consulta_invalida": {
"summary": "Data, número, tomador, nome, valor, texto, cursor ou quantidade inválidos.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/consulta_invalida",
"title": "Consulta inválida",
"status": 400,
"detail": "Data, número, tomador, nome, valor, texto, cursor ou quantidade inválidos.",
"codigo": "consulta_invalida",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos/lote": {
"post": {
"tags": [
"Envio"
],
"summary": "Envia um lote de documentos",
"description": "Recebe uma lista JSON de envelopes (até 1.000 por padrão) e responde 202 com a situação de cada um, na ordem do corpo. Um documento recusado não afeta os outros. Faixa padrão: lote.",
"operationId": "EnviarLote",
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnvelopeNfse"
}
},
"example": [
{
"emissor": "12345678000195",
"chaveIdempotencia": "pedido-2026-000124",
"idCliente": "PED-000124",
"tipo": "nfse",
"conteudo": {
"servico": {
"codigoNacional": "01.07.01",
"descricao": "Manutenção de sistemas"
},
"valores": {
"valorServico": 820.5
}
}
},
{
"emissor": "12345678000195",
"tipo": "nfse",
"conteudo": {
"servico": {
"codigoNacional": "01.07.01",
"descricao": "Sem chave de idempotência"
},
"valores": {
"valorServico": 10
}
}
}
]
}
},
"required": true
},
"responses": {
"202": {
"description": "Lote processado: cada documento tem a sua situação (recebido, ja_recebido, recusado ou pendente_de_aprovacao).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespostaDoLote"
},
"example": {
"documentos": [
{
"chaveIdempotencia": "pedido-2026-000124",
"id": "7a1c3e5g7i9k1m3o5q7s9u1c3e",
"situacao": "recebido",
"faixa": "lote",
"avisos": [ ],
"erros": [ ]
},
{
"situacao": "recusado",
"avisos": [ ],
"erros": [
{
"campo": "chaveIdempotencia",
"codigo": "campo_obrigatorio",
"mensagem": "Informe a chave de idempotência."
}
]
}
]
}
}
}
},
"400": {
"description": "O corpo não é uma lista JSON válida ou o gzip está corrompido.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O corpo não é uma lista JSON válida ou o gzip está corrompido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O corpo não é uma lista JSON válida ou o gzip está corrompido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"413": {
"description": "O lote passa do máximo de documentos ou do tamanho máximo do corpo; nada foi gravado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_excedido": {
"summary": "O lote passa do máximo de documentos ou do tamanho máximo do corpo; nada foi gravado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_excedido",
"title": "Limite da requisição excedido",
"status": 413,
"detail": "O lote passa do máximo de documentos ou do tamanho máximo do corpo; nada foi gravado.",
"codigo": "limite_excedido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A conta da chave está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam. A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"conta_suspensa": {
"summary": "A conta da chave está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/conta_suspensa",
"title": "Conta sem emissão",
"status": 403,
"detail": "A conta da chave está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam.",
"codigo": "conta_suspensa",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"415": {
"description": "O corpo não é application/json. O Content-Encoding não é gzip.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"tipo_de_conteudo_nao_suportado": {
"summary": "O corpo não é application/json.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/tipo_de_conteudo_nao_suportado",
"title": "Tipo de conteúdo não suportado",
"status": 415,
"detail": "O corpo não é application/json.",
"codigo": "tipo_de_conteudo_nao_suportado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"codificacao_nao_suportada": {
"summary": "O Content-Encoding não é gzip.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/codificacao_nao_suportada",
"title": "Codificação não suportada",
"status": 415,
"detail": "O Content-Encoding não é gzip.",
"codigo": "codificacao_nao_suportada",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "Banco ou armazenamento fora do ar; repita o lote inteiro com as mesmas chaves.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "Banco ou armazenamento fora do ar; repita o lote inteiro com as mesmas chaves.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "Banco ou armazenamento fora do ar; repita o lote inteiro com as mesmas chaves.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos/fluxo": {
"post": {
"tags": [
"Envio"
],
"summary": "Envia documentos em fluxo contínuo",
"description": "Recebe application/x-ndjson, um envelope por linha, e responde application/x-ndjson, uma situação por linha, na ordem, à medida que grava. A memória da conexão tem teto constante. Linha vazia é ignorada. Se a conexão for interrompida (banco fora do ar, limite de documentos por conexão, gzip corrompido), a última linha é {\"interrupcao\": \"...\", \"erros\": [...]}; reenvie as linhas sem resposta com as mesmas chaves.",
"operationId": "EnviarFluxo",
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/x-ndjson": {
"schema": {
"type": "string"
},
"example": "{\"emissor\": \"12345678000195\", \"chaveIdempotencia\": \"pedido-2026-000123\", \"idCliente\": \"PED-000123\", \"tipo\": \"nfse\", \"conteudo\": {\"servico\": {\"codigoNacional\": \"01.07.01\", \"descricao\": \"Suporte técnico em informática\"}, \"valores\": {\"valorServico\": 1500.0}}}\n{\"emissor\": \"12345678000195\", \"chaveIdempotencia\": \"pedido-2026-000124\", \"idCliente\": \"PED-000124\", \"tipo\": \"nfse\", \"conteudo\": {\"servico\": {\"codigoNacional\": \"01.07.01\", \"descricao\": \"Manutenção de sistemas\"}, \"valores\": {\"valorServico\": 820.5}}}\n"
}
},
"required": true
},
"responses": {
"202": {
"description": "Uma linha por documento, à medida que grava.",
"content": {
"application/x-ndjson": {
"schema": {
"type": "string"
},
"example": "{\"chaveIdempotencia\": \"pedido-2026-000123\", \"id\": \"4n8q2s6u0c8e4g6i2k0m6o4q2s\", \"situacao\": \"ja_recebido\", \"faixa\": \"lote\", \"avisos\": [], \"erros\": []}\n{\"chaveIdempotencia\": \"pedido-2026-000124\", \"id\": \"7a1c3e5g7i9k1m3o5q7s9u1c3e\", \"situacao\": \"recebido\", \"faixa\": \"lote\", \"avisos\": [], \"erros\": []}\n"
}
}
},
"403": {
"description": "A conta da chave está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam. A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"conta_suspensa": {
"summary": "A conta da chave está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/conta_suspensa",
"title": "Conta sem emissão",
"status": 403,
"detail": "A conta da chave está suspensa: nenhum documento novo é aceito. Consulta e cancelamento continuam.",
"codigo": "conta_suspensa",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"415": {
"description": "O corpo não é application/x-ndjson. O Content-Encoding não é gzip.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"tipo_de_conteudo_nao_suportado": {
"summary": "O corpo não é application/x-ndjson.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/tipo_de_conteudo_nao_suportado",
"title": "Tipo de conteúdo não suportado",
"status": 415,
"detail": "O corpo não é application/x-ndjson.",
"codigo": "tipo_de_conteudo_nao_suportado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"codificacao_nao_suportada": {
"summary": "O Content-Encoding não é gzip.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/codificacao_nao_suportada",
"title": "Codificação não suportada",
"status": 415,
"detail": "O Content-Encoding não é gzip.",
"codigo": "codificacao_nao_suportada",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos/pre-validacao": {
"post": {
"tags": [
"Envio"
],
"summary": "Pré-valida um documento ou um lote",
"description": "Roda exatamente a validação da preparação (envelope, emissor, habilitação, recebedor, contrato e regras do recebedor) e responde na hora, sem numerar, assinar, gravar ou transmitir. Corpo objeto: um documento; corpo lista: um lote (resposta { \"documentos\": [...] }, na ordem).",
"operationId": "PreValidarDocumentos",
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnvelopeNfse"
},
"example": {
"emissor": "12345678000195",
"chaveIdempotencia": "pedido-2026-000123",
"idCliente": "PED-000123",
"tipo": "nfse",
"conteudo": {
"servico": {
"codigoNacional": "01.07.01",
"descricao": "Suporte técnico em informática"
},
"valores": {
"valorServico": 1500.0
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resultado da pré-validação: valido ou criticado, com as críticas por campo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResultadoDaPreValidacao"
},
"example": {
"chaveIdempotencia": "pedido-2026-000123",
"situacao": "criticado",
"criticas": [
{
"campo": "valores.valorServico",
"codigo": "valor_invalido",
"mensagem": "O valor do serviço deve ser maior que zero."
}
]
}
}
}
},
"400": {
"description": "O corpo do lote não é uma lista JSON válida ou o gzip está corrompido.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O corpo do lote não é uma lista JSON válida ou o gzip está corrompido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O corpo do lote não é uma lista JSON válida ou o gzip está corrompido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"413": {
"description": "O corpo passa do tamanho máximo ou o lote passa do máximo de documentos.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_excedido": {
"summary": "O corpo passa do tamanho máximo ou o lote passa do máximo de documentos.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_excedido",
"title": "Limite da requisição excedido",
"status": 413,
"detail": "O corpo passa do tamanho máximo ou o lote passa do máximo de documentos.",
"codigo": "limite_excedido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"415": {
"description": "O corpo não é application/json. O Content-Encoding não é gzip.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"tipo_de_conteudo_nao_suportado": {
"summary": "O corpo não é application/json.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/tipo_de_conteudo_nao_suportado",
"title": "Tipo de conteúdo não suportado",
"status": 415,
"detail": "O corpo não é application/json.",
"codigo": "tipo_de_conteudo_nao_suportado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"codificacao_nao_suportada": {
"summary": "O Content-Encoding não é gzip.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/codificacao_nao_suportada",
"title": "Codificação não suportada",
"status": 415,
"detail": "O Content-Encoding não é gzip.",
"codigo": "codificacao_nao_suportada",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O cadastro não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O cadastro não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O cadastro não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos/{id}": {
"get": {
"tags": [
"Consulta"
],
"summary": "Consulta a situação de um documento",
"description": "Devolve a situação atual, a chave de acesso e a numeração depois da autorização, as datas e as críticas quando criticado. Quando rejeitado, denegado ou criticado, o campo rejeicao traz a explicação de cada código: descrição, causa provável, campo no JSON próprio e correção sugerida.",
"operationId": "ConsultarDocumento",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do documento, devolvido no envio.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "emissor",
"in": "query",
"description": "CNPJ do emissor. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Situação do documento.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentoConsultado"
},
"example": {
"id": "4n8q2s6u0c8e4g6i2k0m6o4q2s",
"chaveIdempotencia": "pedido-2026-000123",
"idCliente": "PED-000123",
"emissor": "12345678000195",
"tipo": "nfse",
"recebedor": "simulado",
"ambiente": "simulacao",
"teste": true,
"faixa": "imediata",
"situacao": "autorizado",
"chaveAcesso": "35503082123456780001950000000000000000123456789012",
"serie": "1",
"numero": 123,
"datas": {
"recebido": "2026-10-22T13:05:21.417Z",
"emissao": "2026-10-22T13:05:21.417Z",
"autorizado": "2026-10-22T13:05:22.031Z"
},
"eventosFiscais": {
"cancelamento": {
"permitido": true,
"ate": "2026-11-21T13:05:22.031Z"
},
"substituicao": {
"permitido": true,
"ate": "2026-11-21T13:05:22.031Z"
}
}
}
}
}
},
"400": {
"description": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O documento não existe, é de outra conta ou de outro ambiente, ou o certificado não pode consultar o emissor.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O documento não existe, é de outra conta ou de outro ambiente, ou o certificado não pode consultar o emissor.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O documento não existe, é de outra conta ou de outro ambiente, ou o certificado não pode consultar o emissor.",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos/{id}/linha-do-tempo": {
"get": {
"tags": [
"Consulta"
],
"summary": "Consulta a linha do tempo de um documento",
"description": "Devolve cada passo do documento (recebido, validado, assinado, pronto, liberado, em transmissão, resposta do recebedor, eventos fiscais, impresso, webhooks entregues) com o horário e a duração desde o passo anterior. Cada intervalo diz onde o tempo foi gasto: nuvdocs, represamento (de pronto a liberado) ou recebedor (do envio à resposta, e do pedido de evento fiscal à resposta). Rejeições, denegações, críticas e recusas de evento fiscal trazem a explicação de cada código; tentativa acima de 1 é repetição. Enquanto o documento espera, o campo espera mostra a espera atual. A soma das durações dos passos e da espera é igual a duracaoTotalEmMilissegundos.",
"operationId": "ConsultarLinhaDoTempo",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do documento, devolvido no envio.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "emissor",
"in": "query",
"description": "CNPJ do emissor. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Linha do tempo do documento. A nota importada de outro emissor vem com a lista de passos vazia.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LinhaDoTempo"
},
"example": {
"documento": "4n8q2s6u0c8e4g6i2k0m6o4q2s",
"emissor": "12345678000195",
"situacao": "autorizado",
"inicio": "2026-10-22T13:05:21.417Z",
"fim": "2026-10-22T13:05:22.395Z",
"duracaoTotalEmMilissegundos": 978,
"totais": {
"nuvdocs": 422,
"represamento": 450,
"recebedor": 106
},
"tentativasDeTransmissao": 1,
"passos": [
{
"sequencia": 1,
"passo": "recebido",
"situacao": "recebido",
"data": "2026-10-22T13:05:21.417Z",
"duracaoEmMilissegundos": 0,
"tentativa": 1
},
{
"sequencia": 2,
"passo": "validado",
"situacao": "validado",
"data": "2026-10-22T13:05:21.433Z",
"duracaoEmMilissegundos": 16,
"categoria": "nuvdocs",
"tentativa": 1
},
{
"sequencia": 3,
"passo": "assinado",
"situacao": "assinado",
"data": "2026-10-22T13:05:21.452Z",
"duracaoEmMilissegundos": 19,
"categoria": "nuvdocs",
"tentativa": 1
},
{
"sequencia": 4,
"passo": "pronto",
"situacao": "pronto",
"data": "2026-10-22T13:05:21.460Z",
"duracaoEmMilissegundos": 8,
"categoria": "nuvdocs",
"tentativa": 1
},
{
"sequencia": 5,
"passo": "liberado",
"situacao": "liberado",
"data": "2026-10-22T13:05:21.910Z",
"duracaoEmMilissegundos": 450,
"categoria": "represamento",
"tentativa": 1
},
{
"sequencia": 6,
"passo": "em_transmissao",
"situacao": "em_transmissao",
"data": "2026-10-22T13:05:21.925Z",
"duracaoEmMilissegundos": 15,
"categoria": "nuvdocs",
"tentativa": 1
},
{
"sequencia": 7,
"passo": "autorizado",
"situacao": "autorizado",
"data": "2026-10-22T13:05:22.031Z",
"duracaoEmMilissegundos": 106,
"categoria": "recebedor",
"tentativa": 1,
"detalhes": {
"protocolo": "SIM-20261022-000123"
}
},
{
"sequencia": 8,
"passo": "impresso",
"situacao": "autorizado",
"data": "2026-10-22T13:05:22.240Z",
"duracaoEmMilissegundos": 209,
"categoria": "nuvdocs",
"tentativa": 1,
"detalhes": {
"origem": "nuvdocs"
}
},
{
"sequencia": 9,
"passo": "webhook.entregue",
"situacao": "autorizado",
"data": "2026-10-22T13:05:22.395Z",
"duracaoEmMilissegundos": 155,
"categoria": "nuvdocs",
"tentativa": 1,
"detalhes": {
"tipos": "documento.autorizado",
"tentativa": "1"
}
}
],
"truncada": false
}
}
}
},
"400": {
"description": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O documento não existe, é de outra conta ou de outro ambiente, ou o certificado não pode consultar o emissor.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O documento não existe, é de outra conta ou de outro ambiente, ou o certificado não pode consultar o emissor.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O documento não existe, é de outra conta ou de outro ambiente, ou o certificado não pode consultar o emissor.",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos/{id}/xml": {
"get": {
"tags": [
"Consulta"
],
"summary": "Baixa o XML de um documento",
"description": "Devolve o XML autorizado pelo recebedor. Enquanto o documento não é autorizado, devolve o XML assinado pelo NuvDocs. O cabeçalho X-NuvDocs-Xml diz qual: autorizado ou assinado.",
"operationId": "BaixarXml",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do documento, devolvido no envio.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "emissor",
"in": "query",
"description": "CNPJ do emissor. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "XML do documento.",
"content": {
"application/xml": {
"schema": {
"type": "string"
},
"example": "\n4n8q2s6u0c8e4g6i2k0m6o4q2sSuporte técnico em informática...\n"
}
}
},
"400": {
"description": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O documento não existe ou não pode ser visto por quem consulta. O documento ainda não foi assinado; consulte de novo em instantes.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O documento não existe ou não pode ser visto por quem consulta.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O documento não existe ou não pode ser visto por quem consulta.",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"xml_ainda_nao_gerado": {
"summary": "O documento ainda não foi assinado; consulte de novo em instantes.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/xml_ainda_nao_gerado",
"title": "XML ainda não gerado",
"status": 404,
"detail": "O documento ainda não foi assinado; consulte de novo em instantes.",
"codigo": "xml_ainda_nao_gerado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos/{id}/pdf": {
"get": {
"tags": [
"Consulta"
],
"summary": "Baixa o PDF de um documento (DANFSe)",
"description": "Devolve o documento auxiliar em PDF de um documento autorizado, cancelado ou substituído. O PDF mostra a situação do documento. Quando o PDF ainda não existe ou expirou, o NuvDocs gera na hora. Se o limite de geração estiver cheio, a resposta é 202 com Retry-After: repita a chamada depois desse tempo.",
"operationId": "BaixarPdf",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do documento, devolvido no envio.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "emissor",
"in": "query",
"description": "CNPJ do emissor. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "PDF do documento.",
"content": {
"application/pdf": {
"schema": {
"type": "string"
},
"example": "%PDF-1.4\n(corpo binário do impresso em application/pdf)\n"
}
}
},
"202": {
"description": "O PDF está em geração; repita depois do Retry-After.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespostaDoPdfEmGeracao"
},
"example": {
"documento": "4n8q2s6u0c8e4g6i2k0m6o4q2s",
"situacao": "em_geracao",
"repetirEmSegundos": 2
}
}
}
},
"400": {
"description": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O documento não existe ou não pode ser visto por quem consulta.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O documento não existe ou não pode ser visto por quem consulta.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O documento não existe ou não pode ser visto por quem consulta.",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"409": {
"description": "O documento não foi autorizado: não tem PDF.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"documento_nao_autorizado": {
"summary": "O documento não foi autorizado: não tem PDF.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/documento_nao_autorizado",
"title": "Documento não autorizado",
"status": 409,
"detail": "O documento não foi autorizado: não tem PDF.",
"codigo": "documento_nao_autorizado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos/{id}/eventos": {
"post": {
"tags": [
"Eventos fiscais"
],
"summary": "Pede um evento fiscal (cancelamento)",
"description": "Pede o cancelamento (tipo cancelamento) ou outro evento aceito pelo recebedor. O NuvDocs confere antes de enviar: documento autorizado, permissão cancelar da chave e do certificado, sem outro evento em andamento, sem bloqueio do município e dentro do prazo. O pedido que seria rejeitado volta impedido, com a explicação e a data-limite. Aceito, responde 202 com o id do evento; o resultado chega pela consulta (eventosFiscais) e pelo webhook. Se a conta ligar a aprovação na API e o emissor exigir aprovação, a resposta traz a situação pendente_de_aprovacao e o id da pendência em aprovacao; o evento só vai ao recebedor depois da aprovação. A chave de idempotência opcional faz o reenvio devolver a mesma pendência. A substituição é o envio do documento substituto, com o grupo substitui no conteúdo.",
"operationId": "SolicitarEventoFiscal",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do documento, devolvido no envio.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "emissor",
"in": "query",
"description": "CNPJ do emissor. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PedidoDeEventoFiscal"
},
"example": {
"tipo": "cancelamento",
"codigoMotivo": "1",
"motivo": "Erro na emissão: serviço cobrado em duplicidade."
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Evento pedido; o recebedor responde depois.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EventoFiscalSolicitado"
},
"example": {
"documento": "4n8q2s6u0c8e4g6i2k0m6o4q2s",
"evento": "019a1c2e-7b44-7c11-9d2e-5a6b7c8d9e0f",
"tipo": "cancelamento",
"situacao": "solicitado"
}
}
}
},
"400": {
"description": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido. Falta o tipo ou o motivo, o motivo é longo demais, ou o tipo é substituicao. Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"evento_invalido": {
"summary": "Falta o tipo ou o motivo, o motivo é longo demais, ou o tipo é substituicao.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/evento_invalido",
"title": "Pedido de evento inválido",
"status": 400,
"detail": "Falta o tipo ou o motivo, o motivo é longo demais, ou o tipo é substituicao.",
"codigo": "evento_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "O certificado não é do emissor e não tem habilitação cancelar. A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao_de_cancelar": {
"summary": "O certificado não é do emissor e não tem habilitação cancelar.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao_de_cancelar",
"title": "Sem permissão de cancelar",
"status": 403,
"detail": "O certificado não é do emissor e não tem habilitação cancelar.",
"codigo": "sem_permissao_de_cancelar",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O documento não existe, é de outra conta ou de outro ambiente.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O documento não existe, é de outra conta ou de outro ambiente.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O documento não existe, é de outra conta ou de outro ambiente.",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"409": {
"description": "O documento não está autorizado. O documento já foi cancelado. O documento já foi substituído. A nota foi emitida em outro sistema e importada como histórico. O documento já tem cancelamento ou substituição em andamento; só um é aceito. A aprovação desta chave de idempotência foi recusada; gere outra chave para pedir de novo.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"documento_nao_autorizado": {
"summary": "O documento não está autorizado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/documento_nao_autorizado",
"title": "Documento não autorizado",
"status": 409,
"detail": "O documento não está autorizado.",
"codigo": "documento_nao_autorizado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"documento_cancelado": {
"summary": "O documento já foi cancelado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/documento_cancelado",
"title": "Documento cancelado",
"status": 409,
"detail": "O documento já foi cancelado.",
"codigo": "documento_cancelado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"documento_ja_substituido": {
"summary": "O documento já foi substituído.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/documento_ja_substituido",
"title": "Documento já substituído",
"status": 409,
"detail": "O documento já foi substituído.",
"codigo": "documento_ja_substituido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"documento_de_historico_externo": {
"summary": "A nota foi emitida em outro sistema e importada como histórico.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/documento_de_historico_externo",
"title": "Nota importada de outro emissor",
"status": 409,
"detail": "A nota foi emitida em outro sistema e importada como histórico.",
"codigo": "documento_de_historico_externo",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"evento_fiscal_em_andamento": {
"summary": "O documento já tem cancelamento ou substituição em andamento; só um é aceito.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/evento_fiscal_em_andamento",
"title": "Evento fiscal em andamento",
"status": 409,
"detail": "O documento já tem cancelamento ou substituição em andamento; só um é aceito.",
"codigo": "evento_fiscal_em_andamento",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"aprovacao_recusada": {
"summary": "A aprovação desta chave de idempotência foi recusada; gere outra chave para pedir de novo.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/aprovacao_recusada",
"title": "Aprovação recusada",
"status": 409,
"detail": "A aprovação desta chave de idempotência foi recusada; gere outra chave para pedir de novo.",
"codigo": "aprovacao_recusada",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"413": {
"description": "O corpo passa de 16 KiB.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_excedido": {
"summary": "O corpo passa de 16 KiB.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_excedido",
"title": "Limite da requisição excedido",
"status": 413,
"detail": "O corpo passa de 16 KiB.",
"codigo": "limite_excedido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"422": {
"description": "Passou o prazo do município; dataLimite diz até quando ia. A administração tributária do município bloqueou os eventos fiscais. O recebedor do documento não aceita o tipo de evento.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"prazo_de_cancelamento_vencido": {
"summary": "Passou o prazo do município; dataLimite diz até quando ia.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/prazo_de_cancelamento_vencido",
"title": "Prazo de cancelamento vencido",
"status": 422,
"detail": "Passou o prazo do município; dataLimite diz até quando ia.",
"codigo": "prazo_de_cancelamento_vencido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"eventos_bloqueados": {
"summary": "A administração tributária do município bloqueou os eventos fiscais.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/eventos_bloqueados",
"title": "Eventos fiscais bloqueados",
"status": 422,
"detail": "A administração tributária do município bloqueou os eventos fiscais.",
"codigo": "eventos_bloqueados",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"evento_nao_suportado": {
"summary": "O recebedor do documento não aceita o tipo de evento.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/evento_nao_suportado",
"title": "Evento não suportado",
"status": 422,
"detail": "O recebedor do documento não aceita o tipo de evento.",
"codigo": "evento_nao_suportado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/represamento": {
"get": {
"tags": [
"Represamento"
],
"summary": "Consulta o represamento",
"description": "Lista, para os emissores da conta, os documentos à espera de liberação por recebedor, ambiente e faixa, o ritmo de escoamento dos últimos minutos e a previsão para esvaziar. O represamento nunca recusa envio: ele só atrasa a transmissão quando o recebedor está lento. A chave de teste vê só o represamento dos documentos de teste.",
"operationId": "ConsultarRepresamento",
"parameters": [
{
"name": "emissor",
"in": "query",
"description": "CNPJ de um emissor da conta. Sem ele, lista todos os emissores.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Represamentos com documentos à espera; lista vazia quando nada está represado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespostaDoRepresamento"
},
"example": {
"represamentos": [
{
"emissor": "12345678000195",
"recebedor": "simulado",
"ambiente": "simulacao",
"faixa": "lote",
"quantidade": 12840,
"escoamentoPorMinuto": 6000,
"previsaoDeEscoamentoEmSegundos": 129
}
]
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/webhooks": {
"get": {
"tags": [
"Webhooks"
],
"summary": "Lista os cadastros de webhook",
"description": "Lista os cadastros de webhook da conta, do mais antigo para o mais novo, sem o segredo. A chave de teste só vê os cadastros de teste, e a de produção só os de produção. Exige a permissão webhooks.",
"operationId": "ListarWebhooks",
"responses": {
"200": {
"description": "Os cadastros do ambiente da chave.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespostaDaListaDeWebhooks"
},
"example": {
"webhooks": [
{
"id": "019a1c2e7b447c119d2e5a6b7c8d9e0f",
"url": "https://erp.exemplo.com.br/nuvdocs/webhook",
"descricao": "ERP da matriz",
"emissores": [
"12345678000195"
],
"tiposDeEvento": [
"documento.autorizado",
"documento.rejeitado",
"documento.cancelado"
],
"tamanhoMaximoDoGrupo": 100,
"janelaDoGrupoEmMilissegundos": 1000,
"situacao": "ativo",
"teste": false,
"criadoEm": "2026-10-23T12:00:00+00:00",
"atualizadoEm": "2026-10-23T12:00:00+00:00"
}
]
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
},
"post": {
"tags": [
"Webhooks"
],
"summary": "Cria um cadastro de webhook",
"description": "Cria um cadastro de webhook no ambiente da chave: a chave de teste cria cadastro que só recebe eventos de documentos de teste. A URL precisa ser https, na porta 443 ou 8443, sem usuário e senha, e o nome não pode resolver para rede interna nem para a infraestrutura do NuvDocs. Emissores e tiposDeEvento vazios assinam todos. O NuvDocs gera o segredo HMAC e o devolve só nesta resposta: guarde-o. Cada chamada leva NuvDocs-Data (segundos Unix), NuvDocs-Entrega (id do grupo) e NuvDocs-Assinatura (v1=.\">, uma por segredo válido, separadas por vírgula). Exige a permissão webhooks.",
"operationId": "CriarWebhook",
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PedidoDeWebhook"
},
"example": {
"url": "https://erp.exemplo.com.br/nuvdocs/webhook",
"descricao": "ERP da matriz",
"emissores": [
"12.345.678/0001-95"
],
"tiposDeEvento": [
"documento.autorizado",
"documento.rejeitado",
"documento.cancelado"
],
"tamanhoMaximoDoGrupo": 100,
"janelaDoGrupoEmMilissegundos": 1000
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Cadastro criado; o segredo vem só aqui.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookVisivel"
},
"example": {
"id": "019a1c2e7b447c119d2e5a6b7c8d9e0f",
"url": "https://erp.exemplo.com.br/nuvdocs/webhook",
"descricao": "ERP da matriz",
"emissores": [
"12345678000195"
],
"tiposDeEvento": [
"documento.autorizado",
"documento.rejeitado",
"documento.cancelado"
],
"tamanhoMaximoDoGrupo": 100,
"janelaDoGrupoEmMilissegundos": 1000,
"situacao": "ativo",
"teste": false,
"criadoEm": "2026-10-23T12:00:00+00:00",
"atualizadoEm": "2026-10-23T12:00:00+00:00",
"segredo": "ndwh_Xq3v8Kp1Zr7mB2nW5yT0cL9fH4dJ6sA8eG1uR3oI2kE"
}
}
}
},
"400": {
"description": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido. Tipo de evento desconhecido, emissor que não é CNPJ nem CPF, descrição longa, grupo fora dos limites ou situação não permitida.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"webhook_invalido": {
"summary": "Tipo de evento desconhecido, emissor que não é CNPJ nem CPF, descrição longa, grupo fora dos limites ou situação não permitida.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_invalido",
"title": "Cadastro de webhook inválido",
"status": 400,
"detail": "Tipo de evento desconhecido, emissor que não é CNPJ nem CPF, descrição longa, grupo fora dos limites ou situação não permitida.",
"codigo": "webhook_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"413": {
"description": "O corpo passa de 64 KiB.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_excedido": {
"summary": "O corpo passa de 64 KiB.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_excedido",
"title": "Limite da requisição excedido",
"status": 413,
"detail": "O corpo passa de 64 KiB.",
"codigo": "limite_excedido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"422": {
"description": "A URL não é https, usa porta não aceita, tem usuário e senha, não resolve ou aponta para rede interna ou para o NuvDocs. A conta já tem o máximo de cadastros neste ambiente.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"endereco_recusado": {
"summary": "A URL não é https, usa porta não aceita, tem usuário e senha, não resolve ou aponta para rede interna ou para o NuvDocs.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/endereco_recusado",
"title": "Endereço do webhook recusado",
"status": 422,
"detail": "A URL não é https, usa porta não aceita, tem usuário e senha, não resolve ou aponta para rede interna ou para o NuvDocs.",
"codigo": "endereco_recusado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"limite_de_webhooks": {
"summary": "A conta já tem o máximo de cadastros neste ambiente.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_webhooks",
"title": "Limite de cadastros de webhook",
"status": 422,
"detail": "A conta já tem o máximo de cadastros neste ambiente.",
"codigo": "limite_de_webhooks",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/webhooks/{id}": {
"get": {
"tags": [
"Webhooks"
],
"summary": "Lê um cadastro de webhook",
"description": "Lê um cadastro de webhook, sem o segredo. Durante a convivência de uma troca, segredoAnteriorValidoAte diz até quando o segredo anterior ainda assina. Exige a permissão webhooks.",
"operationId": "LerWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do cadastro.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "O cadastro.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookVisivel"
},
"example": {
"id": "019a1c2e7b447c119d2e5a6b7c8d9e0f",
"url": "https://erp.exemplo.com.br/nuvdocs/webhook",
"descricao": "ERP da matriz",
"emissores": [
"12345678000195"
],
"tiposDeEvento": [
"documento.autorizado",
"documento.rejeitado",
"documento.cancelado"
],
"tamanhoMaximoDoGrupo": 100,
"janelaDoGrupoEmMilissegundos": 1000,
"situacao": "ativo",
"teste": false,
"criadoEm": "2026-10-23T12:00:00+00:00",
"atualizadoEm": "2026-10-23T12:00:00+00:00"
}
}
}
},
"404": {
"description": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"webhook_nao_encontrado": {
"summary": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_nao_encontrado",
"title": "Cadastro de webhook não encontrado",
"status": 404,
"detail": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"codigo": "webhook_nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Webhooks"
],
"summary": "Altera um cadastro de webhook",
"description": "Substitui o cadastro inteiro: campo ausente volta ao padrão, menos a situação, que fica como está. A URL é conferida de novo. Situação ativo reativa um cadastro suspenso; desativado para a entrega. O segredo não muda: troque pelo método do segredo. Exige a permissão webhooks.",
"operationId": "AlterarWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do cadastro.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PedidoDeWebhook"
},
"example": {
"url": "https://erp.exemplo.com.br/nuvdocs/webhook",
"descricao": "ERP da matriz",
"emissores": [
"12.345.678/0001-95"
],
"tiposDeEvento": [
"documento.autorizado",
"documento.rejeitado",
"documento.cancelado"
],
"tamanhoMaximoDoGrupo": 100,
"janelaDoGrupoEmMilissegundos": 1000
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Cadastro alterado, sem o segredo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookVisivel"
},
"example": {
"id": "019a1c2e7b447c119d2e5a6b7c8d9e0f",
"url": "https://erp.exemplo.com.br/nuvdocs/webhook",
"descricao": "ERP da matriz",
"emissores": [
"12345678000195"
],
"tiposDeEvento": [
"documento.autorizado",
"documento.rejeitado",
"documento.cancelado"
],
"tamanhoMaximoDoGrupo": 100,
"janelaDoGrupoEmMilissegundos": 1000,
"situacao": "ativo",
"teste": false,
"criadoEm": "2026-10-23T12:00:00+00:00",
"atualizadoEm": "2026-10-23T12:00:00+00:00"
}
}
}
},
"400": {
"description": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido. Tipo de evento desconhecido, emissor que não é CNPJ nem CPF, descrição longa, grupo fora dos limites ou situação não permitida.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"webhook_invalido": {
"summary": "Tipo de evento desconhecido, emissor que não é CNPJ nem CPF, descrição longa, grupo fora dos limites ou situação não permitida.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_invalido",
"title": "Cadastro de webhook inválido",
"status": 400,
"detail": "Tipo de evento desconhecido, emissor que não é CNPJ nem CPF, descrição longa, grupo fora dos limites ou situação não permitida.",
"codigo": "webhook_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"webhook_nao_encontrado": {
"summary": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_nao_encontrado",
"title": "Cadastro de webhook não encontrado",
"status": 404,
"detail": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"codigo": "webhook_nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"413": {
"description": "O corpo passa de 64 KiB.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_excedido": {
"summary": "O corpo passa de 64 KiB.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_excedido",
"title": "Limite da requisição excedido",
"status": 413,
"detail": "O corpo passa de 64 KiB.",
"codigo": "limite_excedido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"422": {
"description": "A URL não é https, usa porta não aceita, tem usuário e senha, não resolve ou aponta para rede interna ou para o NuvDocs.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"endereco_recusado": {
"summary": "A URL não é https, usa porta não aceita, tem usuário e senha, não resolve ou aponta para rede interna ou para o NuvDocs.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/endereco_recusado",
"title": "Endereço do webhook recusado",
"status": 422,
"detail": "A URL não é https, usa porta não aceita, tem usuário e senha, não resolve ou aponta para rede interna ou para o NuvDocs.",
"codigo": "endereco_recusado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"Webhooks"
],
"summary": "Remove um cadastro de webhook",
"description": "Remove o cadastro. A entrega para e descarta os eventos pendentes dele. Exige a permissão webhooks.",
"operationId": "RemoverWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do cadastro.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"webhook_nao_encontrado": {
"summary": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_nao_encontrado",
"title": "Cadastro de webhook não encontrado",
"status": 404,
"detail": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"codigo": "webhook_nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/webhooks/{id}/segredo": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Troca o segredo de um cadastro de webhook",
"description": "Gera um segredo novo e o devolve só nesta resposta. Durante a convivência (convivenciaEmHoras, de 0 a 168, padrão 24) cada chamada leva duas assinaturas em NuvDocs-Assinatura, a do segredo novo primeiro: troque o segredo no seu sistema sem perder chamadas. Use 0 quando o segredo anterior vazou. O corpo é opcional. Exige a permissão webhooks.",
"operationId": "TrocarSegredoDoWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do cadastro.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PedidoDeTrocaDeSegredo"
},
"example": {
"convivenciaEmHoras": 24
}
}
}
},
"responses": {
"200": {
"description": "Segredo trocado; o novo vem só aqui.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookVisivel"
},
"example": {
"id": "019a1c2e7b447c119d2e5a6b7c8d9e0f",
"url": "https://erp.exemplo.com.br/nuvdocs/webhook",
"descricao": "ERP da matriz",
"emissores": [
"12345678000195"
],
"tiposDeEvento": [
"documento.autorizado",
"documento.rejeitado",
"documento.cancelado"
],
"tamanhoMaximoDoGrupo": 100,
"janelaDoGrupoEmMilissegundos": 1000,
"situacao": "ativo",
"teste": false,
"criadoEm": "2026-10-23T12:00:00+00:00",
"atualizadoEm": "2026-10-24T09:30:00+00:00",
"segredoAnteriorValidoAte": "2026-10-25T09:30:00+00:00",
"segredo": "ndwh_Lm4pQ8sV2xZ6bN0cR7tY1uW5eA9dF3gH7jK2oP6iU4y"
}
}
}
},
"400": {
"description": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido. A convivência passa de 168 horas ou é negativa.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"webhook_invalido": {
"summary": "A convivência passa de 168 horas ou é negativa.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_invalido",
"title": "Cadastro de webhook inválido",
"status": 400,
"detail": "A convivência passa de 168 horas ou é negativa.",
"codigo": "webhook_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"webhook_nao_encontrado": {
"summary": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_nao_encontrado",
"title": "Cadastro de webhook não encontrado",
"status": 404,
"detail": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"codigo": "webhook_nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/webhooks/{id}/teste": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Envia um evento de teste ao cadastro",
"description": "Grava um evento webhook.teste só para este cadastro, assine ele o que assinar, e responde 202 com o id. A entrega manda o evento em segundos, como qualquer outro: em grupo, assinado e com repetição. Vale também para o cadastro suspenso, para conferir a correção antes de reativar. O resultado aparece no histórico de entregas. Exige a permissão webhooks.",
"operationId": "TestarWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do cadastro.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Evento de teste gravado para a entrega.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespostaDoTesteDeWebhook"
},
"example": {
"evento": "019a1c3f00a47c119d2e5a6b7c8d9e10"
}
}
}
},
"404": {
"description": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"webhook_nao_encontrado": {
"summary": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_nao_encontrado",
"title": "Cadastro de webhook não encontrado",
"status": 404,
"detail": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"codigo": "webhook_nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/webhooks/{id}/reenvio": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Reenvia eventos de um cadastro",
"description": "Volta à entrega, com prazo de repetição novo, os eventos escolhidos: pelos ids (guardados ou já entregues) ou por um período da data do fato (os guardados e, com incluirEntregues, também os entregues). Sem corpo, reenvia todos os guardados. Os eventos ficam guardados por 7 dias depois do prazo da repetição ou da entrega. Exige a permissão webhooks.",
"operationId": "ReenviarWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do cadastro.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PedidoDeReenvio"
},
"example": {
"desde": "2026-10-22T00:00:00+00:00",
"ate": "2026-10-23T00:00:00+00:00",
"incluirEntregues": true
}
}
}
},
"responses": {
"202": {
"description": "Eventos de volta à entrega.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RespostaDoReenvio"
},
"example": {
"reativados": 1250
}
}
}
},
"400": {
"description": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido. Ids que não são de evento (32 dígitos hexadecimais), mais de 1.000 ids ou período com o fim antes do início.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"webhook_invalido": {
"summary": "Ids que não são de evento (32 dígitos hexadecimais), mais de 1.000 ids ou período com o fim antes do início.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_invalido",
"title": "Cadastro de webhook inválido",
"status": 400,
"detail": "Ids que não são de evento (32 dígitos hexadecimais), mais de 1.000 ids ou período com o fim antes do início.",
"codigo": "webhook_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"webhook_nao_encontrado": {
"summary": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_nao_encontrado",
"title": "Cadastro de webhook não encontrado",
"status": 404,
"detail": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"codigo": "webhook_nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"413": {
"description": "O corpo passa de 64 KiB.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_excedido": {
"summary": "O corpo passa de 64 KiB.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_excedido",
"title": "Limite da requisição excedido",
"status": 413,
"detail": "O corpo passa de 64 KiB.",
"codigo": "limite_excedido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/webhooks/{id}/entregas": {
"get": {
"tags": [
"Webhooks"
],
"summary": "Lista o histórico de entregas de um cadastro",
"description": "Lista os eventos do cadastro, do mais novo para o mais antigo, com a situação (pendente, em_entrega, entregue, guardado), as tentativas, a próxima tentativa, o id do grupo (NuvDocs-Entrega) e o motivo da última falha. Filtre por situacao; peça a próxima página com o cursor devolvido. Exige a permissão webhooks.",
"operationId": "ListarEntregasDoWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do cadastro.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"in": "query",
"description": "Cursor da página anterior.",
"schema": {
"type": "string"
}
},
{
"name": "situacao",
"in": "query",
"description": "Só uma situação.",
"schema": {
"type": "string"
}
},
{
"name": "quantidade",
"in": "query",
"description": "Tamanho da página (1 a 1.000; padrão 100).",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "A página do histórico.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginaDeEntregas"
},
"example": {
"entregas": [
{
"evento": "019a1c2f8d117a3b9c0d1e2f3a4b5c6d",
"tipo": "documento.autorizado",
"data": "2026-10-23T12:00:01.512+00:00",
"documento": "4f7c2b9e1a3d5c7e9f1b3d5a7c9e1f3b",
"situacao": "entregue",
"tentativas": 0,
"entrega": "019a1c2f8f207c119d2e5a6b7c8d9e0f",
"entregueEm": "2026-10-23T12:00:02.733+00:00"
},
{
"evento": "019a1c2f6a227a3b9c0d1e2f3a4b5c6e",
"tipo": "documento.rejeitado",
"data": "2026-10-23T11:59:58.104+00:00",
"documento": "8a1c3e5f7b9d1f3a5c7e9b1d3f5a7c9e",
"situacao": "pendente",
"tentativas": 2,
"proximaTentativa": "2026-10-23T12:00:38.104+00:00",
"entrega": "019a1c2f6c317c119d2e5a6b7c8d9e0f",
"ultimaFalha": "http_503"
}
],
"cursor": "019a1c2f6a227a3b9c0d1e2f3a4b5c6e"
}
}
}
},
"400": {
"description": "Cursor que não veio da página anterior, quantidade fora de 1 a 1.000 ou situação desconhecida.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"consulta_invalida": {
"summary": "Cursor que não veio da página anterior, quantidade fora de 1 a 1.000 ou situação desconhecida.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/consulta_invalida",
"title": "Consulta inválida",
"status": 400,
"detail": "Cursor que não veio da página anterior, quantidade fora de 1 a 1.000 ou situação desconhecida.",
"codigo": "consulta_invalida",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"webhook_nao_encontrado": {
"summary": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/webhook_nao_encontrado",
"title": "Cadastro de webhook não encontrado",
"status": 404,
"detail": "O cadastro não existe, foi removido, é de outra conta ou do outro ambiente (chave de teste só vê cadastros de teste).",
"codigo": "webhook_nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/capturas/{cnpj}": {
"put": {
"tags": [
"Captura"
],
"summary": "Ativa a captura das notas recebidas de um CNPJ",
"description": "Liga a busca contínua das notas em que o CNPJ figura como tomador ou intermediário (e dos eventos delas: cancelamento e substituição). O CNPJ (só dígitos) precisa ser de um emissor da conta e da raiz do certificado da conexão. A primeira ativação começa no NSU zero e traz o histórico inteiro do CNPJ; reativar continua de onde parou. Com recebedor que autentica por certificado, o cofre precisa ter o A1 da raiz do CNPJ. A chamada é idempotente: com a captura já ativa, devolve 200 sem mudar nada. A chave de teste ativa a captura do ambiente de testes, e os documentos recebidos dela ficam à parte. Exige a permissão captura, que só a chave de API tem. O corpo é opcional.",
"operationId": "AtivarCaptura",
"parameters": [
{
"name": "cnpj",
"in": "path",
"description": "CNPJ do emissor, só com dígitos (a barra da máscara não cabe no caminho).",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Corpo do pedido; o exemplo mostra o formato.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PedidoDeAtivacaoDaCaptura"
},
"example": {
"tipo": "nfse"
}
}
}
},
"responses": {
"201": {
"description": "Captura ativada pela primeira vez neste CNPJ e ambiente.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapturaVisivel"
},
"example": {
"emissor": "12345678000195",
"recebedor": "nfse-nacional",
"ambiente": "producao",
"teste": false,
"ativa": true,
"ativadaEm": "2026-10-26T12:00:00Z",
"ultimoNsu": 1284,
"proximaConsulta": "2026-10-26T13:00:00Z",
"ultimaConsulta": {
"em": "2026-10-26T12:00:00Z",
"situacao": "nenhum",
"quantidade": 0,
"codigos": [ ],
"mensagem": "Nenhum documento novo."
}
}
}
}
},
"200": {
"description": "A captura já estava ativa, ou foi reativada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapturaVisivel"
},
"example": {
"emissor": "12345678000195",
"recebedor": "nfse-nacional",
"ambiente": "producao",
"teste": false,
"ativa": true,
"ativadaEm": "2026-10-26T12:00:00Z",
"ultimoNsu": 1284,
"proximaConsulta": "2026-10-26T13:00:00Z",
"ultimaConsulta": {
"em": "2026-10-26T12:00:00Z",
"situacao": "nenhum",
"quantidade": 0,
"codigos": [ ],
"mensagem": "Nenhum documento novo."
}
}
}
}
},
"400": {
"description": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"corpo_invalido": {
"summary": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/corpo_invalido",
"title": "Corpo inválido",
"status": 400,
"detail": "O corpo não é um JSON válido no formato do pedido, ou tem campo desconhecido.",
"codigo": "corpo_invalido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"413": {
"description": "O corpo passa de 64 KiB.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_excedido": {
"summary": "O corpo passa de 64 KiB.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_excedido",
"title": "Limite da requisição excedido",
"status": 413,
"detail": "O corpo passa de 64 KiB.",
"codigo": "limite_excedido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"422": {
"description": "O recebedor do CNPJ não oferece a captura de documentos, ou não no ambiente da chave. O cofre não tem o certificado A1 da raiz do CNPJ para a captura. O certificado A1 da raiz do CNPJ no cofre está vencido. Nem o emissor nem a configuração definem o recebedor do tipo de documento.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"captura_nao_oferecida": {
"summary": "O recebedor do CNPJ não oferece a captura de documentos, ou não no ambiente da chave.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/captura_nao_oferecida",
"title": "Captura não oferecida",
"status": 422,
"detail": "O recebedor do CNPJ não oferece a captura de documentos, ou não no ambiente da chave.",
"codigo": "captura_nao_oferecida",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"certificado_ausente": {
"summary": "O cofre não tem o certificado A1 da raiz do CNPJ para a captura.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/certificado_ausente",
"title": "Certificado ausente",
"status": 422,
"detail": "O cofre não tem o certificado A1 da raiz do CNPJ para a captura.",
"codigo": "certificado_ausente",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"certificado_vencido": {
"summary": "O certificado A1 da raiz do CNPJ no cofre está vencido.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/certificado_vencido",
"title": "Certificado vencido",
"status": 422,
"detail": "O certificado A1 da raiz do CNPJ no cofre está vencido.",
"codigo": "certificado_vencido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"recebedor_nao_definido": {
"summary": "Nem o emissor nem a configuração definem o recebedor do tipo de documento.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/recebedor_nao_definido",
"title": "Recebedor não definido",
"status": 422,
"detail": "Nem o emissor nem a configuração definem o recebedor do tipo de documento.",
"codigo": "recebedor_nao_definido",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
},
"get": {
"tags": [
"Captura"
],
"summary": "Consulta a captura de um CNPJ",
"description": "Devolve se a captura está ativa, o último NSU gravado, quando vence a próxima consulta e como terminou a última (localizados, nenhum, limite, rejeicao ou falha, com a mensagem; a falta de certificado aparece como falha). Exige a permissão captura.",
"operationId": "ConsultarCaptura",
"parameters": [
{
"name": "cnpj",
"in": "path",
"description": "CNPJ do emissor, só com dígitos (a barra da máscara não cabe no caminho).",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tipo",
"in": "query",
"description": "Tipo do documento capturado; sem ele vale `nfse`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "A captura do CNPJ no ambiente da chave.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapturaVisivel"
},
"example": {
"emissor": "12345678000195",
"recebedor": "nfse-nacional",
"ambiente": "producao",
"teste": false,
"ativa": true,
"ativadaEm": "2026-10-26T12:00:00Z",
"ultimoNsu": 1284,
"proximaConsulta": "2026-10-26T13:00:00Z",
"ultimaConsulta": {
"em": "2026-10-26T12:00:00Z",
"situacao": "nenhum",
"quantidade": 0,
"codigos": [ ],
"mensagem": "Nenhum documento novo."
}
}
}
}
},
"404": {
"description": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"Captura"
],
"summary": "Desativa a captura de um CNPJ",
"description": "Para a busca das notas recebidas do CNPJ. O registro e o cursor ficam: reativar continua de onde parou, sem perder nem repetir notas. A chamada é idempotente: com a captura já desativada, devolve 204. Exige a permissão captura.",
"operationId": "DesativarCaptura",
"parameters": [
{
"name": "cnpj",
"in": "path",
"description": "CNPJ do emissor, só com dígitos (a barra da máscara não cabe no caminho).",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tipo",
"in": "query",
"description": "Tipo do documento capturado; sem ele vale `nfse`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O CNPJ não é de um emissor da conta, é de outra raiz que a do certificado, ou a captura nunca foi ativada neste ambiente (chave de teste só vê capturas de teste).",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco, a auditoria ou o cofre de certificados não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos-recebidos": {
"get": {
"tags": [
"Documentos recebidos"
],
"summary": "Lista os documentos recebidos",
"description": "Lista as notas que a captura achou para o CNPJ (emissor), do mais novo para o mais antigo pela data de emissão, em páginas de resumos (sem os eventos: consulte pelo id para o histórico). O período (dataInicial, inclusive; dataFinal, exclusive) vale com no máximo um filtro entre prestador (CNPJ ou CPF), situacao (emitido, cancelado, substituido), procedencia (terceiro, emitido_pelo_nuvdocs, emitido_fora), numero (exato), nomePrestador (começo do nome, sem diferença de acento ou maiúscula) e valor (valorMinimo e valorMaximo, inclusive). Os filtros numero, nomePrestador e valor exigem o período inteiro (dataInicial e dataFinal). A chave de acesso vale sozinha e também acha o registro em que só o evento chegou (notaAusente). Outra combinação é recusada com combinacao_nao_suportada. A página vem com até 100 documentos (padrão 50). Para a próxima página, repita o pedido com o cursor da resposta; sem cursor na resposta, não há mais documentos. A chave de teste só vê os documentos recebidos de teste, e a de produção só os de produção. Exige a permissão consultar.",
"operationId": "ListarDocumentosRecebidos",
"parameters": [
{
"name": "emissor",
"in": "query",
"description": "CNPJ consultado. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
},
{
"name": "dataInicial",
"in": "query",
"description": "Início do período, inclusive, pela data de emissão (ISO 8601: 2026-10-01 ou 2026-10-01T12:00:00Z; sem fuso vale UTC).",
"schema": {
"type": "string"
}
},
{
"name": "dataFinal",
"in": "query",
"description": "Fim do período, exclusive (ISO 8601).",
"schema": {
"type": "string"
}
},
{
"name": "prestador",
"in": "query",
"description": "CNPJ ou CPF do prestador da nota, com ou sem pontuação.",
"schema": {
"type": "string"
}
},
{
"name": "situacao",
"in": "query",
"description": "Situação fiscal: emitido, cancelado ou substituido.",
"schema": {
"type": "string"
}
},
{
"name": "procedencia",
"in": "query",
"description": "Procedência: terceiro, emitido_pelo_nuvdocs ou emitido_fora.",
"schema": {
"type": "string"
}
},
{
"name": "chaveAcesso",
"in": "query",
"description": "Chave de acesso da nota; vale sozinha.",
"schema": {
"type": "string"
}
},
{
"name": "limite",
"in": "query",
"description": "Tamanho da página (1 a 100; padrão 50).",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"format": "int32"
}
},
{
"name": "cursor",
"in": "query",
"description": "Cursor da página anterior.",
"schema": {
"type": "string"
}
},
{
"name": "numero",
"in": "query",
"description": "Número exato da nota; exige o período inteiro.",
"schema": {
"type": "string"
}
},
{
"name": "nomePrestador",
"in": "query",
"description": "Começo do nome do prestador (ao menos 3 letras ou dígitos), sem diferença de acento ou maiúscula; exige o período inteiro.",
"schema": {
"type": "string"
}
},
{
"name": "valorMinimo",
"in": "query",
"description": "Menor valor da nota, inclusive, com ponto decimal (ex.: 1500.00); exige o período inteiro.",
"schema": {
"type": "string"
}
},
{
"name": "valorMaximo",
"in": "query",
"description": "Maior valor da nota, inclusive, com ponto decimal; exige o período inteiro.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Documentos recebidos achados; lista vazia quando nenhum.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginaDeRecebidos"
},
"example": {
"documentos": [
{
"id": "2f7k1m9q3b5d8h0j4n6p8r1t3v",
"emissor": "12345678000195",
"tipo": "nfse",
"recebedor": "nfse-nacional",
"ambiente": "producao",
"teste": false,
"procedencia": "terceiro",
"papeis": [
"tomador"
],
"chaveAcesso": "35503082198765432000110000000000000000987654321098",
"numero": "987",
"serie": "1",
"prestador": {
"documento": "98765432000110",
"nome": "Prestador Exemplo Ltda"
},
"tomador": {
"documento": "12345678000195",
"nome": "Empresa Exemplo Ltda"
},
"valor": 2300.00,
"datas": {
"capturado": "2026-10-26T12:00:04Z",
"emissao": "2026-10-22T13:05:21Z"
},
"situacao": "emitido",
"nsu": 1284,
"notaAusente": false
}
],
"cursor": "cjF8MTc5MjY3NDMyMTAwMHwyZjdrMW05cTNiNWQ4aDBqNG42cDhyMXQzdg"
}
}
}
},
"400": {
"description": "Dois filtros além do período, número, nome do prestador ou valor sem o período inteiro, ou a chave de acesso com outro filtro, período ou cursor. Data, prestador, situação, procedência, nome do prestador, valor, cursor ou limite inválidos. Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"combinacao_nao_suportada": {
"summary": "Dois filtros além do período, número, nome do prestador ou valor sem o período inteiro, ou a chave de acesso com outro filtro, período ou cursor.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/combinacao_nao_suportada",
"title": "Combinação de filtros não suportada",
"status": 400,
"detail": "Dois filtros além do período, número, nome do prestador ou valor sem o período inteiro, ou a chave de acesso com outro filtro, período ou cursor.",
"codigo": "combinacao_nao_suportada",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"consulta_invalida": {
"summary": "Data, prestador, situação, procedência, nome do prestador, valor, cursor ou limite inválidos.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/consulta_invalida",
"title": "Consulta inválida",
"status": 400,
"detail": "Data, prestador, situação, procedência, nome do prestador, valor, cursor ou limite inválidos.",
"codigo": "consulta_invalida",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos-recebidos/{id}": {
"get": {
"tags": [
"Documentos recebidos"
],
"summary": "Consulta um documento recebido",
"description": "Devolve a nota recebida com a situação fiscal, a procedência, os papéis do CNPJ e o histórico dos eventos capturados (cancelamento, substituição e outros), na ordem do NSU. Quando só o evento chegou, notaAusente é verdadeiro e os campos da nota vêm ausentes. Exige a permissão consultar.",
"operationId": "ConsultarDocumentoRecebido",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do documento recebido, como a lista devolve.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "emissor",
"in": "query",
"description": "CNPJ consultado. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "O documento recebido com os eventos.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecebidoVisivel"
},
"example": {
"id": "2f7k1m9q3b5d8h0j4n6p8r1t3v",
"emissor": "12345678000195",
"tipo": "nfse",
"recebedor": "nfse-nacional",
"ambiente": "producao",
"teste": false,
"procedencia": "terceiro",
"papeis": [
"tomador"
],
"chaveAcesso": "35503082198765432000110000000000000000987654321098",
"numero": "987",
"serie": "1",
"prestador": {
"documento": "98765432000110",
"nome": "Prestador Exemplo Ltda"
},
"tomador": {
"documento": "12345678000195",
"nome": "Empresa Exemplo Ltda"
},
"valor": 2300.00,
"datas": {
"capturado": "2026-10-26T12:00:04Z",
"emissao": "2026-10-22T13:05:21Z",
"cancelado": "2026-10-25T09:30:00Z"
},
"situacao": "cancelado",
"nsu": 1284,
"notaAusente": false,
"eventos": [
{
"nsu": 1290,
"tipo": "cancelamento",
"codigo": "e101101",
"data": "2026-10-25T09:30:00Z"
}
]
}
}
}
},
"400": {
"description": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O documento recebido não existe, é de outra conta ou de outro ambiente (chave de teste só vê os de teste), ou o certificado não pode consultar o emissor.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O documento recebido não existe, é de outra conta ou de outro ambiente (chave de teste só vê os de teste), ou o certificado não pode consultar o emissor.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O documento recebido não existe, é de outra conta ou de outro ambiente (chave de teste só vê os de teste), ou o certificado não pode consultar o emissor.",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/documentos-recebidos/{id}/xml": {
"get": {
"tags": [
"Documentos recebidos"
],
"summary": "Baixa o XML de um documento recebido",
"description": "Devolve o XML da nota como o recebedor a distribuiu. Exige a permissão consultar.",
"operationId": "BaixarXmlDoDocumentoRecebido",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Id do documento recebido, como a lista devolve.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "emissor",
"in": "query",
"description": "CNPJ consultado. Sem ele, vale o CNPJ do certificado da conexão; empresa de software habilitada informa o emissor.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "XML da nota recebida.",
"content": {
"application/xml": {
"schema": {
"type": "string"
},
"example": "\n4n8q2s6u0c8e4g6i2k0m6o4q2sSuporte técnico em informática...\n"
}
}
},
"400": {
"description": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"emissor_obrigatorio": {
"summary": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/emissor_obrigatorio",
"title": "Emissor obrigatório",
"status": 400,
"detail": "Sem o parâmetro emissor e sem CNPJ no certificado.",
"codigo": "emissor_obrigatorio",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"404": {
"description": "O documento recebido não existe, é de outra conta ou de outro ambiente (chave de teste só vê os de teste), ou o certificado não pode consultar o emissor. Só o evento chegou; a nota e o XML ainda não. Consulte de novo em instantes.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_encontrado": {
"summary": "O documento recebido não existe, é de outra conta ou de outro ambiente (chave de teste só vê os de teste), ou o certificado não pode consultar o emissor.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_encontrado",
"title": "Documento não encontrado",
"status": 404,
"detail": "O documento recebido não existe, é de outra conta ou de outro ambiente (chave de teste só vê os de teste), ou o certificado não pode consultar o emissor.",
"codigo": "nao_encontrado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
},
"xml_ainda_nao_gerado": {
"summary": "Só o evento chegou; a nota e o XML ainda não. Consulte de novo em instantes.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/xml_ainda_nao_gerado",
"title": "XML ainda não gerado",
"status": 404,
"detail": "Só o evento chegou; a nota e o XML ainda não. Consulte de novo em instantes.",
"codigo": "xml_ainda_nao_gerado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco ou o armazenamento não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
},
"/v1/eventos": {
"get": {
"tags": [
"Webhooks"
],
"summary": "Consulta os eventos da conta por cursor",
"description": "Devolve os eventos de webhook da conta no ambiente da chave, com ou sem cadastro de webhook, na ordem em que o NuvDocs os gravou e no mesmo formato do corpo do webhook. Comece sem cursor; guarde o cursor de cada resposta e mande-o na próxima chamada. Sem eventos novos, o cursor volta igual. Os últimos 5 segundos só aparecem na chamada seguinte, para nenhum evento ficar para trás. Cada evento fica disponível por 7 dias. Exige a permissão consultar.",
"operationId": "ConsultarEventos",
"parameters": [
{
"name": "cursor",
"in": "query",
"description": "Cursor da resposta anterior.",
"schema": {
"type": "string"
}
},
{
"name": "quantidade",
"in": "query",
"description": "Tamanho da página (1 a 1.000; padrão 100).",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "A página de eventos.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginaDeEventos"
},
"example": {
"eventos": [
{
"id": "019a1c2f8d117a3b9c0d1e2f3a4b5c6d",
"tipo": "documento.autorizado",
"data": "2026-10-23T12:00:01.512+00:00",
"teste": false,
"documento": {
"id": "4f7c2b9e1a3d5c7e9f1b3d5a7c9e1f3b",
"idCliente": "PED-000123",
"chaveAcesso": "35260712345678000195550010000001231000001230",
"emissor": "12345678000195",
"tipo": "nfse",
"serie": "1",
"numero": 123,
"situacao": "autorizado",
"sequencia": 7
},
"dados": {
"protocolo": "135260000012345"
}
},
{
"id": "019a1c2f6a227a3b9c0d1e2f3a4b5c6e",
"tipo": "documento.rejeitado",
"data": "2026-10-23T11:59:58.104+00:00",
"teste": false,
"documento": {
"id": "8a1c3e5f7b9d1f3a5c7e9b1d3f5a7c9e",
"idCliente": "PED-000124",
"emissor": "12345678000195",
"tipo": "nfse",
"situacao": "rejeitado",
"sequencia": 7,
"mensagem": "O recebedor recusou o documento.",
"rejeicao": [
{
"codigo": "E0312",
"origem": "recebedor",
"mensagemOriginal": "Código de tributação nacional inexistente.",
"descricao": "O código de serviço informado não existe na tabela nacional.",
"causaProvavel": "Código digitado errado ou de outra versão da tabela.",
"campo": "servico.codigoTributacaoNacional",
"correcao": "Use um código da lista nacional de serviços vigente."
}
]
}
}
],
"cursor": "019a1c2f8e9a7f3c8b5d2e1f0a9b8c7d",
"temMais": false
}
}
}
},
"400": {
"description": "Cursor que não veio da resposta anterior ou quantidade fora de 1 a 1.000.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"consulta_invalida": {
"summary": "Cursor que não veio da resposta anterior ou quantidade fora de 1 a 1.000.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/consulta_invalida",
"title": "Consulta inválida",
"status": 400,
"detail": "Cursor que não veio da resposta anterior ou quantidade fora de 1 a 1.000.",
"codigo": "consulta_invalida",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"503": {
"description": "O banco não respondeu; repita depois do Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"indisponivel": {
"summary": "O banco não respondeu; repita depois do Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/indisponivel",
"title": "Serviço indisponível",
"status": 503,
"detail": "O banco não respondeu; repita depois do Retry-After.",
"codigo": "indisponivel",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"401": {
"description": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"nao_autenticado": {
"summary": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/nao_autenticado",
"title": "Não autenticado",
"status": 401,
"detail": "Falta o certificado ICP-Brasil da conexão ou a chave de API (Authorization: Bearer), ou um dos dois foi recusado.",
"codigo": "nao_autenticado",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"403": {
"description": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"sem_permissao": {
"summary": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/sem_permissao",
"title": "Sem permissão",
"status": 403,
"detail": "A chave de API não tem a permissão do método (emitir, consultar, cancelar, webhooks ou captura).",
"codigo": "sem_permissao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
},
"429": {
"description": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemaDaApi"
},
"examples": {
"limite_de_vazao": {
"summary": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"value": {
"type": "https://docs.nuvdocs.com.br/erros/limite_de_vazao",
"title": "Limite de requisições excedido",
"status": 429,
"detail": "A conta passou do limite de requisições por segundo para o emissor; espere o Retry-After.",
"codigo": "limite_de_vazao",
"criticas": [ ],
"correlacao": "0192f3a5c1d27b3e9f4a6b8c0d1e2f3a"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"AjusteDaBaseDaLocacao": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Tipo da parcela, com 2 dígitos (`tpAjusteBCLocImoveis`; códigos em DominiosNt009).",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Descrição da parcela, exigida quando o tipo é \"outras parcelas\" (99).",
"nullable": true
},
"valor": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor total da parcela, sem a proporção do coproprietário.",
"format": "double",
"nullable": true
}
},
"description": "Parcela do aluguel que não entra na base de cálculo do IBS e da CBS (NT 009, `gAjusteBCLocImoveis`)."
},
"AjusteIbsCbs": {
"type": "object",
"properties": {
"finalidade": {
"type": "string",
"description": "Finalidade da nota: `credito` (leiaute `finNFSe` = 1) ou `debito` (`finNFSe` = 2).",
"nullable": true
},
"tipo": {
"type": "string",
"description": "Tipo do ajuste, com 2 dígitos: `tpNFSeCredito` na nota de crédito, `tpNFSeDebito` na nota de débito\n(códigos em DominiosNt009).",
"nullable": true
},
"valorIbs": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor do IBS a ajustar (`gIBSCBSAjuste/vIBS`).",
"format": "double",
"nullable": true
},
"valorCbs": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor da CBS a ajustar (`gIBSCBSAjuste/vCBS`).",
"format": "double",
"nullable": true
}
},
"description": "Nota de ajuste do IBS e da CBS (NT 009): crédito ou débito, o tipo do ajuste e os valores a ajustar. A nota\nreferenciada, quando o tipo pede, vai em IReadOnlyList<string>? IbsCbsNfse.NotasReferenciadas."
},
"BemMovelLocado": {
"type": "object",
"properties": {
"ncm": {
"type": "string",
"description": "Código NCM (Nomenclatura Comum do Mercosul) do bem, 8 dígitos.",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Descrição do bem.",
"nullable": true
},
"quantidade": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Quantidade do bem locado.",
"format": "int32",
"nullable": true
}
},
"description": "Bem móvel objeto da locação (NT 009, `IBSCBS/bensMoveis`)."
},
"BeneficioMunicipal": {
"type": "object",
"properties": {
"codigo": {
"type": "string",
"description": "Código do benefício no cadastro do município.",
"nullable": true
},
"valorReducao": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Redução da base de cálculo em valor.",
"format": "double",
"nullable": true
},
"percentualReducao": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Redução da base de cálculo em percentual.",
"format": "double",
"nullable": true
}
},
"description": "Benefício cadastrado pelo município, com a redução por valor ou por percentual."
},
"CapturaVisivel": {
"required": [
"emissor",
"recebedor",
"ambiente",
"teste",
"ativa",
"ativadaEm",
"ultimoNsu",
"proximaConsulta"
],
"type": "object",
"properties": {
"emissor": {
"type": "string",
"description": "CNPJ consultado."
},
"recebedor": {
"type": "string",
"description": "Recebedor consultado."
},
"ambiente": {
"type": "string",
"description": "Ambiente da captura (`producao`, `producao_restrita` ou `simulacao`)."
},
"teste": {
"type": "boolean",
"description": "Verdadeiro para captura ativada com chave de teste: os documentos recebidos ficam à parte."
},
"ativa": {
"type": "boolean",
"description": "Verdadeiro enquanto a captura está ativa."
},
"ativadaEm": {
"type": "string",
"description": "Quando a captura foi ativada pela última vez.",
"format": "date-time"
},
"desativadaEm": {
"type": "string",
"description": "Quando a captura foi desativada; ausente enquanto ativa.",
"format": "date-time",
"nullable": true
},
"ultimoNsu": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Último NSU (número sequencial único) já gravado; zero antes da primeira consulta.",
"format": "int64"
},
"proximaConsulta": {
"type": "string",
"description": "Quando a próxima consulta vence.",
"format": "date-time"
},
"ultimaConsulta": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/UltimaConsultaVisivel"
}
]
}
},
"description": "Captura de um CNPJ como a API de integração a devolve (`/v1/capturas/{cnpj}`): se está ativa, até que NSU já foi\ngravado, quando vence a próxima consulta e como terminou a última. Em JSON pelo contexto da API: campos em camelCase e\nnulos omitidos."
},
"CobrancaDoCondominio": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Tipo da cobrança, com 2 dígitos (`tpCobranca`; códigos em DominiosNt009).",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Descrição da cobrança, exigida quando o tipo é \"outra cobrança\" (99).",
"nullable": true
},
"valor": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor da cobrança.",
"format": "double",
"nullable": true
},
"detalhes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DetalheDaCobranca"
},
"description": "Detalhes da cobrança, até 20.",
"nullable": true
}
},
"description": "Uma cobrança do condomínio (NT 009, `condominios/gCobranca`)."
},
"ComercioExteriorNfse": {
"type": "object",
"properties": {
"modoPrestacao": {
"type": "string",
"description": "Modo de prestação (transfronteiriço, consumo no Brasil, movimento de pessoas, consumo no exterior; na NT 009,\ntambém 5 = consumo no Brasil e no exterior ao mesmo tempo).",
"nullable": true
},
"vinculo": {
"type": "string",
"description": "Vínculo entre as partes.",
"nullable": true
},
"moeda": {
"type": "string",
"description": "Moeda da transação: código de 3 dígitos da tabela de moedas do Banco Central.",
"nullable": true
},
"valorNaMoeda": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor do serviço na moeda da transação.",
"format": "double",
"nullable": true
},
"apoioPrestador": {
"type": "string",
"description": "Mecanismo de apoio ao comércio exterior usado pelo prestador.",
"nullable": true
},
"apoioTomador": {
"type": "string",
"description": "Mecanismo de apoio ao comércio exterior usado pelo tomador.",
"nullable": true
},
"movimentacaoTemporariaDeBens": {
"type": "string",
"description": "Movimentação temporária de bens.",
"nullable": true
},
"declaracaoImportacao": {
"type": "string",
"description": "Número da declaração de importação, quando há importação temporária: `nDI` no leiaute v1.01,\n`nDUIMP` (Declaração Única de Importação) na NT 009.",
"nullable": true
},
"registroExportacao": {
"type": "string",
"description": "Número do registro de exportação, quando há exportação temporária: `nRE` no leiaute v1.01,\n`nDUE` (Declaração Única de Exportação) na NT 009.",
"nullable": true
},
"numeroFatura": {
"type": "string",
"description": "Número da fatura ou do documento que comprova a transação, até 20 dígitos (NT 009, `nFatura`).",
"nullable": true
},
"valorFatura": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor total da fatura, na moeda da transação (NT 009, `vFatura`).",
"format": "double",
"nullable": true
},
"contratoDeCambio": {
"type": "string",
"description": "Número do contrato de câmbio ou do documento que comprova o pagamento, até 20 dígitos (NT 009,\n`nContCambio`).",
"nullable": true
},
"ajusteDaBaseIbsCbs": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Ajuste da base de cálculo do IBS e da CBS no comércio exterior, em reais; pode ser negativo (NT 009,\n`vAjusteBC/vAjusteBCIBSCBSComExt`).",
"format": "double",
"nullable": true
},
"compartilharComMdic": {
"type": "boolean",
"description": "Verdadeiro para compartilhar a nota com o MDIC.",
"nullable": true
},
"paisDoResultado": {
"type": "string",
"description": "País onde o cliente aproveita o resultado do serviço (ISO de duas letras).",
"nullable": true
}
},
"description": "Comércio exterior de serviços: como o serviço chegou ao cliente, moeda, apoio e bens temporários.\nOs códigos seguem as tabelas oficiais; o adaptador confere os valores aceitos pelo leiaute."
},
"CondominioNfse": {
"type": "object",
"properties": {
"vencimentoOriginal": {
"type": "string",
"description": "Data de vencimento original das taxas cobradas; obrigatória.",
"format": "date",
"nullable": true
},
"cobrancas": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CobrancaDoCondominio"
},
"description": "Cobranças, de 1 a 20; a soma dos valores dá o valor do serviço.",
"nullable": true
},
"descontos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DescontoDoCondominio"
},
"description": "Descontos dados nas cobranças, até 10.",
"nullable": true
}
},
"description": "Cobrança das taxas e dos demais valores do condomínio ao condômino (NT 009, `IBSCBS/condominios`)."
},
"ConteudoNfse": {
"type": "object",
"properties": {
"prestador": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/PrestadorNfse"
}
]
},
"tomador": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ParteNfse"
}
]
},
"intermediario": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ParteNfse"
}
]
},
"servico": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ServicoNfse"
}
]
},
"obra": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ObraNfse"
}
]
},
"evento": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EventoNfse"
}
]
},
"comercioExterior": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ComercioExteriorNfse"
}
]
},
"referencias": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ReferenciasNfse"
}
]
},
"valores": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ValoresNfse"
}
]
},
"tributos": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/TributosNfse"
}
]
},
"ibsCbs": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/IbsCbsNfse"
}
]
},
"substitui": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/SubstituicaoNfse"
}
]
},
"serie": {
"type": "string",
"description": "Série informada pelo cliente; ausente, a preparação numera.",
"nullable": true
},
"numero": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Número informado pelo cliente; ausente, a preparação numera.",
"format": "int64",
"nullable": true
}
},
"description": "Conteúdo da NFS-e no JSON próprio (fluxo/entrada-json, \"Conteúdo NFS-e\"). Os nomes não seguem o leiaute\nda DPS: o adaptador converte. O que o NuvDocs infere pode ser omitido; o que vier prevalece e é validado."
},
"CorpoDoEventoDeWebhook": {
"required": [
"id",
"tipo",
"data",
"teste"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id do evento, estável: a repetição da entrega leva o mesmo id, para o cliente descartar o repetido."
},
"tipo": {
"type": "string",
"description": "Tipo do catálogo (TiposDeEventoDoWebhook)."
},
"data": {
"type": "string",
"description": "Data do fato, em UTC.",
"format": "date-time"
},
"teste": {
"type": "boolean",
"description": "Verdadeiro para evento do ambiente de testes (sem efeito fiscal)."
},
"documento": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/DocumentoNoWebhook"
}
]
},
"emissor": {
"type": "string",
"description": "CNPJ ou CPF do emissor, nos eventos de conta ligados a um emissor (certificado, habilitação).",
"nullable": true
},
"dados": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Dados próprios do tipo (protocolo, motivo, substituto, cadastro...), em texto.",
"nullable": true
}
},
"description": "Um evento como o cliente recebe, no webhook (lista `eventos` do corpo) e na consulta `GET /v1/eventos`. Em\nJSON pelo ContextoJsonDosWebhooks: camelCase, nulos omitidos."
},
"Critica": {
"required": [
"campo",
"codigo",
"mensagem"
],
"type": "object",
"properties": {
"campo": {
"type": "string",
"description": "Caminho do campo no JSON próprio, relativo ao conteúdo (`tomador.cnpj`, `valores.deducao.documentos[0].valor`);\ncampos do envelope vêm pelo nome (`emissor`); vazio quando o problema é do documento inteiro."
},
"codigo": {
"type": "string",
"description": "Código estável da regra (ver CodigosDeCritica ou o código do recebedor)."
},
"mensagem": {
"type": "string",
"description": "Explicação curta em português, para quem integra."
}
},
"description": "Problema encontrado num campo antes da transmissão. É o formato único das críticas da leitura da\nentrada, dos validadores genéricos, de `IAdaptadorRecebedor.ValidarAsync`, da pré-validação e do\nevento `documento.criticado` (funcionalidades/rejeicoes, origem `nuvdocs`). A explicação\ncompleta (descrição, causa provável, correção) vem do catálogo de rejeições pelo código."
},
"DatasDoDocumento": {
"required": [
"recebido"
],
"type": "object",
"properties": {
"recebido": {
"type": "string",
"description": "Quando o NuvDocs gravou o documento e confirmou ao cliente.",
"format": "date-time"
},
"emissao": {
"type": "string",
"description": "Data de emissão: a declarada pelo cliente ou, sem ela, a do recebimento (a mesma que a preparação põe no XML).\n[PROPOSTA] É o campo do período da busca (funcionalidades/busca); nulo só em registro gravado antes da S4.",
"format": "date-time",
"nullable": true
},
"autorizado": {
"type": "string",
"description": "Quando o recebedor autorizou.",
"format": "date-time",
"nullable": true
},
"cancelado": {
"type": "string",
"description": "Quando o cancelamento foi registrado.",
"format": "date-time",
"nullable": true
},
"substituido": {
"type": "string",
"description": "Quando a substituição foi registrada.",
"format": "date-time",
"nullable": true
}
},
"description": "Datas marcantes do documento, todas em UTC. As do caminho intermediário ficam no histórico de eventos."
},
"DatasDoRecebido": {
"required": [
"capturado"
],
"type": "object",
"properties": {
"capturado": {
"type": "string",
"description": "Quando a captura gravou o registro pela primeira vez.",
"format": "date-time"
},
"emissao": {
"type": "string",
"description": "Data de emissão da nota; nula enquanto só o evento chegou (bool DocumentoRecebido.NotaAusente).",
"format": "date-time",
"nullable": true
},
"cancelado": {
"type": "string",
"description": "Quando o cancelamento foi registrado no recebedor.",
"format": "date-time",
"nullable": true
}
},
"description": "Datas do documento recebido, todas em UTC."
},
"DeducaoNfse": {
"type": "object",
"properties": {
"percentual": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Percentual de dedução.",
"format": "double",
"nullable": true
},
"valor": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor da dedução.",
"format": "double",
"nullable": true
},
"documentos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentoDeDeducao"
},
"description": "Documentos que comprovam a dedução.",
"nullable": true
}
},
"description": "Dedução da base de cálculo, num dos três modos que o município aceita: percentual, valor ou documentos."
},
"DescontoDoCondominio": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Tipo do desconto: `incondicionado` (leiaute `tpDesconto` = 1) ou `condicionado` (`tpDesconto` = 2).",
"nullable": true
},
"valor": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor do desconto.",
"format": "double",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Descrição do desconto; obrigatória.",
"nullable": true
}
},
"description": "Desconto dado nas cobranças do condomínio (NT 009, `condominios/gDesconto`)."
},
"DetalheDaCobranca": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Tipo do detalhe, com 3 dígitos (`tpDetCobranca`; códigos em DominiosNt009).",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Descrição do detalhe, exigida quando o tipo é \"outro\" (999).",
"nullable": true
},
"valor": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor do detalhe, que compõe o valor da cobrança.",
"format": "double",
"nullable": true
}
},
"description": "Detalhe de uma cobrança do condomínio (NT 009, `gCobranca/gDetCobranca`)."
},
"DiferimentoIbsCbs": {
"type": "object",
"properties": {
"percentualIbsEstadual": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Diferimento do IBS estadual, em percentual.",
"format": "double",
"nullable": true
},
"percentualIbsMunicipal": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Diferimento do IBS municipal, em percentual.",
"format": "double",
"nullable": true
},
"percentualCbs": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Diferimento da CBS, em percentual.",
"format": "double",
"nullable": true
}
},
"description": "Percentuais de diferimento do IBS (estadual e municipal) e da CBS."
},
"DocumentoConsultado": {
"required": [
"id",
"chaveIdempotencia",
"emissor",
"tipo",
"recebedor",
"ambiente",
"teste",
"faixa",
"situacao",
"datas"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id do documento."
},
"chaveIdempotencia": {
"type": "string",
"description": "Chave de idempotência do envio."
},
"idCliente": {
"type": "string",
"description": "Identificador informado pelo cliente.",
"nullable": true
},
"emissor": {
"type": "string",
"description": "CNPJ do emissor."
},
"tipo": {
"type": "string",
"description": "Tipo do documento (`nfse`...)."
},
"recebedor": {
"type": "string",
"description": "Recebedor de destino."
},
"ambiente": {
"type": "string",
"description": "Ambiente de emissão."
},
"teste": {
"type": "boolean",
"description": "Verdadeiro para documento de chave de teste."
},
"faixa": {
"type": "string",
"description": "Faixa de processamento."
},
"situacao": {
"type": "string",
"description": "Estado atual do documento."
},
"chaveAcesso": {
"type": "string",
"description": "Chave de acesso, depois da autorização.",
"nullable": true
},
"serie": {
"type": "string",
"description": "Série, informada ou atribuída na preparação.",
"nullable": true
},
"numero": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Número, informado ou atribuído na preparação.",
"format": "int64",
"nullable": true
},
"datas": {
"$ref": "#/components/schemas/DatasDoDocumento"
},
"criticas": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Critica"
},
"description": "Críticas do NuvDocs, quando `criticado`; nulo nos outros estados.",
"nullable": true
},
"rejeicao": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RejeicaoExplicada"
},
"description": "Explicação completa de cada código, no formato de RejeicaoExplicada (descrição, causa provável,\ncampo e correção do catálogo atual): os códigos do recebedor quando `rejeitado` ou `denegado`, e as\ncríticas do NuvDocs (origem `nuvdocs`) quando `criticado`. Nulo nos outros estados.",
"nullable": true
},
"eventosFiscais": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/SituacaoDosEventos"
}
]
},
"tomador": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/TomadorConsultado"
}
]
},
"valor": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor do serviço declarado, quando a preparação já leu o conteúdo.",
"format": "double",
"nullable": true
}
},
"description": "Situação de um documento como a API de integração a devolve (interfaces/integracao,\n`GET /v1/documentos/{id}`). Em JSON pelo ContextoJsonDaConsulta: campos em camelCase,\nnulos omitidos, estado, ambiente e faixa nos textos gravados (`em_transmissao`, `simulacao`...)."
},
"DocumentoDeDeducao": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Tipo da dedução (materiais, subempreitada, outras...), pelo código da tabela oficial.",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Descrição, exigida quando o tipo é \"outras\".",
"nullable": true
},
"chaveAcesso": {
"type": "string",
"description": "Chave de acesso da nota eletrônica nacional: 50 dígitos (nota de serviço) ou 44 (nota de produto).",
"nullable": true
},
"numero": {
"type": "string",
"description": "Número de documento não fiscal (recibo, contrato), quando não há documento fiscal.",
"nullable": true
},
"data": {
"type": "string",
"description": "Data de emissão do documento.",
"format": "date",
"nullable": true
},
"valorDedutivel": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor dedutível do documento.",
"format": "double",
"nullable": true
},
"valorDeduzido": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor deduzido nesta nota.",
"format": "double",
"nullable": true
},
"fornecedor": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ParteNfse"
}
]
},
"notaMunicipal": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/NotaMunicipal"
}
]
},
"notaEmPapel": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/NotaEmPapel"
}
]
},
"documentoFiscal": {
"type": "string",
"description": "Número de outro documento fiscal, quando não há chave nem nota municipal.",
"nullable": true
}
},
"description": "Documento que comprova uma dedução: nota de material, subempreitada e afins."
},
"DocumentoFiscalDeTerceiro": {
"type": "object",
"properties": {
"municipio": {
"type": "string",
"description": "Código do município emissor no IBGE, 7 dígitos.",
"nullable": true
},
"numero": {
"type": "string",
"description": "Número do documento.",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Descrição do documento.",
"nullable": true
}
},
"description": "Documento fiscal de um terceiro que não está no repositório nacional: município, número e descrição."
},
"DocumentoNoWebhook": {
"required": [
"id",
"emissor",
"tipo",
"situacao",
"sequencia"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id do documento no NuvDocs (no cancelamento e na substituição, o id do documento original)."
},
"idCliente": {
"type": "string",
"description": "Identificador informado pelo cliente no envio.",
"nullable": true
},
"chaveAcesso": {
"type": "string",
"description": "Chave de acesso, depois da autorização.",
"nullable": true
},
"emissor": {
"type": "string",
"description": "CNPJ ou CPF do emissor."
},
"tipo": {
"type": "string",
"description": "Tipo do documento (`nfse`...)."
},
"serie": {
"type": "string",
"description": "Série.",
"nullable": true
},
"numero": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Número.",
"format": "int64",
"nullable": true
},
"situacao": {
"type": "string",
"description": "Situação do documento logo depois do evento (`autorizado`, `cancelado`...)."
},
"sequencia": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Sequência do evento no documento: sem garantia de ordem na entrega, vale a maior.",
"format": "int64"
},
"mensagem": {
"type": "string",
"description": "Explicação curta do resultado, em português, quando o recebedor ou o NuvDocs deu.",
"nullable": true
},
"rejeicao": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RejeicaoExplicada"
},
"description": "Códigos e críticas com a explicação do catálogo (funcionalidades/rejeicoes).",
"nullable": true
}
},
"description": "O documento num evento de webhook (definição, 4.5, \"Conteúdo enxuto\"): os três identificadores, a situação depois do\nevento, a sequência e, quando há, mensagem e explicação da rejeição. Sem XML e sem PDF: o cliente os busca pela API."
},
"EnderecoExterior": {
"type": "object",
"properties": {
"pais": {
"type": "string",
"description": "País, código ISO 3166-1 de duas letras.",
"nullable": true
},
"codigoPostal": {
"type": "string",
"description": "Código postal.",
"nullable": true
},
"cidade": {
"type": "string",
"description": "Cidade.",
"nullable": true
},
"estado": {
"type": "string",
"description": "Estado, província ou região.",
"nullable": true
},
"logradouro": {
"type": "string",
"description": "Logradouro.",
"nullable": true
},
"numero": {
"type": "string",
"description": "Número.",
"nullable": true
},
"complemento": {
"type": "string",
"description": "Complemento.",
"nullable": true
},
"bairro": {
"type": "string",
"description": "Bairro ou distrito.",
"nullable": true
}
},
"description": "Endereço fora do Brasil, com o país pelo código ISO de duas letras."
},
"EnderecoNacional": {
"type": "object",
"properties": {
"cep": {
"type": "string",
"description": "CEP, 8 dígitos.",
"nullable": true
},
"municipio": {
"type": "string",
"description": "Código do município no IBGE, 7 dígitos.",
"nullable": true
},
"logradouro": {
"type": "string",
"description": "Logradouro.",
"nullable": true
},
"numero": {
"type": "string",
"description": "Número.",
"nullable": true
},
"complemento": {
"type": "string",
"description": "Complemento.",
"nullable": true
},
"bairro": {
"type": "string",
"description": "Bairro.",
"nullable": true
}
},
"description": "Endereço no Brasil, com o município pelo código do IBGE."
},
"EntregaVisivel": {
"required": [
"evento",
"tipo",
"data",
"situacao",
"tentativas"
],
"type": "object",
"properties": {
"evento": {
"type": "string",
"description": "Id do evento."
},
"tipo": {
"type": "string",
"description": "Tipo do evento."
},
"data": {
"type": "string",
"description": "Data do fato, em UTC.",
"format": "date-time"
},
"documento": {
"type": "string",
"description": "Id do documento, nos eventos de documento.",
"nullable": true
},
"situacao": {
"type": "string",
"description": "`pendente`, `em_entrega`, `entregue` ou `guardado`."
},
"tentativas": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Chamadas sem 2xx.",
"format": "int32"
},
"proximaTentativa": {
"type": "string",
"description": "Quando vai de novo, nos pendentes.",
"format": "date-time",
"nullable": true
},
"entrega": {
"type": "string",
"description": "Id do último grupo (`NuvDocs-Entrega`).",
"nullable": true
},
"entregueEm": {
"type": "string",
"description": "Quando o cliente confirmou.",
"format": "date-time",
"nullable": true
},
"ultimaFalha": {
"type": "string",
"description": "Motivo da última falha (`http_503`, `tempo_esgotado`, `conexao`...).",
"nullable": true
}
},
"description": "Um evento no histórico de entregas de um cadastro, como o cliente vê (`GET /v1/webhooks/{id}/entregas`, site e\napp). Sem o corpo: o evento completo vem na consulta por cursor."
},
"EnvelopeNfse": {
"type": "object",
"properties": {
"conteudo": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ConteudoNfse"
}
]
},
"emissor": {
"type": "string",
"description": "CNPJ do emissor.",
"nullable": true
},
"chaveIdempotencia": {
"type": "string",
"description": "Chave de idempotência, até 64 caracteres.",
"nullable": true
},
"idCliente": {
"type": "string",
"description": "Identificador opcional do cliente.",
"nullable": true
},
"faixa": {
"type": "string",
"description": "Faixa pedida: `imediata` ou `lote`.",
"nullable": true
},
"tipo": {
"type": "string",
"description": "Tipo do documento (`nfse`...).",
"nullable": true
},
"recebedor": {
"type": "string",
"description": "Recebedor de destino; obrigatório quando o cliente manda XML.",
"nullable": true
},
"xml": {
"type": "string",
"description": "XML no leiaute do recebedor, quando o cliente não manda o JSON próprio.",
"nullable": true
}
},
"description": "Envelope do JSON próprio com o conteúdo de NFS-e (tipo `nfse`)."
},
"EsperaAtual": {
"required": [
"situacao",
"desde",
"duracaoEmMilissegundos",
"categoria"
],
"type": "object",
"properties": {
"situacao": {
"type": "string",
"description": "Situação em que o documento espera."
},
"desde": {
"type": "string",
"description": "Data do último passo, em UTC.",
"format": "date-time"
},
"duracaoEmMilissegundos": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Duração da espera até a consulta.",
"format": "int64"
},
"categoria": {
"type": "string",
"description": "Onde o tempo está sendo gasto."
}
},
"description": "Intervalo ainda aberto: o documento espera desde o último passo (no represamento, no recebedor, numa fila ou\nretido). Entra no tempo total, para a soma das durações bater com ele."
},
"EstornoDeCreditoIbsCbs": {
"type": "object",
"properties": {
"valorIbs": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor do IBS a estornar (`vIBSEstCred`).",
"format": "double",
"nullable": true
},
"valorCbs": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor da CBS a estornar (`vCBSEstCred`).",
"format": "double",
"nullable": true
}
},
"description": "Estorno dos créditos de IBS e de CBS da entrada, na doação com anulação de crédito (NT 009, `gEstornoCred`)."
},
"EventoEmAndamentoNaConsulta": {
"required": [
"id",
"tipo",
"solicitadoEm"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identificador do evento, o mesmo devolvido no pedido.",
"format": "uuid"
},
"tipo": {
"type": "string",
"description": "Tipo do evento."
},
"solicitadoEm": {
"type": "string",
"description": "Quando foi pedido, em UTC.",
"format": "date-time"
},
"substituto": {
"type": "string",
"description": "Id do documento substituto, na substituição.",
"nullable": true
}
},
"description": "Evento fiscal em andamento, como a consulta o mostra."
},
"EventoFiscalSolicitado": {
"required": [
"documento",
"evento",
"tipo",
"situacao"
],
"type": "object",
"properties": {
"documento": {
"type": "string",
"description": "Id do documento."
},
"evento": {
"type": "string",
"description": "Identificador do evento fiscal (UUID v7; derivado da pendência, com aprovação).",
"format": "uuid"
},
"tipo": {
"type": "string",
"description": "Tipo do evento."
},
"situacao": {
"type": "string",
"description": "`solicitado`, ou `pendente_de_aprovacao` quando o evento espera aprovação."
},
"aprovacao": {
"type": "string",
"description": "Id da pendência de aprovação; nulo quando o evento não espera aprovação.",
"nullable": true
}
},
"description": "Resposta 202 de `POST /v1/documentos/{id}/eventos`: o id do evento para acompanhar pela consulta e pelo\nwebhook. O resultado do recebedor chega depois (`documento.evento.registrado` ou `.rejeitado`)."
},
"EventoNfse": {
"type": "object",
"properties": {
"nome": {
"type": "string",
"description": "Nome do evento.",
"nullable": true
},
"inicio": {
"type": "string",
"description": "Primeiro dia do evento.",
"format": "date",
"nullable": true
},
"fim": {
"type": "string",
"description": "Último dia do evento.",
"format": "date",
"nullable": true
},
"municipio": {
"type": "string",
"description": "Município do evento (IBGE, 7 dígitos; NT 009, `atvEvento/cMun`), quando o evento é fora do local da\nprestação.",
"nullable": true
},
"codigoMunicipal": {
"type": "string",
"description": "Código do evento no cadastro do município.",
"nullable": true
},
"endereco": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoNacional"
}
]
},
"enderecoExterior": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoExterior"
}
]
}
},
"description": "Show ou evento: nome, período e local (código municipal do evento ou endereço)."
},
"EventoVisivelDoRecebido": {
"required": [
"nsu",
"tipo",
"codigo",
"data"
],
"type": "object",
"properties": {
"nsu": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "NSU (número sequencial único) do evento na distribuição do recebedor.",
"format": "int64"
},
"tipo": {
"type": "string",
"description": "Tipo no vocabulário do NuvDocs: `cancelamento`, `substituicao` ou `outro`."
},
"codigo": {
"type": "string",
"description": "Código do evento no recebedor (por exemplo `e101101`)."
},
"data": {
"type": "string",
"description": "Quando o recebedor registrou o evento, em UTC.",
"format": "date-time"
},
"chaveDaSubstituta": {
"type": "string",
"description": "Chave de acesso da nota substituta, só na substituição.",
"nullable": true
}
},
"description": "Evento fiscal capturado sobre um documento recebido, como a API o devolve."
},
"FaixaDeProcessamento": {
"enum": [
"imediata",
"lote"
],
"type": "string"
},
"IbsCbsNfse": {
"type": "object",
"properties": {
"indicadorOperacao": {
"type": "string",
"description": "Indicador da operação (tabela oficial); inferido quando omitido.",
"nullable": true
},
"consumoFinal": {
"type": "boolean",
"description": "Verdadeiro quando o cliente usa o serviço para consumo próprio.",
"nullable": true
},
"cst": {
"type": "string",
"description": "Situação tributária do IBS e da CBS (CST, 3 dígitos).",
"nullable": true
},
"classificacaoTributaria": {
"type": "string",
"description": "Classificação tributária (começa pelo CST).",
"nullable": true
},
"creditoPresumido": {
"type": "string",
"description": "Código do crédito presumido, quando a classificação permite.",
"nullable": true
},
"diferimento": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/DiferimentoIbsCbs"
}
]
},
"tipoOperacao": {
"type": "string",
"description": "Tipo de operação com o ente governamental.",
"nullable": true
},
"enteGovernamental": {
"type": "string",
"description": "Esfera do ente governamental (União, estado, Distrito Federal, município).",
"nullable": true
},
"notasReferenciadas": {
"type": "array",
"items": {
"type": "string"
},
"description": "Chaves de acesso das notas referenciadas.",
"nullable": true
},
"destinatario": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ParteNfse"
}
]
},
"imovel": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ImovelNfse"
}
]
},
"reembolsos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReembolsoNfse"
},
"description": "Reembolsos e repasses a terceiros.",
"nullable": true
},
"tributacaoRegular": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/TributacaoRegularIbsCbs"
}
]
},
"ajuste": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/AjusteIbsCbs"
}
]
},
"doacao": {
"type": "boolean",
"description": "Verdadeiro na operação de doação (NT 009, `indDoacao`).",
"nullable": true
},
"estornoCredito": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EstornoDeCreditoIbsCbs"
}
]
},
"zonaFrancaOuLivreComercio": {
"type": "boolean",
"description": "Verdadeiro na operação com alíquota zero de CBS na Zona Franca de Manaus ou em área de livre comércio\n(NT 009, `indZFMALC`).",
"nullable": true
},
"notasDePagamentoAntecipado": {
"type": "array",
"items": {
"type": "string"
},
"description": "Chaves das notas de pagamento antecipado abatidas por esta nota (NT 009, `gPagAntecipado`), até 99.",
"nullable": true
},
"bensMoveis": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BemMovelLocado"
},
"description": "Bens móveis objeto da locação (NT 009, `bensMoveis`), até 1.000.",
"nullable": true
},
"condominio": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/CondominioNfse"
}
]
},
"pagamentosVinculados": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PagamentoVinculado"
},
"description": "Pagamentos vinculados à nota (NT 009, `gPgtoVinc/pgto`), de 1 a 99.",
"nullable": true
}
},
"description": "IBS e CBS da reforma tributária (definição, 11.6), com nomes independentes do leiaute. Os campos cobrem o\nleiaute em produção (S5) e os grupos novos da NT 009 (S16); o adaptador infere o indicador da operação e a classificação quando omitidos."
},
"ImovelNfse": {
"type": "object",
"properties": {
"municipio": {
"type": "string",
"description": "Município do imóvel (IBGE, 7 dígitos; NT 009, `imovel/cMun`).",
"nullable": true
},
"locacao": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/LocacaoDeImovel"
}
]
},
"unidades": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UnidadeImobiliaria"
},
"description": "Unidades imobiliárias da operação (NT 009, `gUnidImob`), até 99, no mesmo município.",
"nullable": true
},
"inscricaoImobiliaria": {
"type": "string",
"description": "Inscrição imobiliária fiscal.",
"nullable": true
},
"cib": {
"type": "string",
"description": "Cadastro Imobiliário Brasileiro (CIB).",
"nullable": true
},
"endereco": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoNacional"
}
]
},
"enderecoExterior": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoExterior"
}
]
}
},
"description": "Imóvel da operação (venda, locação, administração): inscrição, CIB ou endereço. Na NT 009, o leiaute leva o\nimóvel por município e por unidades; os campos de uma unidade só continuam aceitos aqui."
},
"LinhaDoTempo": {
"required": [
"documento",
"emissor",
"situacao",
"inicio",
"fim",
"duracaoTotalEmMilissegundos",
"totais",
"tentativasDeTransmissao",
"passos",
"truncada"
],
"type": "object",
"properties": {
"documento": {
"type": "string",
"description": "Id do documento."
},
"emissor": {
"type": "string",
"description": "CNPJ do emissor."
},
"situacao": {
"type": "string",
"description": "Situação do documento no último passo."
},
"inicio": {
"type": "string",
"description": "Data do primeiro passo (recebido), em UTC.",
"format": "date-time"
},
"fim": {
"type": "string",
"description": "Data do último passo ou, com espera aberta, da consulta, em UTC.",
"format": "date-time"
},
"duracaoTotalEmMilissegundos": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "De DateTime LinhaDoTempo.Inicio a DateTime LinhaDoTempo.Fim.",
"format": "int64"
},
"totais": {
"$ref": "#/components/schemas/TotaisPorCategoria"
},
"tentativasDeTransmissao": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Quantas vezes o documento foi enviado ao recebedor.",
"format": "int32"
},
"passos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PassoDaLinhaDoTempo"
},
"description": "Passos, em ordem."
},
"espera": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EsperaAtual"
}
]
},
"truncada": {
"type": "boolean",
"description": "Verdadeiro quando o histórico tem mais passos que o máximo mostrado; a soma vale para os mostrados."
}
},
"description": "Linha do tempo de um documento (funcionalidades/linha-do-tempo; `GET /v1/documentos/{id}/linha-do-tempo`): cada\npasso com horário e duração, a espera atual e os totais por categoria. A soma das durações dos passos e da espera é\nigual a long LinhaDoTempo.DuracaoTotalEmMilissegundos."
},
"LocacaoDeImovel": {
"type": "object",
"properties": {
"percentualCopropriedade": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Percentual de copropriedade do locador; 100 quando há um só locador.",
"format": "double",
"nullable": true
},
"valorTotalOperacao": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor total da operação, sem a proporção do coproprietário.",
"format": "double",
"nullable": true
},
"descontoIncondicionadoTotal": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Total do desconto incondicionado da operação.",
"format": "double",
"nullable": true
},
"descontoCondicionadoTotal": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Total do desconto condicionado da operação.",
"format": "double",
"nullable": true
},
"vencimentoOriginal": {
"type": "string",
"description": "Data de vencimento original do aluguel ou equivalente; só informativa.",
"format": "date",
"nullable": true
}
},
"description": "Dados da locação, cessão onerosa ou arrendamento de bem imóvel (NT 009, `imovel/gLocacao`)."
},
"NotaEmPapel": {
"type": "object",
"properties": {
"numero": {
"type": "string",
"description": "Número da nota, até 7 dígitos.",
"nullable": true
},
"modelo": {
"type": "string",
"description": "Modelo da nota.",
"nullable": true
},
"serie": {
"type": "string",
"description": "Série da nota, até 15 letras ou dígitos.",
"nullable": true
}
},
"description": "Nota fiscal em papel, identificada por número, modelo e série."
},
"NotaMunicipal": {
"type": "object",
"properties": {
"municipio": {
"type": "string",
"description": "Código do município emissor no IBGE, 7 dígitos.",
"nullable": true
},
"numero": {
"type": "string",
"description": "Número da nota, até 15 dígitos.",
"nullable": true
},
"codigoVerificacao": {
"type": "string",
"description": "Código de verificação da nota, até 9 letras ou dígitos.",
"nullable": true
}
},
"description": "Nota de serviço emitida no sistema de um município, sem chave de acesso nacional."
},
"ObraNfse": {
"type": "object",
"properties": {
"cno": {
"type": "string",
"description": "Cadastro Nacional de Obras (CNO, antigo CEI).",
"nullable": true
},
"cib": {
"type": "string",
"description": "Cadastro Imobiliário Brasileiro (CIB).",
"nullable": true
},
"endereco": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoNacional"
}
]
},
"enderecoExterior": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoExterior"
}
]
},
"inscricaoImobiliaria": {
"type": "string",
"description": "Inscrição imobiliária fiscal.",
"nullable": true
}
},
"description": "Obra de construção civil: identificada pelo CNO, pelo CIB ou pelo endereço."
},
"PagamentoVinculado": {
"type": "object",
"properties": {
"idTransacao": {
"type": "string",
"description": "Identificador da transação financeira; não se repete na nota.",
"nullable": true
},
"meioPagamento": {
"type": "string",
"description": "Meio de pagamento, com 2 dígitos (`tpMeioPgto`; códigos em DominiosNt009).",
"nullable": true
},
"cnpjRecebedor": {
"type": "string",
"description": "CNPJ de quem recebe o pagamento do tomador (fornecedor, plataforma ou outra entidade).",
"nullable": true
},
"cnpjBaseInstituicao": {
"type": "string",
"description": "CNPJ base (8 dígitos) da instituição financeira ou de pagamento do recebedor.",
"nullable": true
}
},
"description": "Pagamento vinculado à nota (NT 009, `gPgtoVinc/pgto`). O numerador do leiaute (`nPag`) não vem no\nJSON: o adaptador usa a posição na lista, a partir de 1."
},
"PaginaDeEntregas": {
"required": [
"entregas"
],
"type": "object",
"properties": {
"entregas": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntregaVisivel"
},
"description": "Eventos da página."
},
"cursor": {
"type": "string",
"description": "Valor para pedir a página seguinte; nulo na última.",
"nullable": true
}
},
"description": "Uma página do histórico de entregas de um cadastro, do evento mais novo para o mais antigo."
},
"PaginaDeEventos": {
"required": [
"eventos",
"temMais"
],
"type": "object",
"properties": {
"eventos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CorpoDoEventoDeWebhook"
},
"description": "Eventos da página, no mesmo formato do webhook."
},
"cursor": {
"type": "string",
"description": "Valor para a próxima chamada. Guarde-o: sem eventos novos, volta o mesmo. Nunca vem nulo depois da primeira\npágina com eventos.",
"nullable": true
},
"temMais": {
"type": "boolean",
"description": "Verdadeiro quando já há outra página pronta."
}
},
"description": "Uma página da consulta de eventos por cursor (`GET /v1/eventos`), na ordem em que o NuvDocs gravou os eventos."
},
"PaginaDeRecebidos": {
"required": [
"documentos"
],
"type": "object",
"properties": {
"documentos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RecebidoVisivel"
},
"description": "Documentos da página, em resumo (sem os eventos); vazio quando nenhum."
},
"cursor": {
"type": "string",
"description": "Cursor da próxima página; ausente quando não há mais documentos.",
"nullable": true
}
},
"description": "Uma página da consulta dos documentos recebidos (`GET /v1/documentos-recebidos`), do mais novo para o mais antigo\npela data de emissão."
},
"ParteDaNota": {
"required": [
"documento"
],
"type": "object",
"properties": {
"documento": {
"type": "string",
"description": "CNPJ ou CPF da parte, só com dígitos."
},
"nome": {
"type": "string",
"description": "Nome ou razão social, quando a nota traz.",
"nullable": true
}
},
"description": "Uma parte de uma nota capturada: prestador, tomador ou intermediário."
},
"ParteNfse": {
"type": "object",
"properties": {
"cnpj": {
"type": "string",
"description": "CNPJ, 14 dígitos.",
"nullable": true
},
"cpf": {
"type": "string",
"description": "CPF, 11 dígitos.",
"nullable": true
},
"nif": {
"type": "string",
"description": "Número de identificação fiscal no exterior.",
"nullable": true
},
"motivoSemNif": {
"type": "string",
"description": "Motivo de não ter NIF (`nao_exigido` ou `dispensado`), para quem é do exterior.",
"nullable": true
},
"nome": {
"type": "string",
"description": "Nome ou razão social.",
"nullable": true
},
"inscricaoMunicipal": {
"type": "string",
"description": "Inscrição municipal.",
"nullable": true
},
"caepf": {
"type": "string",
"description": "Cadastro de atividade econômica da pessoa física (CAEPF).",
"nullable": true
},
"endereco": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoNacional"
}
]
},
"enderecoExterior": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoExterior"
}
]
},
"telefone": {
"type": "string",
"description": "Telefone, só dígitos.",
"nullable": true
},
"email": {
"type": "string",
"description": "E-mail; usado também na entrega da nota (11.9).",
"nullable": true
}
},
"description": "Pessoa da nota além do prestador: tomador, intermediário, destinatário ou fornecedor. Identificada por um\nsó documento: CNPJ, CPF, NIF ou o motivo de não ter NIF."
},
"PassoDaLinhaDoTempo": {
"required": [
"sequencia",
"passo",
"situacao",
"data",
"duracaoEmMilissegundos",
"tentativa"
],
"type": "object",
"properties": {
"sequencia": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Posição do evento no histórico, começando em 1.",
"format": "int64"
},
"passo": {
"type": "string",
"description": "Nome do passo: o tipo do evento sem o prefixo `documento.` (`recebido`, `em_transmissao`,\n`evento_fiscal.registrado`, `webhook.entregue`...)."
},
"situacao": {
"type": "string",
"description": "Situação do documento depois do evento."
},
"data": {
"type": "string",
"description": "Quando o evento aconteceu, em UTC.",
"format": "date-time"
},
"duracaoEmMilissegundos": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Duração do intervalo desde o passo anterior; zero no primeiro.",
"format": "int64"
},
"categoria": {
"type": "string",
"description": "Onde o tempo do intervalo foi gasto (`nuvdocs`, `represamento`, `recebedor`); nula no primeiro passo.",
"nullable": true
},
"tentativa": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Quantas vezes o passo já aconteceu, contando este; acima de 1 é repetição (nova transmissão, nova entrega).",
"format": "int32"
},
"explicacao": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RejeicaoExplicada"
},
"description": "Explicação de cada código, nas rejeições, denegações, críticas e eventos fiscais recusados.",
"nullable": true
},
"detalhes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Dados do evento (protocolo, recibo, mensagem, motivo, tipos de webhook...), sem os códigos já explicados.",
"nullable": true
}
},
"description": "Um passo da linha do tempo: um evento do histórico do documento, com o horário e o intervalo que termina nele."
},
"PedidoDeAtivacaoDaCaptura": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Tipo do documento capturado (`nfse`); ausente vale `nfse`.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Corpo opcional da ativação da captura (`PUT /v1/capturas/{cnpj}`). Contrato estrito: campo desconhecido é recusado."
},
"PedidoDeEventoFiscal": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Tipo do evento: `cancelamento` ou outro aceito pelo recebedor.",
"nullable": true
},
"codigoMotivo": {
"type": "string",
"description": "Código do motivo na tabela do recebedor (na NFS-e, `cMotivo`), quando houver.",
"nullable": true
},
"motivo": {
"type": "string",
"description": "Motivo em texto, obrigatório (na NFS-e, `xMotivo`).",
"nullable": true
},
"chaveIdempotencia": {
"type": "string",
"description": "Chave do pedido, quando o evento pode ficar pendente de aprovação (opcional): mandar a mesma chave de novo devolve a mesma pendência. Sem chave, cada pedido cria uma pendência.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Corpo de `POST /v1/documentos/{id}/eventos` (fluxo/eventos-fiscais): o tipo do evento e o motivo. Contrato\nestrito: campo desconhecido recusa o pedido. A substituição não entra aqui: ela é o envio do documento substituto,\ncom o grupo `substitui` do conteúdo."
},
"PedidoDeReenvio": {
"type": "object",
"properties": {
"eventos": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ids dos eventos a reenviar (até 1.000), guardados ou já entregues.",
"nullable": true
},
"desde": {
"type": "string",
"description": "Início do período, pela data do fato (inclusive).",
"format": "date-time",
"nullable": true
},
"ate": {
"type": "string",
"description": "Fim do período, pela data do fato (exclusive).",
"format": "date-time",
"nullable": true
},
"incluirEntregues": {
"type": "boolean",
"description": "No período, inclui também os já entregues (o cliente perdeu o que recebeu). Padrão falso: só os guardados. Com\nIReadOnlyList<string>? PedidoDeReenvio.Eventos, os entregues sempre entram.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Corpo do reenvio manual (`POST /v1/webhooks/{id}/reenvio`) [PROPOSTA]. Escolha os eventos pelos ids ou por um\nperíodo da data do fato. Sem nada, reenvia todos os guardados do cadastro. Contrato estrito."
},
"PedidoDeTrocaDeSegredo": {
"type": "object",
"properties": {
"convivenciaEmHoras": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Horas em que o segredo anterior ainda assina as chamadas, de 0 a 168; padrão 24. Use 0 quando o segredo\nanterior vazou: a troca vale na hora.",
"format": "int32",
"nullable": true
}
},
"additionalProperties": false,
"description": "Corpo opcional da troca do segredo (`POST /v1/webhooks/{id}/segredo`). Contrato estrito."
},
"PedidoDeWebhook": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Endereço HTTPS que recebe as chamadas.",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Texto livre para reconhecer o cadastro, até 200 caracteres.",
"nullable": true
},
"emissores": {
"type": "array",
"items": {
"type": "string"
},
"description": "CNPJs ou CPFs dos emissores assinados, com ou sem pontuação; ausente ou vazio assina todos.",
"nullable": true
},
"tiposDeEvento": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tipos de evento assinados; ausente ou vazio assina todos.",
"nullable": true
},
"tamanhoMaximoDoGrupo": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Eventos por chamada, de 1 a 1000; padrão 100.",
"format": "int32",
"nullable": true
},
"janelaDoGrupoEmMilissegundos": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Espera por mais eventos antes de enviar o grupo, de 100 a 60000 ms; padrão 1000.",
"format": "int32",
"nullable": true
},
"situacao": {
"type": "string",
"description": "`ativo` ou `desativado`; ausente cria ativo e, na alteração, mantém a situação.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Corpo da criação (`POST /v1/webhooks`) e da alteração (`PUT /v1/webhooks/{id}`) de um cadastro, igual no\nsite e no app. Contrato estrito: campo desconhecido recusa o pedido. A alteração substitui o cadastro inteiro: campo\nausente volta ao padrão, menos a situação, que fica como está."
},
"PossibilidadeDoEvento": {
"required": [
"permitido"
],
"type": "object",
"properties": {
"permitido": {
"type": "boolean",
"description": "Verdadeiro quando o evento pode ser pedido agora."
},
"ate": {
"type": "string",
"description": "Data-limite do prazo do município, em UTC; nula quando o município não tem prazo.",
"format": "date-time",
"nullable": true
},
"codigo": {
"type": "string",
"description": "Código estável do impedimento (`CodigosDeCritica`); nulo quando permitido.",
"nullable": true
},
"motivo": {
"type": "string",
"description": "Explicação do impedimento em português; nula quando permitido.",
"nullable": true
}
},
"description": "Se um tipo de evento fiscal é possível agora, até quando e, quando não é, por quê (fluxo/eventos-fiscais,\n\"Situação de cancelamento na consulta\"). O mesmo resultado decide o pedido: tentativa que seria rejeitada é\nimpedida antes de enviar, com o mesmo código e a mesma explicação."
},
"PrestadorNfse": {
"type": "object",
"properties": {
"inscricaoMunicipal": {
"type": "string",
"description": "Inscrição municipal, quando diferente da cadastrada.",
"nullable": true
},
"telefone": {
"type": "string",
"description": "Telefone de contato, só dígitos.",
"nullable": true
},
"email": {
"type": "string",
"description": "E-mail de contato.",
"nullable": true
}
},
"description": "Sobreposições permitidas aos dados do prestador. O emissor já é conhecido e o regime vem do perfil; por\nisso só contato e inscrição municipal podem mudar por nota."
},
"ProblemaDaApi": {
"required": [
"type",
"title",
"status",
"detail",
"codigo",
"criticas"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Endereço da explicação do código (string CodigosDeProblema.EnderecoDaExplicacao)."
},
"title": {
"type": "string",
"description": "Título curto do problema, em português."
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Código HTTP.",
"format": "int32"
},
"detail": {
"type": "string",
"description": "Explicação do caso, em português."
},
"codigo": {
"type": "string",
"description": "Código estável (CodigosDeProblema)."
},
"criticas": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Critica"
},
"description": "Críticas por campo; vazio quando o problema é da requisição inteira sem campo."
},
"correlacao": {
"type": "string",
"description": "Identificador de correlação da requisição, para o suporte achar o caso nos logs.",
"nullable": true
},
"dataLimite": {
"type": "string",
"description": "Data-limite do prazo do município, em UTC, quando o evento fiscal foi impedido pelo prazo (fluxo/eventos-fiscais).",
"format": "date-time",
"nullable": true
}
},
"description": "Erro da API no formato `application/problem+json` (RFC 9457; interfaces/integracao), com código próprio\nestável e a lista de críticas por campo. Os campos padrão (`type`, `title`, `status`,\n`detail`) vêm junto com as extensões do NuvDocs (`codigo`, `criticas`, `correlacao`, `dataLimite`)."
},
"RecebidoVisivel": {
"required": [
"id",
"emissor",
"tipo",
"recebedor",
"ambiente",
"teste",
"procedencia",
"papeis",
"chaveAcesso",
"datas",
"situacao",
"notaAusente"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id do documento recebido."
},
"emissor": {
"type": "string",
"description": "CNPJ consultado, o emissor do cliente."
},
"tipo": {
"type": "string",
"description": "Tipo do documento (`nfse`...)."
},
"recebedor": {
"type": "string",
"description": "Recebedor que distribuiu o documento."
},
"ambiente": {
"type": "string",
"description": "Ambiente da captura (`producao`, `producao_restrita` ou `simulacao`)."
},
"teste": {
"type": "boolean",
"description": "Verdadeiro para documento capturado com chave de teste."
},
"procedencia": {
"type": "string",
"description": "Quem emitiu: `terceiro`, `emitido_pelo_nuvdocs` ou `emitido_fora`."
},
"documentoEmitido": {
"type": "string",
"description": "Id do documento emitido no NuvDocs, quando a procedência é `emitido_pelo_nuvdocs`.",
"nullable": true
},
"papeis": {
"type": "array",
"items": {
"type": "string"
},
"description": "Papéis do CNPJ consultado na nota: `emitente`, `tomador` ou `intermediario`."
},
"chaveAcesso": {
"type": "string",
"description": "Chave de acesso da nota."
},
"numero": {
"type": "string",
"description": "Número da nota; ausente enquanto só o evento chegou.",
"nullable": true
},
"serie": {
"type": "string",
"description": "Série da nota, quando o leiaute tem série.",
"nullable": true
},
"prestador": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ParteDaNota"
}
]
},
"tomador": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ParteDaNota"
}
]
},
"valor": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor da nota.",
"format": "double",
"nullable": true
},
"datas": {
"$ref": "#/components/schemas/DatasDoRecebido"
},
"situacao": {
"type": "string",
"description": "Situação fiscal: `emitido`, `cancelado` ou `substituido`."
},
"chaveDaSubstituta": {
"type": "string",
"description": "Chave de acesso da nota substituta, quando substituída.",
"nullable": true
},
"nsu": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "NSU da nota na distribuição do recebedor.",
"format": "int64",
"nullable": true
},
"notaAusente": {
"type": "boolean",
"description": "Verdadeiro quando o evento chegou antes da nota: ainda não há nota nem XML."
},
"eventos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EventoVisivelDoRecebido"
},
"description": "Eventos capturados, na ordem do NSU; ausente na lista.",
"nullable": true
}
},
"description": "Documento recebido como a API de integração o devolve (`GET /v1/documentos-recebidos`): a nota em que o CNPJ\nconsultado figura sem ter sido quem a enviou pelo NuvDocs, com a situação fiscal pelos eventos capturados. A lista traz\no resumo, sem os eventos; a consulta pelo id traz os eventos. Em JSON pelo contexto da API: campos em camelCase e nulos\nomitidos."
},
"ReembolsoNfse": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Tipo (corretagem, turismo, publicidade, outros), pelo código da tabela oficial. Na NT 009, também\n`105` (glosa de serviços de saúde, `tpAjusteBC`). O adaptador confere o código pela versão do leiaute.",
"nullable": true
},
"documento": {
"type": "string",
"description": "Número de documento não fiscal do terceiro, quando não há chave nem documento fiscal.",
"nullable": true
},
"data": {
"type": "string",
"description": "Data de emissão do documento.",
"format": "date",
"nullable": true
},
"fornecedor": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/ParteNfse"
}
]
},
"valor": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor repassado.",
"format": "double",
"nullable": true
},
"competencia": {
"type": "string",
"description": "Data de competência do documento do terceiro; padrão: a data de emissão.",
"format": "date",
"nullable": true
},
"descricaoDoTipo": {
"type": "string",
"description": "Descrição do tipo, exigida quando o tipo é \"outros\".",
"nullable": true
},
"chaveAcesso": {
"type": "string",
"description": "Chave de acesso do documento eletrônico nacional do terceiro.",
"nullable": true
},
"tipoDaChave": {
"type": "string",
"description": "Tipo do documento da chave: `nfse`, `nfe`, `cte` ou `outro`; padrão pelo tamanho da chave.",
"nullable": true
},
"descricaoDaChave": {
"type": "string",
"description": "Descrição do documento da chave, exigida quando o tipo da chave é `outro`.",
"nullable": true
},
"documentoFiscal": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/DocumentoFiscalDeTerceiro"
}
]
},
"descricaoDoDocumento": {
"type": "string",
"description": "Descrição do documento não fiscal informado em string? ReembolsoNfse.Documento.",
"nullable": true
}
},
"description": "Repasse ou reembolso a terceiros incluído no valor da nota."
},
"ReferenciasNfse": {
"type": "object",
"properties": {
"documentoTecnico": {
"type": "string",
"description": "Documento técnico de responsabilidade (ART, RRT ou DRT).",
"nullable": true
},
"pedido": {
"type": "string",
"description": "Número do pedido ou contrato.",
"nullable": true
},
"itensDoPedido": {
"type": "array",
"items": {
"type": "string"
},
"description": "Itens do pedido.",
"nullable": true
},
"informacoesComplementares": {
"type": "string",
"description": "Informações complementares, em texto livre.",
"nullable": true
}
},
"description": "Documentos citados na nota: ART/RRT/DRT, pedido e itens, informações complementares."
},
"RejeicaoExplicada": {
"required": [
"codigo",
"origem",
"mensagemOriginal"
],
"type": "object",
"properties": {
"codigo": {
"type": "string",
"description": "Código do recebedor (ex.: `E0123`) ou da crítica (ex.: `campo_obrigatorio`)."
},
"origem": {
"type": "string",
"description": "Quem deu o código: `recebedor` ou `nuvdocs`."
},
"mensagemOriginal": {
"type": "string",
"description": "Mensagem original do recebedor ou da crítica."
},
"descricao": {
"type": "string",
"description": "Descrição clara, do catálogo.",
"nullable": true
},
"causaProvavel": {
"type": "string",
"description": "Causa provável, do catálogo.",
"nullable": true
},
"campo": {
"type": "string",
"description": "Caminho do campo no JSON próprio.",
"nullable": true
},
"correcao": {
"type": "string",
"description": "Correção sugerida, do catálogo.",
"nullable": true
}
},
"description": "Um código do recebedor, ou uma crítica do NuvDocs, com a explicação do catálogo (funcionalidades/rejeicoes,\n\"Formato da explicação\"). É o mesmo formato na consulta, nos webhooks e na linha do tempo. Sem explicação no\ncatálogo, só código, origem, mensagem original e, quando há, campo vêm preenchidos."
},
"RepresamentoNaApi": {
"required": [
"emissor",
"recebedor",
"ambiente",
"faixa",
"quantidade",
"escoamentoPorMinuto"
],
"type": "object",
"properties": {
"emissor": {
"type": "string",
"description": "CNPJ do emissor."
},
"recebedor": {
"type": "string",
"description": "Recebedor."
},
"ambiente": {
"type": "string",
"description": "Ambiente: `producao`, `producao_restrita` ou `simulacao`."
},
"faixa": {
"type": "string",
"description": "Faixa: `imediata` ou `lote`."
},
"quantidade": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Documentos à espera de liberação na última contagem.",
"format": "int64"
},
"escoamentoPorMinuto": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Documentos liberados por minuto, em média, nos últimos minutos.",
"format": "int64"
},
"previsaoDeEscoamentoEmSegundos": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Segundos até esvaziar no ritmo atual; nulo sem ritmo medido.",
"format": "int64",
"nullable": true
}
},
"description": "Represamento de um emissor num recebedor, num ambiente e numa faixa, como a API o devolve (fluxo/despacho,\n\"Represamento visível\")."
},
"RespostaDaBusca": {
"required": [
"documentos"
],
"type": "object",
"properties": {
"documentos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentoConsultado"
},
"description": "Documentos achados; vazio quando nenhum."
},
"cursor": {
"type": "string",
"description": "Cursor da próxima página da busca por filtros; ausente quando não há mais documentos.",
"nullable": true
}
},
"description": "Resposta da busca de documentos (`GET /v1/documentos`): os documentos achados, do mais novo para o mais antigo.\nNa busca por `idCliente` ou `chaveAcesso`, até int ConsultaDeDocumentos.MaximoDeDocumentosNaBusca\ncom a situação completa. Na busca por filtros, uma página de resumos e o cursor da próxima."
},
"RespostaDaListaDeWebhooks": {
"required": [
"webhooks"
],
"type": "object",
"properties": {
"webhooks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookVisivel"
},
"description": "Cadastros, do mais antigo para o mais novo; vazio quando nenhum."
}
},
"description": "Resposta de `GET /v1/webhooks`: os cadastros da conta no ambiente da chave, sem segredo."
},
"RespostaDoDocumento": {
"required": [
"situacao",
"avisos",
"erros"
],
"type": "object",
"properties": {
"chaveIdempotencia": {
"type": "string",
"description": "Chave informada; nula quando o envelope nem pôde ser lido.",
"nullable": true
},
"id": {
"type": "string",
"description": "Id do documento; o original em SituacaoDaRecepcao.JaRecebido; o da pendência em SituacaoDaRecepcao.PendenteDeAprovacao; nulo quando recusado.",
"nullable": true
},
"situacao": {
"$ref": "#/components/schemas/SituacaoDaRecepcao"
},
"faixa": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/FaixaDeProcessamento"
}
]
},
"avisos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Critica"
},
"description": "Mudanças feitas no documento aceito (ex.: faixa convertida para lote) e avisos que não bloqueiam (ex.: possível duplicidade, só no envio unitário e só quando a conta liga o aviso)."
},
"erros": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Critica"
},
"description": "Motivos da recusa; vazio quando aceito."
}
},
"description": "Resposta individual de um documento (fluxo/recepcao, \"Resposta individual\"). Em JSON:\n`{ chaveIdempotencia, id, situacao, faixa, avisos, erros }`, pelo ContextoJsonDaRecepcao."
},
"RespostaDoLote": {
"required": [
"documentos"
],
"type": "object",
"properties": {
"documentos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RespostaDoDocumento"
},
"description": "Uma resposta por documento."
}
},
"description": "Resposta do envio em lote (HTTP 202): a situação individual de cada documento, na ordem do corpo\n(fluxo/recepcao, \"Modos de envio\")."
},
"RespostaDoPdfEmGeracao": {
"required": [
"documento",
"situacao",
"repetirEmSegundos"
],
"type": "object",
"properties": {
"documento": {
"type": "string",
"description": "Id do documento."
},
"situacao": {
"type": "string",
"description": "Sempre string RespostaDoPdfEmGeracao.EmGeracao."
},
"repetirEmSegundos": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Espera sugerida, em segundos.",
"format": "int32"
}
},
"description": "Corpo do 202 de `GET /v1/documentos/{id}/pdf` (fluxo/impressao): o PDF ainda não existe e o limite de geração\nestá cheio. O cliente repete depois de int RespostaDoPdfEmGeracao.RepetirEmSegundos, o mesmo valor do cabeçalho `Retry-After`."
},
"RespostaDoReenvio": {
"required": [
"reativados"
],
"type": "object",
"properties": {
"reativados": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Eventos que voltaram a pendente.",
"format": "int64"
}
},
"description": "Resposta 202 do reenvio manual (`POST /v1/webhooks/{id}/reenvio`): quantos eventos voltaram à entrega."
},
"RespostaDoRepresamento": {
"required": [
"represamentos"
],
"type": "object",
"properties": {
"represamentos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RepresamentoNaApi"
},
"description": "Itens com documentos à espera; vazio quando nada está represado."
}
},
"description": "Resposta de `GET /v1/represamento`: os represamentos da conta com documentos à espera, por emissor,\nrecebedor e faixa."
},
"RespostaDoTesteDeWebhook": {
"required": [
"evento"
],
"type": "object",
"properties": {
"evento": {
"type": "string",
"description": "Id do evento de teste."
}
},
"description": "Resposta 202 do evento de teste (`POST /v1/webhooks/{id}/teste`): o id do evento `webhook.teste` que a entrega\nvai mandar. O resultado da chamada aparece no histórico de entregas."
},
"ResultadoDaPreValidacao": {
"required": [
"situacao",
"criticas"
],
"type": "object",
"properties": {
"chaveIdempotencia": {
"type": "string",
"description": "Chave de idempotência do envelope, quando foi possível lê-la.",
"nullable": true
},
"situacao": {
"$ref": "#/components/schemas/SituacaoDaPreValidacao"
},
"criticas": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Critica"
},
"description": "Críticas; vazio quando válido ou indisponível."
}
},
"description": "Resposta da pré-validação de um documento (fluxo/preparacao, \"Pré-validação\"): a situação e as críticas\npor campo, no mesmo formato de `documento.criticado` (Critica)."
},
"ServicoNfse": {
"type": "object",
"properties": {
"codigoNacional": {
"type": "string",
"description": "Código de tributação nacional (item, subitem e desdobro, ex.: `01.07.01`).",
"nullable": true
},
"codigoMunicipal": {
"type": "string",
"description": "Código de tributação municipal, quando o município administra código próprio.",
"nullable": true
},
"nbs": {
"type": "string",
"description": "Código da Nomenclatura Brasileira de Serviços (NBS); sugerido pelo NuvDocs quando omitido.",
"nullable": true
},
"atividadeSimples": {
"type": "string",
"description": "Atividade do Simples Nacional, com 2 dígitos (NT 009, `cAtvSN`; códigos em DominiosNt009);\nquando omitida, vem do cadastro do emissor optante.",
"nullable": true
},
"descricao": {
"type": "string",
"description": "Descrição do serviço.",
"nullable": true
},
"codigoInterno": {
"type": "string",
"description": "Código interno do serviço no cadastro do emissor.",
"nullable": true
},
"municipioPrestacao": {
"type": "string",
"description": "Município da prestação (IBGE, 7 dígitos); padrão: município do emissor.",
"nullable": true
},
"paisPrestacao": {
"type": "string",
"description": "País da prestação (ISO de duas letras), quando prestado no exterior.",
"nullable": true
},
"competencia": {
"type": "string",
"description": "Competência: data em que o serviço foi prestado.",
"format": "date",
"nullable": true
}
},
"description": "O serviço prestado: código, descrição, onde e quando."
},
"SituacaoDaPreValidacao": {
"enum": [
"valido",
"criticado",
"indisponivel"
],
"type": "string",
"description": "Como terminou a pré-validação de um documento."
},
"SituacaoDaRecepcao": {
"type": "string",
"description": "O que aconteceu com um documento na recepção (fluxo/recepcao, \"Resposta individual\"). Em JSON:\n`recebido`, `ja_recebido`, `recusado` e `pendente_de_aprovacao`.",
"x-extensible-enum": [
"recebido",
"ja_recebido",
"recusado",
"pendente_de_aprovacao"
]
},
"SituacaoDosEventos": {
"required": [
"cancelamento",
"substituicao"
],
"type": "object",
"properties": {
"cancelamento": {
"$ref": "#/components/schemas/PossibilidadeDoEvento"
},
"substituicao": {
"$ref": "#/components/schemas/PossibilidadeDoEvento"
},
"emAndamento": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EventoEmAndamentoNaConsulta"
}
]
},
"ultimaRejeicao": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RejeicaoExplicada"
},
"description": "Explicação dos códigos do recebedor quando o último fato do documento é um evento fiscal recusado; nula nos outros\ncasos.",
"nullable": true
}
},
"description": "Situação dos eventos fiscais de um documento, em toda consulta (fluxo/eventos-fiscais): pode cancelar? pode\nsubstituir? até quando? motivo quando não pode. Prazo e bloqueio vêm dos parâmetros municipais do recebedor."
},
"SubstituicaoNfse": {
"type": "object",
"properties": {
"chaveAcesso": {
"type": "string",
"description": "Chave de acesso da nota substituída.",
"nullable": true
},
"codigoMotivo": {
"type": "string",
"description": "Código do motivo (tabela oficial; `99` = outros).",
"nullable": true
},
"motivo": {
"type": "string",
"description": "Descrição do motivo, exigida quando o código é `99`.",
"nullable": true
}
},
"description": "Nota substituída por esta e o motivo."
},
"SuspensaoDoIss": {
"type": "object",
"properties": {
"tipo": {
"type": "string",
"description": "Origem da decisão: `judicial` ou `administrativa`.",
"nullable": true
},
"processo": {
"type": "string",
"description": "Número do processo.",
"nullable": true
}
},
"description": "Decisão que suspende a exigibilidade do ISS."
},
"TomadorConsultado": {
"type": "object",
"properties": {
"documento": {
"type": "string",
"description": "CNPJ ou CPF, só dígitos; nulo quando o tomador não tem.",
"nullable": true
},
"nome": {
"type": "string",
"description": "Nome como o cliente informou.",
"nullable": true
}
},
"description": "Tomador do documento na resposta da consulta e da busca, tirado dos campos da busca (funcionalidades/busca)."
},
"TotaisPorCategoria": {
"required": [
"nuvdocs",
"represamento",
"recebedor"
],
"type": "object",
"properties": {
"nuvdocs": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Tempo no NuvDocs.",
"format": "int64"
},
"represamento": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Tempo no represamento.",
"format": "int64"
},
"recebedor": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Tempo no recebedor.",
"format": "int64"
}
},
"description": "Soma das durações por categoria, em milissegundos. A soma das três é o tempo total da linha do tempo."
},
"TotalDeTributos": {
"type": "object",
"properties": {
"federal": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Tributos federais, em valor.",
"format": "double",
"nullable": true
},
"estadual": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Tributos estaduais, em valor.",
"format": "double",
"nullable": true
},
"municipal": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Tributos municipais, em valor.",
"format": "double",
"nullable": true
},
"percentual": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Percentual total, para quem informa só o percentual (Simples Nacional).",
"format": "double",
"nullable": true
},
"percentualFederal": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Tributos federais, em percentual do valor do serviço.",
"format": "double",
"nullable": true
},
"percentualEstadual": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Tributos estaduais, em percentual do valor do serviço.",
"format": "double",
"nullable": true
},
"percentualMunicipal": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Tributos municipais, em percentual do valor do serviço.",
"format": "double",
"nullable": true
}
},
"description": "Total aproximado de tributos da nota, por esfera. A forma exigida (valor ou percentual) vem do regime."
},
"TributacaoRegularIbsCbs": {
"type": "object",
"properties": {
"cst": {
"type": "string",
"description": "Situação tributária regular (CST, 3 dígitos).",
"nullable": true
},
"classificacaoTributaria": {
"type": "string",
"description": "Classificação tributária regular (começa pelo CST).",
"nullable": true
}
},
"description": "Situação e classificação tributárias que valeriam se a operação não tivesse tratamento especial."
},
"TributosFederais": {
"type": "object",
"properties": {
"cstPisCofins": {
"type": "string",
"description": "Situação tributária do PIS e da COFINS (CST).",
"nullable": true
},
"basePisCofins": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Base de cálculo do PIS e da COFINS.",
"format": "double",
"nullable": true
},
"aliquotaPis": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Alíquota do PIS, em percentual.",
"format": "double",
"nullable": true
},
"aliquotaCofins": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Alíquota da COFINS, em percentual.",
"format": "double",
"nullable": true
},
"retencaoPisCofins": {
"type": "boolean",
"description": "Verdadeiro quando o tomador retém PIS e COFINS.",
"nullable": true
},
"retidoInss": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Contribuição previdenciária retida.",
"format": "double",
"nullable": true
},
"retidoIrrf": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Imposto de renda retido.",
"format": "double",
"nullable": true
},
"retidoCsll": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "CSLL retida.",
"format": "double",
"nullable": true
},
"retencaoCsll": {
"type": "boolean",
"description": "Verdadeiro quando o tomador retém a CSLL.",
"nullable": true
}
},
"description": "Tributos federais da nota: PIS e COFINS e as retenções de INSS, IR e CSLL."
},
"TributosNfse": {
"type": "object",
"properties": {
"situacaoIss": {
"type": "string",
"description": "Situação do ISS: `tributavel` (padrão), `imune`, `exportacao` ou `nao_incidencia`.",
"nullable": true
},
"tipoImunidade": {
"type": "string",
"description": "Tipo de imunidade, exigido quando a situação é `imune`.",
"nullable": true
},
"suspensao": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/SuspensaoDoIss"
}
]
},
"beneficio": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/BeneficioMunicipal"
}
]
},
"retencaoIss": {
"type": "string",
"description": "Quem recolhe o ISS: `prestador`, `tomador` ou `intermediario`.",
"nullable": true
},
"aliquota": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Alíquota do ISS em percentual, quando a regra exige.",
"format": "double",
"nullable": true
},
"federais": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/TributosFederais"
}
]
},
"total": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/TotalDeTributos"
}
]
}
},
"description": "Tributos da nota: situação do ISS, retenções, alíquota e tributos federais."
},
"UltimaConsultaVisivel": {
"required": [
"em",
"situacao",
"quantidade",
"codigos",
"mensagem"
],
"type": "object",
"properties": {
"em": {
"type": "string",
"description": "Quando a consulta terminou.",
"format": "date-time"
},
"situacao": {
"type": "string",
"description": "Como terminou: `localizados`, `nenhum`, `limite`, `rejeicao` ou `falha`."
},
"quantidade": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Quantidade de itens devolvidos pelo recebedor.",
"format": "int32"
},
"codigos": {
"type": "array",
"items": {
"type": "string"
},
"description": "Códigos que o recebedor devolveu na rejeição; vazio nas outras situações."
},
"mensagem": {
"type": "string",
"description": "Explicação curta em português; a falta de certificado aparece aqui."
}
},
"description": "Resumo da última consulta ao recebedor, como a API de integração o devolve."
},
"UnidadeImobiliaria": {
"type": "object",
"properties": {
"inscricaoImobiliaria": {
"type": "string",
"description": "Inscrição imobiliária fiscal (IPTU).",
"nullable": true
},
"cib": {
"type": "string",
"description": "Cadastro Imobiliário Brasileiro (CIB), 8 caracteres.",
"nullable": true
},
"endereco": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/EnderecoNacional"
}
]
},
"ajustes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AjusteDaBaseDaLocacao"
},
"description": "Parcelas que não entram na base de cálculo do IBS e da CBS (IPTU, condomínio, redutor social...).",
"nullable": true
}
},
"description": "Unidade imobiliária da operação (NT 009, `imovel/gUnidImob`): identificada pelo CIB ou pelo endereço."
},
"ValoresNfse": {
"type": "object",
"properties": {
"valorServico": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Valor do serviço prestado; obrigatório.",
"format": "double",
"nullable": true
},
"descontoIncondicionado": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Desconto dado na nota, sem condição.",
"format": "double",
"nullable": true
},
"descontoCondicionado": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"enum": [
null
],
"nullable": true
}
],
"description": "Desconto que depende de condição.",
"format": "double",
"nullable": true
},
"deducao": {
"oneOf": [
{
"enum": [
null
],
"nullable": true
},
{
"$ref": "#/components/schemas/DeducaoNfse"
}
]
}
},
"description": "Valores do serviço: valor, descontos e deduções."
},
"WebhookVisivel": {
"required": [
"id",
"url",
"emissores",
"tiposDeEvento",
"tamanhoMaximoDoGrupo",
"janelaDoGrupoEmMilissegundos",
"situacao",
"teste",
"criadoEm",
"atualizadoEm"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identificador do cadastro."
},
"url": {
"type": "string",
"description": "Endereço HTTPS."
},
"descricao": {
"type": "string",
"description": "Texto livre do cliente.",
"nullable": true
},
"emissores": {
"type": "array",
"items": {
"type": "string"
},
"description": "Emissores assinados; vazio assina todos."
},
"tiposDeEvento": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tipos assinados; vazio assina todos."
},
"tamanhoMaximoDoGrupo": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Eventos por chamada.",
"format": "int32"
},
"janelaDoGrupoEmMilissegundos": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Espera por mais eventos antes de enviar.",
"format": "int32"
},
"situacao": {
"type": "string",
"description": "`ativo`, `suspenso` ou `desativado`."
},
"teste": {
"type": "boolean",
"description": "Verdadeiro para cadastro do ambiente de testes."
},
"criadoEm": {
"type": "string",
"description": "Data da criação, em UTC.",
"format": "date-time"
},
"atualizadoEm": {
"type": "string",
"description": "Data da última alteração, em UTC.",
"format": "date-time"
},
"suspensoEm": {
"type": "string",
"description": "Quando a entrega suspendeu o cadastro.",
"format": "date-time",
"nullable": true
},
"motivoDaSuspensao": {
"type": "string",
"description": "Por que a entrega suspendeu.",
"nullable": true
},
"segredoAnteriorValidoAte": {
"type": "string",
"description": "Até quando o segredo anterior ainda assina, durante a convivência da troca.",
"format": "date-time",
"nullable": true
},
"segredo": {
"type": "string",
"description": "Texto do segredo; só na criação e na troca, e só nessa resposta.",
"nullable": true
}
},
"description": "Cadastro de webhook como o cliente vê (API, site e app). O segredo só vem na criação e na troca; nas outras\nrespostas o campo não aparece."
}
},
"securitySchemes": {
"chaveDeApi": {
"type": "http",
"description": "Chave de API (nd_live_... ou nd_test_...). Vale só com o certificado ICP-Brasil da mesma raiz de CNPJ na conexão TLS.",
"scheme": "bearer"
}
}
},
"security": [
{
"chaveDeApi": [ ]
}
],
"tags": [
{
"name": "Envio"
},
{
"name": "Consulta"
},
{
"name": "Eventos fiscais"
},
{
"name": "Represamento"
},
{
"name": "Webhooks",
"description": "Cadastros de webhook, entregas e consulta de eventos.\n\n## Chamada do NuvDocs ao seu endereço\n\nO NuvDocs faz `POST` em JSON (UTF-8) na URL do cadastro. Cada chamada leva um grupo de eventos, fechado por quantidade (`tamanhoMaximoDoGrupo`) ou pela janela do cadastro (`janelaDoGrupoEmMilissegundos`). O corpo é `{\"eventos\":[...]}`, e cada evento tem o formato dos itens de `GET /v1/eventos`: `id`, `tipo`, `data`, `teste`, `documento` (`id`, `idCliente`, `chaveAcesso`, `emissor`, `situacao`, `sequencia`, `mensagem`, `rejeicao`) ou, nos eventos de conta, `emissor`, e `dados`. XML e PDF não vão no webhook: busque-os pela API.\n\nCabeçalhos:\n\n- `NuvDocs-Data`: segundos Unix (UTC) do envio.\n- `NuvDocs-Assinatura`: `v1=`, uma por segredo válido, separadas por vírgula, a do segredo atual primeiro.\n- `NuvDocs-Entrega`: id do grupo. A repetição do mesmo grupo leva o mesmo id, com data e assinatura novas.\n\n## Como conferir a assinatura\n\n1. Leia o corpo como bytes, sem transformar.\n2. Monte a base: o texto exato de `NuvDocs-Data`, um ponto (`.`) e os bytes do corpo.\n3. Calcule o HMAC-SHA256 da base com o segredo do cadastro (texto em UTF-8) e escreva em hexadecimal minúsculo.\n4. Aceite quando um dos valores `v1=` for igual, comparando em tempo constante.\n5. Recuse quando `NuvDocs-Data` estiver a mais de 5 minutos do seu relógio.\n\nVetor para testar: segredo `ndwh_segredo-de-exemplo`, data `1767225600` e corpo `{\"eventos\":[]}` dão `5ed9e602d7a06d5e929e87cf87d91ff6af463453aade9d4c997a52c0832fadeb`.\n\n## Resposta e repetição\n\n- Responda 2xx em até 10 segundos para confirmar o grupo inteiro. Processe depois, numa fila sua.\n- Sem 2xx, o NuvDocs repete o grupo com espera crescente (10 s, dobrando até 1 h) por até 72 horas.\n- Pode haver repetição: descarte o evento cujo `id` você já processou.\n- Não há garantia de ordem: vale o evento de maior `documento.sequencia`.\n- Prazo esgotado ou 24 horas sem nenhum 2xx: o cadastro fica `suspenso`, a conta recebe `webhook.suspenso` e um e-mail, e os eventos ficam guardados. Reative o cadastro (`situacao: ativo`) ou peça o reenvio.\n- O endereço tem de ser HTTPS com certificado válido. Endereços de rede interna são recusados no cadastro e em cada envio.\n\nTipos: `documento.autorizado`, `documento.rejeitado` (também a denegação, com `situacao: denegado`), `documento.criticado`, `documento.cancelado`, `documento.substituido`, `documento.evento.registrado`, `documento.evento.rejeitado`, `documento.retido`, `documento.falha`, `documento.impresso`, `certificado.vencendo`, `certificado.vencido`, `habilitacao.concedida`, `habilitacao.revogada`, `webhook.suspenso` e `webhook.teste`. Os outros tipos do catálogo já podem ser assinados e chegam quando forem gerados."
},
{
"name": "Captura"
},
{
"name": "Documentos recebidos"
}
]
}