{ "openapi": "3.1.0", "info": { "title": "OpenNota API", "version": "1.0.0", "description": "Emissor fiscal independente: NFCom 62, NFS-e Nacional (DPS) e NF-e 55, por UM endpoint (o modelo vai no corpo). Guia completo e autenticação: https://developer.opennota.com.br" }, "servers": [ { "url": "https://api.opennota.com.br", "description": "Produção e sandbox: o ambiente é decidido pela credencial" } ], "paths": { "/v1/ping": { "get": { "summary": "Valida a credencial e mostra ambiente, emitentes e séries", "parameters": [ { "name": "X-OpenNota-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "key_id público da credencial" }, { "name": "X-OpenNota-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "epoch em segundos (janela ±300 s)" }, { "name": "X-OpenNota-Nonce", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID v4 novo a cada requisição" }, { "name": "X-OpenNota-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "sha256=hex(HMAC_SHA256(segredo, \"{ts}.{nonce}.{METODO}.{path}.{corpo}\"))" } ], "responses": { "200": { "description": "credencial ok" }, "401": { "description": "assinatura, timestamp ou nonce inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "credencial sem a operação/documento, ou IP fora da allowlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "não encontrado — inclusive emitente ou emissão fora do escopo da credencial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "limite de requisições ou credencial bloqueada (veja Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/v1/emissoes": { "post": { "summary": "Emite uma nota (NFCOM, NFSE ou NFE)", "description": "Idempotente pela Idempotency-Key. Em homologação/sandbox, a credencial de sandbox força HOMOLOGACAO e a série própria.", "parameters": [ { "name": "X-OpenNota-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "key_id público da credencial" }, { "name": "X-OpenNota-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "epoch em segundos (janela ±300 s)" }, { "name": "X-OpenNota-Nonce", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID v4 novo a cada requisição" }, { "name": "X-OpenNota-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "sha256=hex(HMAC_SHA256(segredo, \"{ts}.{nonce}.{METODO}.{path}.{corpo}\"))" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "ex.: fin-3816978-nfcom" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PedidoNFCOM" }, { "$ref": "#/components/schemas/PedidoNFSE" }, { "$ref": "#/components/schemas/PedidoNFE" } ], "discriminator": { "propertyName": "modelo", "mapping": { "NFCOM": "#/components/schemas/PedidoNFCOM", "NFSE": "#/components/schemas/PedidoNFSE", "NFE": "#/components/schemas/PedidoNFE" } } }, "examples": { "NFCOM": { "summary": "Mensalidade de acesso (NFCom 62)", "value": { "modelo": "NFCOM", "emitente": { "cnpj": "11222333000181" }, "destinatario": { "documento": "52998224725", "nome": "Fulano de Tal", "email": "fulano@example.com", "telefone": "21999998888", "endereco": { "logradouro": "Rua do Teste", "numero": "100", "complemento": "Casa 2", "bairro": "Centro", "ibge": "3304557", "municipio": "Rio de Janeiro", "uf": "RJ", "cep": "20040002" }, "codigoExterno": "169162" }, "referenciaExterna": "fin-3816978", "competencia": "2026-10", "vencimento": "2026-10-10", "contrato": { "numero": "169162", "inicio": "2026-10-01", "fim": "2026-10-31" }, "tipoServicoUtilizado": 4, "itens": [ { "codigo": "3816978", "descricao": "Plano de acesso a Internet", "cClass": "0400401", "unidade": 4, "quantidade": 1, "valorUnitario": 99.9, "icms": { "cst": "90", "aliquota": 20, "fcp": 4 }, "fust": 1, "funttel": 0.5 } ], "fatura": { "codigoBarras": "34191790010104351004791020150008291070026000" } } }, "NFSE": { "summary": "Serviço de ativação (NFS-e Nacional)", "value": { "modelo": "NFSE", "emitente": { "cnpj": "11222333000181" }, "destinatario": { "documento": "11444777000161", "nome": "Empresa Cliente Ltda", "email": "financeiro@example.com", "endereco": { "logradouro": "Rua do Teste", "numero": "100", "complemento": "Casa 2", "bairro": "Centro", "ibge": "3304557", "municipio": "Rio de Janeiro", "uf": "RJ", "cep": "20040002" }, "codigoExterno": "117318" }, "referenciaExterna": "fin-3817002-nfse", "observacoes": [ "OS 456" ], "competencia": "2026-10-07", "servico": { "cTribNac": "010301", "cTribMun": "002", "descricao": "Serviço de ativação (instalação)", "municipioPrestacao": "3304557" }, "valores": { "servico": 150, "desconto": 0, "iss": { "tributacao": 1, "retido": false } } } }, "NFE": { "summary": "Remessa em comodato (NF-e 55)", "value": { "modelo": "NFE", "emitente": { "cnpj": "11222333000181" }, "destinatario": { "codigoExterno": "169162" }, "referenciaExterna": "estoque-remessa-778", "naturezaOperacao": "REMESSA EM COMODATO", "tipo": 1, "finalidade": 1, "consumidorFinal": true, "presenca": 9, "destinoOperacao": 1, "itens": [ { "codigo": "ONU-XPON", "descricao": "ONU GPON", "ncm": "85176277", "cfop": "5908", "unidade": "UN", "quantidade": 1, "valorUnitario": 180, "icms": { "cst": "41" }, "pis": { "cst": "07" }, "cofins": { "cst": "07" } } ], "transporte": { "modalidade": 9 }, "pagamento": [ { "tPag": "90", "valor": 0 } ] } } } } } }, "responses": { "200": { "description": "repetição idempotente (mesmo corpo): devolve a resposta original; header Idempotent-Replay: true" }, "201": { "description": "autorizada", "content": { "application/json": { "schema": { "type": "object", "properties": { "emissao": { "$ref": "#/components/schemas/Emissao" }, "xml": { "type": "string" } } } } } }, "202": { "description": "INDETERMINADA: falha de rede DEPOIS de transmitir; o OpenNota reconcilia sozinho — consulte GET /v1/emissoes/{id}. NÃO reenvie com outra chave", "content": { "application/json": { "schema": { "type": "object", "properties": { "emissao": { "$ref": "#/components/schemas/Emissao" } } } } } }, "400": { "description": "JSON inválido, modelo desconhecido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "assinatura, timestamp ou nonce inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "credencial sem a operação/documento, ou IP fora da allowlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "não encontrado — inclusive emitente ou emissão fora do escopo da credencial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (mesma chave, corpo diferente) ou IDEMPOTENCY_IN_PROGRESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "422": { "description": "VALIDACAO_LOCAL (campos a corrigir; nenhum número consumido) ou ORGAO (rejeição do órgão)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "limite de requisições ou credencial bloqueada (veja Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "antes de transmitir: modelo não habilitado, certificado ausente/vencido ou órgão indisponível — pode repetir com a MESMA chave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } }, "get": { "summary": "Busca emissões por referenciaExterna, idempotencyKey ou chave", "parameters": [ { "name": "X-OpenNota-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "key_id público da credencial" }, { "name": "X-OpenNota-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "epoch em segundos (janela ±300 s)" }, { "name": "X-OpenNota-Nonce", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID v4 novo a cada requisição" }, { "name": "X-OpenNota-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "sha256=hex(HMAC_SHA256(segredo, \"{ts}.{nonce}.{METODO}.{path}.{corpo}\"))" }, { "name": "referenciaExterna", "in": "query", "schema": { "type": "string" } }, { "name": "idempotencyKey", "in": "query", "schema": { "type": "string" } }, { "name": "chave", "in": "query", "schema": { "type": "string" } }, { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "lista", "content": { "application/json": { "schema": { "type": "object", "properties": { "emissoes": { "type": "array", "items": { "$ref": "#/components/schemas/Emissao" } } } } } } }, "400": { "description": "nenhum filtro informado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "assinatura, timestamp ou nonce inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "credencial sem a operação/documento, ou IP fora da allowlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "não encontrado — inclusive emitente ou emissão fora do escopo da credencial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "limite de requisições ou credencial bloqueada (veja Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/v1/emissoes/validar": { "post": { "summary": "Valida o pedido sem emitir (não consome número, não precisa de Idempotency-Key)", "parameters": [ { "name": "X-OpenNota-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "key_id público da credencial" }, { "name": "X-OpenNota-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "epoch em segundos (janela ±300 s)" }, { "name": "X-OpenNota-Nonce", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID v4 novo a cada requisição" }, { "name": "X-OpenNota-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "sha256=hex(HMAC_SHA256(segredo, \"{ts}.{nonce}.{METODO}.{path}.{corpo}\"))" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PedidoNFCOM" }, { "$ref": "#/components/schemas/PedidoNFSE" }, { "$ref": "#/components/schemas/PedidoNFE" } ], "discriminator": { "propertyName": "modelo", "mapping": { "NFCOM": "#/components/schemas/PedidoNFCOM", "NFSE": "#/components/schemas/PedidoNFSE", "NFE": "#/components/schemas/PedidoNFE" } } }, "examples": { "NFCOM": { "summary": "Mensalidade de acesso (NFCom 62)", "value": { "modelo": "NFCOM", "emitente": { "cnpj": "11222333000181" }, "destinatario": { "documento": "52998224725", "nome": "Fulano de Tal", "email": "fulano@example.com", "telefone": "21999998888", "endereco": { "logradouro": "Rua do Teste", "numero": "100", "complemento": "Casa 2", "bairro": "Centro", "ibge": "3304557", "municipio": "Rio de Janeiro", "uf": "RJ", "cep": "20040002" }, "codigoExterno": "169162" }, "referenciaExterna": "fin-3816978", "competencia": "2026-10", "vencimento": "2026-10-10", "contrato": { "numero": "169162", "inicio": "2026-10-01", "fim": "2026-10-31" }, "tipoServicoUtilizado": 4, "itens": [ { "codigo": "3816978", "descricao": "Plano de acesso a Internet", "cClass": "0400401", "unidade": 4, "quantidade": 1, "valorUnitario": 99.9, "icms": { "cst": "90", "aliquota": 20, "fcp": 4 }, "fust": 1, "funttel": 0.5 } ], "fatura": { "codigoBarras": "34191790010104351004791020150008291070026000" } } }, "NFSE": { "summary": "Serviço de ativação (NFS-e Nacional)", "value": { "modelo": "NFSE", "emitente": { "cnpj": "11222333000181" }, "destinatario": { "documento": "11444777000161", "nome": "Empresa Cliente Ltda", "email": "financeiro@example.com", "endereco": { "logradouro": "Rua do Teste", "numero": "100", "complemento": "Casa 2", "bairro": "Centro", "ibge": "3304557", "municipio": "Rio de Janeiro", "uf": "RJ", "cep": "20040002" }, "codigoExterno": "117318" }, "referenciaExterna": "fin-3817002-nfse", "observacoes": [ "OS 456" ], "competencia": "2026-10-07", "servico": { "cTribNac": "010301", "cTribMun": "002", "descricao": "Serviço de ativação (instalação)", "municipioPrestacao": "3304557" }, "valores": { "servico": 150, "desconto": 0, "iss": { "tributacao": 1, "retido": false } } } }, "NFE": { "summary": "Remessa em comodato (NF-e 55)", "value": { "modelo": "NFE", "emitente": { "cnpj": "11222333000181" }, "destinatario": { "codigoExterno": "169162" }, "referenciaExterna": "estoque-remessa-778", "naturezaOperacao": "REMESSA EM COMODATO", "tipo": 1, "finalidade": 1, "consumidorFinal": true, "presenca": 9, "destinoOperacao": 1, "itens": [ { "codigo": "ONU-XPON", "descricao": "ONU GPON", "ncm": "85176277", "cfop": "5908", "unidade": "UN", "quantidade": 1, "valorUnitario": 180, "icms": { "cst": "41" }, "pis": { "cst": "07" }, "cofins": { "cst": "07" } } ], "transporte": { "modalidade": 9 }, "pagamento": [ { "tPag": "90", "valor": 0 } ] } } } } } }, "responses": { "200": { "description": "válido", "content": { "application/json": { "schema": { "type": "object", "properties": { "valido": { "const": true }, "modelo": { "type": "string" }, "ambiente": { "type": "string" } } } } } }, "400": { "description": "JSON inválido ou modelo desconhecido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "assinatura, timestamp ou nonce inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "credencial sem a operação/documento, ou IP fora da allowlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "não encontrado — inclusive emitente ou emissão fora do escopo da credencial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "422": { "description": "campos a corrigir", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "limite de requisições ou credencial bloqueada (veja Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/v1/emissoes/{id}": { "get": { "summary": "Situação de uma emissão", "parameters": [ { "name": "X-OpenNota-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "key_id público da credencial" }, { "name": "X-OpenNota-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "epoch em segundos (janela ±300 s)" }, { "name": "X-OpenNota-Nonce", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID v4 novo a cada requisição" }, { "name": "X-OpenNota-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "sha256=hex(HMAC_SHA256(segredo, \"{ts}.{nonce}.{METODO}.{path}.{corpo}\"))" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "emissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "emissao": { "$ref": "#/components/schemas/Emissao" } } } } } }, "401": { "description": "assinatura, timestamp ou nonce inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "credencial sem a operação/documento, ou IP fora da allowlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "não encontrado — inclusive emitente ou emissão fora do escopo da credencial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "limite de requisições ou credencial bloqueada (veja Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/v1/emissoes/{id}/xml": { "get": { "summary": "Segunda via do XML autorizado (guardado no OpenNota)", "parameters": [ { "name": "X-OpenNota-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "key_id público da credencial" }, { "name": "X-OpenNota-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "epoch em segundos (janela ±300 s)" }, { "name": "X-OpenNota-Nonce", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID v4 novo a cada requisição" }, { "name": "X-OpenNota-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "sha256=hex(HMAC_SHA256(segredo, \"{ts}.{nonce}.{METODO}.{path}.{corpo}\"))" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "XML (nfcomProc | NFSe | nfeProc), como anexo", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "assinatura, timestamp ou nonce inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "credencial sem a operação/documento, ou IP fora da allowlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "não encontrado — inclusive emitente ou emissão fora do escopo da credencial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "XML_INDISPONIVEL: a emissão não está autorizada nem cancelada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "limite de requisições ou credencial bloqueada (veja Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } } }, "components": { "schemas": { "PedidoNFCOM": { "type": "object", "additionalProperties": false, "required": [ "modelo", "emitente", "destinatario", "competencia", "vencimento", "itens" ], "properties": { "modelo": { "type": "string", "const": "NFCOM" }, "emitente": { "type": "object", "additionalProperties": false, "required": [ "cnpj" ], "properties": { "cnpj": { "type": "string", "pattern": "^[0-9]{14}$", "description": "CNPJ do emitente CADASTRADO no OpenNota (o certificado A1 dele está no cofre)" } } }, "destinatario": { "description": "Dados completos OU referência a um cadastro deste emitente", "oneOf": [ { "$ref": "#/components/schemas/DestinatarioCompleto" }, { "$ref": "#/components/schemas/DestinatarioReferencia" } ] }, "referenciaExterna": { "type": "string", "minLength": 1, "maxLength": 100, "description": "livre; volta em todas as respostas (ex.: id do lançamento no seu sistema)" }, "observacoes": { "type": "array", "maxItems": 12, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "linhas de informação complementar" }, "competencia": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$", "description": "mês de referência AAAA-MM" }, "vencimento": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "description": "AAAA-MM-DD" }, "contrato": { "type": "object", "additionalProperties": false, "properties": { "numero": { "type": "string", "minLength": 1, "maxLength": 20, "description": "padrão: documento do destinatário" }, "inicio": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "description": "AAAA-MM-DD" }, "fim": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "description": "AAAA-MM-DD" } } }, "tipoServicoUtilizado": { "type": "integer", "minimum": 1, "maximum": 7, "description": "tpServUtil (4 = provimento de acesso à internet). Padrão do cadastro do emitente" }, "itens": { "type": "array", "minItems": 1, "maxItems": 990, "items": { "type": "object", "additionalProperties": false, "required": [ "codigo", "descricao", "cClass", "quantidade", "valorUnitario" ], "properties": { "codigo": { "type": "string", "minLength": 1, "maxLength": 60 }, "descricao": { "type": "string", "minLength": 1, "maxLength": 120 }, "cClass": { "type": "string", "pattern": "^[0-9]{7}$", "description": "classificação do item (mensalidade de internet: 0400401)" }, "unidade": { "type": "integer", "minimum": 1, "maximum": 4, "description": "1 minuto · 2 MB · 3 GB · 4 UN (padrão 4)" }, "quantidade": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999 }, "valorUnitario": { "type": "number", "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01, "exclusiveMinimum": 0 }, "icms": { "type": "object", "additionalProperties": false, "properties": { "cst": { "type": "string", "pattern": "^[0-9]{2}$" }, "aliquota": { "type": "number", "minimum": 0, "maximum": 100, "description": "pontos percentuais (5 = 5%)" }, "fcp": { "type": "number", "minimum": 0, "maximum": 100, "description": "pontos percentuais (5 = 5%)" } }, "description": "padrão do cadastro do emitente se omitido" }, "fust": { "type": "number", "minimum": 0, "maximum": 100, "description": "pontos percentuais (5 = 5%)" }, "funttel": { "type": "number", "minimum": 0, "maximum": 100, "description": "pontos percentuais (5 = 5%)" } } } }, "fatura": { "type": "object", "additionalProperties": false, "properties": { "codigoBarras": { "type": "string", "pattern": "^[0-9]{44,48}$", "description": "linha digitável ou código de barras do boleto" }, "pix": { "type": "string", "minLength": 1, "maxLength": 512 } } } } }, "PedidoNFSE": { "type": "object", "additionalProperties": false, "required": [ "modelo", "emitente", "destinatario", "competencia", "servico", "valores" ], "properties": { "modelo": { "type": "string", "const": "NFSE" }, "emitente": { "type": "object", "additionalProperties": false, "required": [ "cnpj" ], "properties": { "cnpj": { "type": "string", "pattern": "^[0-9]{14}$", "description": "CNPJ do emitente CADASTRADO no OpenNota (o certificado A1 dele está no cofre)" } } }, "destinatario": { "description": "Dados completos OU referência a um cadastro deste emitente", "oneOf": [ { "$ref": "#/components/schemas/DestinatarioCompleto" }, { "$ref": "#/components/schemas/DestinatarioReferencia" } ] }, "referenciaExterna": { "type": "string", "minLength": 1, "maxLength": 100, "description": "livre; volta em todas as respostas (ex.: id do lançamento no seu sistema)" }, "observacoes": { "type": "array", "maxItems": 12, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "linhas de informação complementar" }, "competencia": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "description": "data de competência AAAA-MM-DD" }, "servico": { "type": "object", "additionalProperties": false, "required": [ "cTribNac", "descricao", "municipioPrestacao" ], "properties": { "cTribNac": { "type": "string", "pattern": "^[0-9]{6}$", "description": "código de tributação nacional (item+subitem+desdobro da LC 116). Rio, acesso à internet: 010301" }, "cTribMun": { "type": "string", "pattern": "^[0-9A-Za-z./-]{1,20}$", "description": "código de tributação municipal (Rio, acesso: 002)" }, "cNBS": { "type": "string", "pattern": "^[0-9]{9}$", "description": "opcional" }, "descricao": { "type": "string", "minLength": 1, "maxLength": 2000 }, "municipioPrestacao": { "type": "string", "pattern": "^[0-9]{7}$", "description": "IBGE do local da prestação" } } }, "valores": { "type": "object", "additionalProperties": false, "required": [ "servico", "iss" ], "properties": { "servico": { "type": "number", "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01, "exclusiveMinimum": 0 }, "desconto": { "type": "number", "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01 }, "iss": { "type": "object", "additionalProperties": false, "required": [ "retido" ], "properties": { "tributacao": { "type": "integer", "minimum": 1, "maximum": 4, "description": "tribISSQN (1 = operação tributável). Padrão 1" }, "retido": { "type": "boolean" }, "aliquota": { "type": "number", "minimum": 0, "maximum": 100, "description": "só para emitente NÃO optante do Simples (o cadastro decide)" } } }, "federais": { "type": "object", "additionalProperties": false, "properties": { "pis": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01 }, "cofins": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01 }, "irrf": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01 }, "csll": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01 }, "cp": { "type": [ "number", "null" ], "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01 } } } } } } }, "PedidoNFE": { "type": "object", "additionalProperties": false, "required": [ "modelo", "emitente", "destinatario", "naturezaOperacao", "tipo", "finalidade", "consumidorFinal", "presenca", "destinoOperacao", "itens", "transporte", "pagamento" ], "properties": { "modelo": { "type": "string", "const": "NFE" }, "emitente": { "type": "object", "additionalProperties": false, "required": [ "cnpj" ], "properties": { "cnpj": { "type": "string", "pattern": "^[0-9]{14}$", "description": "CNPJ do emitente CADASTRADO no OpenNota (o certificado A1 dele está no cofre)" } } }, "destinatario": { "description": "Dados completos OU referência a um cadastro deste emitente", "oneOf": [ { "$ref": "#/components/schemas/DestinatarioCompleto" }, { "$ref": "#/components/schemas/DestinatarioReferencia" } ] }, "referenciaExterna": { "type": "string", "minLength": 1, "maxLength": 100, "description": "livre; volta em todas as respostas (ex.: id do lançamento no seu sistema)" }, "observacoes": { "type": "array", "maxItems": 12, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "linhas de informação complementar" }, "naturezaOperacao": { "type": "string", "minLength": 1, "maxLength": 60 }, "tipo": { "type": "integer", "enum": [ 0, 1 ], "description": "tpNF: 0 entrada · 1 saída" }, "finalidade": { "type": "integer", "minimum": 1, "maximum": 4, "description": "finNFe: 1 normal · 2 complementar · 3 ajuste · 4 devolução" }, "consumidorFinal": { "type": "boolean" }, "presenca": { "type": "integer", "minimum": 0, "maximum": 9, "description": "indPres (9 = operação não presencial, outros)" }, "destinoOperacao": { "type": "integer", "minimum": 1, "maximum": 3, "description": "idDest: 1 interna · 2 interestadual · 3 exterior" }, "itens": { "type": "array", "minItems": 1, "maxItems": 990, "items": { "type": "object", "additionalProperties": false, "required": [ "codigo", "descricao", "ncm", "cfop", "unidade", "quantidade", "valorUnitario", "icms", "pis", "cofins" ], "properties": { "codigo": { "type": "string", "minLength": 1, "maxLength": 60 }, "descricao": { "type": "string", "minLength": 1, "maxLength": 120 }, "ncm": { "type": "string", "pattern": "^[0-9]{8}$" }, "cest": { "type": [ "string", "null" ], "pattern": "^[0-9]{7}$" }, "cfop": { "type": "string", "pattern": "^[0-9]{4}$" }, "unidade": { "type": "string", "minLength": 1, "maxLength": 6 }, "quantidade": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999 }, "valorUnitario": { "type": "number", "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01 }, "icms": { "type": "object", "additionalProperties": false, "properties": { "cst": { "type": "string", "pattern": "^[0-9]{2}$", "description": "regime normal" }, "csosn": { "type": "string", "pattern": "^[0-9]{3}$", "description": "Simples Nacional" }, "aliquota": { "type": "number", "minimum": 0, "maximum": 100, "description": "pontos percentuais (5 = 5%)" } } }, "ipi": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "cst": { "type": "string", "pattern": "^[0-9]{2}$" }, "aliquota": { "type": "number", "minimum": 0, "maximum": 100, "description": "pontos percentuais (5 = 5%)" } } }, "pis": { "type": "object", "additionalProperties": false, "required": [ "cst" ], "properties": { "cst": { "type": "string", "pattern": "^[0-9]{2}$" }, "aliquota": { "type": "number", "minimum": 0, "maximum": 100, "description": "pontos percentuais (5 = 5%)" } } }, "cofins": { "type": "object", "additionalProperties": false, "required": [ "cst" ], "properties": { "cst": { "type": "string", "pattern": "^[0-9]{2}$" }, "aliquota": { "type": "number", "minimum": 0, "maximum": 100, "description": "pontos percentuais (5 = 5%)" } } } } } }, "transporte": { "type": "object", "additionalProperties": false, "required": [ "modalidade" ], "properties": { "modalidade": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 9 ], "description": "modFrete (9 = sem frete)" } } }, "pagamento": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "tPag", "valor" ], "properties": { "tPag": { "type": "string", "pattern": "^[0-9]{2}$", "description": "90 = sem pagamento (remessa)" }, "valor": { "type": "number", "minimum": 0, "maximum": 999999999.99, "multipleOf": 0.01 } } } }, "referencias": { "type": "array", "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "chave" ], "properties": { "chave": { "type": "string", "pattern": "^[0-9]{44}$" } } } } } }, "DestinatarioCompleto": { "type": "object", "additionalProperties": false, "required": [ "documento", "nome", "endereco" ], "properties": { "documento": { "type": "string", "pattern": "^([0-9]{11}|[0-9]{14})$", "description": "CPF (11) ou CNPJ (14), só dígitos, com DV válido" }, "nome": { "type": "string", "minLength": 1, "maxLength": 60, "description": "razão social ou nome" }, "nomeFantasia": { "type": "string", "minLength": 0, "maxLength": 60 }, "ie": { "type": "string", "pattern": "^(ISENTO|[0-9]{2,14})$", "description": "inscrição estadual só dígitos, ou ISENTO" }, "im": { "type": "string", "pattern": "^[0-9]{1,15}$", "description": "inscrição municipal (só para o DANFSe; não vai na DPS)" }, "email": { "type": "string", "maxLength": 80, "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$" }, "telefone": { "type": "string", "pattern": "^[0-9]{10,11}$", "description": "DDD + número, só dígitos. Obrigatório na NFCOM" }, "endereco": { "type": "object", "additionalProperties": false, "required": [ "logradouro", "numero", "bairro", "ibge", "municipio", "uf", "cep" ], "properties": { "logradouro": { "type": "string", "minLength": 1, "maxLength": 60 }, "numero": { "type": "string", "minLength": 1, "maxLength": 60, "description": "use \"S/N\" quando não houver" }, "complemento": { "type": "string", "minLength": 0, "maxLength": 60 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60 }, "ibge": { "type": "string", "pattern": "^[0-9]{7}$", "description": "código IBGE do município (7 dígitos), coerente com a UF" }, "municipio": { "type": "string", "minLength": 1, "maxLength": 60 }, "uf": { "type": "string", "enum": [ "RO", "AC", "AM", "RR", "PA", "AP", "TO", "MA", "PI", "CE", "RN", "PB", "PE", "AL", "SE", "BA", "MG", "ES", "RJ", "SP", "PR", "SC", "RS", "MS", "MT", "GO", "DF" ] }, "cep": { "type": "string", "pattern": "^[0-9]{8}$", "description": "só dígitos" } } }, "codigoExterno": { "type": "string", "minLength": 1, "maxLength": 60, "description": "id do cliente no seu sistema (NFCOM: vira iCodAssinante). Com ele o OpenNota grava/atualiza o cadastro do destinatário" } } }, "DestinatarioReferencia": { "type": "object", "additionalProperties": false, "minProperties": 1, "maxProperties": 1, "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "id de um destinatário já cadastrado DESTE emitente" }, "codigoExterno": { "type": "string", "minLength": 1, "maxLength": 60, "description": "codigoExterno de um destinatário já cadastrado DESTE emitente" } } }, "Emissao": { "type": "object", "properties": { "id": { "type": "string", "description": "id da emissão no OpenNota — guarde" }, "modelo": { "type": "string", "enum": [ "NFCOM", "NFSE", "NFE" ] }, "ambiente": { "type": "string", "enum": [ "PRODUCAO", "HOMOLOGACAO" ] }, "status": { "type": "string", "enum": [ "EM_FILA", "ASSINADA", "TRANSMITIDA", "AUTORIZADA", "REJEITADA", "ERRO_TRANSPORTE", "INDETERMINADA", "CANCELADA", "DENEGADA" ] }, "emitenteCnpj": { "type": "string" }, "destinatarioId": { "type": "string" }, "serie": { "type": [ "string", "null" ] }, "numero": { "type": [ "string", "null" ], "description": "número da nota (NFS-e: nNFSe da Sefin)" }, "chave": { "type": [ "string", "null" ], "description": "44 dígitos (NFCom/NF-e) ou 50 (NFS-e)" }, "protocolo": { "type": [ "string", "null" ] }, "valor": { "type": [ "number", "null" ] }, "referenciaExterna": { "type": [ "string", "null" ] }, "idempotencyKey": { "type": "string" }, "origemFalha": { "type": [ "string", "null" ], "enum": [ "VALIDACAO_LOCAL", "ORGAO", "TRANSPORTE", null ] }, "motivo": { "type": [ "object", "null" ], "properties": { "codigo": { "type": [ "string", "null" ] }, "mensagem": { "type": [ "string", "null" ] }, "campo": { "type": [ "string", "null" ] }, "correcao": { "type": [ "string", "null" ] } } }, "criadaEm": { "type": "string", "format": "date-time" }, "autorizadaEm": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "xml": { "type": [ "string", "null" ], "description": "segunda via do XML (nota autorizada ou cancelada)" } } } } }, "Erro": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "codigo", "mensagem", "correlationId" ], "properties": { "codigo": { "type": "string", "examples": [ "VALIDACAO_LOCAL" ] }, "mensagem": { "type": "string" }, "correlationId": { "type": "string", "description": "informe ao suporte; também vai no header X-Correlation-Id" }, "origem": { "type": "string", "enum": [ "VALIDACAO_LOCAL", "ORGAO", "TRANSPORTE" ] }, "campos": { "type": "array", "items": { "type": "object", "required": [ "campo", "mensagem", "correcao" ], "properties": { "campo": { "type": "string", "description": "JSON Pointer do campo (ex.: /destinatario/documento)" }, "mensagem": { "type": "string" }, "correcao": { "type": "string", "description": "o que fazer para corrigir" } } } } } } } } } } }