{ "openapi": "3.0.0", "info": { "title": "API NFS-e Brasil - Sistema Nacional", "description": "API REST para integração com o Sistema Nacional de Nota Fiscal de Serviço Eletrônica (NFS-e).\n *\n * ## Visão Geral\n * Esta API implementa os serviços definidos no Manual de Integração v1.00.02 do Sistema Nacional NFS-e.\n *\n * ## Autenticação\n * A API utiliza autenticação via Bearer Token (Laravel Sanctum). Para obter um token:\n * 1. Faça uma requisição POST para `/api/auth/login` com email e senha\n * 2. Use o token retornado no header `Authorization: Bearer {token}`\n *\n * ## Ambientes\n * - **Homologação (ambiente=2)**: Para testes, não gera documentos fiscais válidos\n * - **Produção (ambiente=1)**: Documentos fiscais com validade jurídica\n *\n * ## Recursos Principais\n * - **NFS-e**: Emissão, consulta, listagem e download de documentos\n * - **Eventos**: Cancelamento, substituição e outros eventos\n * - **Contribuintes**: Cadastro e gestão de prestadores/tomadores\n * - **Certificados**: Upload e gestão de certificados digitais A1\n * - **Parâmetros Municipais**: Consulta de alíquotas e configurações por município\n * - **Tributos IBS/CBS**: Consulta de tributos da Reforma Tributária (IBS e CBS)\n *\n * ## Reforma Tributária - IBS e CBS\n * A partir de 2026, os novos tributos IBS (Imposto sobre Bens e Serviços) e CBS (Contribuição sobre Bens e Serviços)\n * devem ser calculados e informados pelo contribuinte/sistema emissor na DPS (Declaração de Prestação de Serviços):\n * - **IBS Estadual (UF)**: Parcela estadual do IBS\n * - **IBS Municipal**: Parcela municipal do IBS\n * - **CBS**: Contribuição federal sobre bens e serviços\n * - **Fase de Testes (2026)**: Alíquotas simbólicas de 0,9% para CBS e 0,1% para IBS, sem cobrança efetiva, mas destaque obrigatório\n * - **Cronograma**: Em 2026 vTotNF = vLiq; a partir de 2027 vTotNF = vLiq + vCBS + vIBSTot\n * - **Responsabilidade**: O preenchimento dos campos IBS/CBS é de responsabilidade exclusiva do emissor\n *\n * ## Respostas\n * Todas as respostas seguem o padrão JSON com os campos: sucesso (boolean), mensagem (string) e dados (object).\n *\n * ## Rate Limiting\n * - 60 requisições por minuto por IP\n * - 1000 requisições por hora por usuário autenticado\n *\n * ## Suporte\n * Em caso de dúvidas, entre em contato: fred@macroflexerp.com.br", "contact": { "name": "Fred Azevedo - MacroFlex ERP", "url": "https://www.linkedin.com/in/fred-azev%C3%AAdo-20412b33/", "email": "fred@macroflexerp.com.br" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "1.0.02" }, "servers": [ { "url": "http://127.0.0.1:8000/api", "description": "Servidor Local (Desenvolvimento)" }, { "url": "https://api.seudominio.com.br/api", "description": "Servidor de Produção" } ], "paths": { "/auth/login": { "post": { "tags": [ "Autenticação" ], "summary": "Realizar login e obter token", "description": "Autentica o usuário e retorna um Bearer Token para uso nas demais requisições. O token não expira automaticamente mas pode ser revogado via logout.", "operationId": "login", "requestBody": { "description": "Credenciais de acesso", "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "admin@exemplo.com.br" }, "password": { "type": "string", "format": "password", "example": "password" }, "device_name": { "description": "Nome do dispositivo/aplicação para identificação do token", "type": "string", "default": "api", "example": "postman" } }, "type": "object" }, "example": { "email": "admin@exemplo.com.br", "password": "password", "device_name": "postman" } } } }, "responses": { "200": { "description": "Login realizado com sucesso", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "properties": { "token": { "type": "string", "example": "1|abc123def456ghi789jkl012mno345pqr678stu901vwx234" }, "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Administrador" }, "email": { "type": "string", "example": "admin@exemplo.com.br" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Credenciais inválidas", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "As credenciais informadas estão incorretas." }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } } } } }, "/auth/register": { "post": { "tags": [ "Autenticação" ], "summary": "Registrar novo usuário", "description": "Cria uma nova conta de usuário e retorna um token de acesso. A senha deve ter no mínimo 8 caracteres.", "operationId": "register", "requestBody": { "description": "Dados do novo usuário", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "password_confirmation" ], "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 2, "example": "Novo Usuário" }, "email": { "type": "string", "format": "email", "example": "novo@exemplo.com.br" }, "password": { "type": "string", "format": "password", "minLength": 8, "example": "senha123456" }, "password_confirmation": { "type": "string", "format": "password", "example": "senha123456" } }, "type": "object" }, "example": { "name": "Novo Usuário", "email": "novo@exemplo.com.br", "password": "senha123456", "password_confirmation": "senha123456" } } } }, "responses": { "201": { "description": "Usuário criado com sucesso", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": true }, "mensagem": { "type": "string", "example": "Usuário criado com sucesso" }, "dados": { "properties": { "token": { "type": "string" }, "user": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erro de validação (email já existe, senha fraca, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } } } }, "/auth/logout": { "post": { "tags": [ "Autenticação" ], "summary": "Realizar logout", "description": "Revoga o token de acesso atual. Após logout, será necessário fazer login novamente para obter um novo token.", "operationId": "logout", "responses": { "200": { "description": "Logout realizado com sucesso", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": true }, "mensagem": { "type": "string", "example": "Logout realizado com sucesso" } }, "type": "object" } } } }, "401": { "description": "Não autorizado (token inválido ou já revogado)" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/me": { "get": { "tags": [ "Autenticação" ], "summary": "Obter dados do usuário autenticado", "description": "Retorna os dados do usuário autenticado pelo token atual. Útil para validar sessão e obter informações do usuário logado.", "operationId": "me", "responses": { "200": { "description": "Dados do usuário autenticado", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Administrador" }, "email": { "type": "string", "example": "admin@exemplo.com.br" }, "email_verified_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "contribuintes": { "description": "Empresas que o usuário tem acesso", "type": "array", "items": { "properties": { "id": { "type": "integer" }, "documento": { "type": "string" }, "razao_social": { "type": "string" }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ] }, "is_default": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Não autorizado" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/refresh": { "post": { "tags": [ "Autenticação" ], "summary": "Renovar token de acesso", "description": "Revoga o token atual e gera um novo. Use quando precisar invalidar sessões anteriores mantendo o usuário logado.", "operationId": "refresh", "responses": { "200": { "description": "Token renovado com sucesso", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": true }, "mensagem": { "type": "string", "example": "Token renovado com sucesso" }, "dados": { "properties": { "token": { "type": "string", "example": "2|xyz789abc123..." } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Não autorizado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/change-password": { "post": { "tags": [ "Autenticação" ], "summary": "Alterar senha", "operationId": "58e67cdbde52513b62902b05abf9abcb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "current_password", "password", "password_confirmation" ], "properties": { "current_password": { "type": "string", "format": "password", "example": "senha_atual_123" }, "password": { "type": "string", "format": "password", "minLength": 8, "example": "nova_senha_456" }, "password_confirmation": { "type": "string", "format": "password", "example": "nova_senha_456" } }, "type": "object" }, "example": { "current_password": "senha_atual_123", "password": "nova_senha_456", "password_confirmation": "nova_senha_456" } } } }, "responses": { "200": { "description": "Senha alterada com sucesso" } }, "security": [ { "sanctum": [] } ] } }, "/contribuintes": { "get": { "tags": [ "Contribuintes" ], "summary": "Listar contribuintes", "description": "Lista todos os contribuintes cadastrados com suporte a filtros e paginação.", "operationId": "listarContribuintes", "parameters": [ { "name": "ativo", "in": "query", "description": "Filtrar por status ativo/inativo", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "municipio_id", "in": "query", "description": "Filtrar por ID do município", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Registros por página", "required": false, "schema": { "type": "integer", "default": 15 }, "example": 15 } ], "responses": { "200": { "description": "Lista de contribuintes paginada", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Não autorizado" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Contribuintes" ], "summary": "Cadastrar novo contribuinte", "description": "Cadastra um novo contribuinte (prestador ou tomador de serviços). O tipo de documento (CPF/CNPJ) é detectado automaticamente pelo tamanho.", "operationId": "criarContribuinte", "requestBody": { "description": "Dados do contribuinte", "required": true, "content": { "application/json": { "schema": { "required": [ "cnpj", "razao_social" ], "properties": { "tipo_documento": { "description": "Opcional — detectado automaticamente pelo tamanho do cnpj", "type": "string", "enum": [ "CPF", "CNPJ" ], "example": "CNPJ" }, "cnpj": { "description": "CPF (11) ou CNPJ (14), sem formatação. Deve ser único.", "type": "string", "example": "11222333000181" }, "razao_social": { "type": "string", "maxLength": 150, "example": "Empresa Teste LTDA" }, "nome_fantasia": { "type": "string", "maxLength": 60, "example": "Empresa Teste" }, "inscricao_municipal": { "type": "string", "maxLength": 20, "example": "12345678" }, "logradouro": { "type": "string", "maxLength": 125, "example": "Rua das Flores" }, "numero": { "type": "string", "maxLength": 10, "example": "100" }, "complemento": { "type": "string", "maxLength": 60, "example": "Sala 101" }, "bairro": { "type": "string", "maxLength": 60, "example": "Centro" }, "cep": { "description": "CEP sem formatação", "type": "string", "maxLength": 8, "example": "01310100" }, "cidade": { "type": "string", "maxLength": 100, "example": "São Paulo" }, "uf": { "type": "string", "maxLength": 2, "minLength": 2, "example": "SP" }, "codigo_ibge": { "description": "Código IBGE do município (7 dígitos)", "type": "string", "maxLength": 7, "example": "3550308" }, "telefone": { "type": "string", "maxLength": 15, "example": "1133334444" }, "email": { "type": "string", "format": "email", "maxLength": 80, "example": "empresa@teste.com.br" }, "regime_tributacao": { "description": "1=Microempresa, 2=Estimativa, 3=Soc.Profissionais, 4=Cooperativa, 5=MEI, 6=Simples Nacional", "type": "string", "enum": [ "1", "2", "3", "4", "5", "6" ], "example": "6" } }, "type": "object" }, "example": { "cnpj": "11222333000181", "razao_social": "Empresa Teste LTDA", "nome_fantasia": "Empresa Teste", "inscricao_municipal": "12345678", "logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro", "cep": "01310100", "cidade": "São Paulo", "uf": "SP", "codigo_ibge": "3550308", "telefone": "1133334444", "email": "empresa@teste.com.br", "regime_tributacao": "6" } } } }, "responses": { "201": { "description": "Contribuinte cadastrado com sucesso" }, "401": { "description": "Não autorizado" }, "422": { "description": "Erro de validação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contribuintes/{id}": { "get": { "tags": [ "Contribuintes" ], "summary": "Consultar contribuinte por ID", "description": "Retorna os dados completos de um contribuinte, incluindo município e certificados digitais vinculados.", "operationId": "consultarContribuinte", "parameters": [ { "name": "id", "in": "path", "description": "ID do contribuinte", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Dados do contribuinte", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Não autorizado" }, "404": { "description": "Contribuinte não encontrado" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/contribuintes/{id}": { "put": { "tags": [ "Contribuintes" ], "summary": "Atualizar contribuinte", "operationId": "1b45445fb5847486525079e289254c3d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Atualização parcial — envie apenas os campos a alterar.", "required": true, "content": { "application/json": { "schema": { "properties": { "razao_social": { "type": "string", "maxLength": 150, "example": "Empresa Renomeada LTDA" }, "nome_fantasia": { "type": "string", "maxLength": 60, "example": "Empresa Renomeada" }, "inscricao_municipal": { "type": "string", "maxLength": 20, "example": "98765432" }, "municipio_id": { "type": "integer", "example": 1 }, "endereco": { "type": "string", "maxLength": 125, "example": "Av. Brigadeiro Faria Lima" }, "numero": { "type": "string", "maxLength": 10, "example": "2000" }, "complemento": { "type": "string", "maxLength": 60, "example": "Andar 10" }, "bairro": { "type": "string", "maxLength": 60, "example": "Itaim Bibi" }, "cep": { "type": "string", "maxLength": 8, "example": "01451000" }, "telefone": { "type": "string", "maxLength": 15, "example": "1144445555" }, "email": { "type": "string", "format": "email", "maxLength": 80, "example": "contato@renomeada.com.br" }, "regime_tributacao": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6 ], "example": 6 }, "ativo": { "type": "boolean", "example": true } }, "type": "object" }, "example": { "razao_social": "Empresa Renomeada LTDA", "endereco": "Av. Brigadeiro Faria Lima", "numero": "2000", "bairro": "Itaim Bibi", "cep": "01451000", "email": "contato@renomeada.com.br" } } } }, "responses": { "200": { "description": "Contribuinte atualizado" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Contribuintes" ], "summary": "Desativar contribuinte", "operationId": "e7bc3afa432c9cb5104d7f73d72e1fa8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Contribuinte desativado" } }, "security": [ { "sanctum": [] } ] } }, "/api/contribuintes/{id}/certificados": { "get": { "tags": [ "Contribuintes" ], "summary": "Listar certificados do contribuinte", "operationId": "c9967b208d60ee8ba996f93b1c29c0d8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista de certificados" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Contribuintes" ], "summary": "Cadastrar certificado digital para contribuinte", "operationId": "e62c5c751c73c6fe670329e3babf5950", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "certificado", "senha" ], "properties": { "certificado": { "type": "string", "format": "binary" }, "senha": { "type": "string" }, "descricao": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Certificado cadastrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/contribuintes/documento/{documento}": { "get": { "tags": [ "Contribuintes" ], "summary": "Buscar contribuinte por documento", "operationId": "c22f0442f05edce878ebbf02ea524f11", "parameters": [ { "name": "documento", "in": "path", "description": "CPF ou CNPJ", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dados do contribuinte" }, "404": { "description": "Contribuinte não encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/contribuintes/consultar-cnpj/{cnpj}": { "get": { "tags": [ "Contribuintes" ], "summary": "Consultar dados de CNPJ na Receita Federal", "description": "Consulta dados de um CNPJ diretamente na base da Receita Federal através da API CNPJA. Retorna informações como razão social, endereço, CNAE principal e email.", "operationId": "consultarCnpj", "parameters": [ { "name": "cnpj", "in": "path", "description": "CNPJ a ser consultado (apenas números)", "required": true, "schema": { "type": "string" }, "example": "07526557011659" } ], "responses": { "200": { "description": "Dados do CNPJ retornados com sucesso", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "properties": { "razao_social": { "type": "string", "example": "AMBEV S.A." }, "cnae": { "type": "string", "example": "1113502" }, "descricao_cnae": { "type": "string", "example": "Fabricação de cervejas e chopes" }, "email": { "type": "string", "example": "opobrigaces@ambev.com.br" }, "logradouro": { "type": "string", "example": "Avenida Constantino Nery" }, "numero": { "type": "string", "example": "2575" }, "bairro": { "type": "string", "example": "Flores" }, "cidade": { "type": "string", "example": "Manaus" }, "uf": { "type": "string", "example": "AM" }, "cep": { "type": "string", "example": "69058795" }, "codigo_ibge": { "type": "integer", "example": 1302603 }, "municipio_id": { "description": "ID do município no sistema, se existir", "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "CNPJ inválido", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": false }, "mensagem": { "type": "string", "example": "CNPJ inválido. Informe 14 dígitos numéricos." } }, "type": "object" } } } }, "404": { "description": "CNPJ não encontrado na base da Receita Federal", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": false }, "mensagem": { "type": "string", "example": "CNPJ não encontrado na base da Receita Federal." } }, "type": "object" } } } }, "503": { "description": "Erro ao consultar API externa", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean", "example": false }, "mensagem": { "type": "string", "example": "Erro ao consultar dados do CNPJ. Tente novamente." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/DFe/{ultimoNSU}": { "get": { "tags": [ "DF-e" ], "summary": "Distribuir DF-e a partir do último NSU", "description": "Retorna documentos fiscais eletrônicos (NFS-e e eventos) a partir do último NSU conhecido", "operationId": "5434e034bfb6ee18b411254bf086a548", "parameters": [ { "name": "ultimoNSU", "in": "path", "description": "Último NSU conhecido (para primeira consulta usar 0)", "required": true, "schema": { "type": "string" } }, { "name": "certificado_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Documentos distribuídos", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean" }, "dados": { "properties": { "ultimo_nsu": { "type": "string" }, "max_nsu": { "type": "string" }, "documentos": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erro na distribuição" } }, "security": [ { "sanctum": [] } ] } }, "/api/lotes": { "get": { "tags": [ "DF-e" ], "summary": "Listar lotes de DF-e", "operationId": "1836d8f91c4a6726fc760af8c3cbd7d7", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "processando", "processado", "erro" ] } }, { "name": "tipo_documento", "in": "query", "schema": { "type": "string", "enum": [ "DPS", "EVENTO" ] } }, { "name": "data_inicio", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "data_fim", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Lista de lotes paginada" } }, "security": [ { "sanctum": [] } ] } }, "/api/lotes/{id}": { "get": { "tags": [ "DF-e" ], "summary": "Consultar detalhes de um lote", "operationId": "7d53a33dd27ddbc2b0775b003be447a3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Detalhes do lote" }, "404": { "description": "Lote não encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/lotes/{id}/xml": { "get": { "tags": [ "DF-e" ], "summary": "Obter XML de um lote", "operationId": "c92c07f6bd7444d1e8c029af48f2a7e3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "tipo", "in": "query", "description": "Tipo de XML (enviado ou retorno)", "schema": { "type": "string", "default": "enviado", "enum": [ "enviado", "retorno" ] } } ], "responses": { "200": { "description": "XML do lote", "content": { "application/xml": {} } } }, "security": [ { "sanctum": [] } ] } }, "/api/dps/{id}": { "get": { "tags": [ "DF-e" ], "summary": "Consultar DPS por ID", "operationId": "432d0d7c73bf6022f81927243afc57dd", "parameters": [ { "name": "id", "in": "path", "description": "ID do DPS (42 caracteres)", "required": true, "schema": { "type": "string" } }, { "name": "certificado_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Dados do DPS" }, "404": { "description": "DPS não encontrado" } }, "security": [ { "sanctum": [] } ] } }, "/api/nfse/{chaveAcesso}/eventos": { "get": { "tags": [ "Eventos" ], "summary": "Consultar eventos de uma NFS-e", "operationId": "8e4c1af32e6a7e702b4dac3983908da2", "parameters": [ { "name": "chaveAcesso", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tipo_evento", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista de eventos" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Eventos" ], "summary": "Registrar evento em uma NFS-e", "operationId": "0c6811c05fa25d9b250f0776d3bac2e3", "parameters": [ { "name": "chaveAcesso", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrarEventoRequest" } } } }, "responses": { "201": { "description": "Evento registrado com sucesso" }, "422": { "description": "Erro de validação ou rejeição" } }, "security": [ { "sanctum": [] } ] } }, "/api/nfse/{chaveAcesso}/cancelar": { "post": { "tags": [ "Eventos" ], "summary": "Cancelar uma NFS-e", "operationId": "ad04b25cd96af4689179919e71097c9d", "parameters": [ { "name": "chaveAcesso", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelarNFSeRequest" } } } }, "responses": { "200": { "description": "NFS-e cancelada com sucesso" }, "422": { "description": "Erro ao cancelar" } }, "security": [ { "sanctum": [] } ] } }, "/nfse/cancelar": { "post": { "tags": [ "Eventos" ], "summary": "Cancelar NFS-e (simplificado)", "description": "Cancela uma NFS-e informando todos os dados no body JSON, incluindo a chave de acesso.", "operationId": "cancelarNFSeSimplificado", "requestBody": { "description": "Dados do cancelamento", "required": true, "content": { "application/json": { "schema": { "required": [ "chave_acesso", "motivo", "codigo_motivo" ], "properties": { "chave_acesso": { "type": "string", "maxLength": 50, "minLength": 40, "example": "35260111222333000181NFS0000009049238145145" }, "motivo": { "type": "string", "maxLength": 255, "minLength": 15, "example": "Erro na emissão - serviço não prestado ao cliente" }, "codigo_motivo": { "description": "1=Erro na emissão, 2=Serviço não prestado, 3=Duplicidade, 4=Erro preenchimento", "type": "string", "maxLength": 10, "example": "1" } }, "type": "object" }, "example": { "chave_acesso": "35260111222333000181NFS0000009049238145145", "motivo": "Erro na emissão - serviço não prestado ao cliente", "codigo_motivo": "1" } } } }, "responses": { "200": { "description": "NFS-e cancelada com sucesso" }, "422": { "description": "Erro ao cancelar" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/nfse/{chaveAcesso}/substituir": { "post": { "tags": [ "Eventos" ], "summary": "Cancelar NFS-e por substituição", "operationId": "95dc61fd395c2bcde960078245f22c98", "parameters": [ { "name": "chaveAcesso", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "A NFS-e substituta precisa ter sido emitida ANTES (POST /nfse). Aqui você só passa a chave de acesso da nova nota.", "required": true, "content": { "application/json": { "schema": { "required": [ "chave_substituta", "autor_documento", "certificado_id" ], "properties": { "chave_substituta": { "description": "Chave de acesso (50 chars) da NFS-e substituta", "type": "string", "maxLength": 50, "minLength": 50, "example": "35260111222333000181NFS0000009049238145146" }, "autor_documento": { "description": "CPF (11) ou CNPJ (14) do autor, sem formatação", "type": "string", "maxLength": 14, "minLength": 11, "example": "11222333000181" }, "certificado_id": { "description": "ID do certificado digital ativo", "type": "integer", "example": 1 } }, "type": "object" }, "example": { "chave_substituta": "35260111222333000181NFS0000009049238145146", "autor_documento": "11222333000181", "certificado_id": 1 } } } }, "responses": { "200": { "description": "NFS-e substituída com sucesso" } }, "security": [ { "sanctum": [] } ] } }, "/api/nfse/{chaveAcesso}/confirmar-tomador": { "post": { "tags": [ "Eventos" ], "summary": "Registrar confirmação do tomador", "operationId": "ed2a8069c0ef026c4a1f7c5f73a72c21", "parameters": [ { "name": "chaveAcesso", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "autor_documento", "certificado_id" ], "properties": { "descricao": { "type": "string", "maxLength": 255, "example": "Confirmação após verificação do serviço" }, "autor_documento": { "type": "string", "maxLength": 14, "minLength": 11, "example": "11222333000181" }, "certificado_id": { "type": "integer", "example": 1 } }, "type": "object" }, "example": { "descricao": "Confirmação após verificação do serviço", "autor_documento": "11222333000181", "certificado_id": 1 } } } }, "responses": { "200": { "description": "Confirmação registrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/nfse/{chaveAcesso}/rejeitar-tomador": { "post": { "tags": [ "Eventos" ], "summary": "Registrar rejeição do tomador", "operationId": "b2536eb39fa518da3ab93162ea480562", "parameters": [ { "name": "chaveAcesso", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "descricao", "autor_documento", "certificado_id" ], "properties": { "descricao": { "type": "string", "maxLength": 255, "example": "Serviço não foi prestado conforme contratado" }, "autor_documento": { "type": "string", "maxLength": 14, "minLength": 11, "example": "52998224725" }, "certificado_id": { "type": "integer", "example": 1 } }, "type": "object" }, "example": { "descricao": "Serviço não foi prestado conforme contratado", "autor_documento": "52998224725", "certificado_id": 1 } } } }, "responses": { "200": { "description": "Rejeição registrada" } }, "security": [ { "sanctum": [] } ] } }, "/api/eventos": { "get": { "tags": [ "Eventos" ], "summary": "Listar eventos por tipo", "operationId": "3be205a6e13d86f27b4a4befd22da6c7", "parameters": [ { "name": "tipo_evento", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "data_inicio", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "data_fim", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "autorizado", "rejeitado", "erro" ] } } ], "responses": { "200": { "description": "Lista de eventos paginada" } }, "security": [ { "sanctum": [] } ] } }, "/api/eventos/estatisticas": { "get": { "tags": [ "Eventos" ], "summary": "Obter estatísticas de eventos", "operationId": "68b417de58ac66b630039c525b344868", "parameters": [ { "name": "competencia", "in": "query", "description": "Competência no formato YYYY-MM", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Estatísticas de eventos" } }, "security": [ { "sanctum": [] } ] } }, "/nfse": { "get": { "tags": [ "NFS-e" ], "summary": "Listar NFS-e do contribuinte", "description": "Lista todas as NFS-e emitidas por um contribuinte (prestador) com suporte a filtros e paginação.", "operationId": "listarNFSe", "parameters": [ { "name": "prestador_id", "in": "query", "description": "ID do contribuinte prestador", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "data_inicio", "in": "query", "description": "Data inicial do período (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "data_fim", "in": "query", "description": "Data final do período (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "situacao", "in": "query", "description": "Filtrar por situação da NFS-e", "required": false, "schema": { "type": "string", "enum": [ "normal", "cancelada", "substituida" ] }, "example": "normal" }, { "name": "tomador_documento", "in": "query", "description": "Filtrar por CPF/CNPJ do tomador", "required": false, "schema": { "type": "string" }, "example": "52998224725" }, { "name": "per_page", "in": "query", "description": "Quantidade de registros por página (1-100)", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 }, "example": 15 } ], "responses": { "200": { "description": "Lista de NFS-e paginada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NFSeListaResponse" } } } }, "401": { "description": "Não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Erro de validação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "NFS-e" ], "summary": "Emitir uma nova NFS-e", "description": "Emite uma nova Nota Fiscal de Serviço Eletrônica. Retorna a NFS-e emitida junto com o PDF (DANFS-e) e XML em base64.", "operationId": "emitirNFSe", "requestBody": { "description": "Dados da NFS-e a ser emitida", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitirNFSeRequestFull" } } } }, "responses": { "201": { "description": "NFS-e emitida com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NFSeEmitidaResponse" } } } }, "401": { "description": "Não autorizado - Token inválido ou ausente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Erro de validação ou processamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/nfse/lote": { "post": { "tags": [ "NFS-e" ], "summary": "Emitir NFS-e em lote", "description": "Envia um lote de até 50 NFS-e para processamento assíncrono. Retorna o ID do lote e protocolo para consulta posterior.", "operationId": "emitirLoteNFSe", "requestBody": { "description": "Lote de NFS-e para emissão", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitirLoteNFSeRequest" } } } }, "responses": { "201": { "description": "Lote recebido para processamento" }, "401": { "description": "Não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Erro de validação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/nfse/{chaveAcesso}": { "get": { "tags": [ "NFS-e" ], "summary": "Consultar NFS-e por chave de acesso", "description": "Consulta uma NFS-e pela sua chave de acesso. Use o parâmetro `incluir_arquivos=true` para retornar também o PDF e XML em base64.", "operationId": "consultarNFSe", "parameters": [ { "name": "chaveAcesso", "in": "path", "description": "Chave de acesso da NFS-e (44 ou 50 caracteres)", "required": true, "schema": { "type": "string", "maxLength": 50, "minLength": 44 }, "example": "35260111222333000181NFS0000009049238145145" }, { "name": "incluir_arquivos", "in": "query", "description": "Se true, inclui PDF e XML em base64 na resposta. Os arquivos são salvos no banco para consultas futuras.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "certificado_id", "in": "query", "description": "ID do certificado digital para consulta no SEFAZ (opcional)", "required": false, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "NFS-e encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NFSeConsultaResponse" } } } }, "401": { "description": "Não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "NFS-e não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/nfse/{chaveAcesso}/xml": { "get": { "tags": [ "NFS-e" ], "summary": "Download do XML da NFS-e", "description": "Faz download do arquivo XML da NFS-e para integração com sistemas contábeis ou backup.", "operationId": "downloadXmlNFSe", "parameters": [ { "name": "chaveAcesso", "in": "path", "description": "Chave de acesso da NFS-e", "required": true, "schema": { "type": "string" }, "example": "35260111222333000181NFS0000009049238145145" } ], "responses": { "200": { "description": "Arquivo XML da NFS-e", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Não autorizado" }, "404": { "description": "NFS-e não encontrada" } }, "security": [ { "bearerAuth": [] } ] } }, "/danfse/{chaveAcesso}": { "get": { "tags": [ "NFS-e" ], "summary": "Gerar/Download do DANFS-e (PDF)", "description": "Gera o Documento Auxiliar da NFS-e (DANFS-e) em formato PDF para impressão ou visualização.", "operationId": "downloadDanfse", "parameters": [ { "name": "chaveAcesso", "in": "path", "description": "Chave de acesso da NFS-e", "required": true, "schema": { "type": "string" }, "example": "35260111222333000181NFS0000009049238145145" } ], "responses": { "200": { "description": "Arquivo PDF do DANFS-e", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "NFS-e não encontrada" } } } }, "/nfse/estatisticas": { "get": { "tags": [ "NFS-e" ], "summary": "Estatísticas de NFS-e do contribuinte", "description": "Retorna estatísticas consolidadas de NFS-e por competência, incluindo totais por situação, valores e distribuição por tomador.", "operationId": "estatisticasNFSe", "parameters": [ { "name": "prestador_id", "in": "query", "description": "ID do contribuinte prestador", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "competencia", "in": "query", "description": "Competência no formato YYYY-MM. Se não informada, retorna o mês atual.", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "example": "2026-01" } ], "responses": { "200": { "description": "Estatísticas calculadas com sucesso" }, "401": { "description": "Não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Erro de validação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/health": { "get": { "tags": [ "Sistema" ], "summary": "Verificar status da API", "description": "Endpoint de health check para monitoramento. Retorna status do sistema e ambiente de execução.", "operationId": "healthCheck", "responses": { "200": { "description": "API operacional", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "1.0.02" }, "ambiente": { "description": "1=Produção, 2=Homologação", "type": "integer", "example": 2 } }, "type": "object" } } } } } } }, "/api/parametros_municipais/{codigoMunicipio}/convenio": { "get": { "tags": [ "Parâmetros Municipais" ], "summary": "Consultar dados do convênio do município", "operationId": "bad889e8355c8f19ca7ff170795a5e7e", "parameters": [ { "name": "codigoMunicipio", "in": "path", "description": "Código IBGE do município (7 dígitos)", "required": true, "schema": { "type": "string", "maxLength": 7, "minLength": 7 } }, { "name": "forcar_atualizacao", "in": "query", "description": "Forçar atualização do cache", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Dados do convênio", "content": { "application/json": { "schema": { "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Município não encontrado" } } } }, "/api/parametros_municipais/{codigoMunicipio}/aliquotas": { "get": { "tags": [ "Parâmetros Municipais" ], "summary": "Consultar alíquotas de ISS do município", "operationId": "ebfcd4ed1d6cf9b805c689defa588705", "parameters": [ { "name": "codigoMunicipio", "in": "path", "description": "Código IBGE do município (7 dígitos)", "required": true, "schema": { "type": "string", "maxLength": 7, "minLength": 7 } }, { "name": "codigoServico", "in": "query", "description": "Código do serviço (LC 116/03)", "schema": { "type": "string" } }, { "name": "competencia", "in": "query", "description": "Data de competência (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Lista de alíquotas" }, "404": { "description": "Município não encontrado" } } } }, "/api/parametros_municipais/{codigoMunicipio}/regimes_especiais": { "get": { "tags": [ "Parâmetros Municipais" ], "summary": "Consultar regimes especiais de tributação", "operationId": "62e12a29f68bf8a05938d8e7343ac544", "parameters": [ { "name": "codigoMunicipio", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 7, "minLength": 7 } } ], "responses": { "200": { "description": "Lista de regimes especiais" } } } }, "/api/parametros_municipais/{codigoMunicipio}/retencoes": { "get": { "tags": [ "Parâmetros Municipais" ], "summary": "Consultar parâmetros de retenção de ISS", "operationId": "45a6ad31d77af2f2037b5e3e161ed0bd", "parameters": [ { "name": "codigoMunicipio", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 7, "minLength": 7 } } ], "responses": { "200": { "description": "Lista de parâmetros de retenção" } } } }, "/api/parametros_municipais/{codigoMunicipio}/beneficios": { "get": { "tags": [ "Parâmetros Municipais" ], "summary": "Consultar benefícios fiscais do município", "operationId": "f8565681cdc268e106abf846aeada8d7", "parameters": [ { "name": "codigoMunicipio", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 7, "minLength": 7 } } ], "responses": { "200": { "description": "Lista de benefícios fiscais" } } } }, "/api/parametros_municipais/{codigoMunicipio}": { "get": { "tags": [ "Parâmetros Municipais" ], "summary": "Consultar todos os parâmetros do município", "operationId": "020d59f6aa309e7dc1219b45870e7d1b", "parameters": [ { "name": "codigoMunicipio", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 7, "minLength": 7 } } ], "responses": { "200": { "description": "Todos os parâmetros do município" } } } }, "/api/municipios/conveniados": { "get": { "tags": [ "Parâmetros Municipais" ], "summary": "Listar municípios conveniados ao Sistema Nacional", "operationId": "35775f2cd7d732501babc73e105f581e", "responses": { "200": { "description": "Lista de municípios conveniados" } } } }, "/api/parametros_municipais/{codigoMunicipio}/cache": { "delete": { "tags": [ "Parâmetros Municipais" ], "summary": "Limpar cache de parâmetros municipais", "operationId": "d399fd83fdc3e456e5634fa899583e20", "parameters": [ { "name": "codigoMunicipio", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 7, "minLength": 7 } } ], "responses": { "200": { "description": "Cache limpo com sucesso" } }, "security": [ { "sanctum": [] } ] } }, "/api/parametros_municipais/{codigoMunicipio}/aliquota/{codigoServico}": { "get": { "tags": [ "Parâmetros Municipais" ], "summary": "Buscar alíquota específica para um serviço", "operationId": "962805ae235faf845211adbc226e46cb", "parameters": [ { "name": "codigoMunicipio", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codigoServico", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "competencia", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Alíquota do serviço" }, "404": { "description": "Alíquota não encontrada" } } } } }, "components": { "schemas": { "NFSe": { "properties": { "id": { "type": "integer", "example": 1 }, "chave_acesso": { "type": "string", "example": "35240112345678000195550010000000011123456789" }, "numero": { "type": "string", "example": "000000001" }, "serie": { "type": "string", "example": "NFS" }, "codigo_verificacao": { "type": "string", "example": "ABC123" }, "data_emissao": { "type": "string", "format": "date-time" }, "situacao": { "type": "string", "enum": [ "normal", "cancelada", "substituida" ] }, "valor_servico": { "type": "number", "format": "float", "example": 1000 }, "valor_iss": { "type": "number", "format": "float", "example": 50 }, "valor_liquido": { "type": "number", "format": "float", "example": 950 } }, "type": "object" }, "DPS": { "properties": { "id_dps": { "type": "string", "example": "352401123456780001955500100000000110000001" }, "numero": { "type": "string", "example": "000000001" }, "serie": { "type": "string", "example": "DPS" }, "data_emissao": { "type": "string", "format": "date-time" }, "data_competencia": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "pendente", "processando", "autorizada", "rejeitada" ] } }, "type": "object" }, "Evento": { "properties": { "id": { "type": "integer", "example": 1 }, "tipo_evento": { "type": "string", "example": "101101" }, "sequencial_evento": { "type": "integer", "example": 1 }, "data_evento": { "type": "string", "format": "date-time" }, "numero_protocolo": { "type": "string" }, "status": { "type": "string", "enum": [ "pendente", "processado", "rejeitado" ] } }, "type": "object" }, "Contribuinte": { "properties": { "id": { "type": "integer", "example": 1 }, "tipo_documento": { "type": "string", "enum": [ "CPF", "CNPJ" ] }, "documento": { "type": "string", "example": "12345678000195" }, "razao_social": { "type": "string", "example": "Empresa Exemplo LTDA" }, "nome_fantasia": { "type": "string", "example": "Empresa Exemplo" }, "inscricao_municipal": { "type": "string" }, "regime_tributacao": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "type": "object" }, "Municipio": { "properties": { "codigo_ibge": { "type": "string", "example": "3550308" }, "nome": { "type": "string", "example": "São Paulo" }, "uf": { "type": "string", "example": "SP" }, "conveniado": { "type": "boolean", "example": true }, "data_convenio": { "type": "string", "format": "date" } }, "type": "object" }, "ParametroMunicipal": { "properties": { "codigo_servico": { "type": "string", "example": "01.01" }, "descricao_servico": { "type": "string", "example": "Análise e desenvolvimento de sistemas" }, "aliquota_minima": { "type": "number", "format": "float", "example": 2 }, "aliquota_maxima": { "type": "number", "format": "float", "example": 5 }, "codigo_cnae": { "type": "string", "example": "6201500" } }, "type": "object" }, "EmitirNFSeRequest": { "required": [ "prestador", "tomador", "servico", "valores" ], "properties": { "prestador": { "properties": { "documento": { "type": "string", "example": "12345678000195" }, "inscricao_municipal": { "type": "string" } }, "type": "object" }, "tomador": { "properties": { "documento": { "type": "string", "example": "98765432000198" }, "razao_social": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "type": "object" }, "servico": { "properties": { "codigo_servico": { "type": "string", "example": "01.01" }, "discriminacao": { "type": "string" }, "codigo_municipio_prestacao": { "type": "string" } }, "type": "object" }, "valores": { "properties": { "valor_servico": { "type": "number", "format": "float", "example": 1000 }, "aliquota_iss": { "type": "number", "format": "float", "example": 5 } }, "type": "object" } }, "type": "object" }, "ErrorResponse": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Erro ao processar requisição" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SuccessResponse": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operação realizada com sucesso" }, "data": { "type": "object" } }, "type": "object" }, "RegistrarEventoRequest": { "description": "Registra um evento (cancelamento, substituição, confirmação, etc.) numa NFS-e.", "required": [ "tipo_evento", "autor_documento", "certificado_id" ], "properties": { "tipo_evento": { "description": "Código do tipo de evento (6 dígitos). Ex: 101101=Cancelamento, 305101=Substituição, 202201=Confirmação Tomador", "type": "string", "maxLength": 6, "minLength": 6, "example": "101101" }, "autor_documento": { "description": "CPF (11) ou CNPJ (14) do autor do evento, apenas dígitos", "type": "string", "maxLength": 14, "minLength": 11, "example": "11222333000181" }, "certificado_id": { "description": "ID do certificado digital ativo do contribuinte", "type": "integer", "example": 1 }, "detalhes": { "description": "Detalhes específicos do evento conforme o tipo", "properties": { "motivo": { "type": "string", "maxLength": 255, "example": "Erro na emissão - serviço não prestado" }, "codigo_cancelamento": { "type": "string", "maxLength": 10, "example": "1" }, "descricao": { "type": "string", "maxLength": 255 }, "chave_substituta": { "description": "Chave de 50 caracteres da NFS-e substituta (eventos 305101/305102/305103)", "type": "string", "maxLength": 50, "minLength": 50, "example": "35260111222333000181NFS0000009049238145146" } }, "type": "object" } }, "type": "object", "example": { "tipo_evento": "101101", "autor_documento": "11222333000181", "certificado_id": 1, "detalhes": { "motivo": "Erro na emissão - serviço não prestado", "codigo_cancelamento": "1" } } }, "LoginRequest": { "required": [ "email", "password" ], "properties": { "email": { "description": "Email do usuário", "type": "string", "format": "email", "example": "admin@exemplo.com.br" }, "password": { "description": "Senha do usuário", "type": "string", "format": "password", "example": "password" } }, "type": "object" }, "LoginResponse": { "properties": { "sucesso": { "type": "boolean", "example": true }, "mensagem": { "type": "string", "example": "Login realizado com sucesso" }, "dados": { "properties": { "token": { "type": "string", "example": "1|abc123def456..." }, "token_type": { "type": "string", "example": "Bearer" }, "usuario": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Administrador" }, "email": { "type": "string", "example": "admin@exemplo.com.br" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "RegisterRequest": { "required": [ "name", "email", "password", "password_confirmation" ], "properties": { "name": { "type": "string", "example": "Novo Usuário" }, "email": { "type": "string", "format": "email", "example": "novo@exemplo.com.br" }, "password": { "type": "string", "format": "password", "example": "senha123" }, "password_confirmation": { "type": "string", "format": "password", "example": "senha123" } }, "type": "object" }, "ChangePasswordRequest": { "required": [ "current_password", "password", "password_confirmation" ], "properties": { "current_password": { "type": "string", "format": "password", "example": "senha_atual" }, "password": { "type": "string", "format": "password", "example": "nova_senha" }, "password_confirmation": { "type": "string", "format": "password", "example": "nova_senha" } }, "type": "object" }, "ContribuinteRequest": { "required": [ "tipo_documento", "documento", "razao_social" ], "properties": { "tipo_documento": { "type": "string", "enum": [ "CPF", "CNPJ" ], "example": "CNPJ" }, "documento": { "type": "string", "example": "12345678000195" }, "inscricao_municipal": { "type": "string", "example": "12345678" }, "razao_social": { "type": "string", "example": "Empresa Exemplo LTDA" }, "nome_fantasia": { "type": "string", "example": "Empresa Exemplo" }, "logradouro": { "type": "string", "example": "Rua das Flores" }, "numero": { "type": "string", "example": "100" }, "complemento": { "type": "string", "example": "Sala 101" }, "bairro": { "type": "string", "example": "Centro" }, "codigo_municipio": { "type": "string", "example": "3550308" }, "uf": { "type": "string", "example": "SP" }, "cep": { "type": "string", "example": "01310100" }, "telefone": { "type": "string", "example": "1133334444" }, "email": { "type": "string", "format": "email", "example": "contato@empresa.com.br" }, "regime_tributacao": { "type": "integer", "example": 1 }, "optante_simples": { "type": "boolean", "example": false }, "incentivador_cultural": { "type": "boolean", "example": false } }, "type": "object" }, "ContribuinteResponse": { "properties": { "sucesso": { "type": "boolean", "example": true }, "mensagem": { "type": "string", "example": "Contribuinte criado com sucesso" }, "dados": { "properties": { "id": { "type": "integer", "example": 1 }, "tipo_documento": { "type": "string", "example": "CNPJ" }, "documento": { "type": "string", "example": "12345678000195" }, "razao_social": { "type": "string", "example": "Empresa Exemplo LTDA" }, "nome_fantasia": { "type": "string", "example": "Empresa Exemplo" }, "inscricao_municipal": { "type": "string", "example": "12345678" }, "email": { "type": "string", "example": "contato@empresa.com.br" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" }, "CertificadoResponse": { "properties": { "id": { "type": "integer", "example": 1 }, "tipo_certificado": { "type": "string", "example": "A1" }, "cn": { "type": "string", "example": "EMPRESA TESTE LTDA:11222333000181" }, "validade_inicio": { "type": "string", "format": "date" }, "validade_fim": { "type": "string", "format": "date" }, "ativo": { "type": "boolean", "example": true } }, "type": "object" }, "EmitirNFSeRequestFull": { "description": "Dados para emissão de NFS-e. Quando autenticado via API Token (Bearer), os dados do prestador, certificado_id, contribuinte_id, ambiente, tipo_emitente, codigo_municipio, serie, numero (sequencial automático) e datas são preenchidos automaticamente a partir do contribuinte vinculado ao token. Apenas codigo_servico, discriminacao, valor_servico e dados do tomador são realmente necessários.", "required": [ "codigo_servico", "discriminacao", "valor_servico" ], "properties": { "codigo_municipio": { "description": "Código IBGE do município", "type": "string", "example": "3550308" }, "serie": { "description": "Série da NFS-e", "type": "string", "example": "NFS" }, "numero": { "description": "Número da NFS-e", "type": "integer", "example": 1 }, "data_emissao": { "type": "string", "format": "date", "example": "2026-01-13" }, "data_competencia": { "type": "string", "format": "date", "example": "2026-01-13" }, "ambiente": { "description": "1=Produção, 2=Homologação", "type": "integer", "enum": [ 1, 2 ], "example": 2 }, "tipo_emitente": { "type": "integer", "example": 1 }, "prestador_documento": { "type": "string", "example": "11222333000181" }, "prestador_inscricao_municipal": { "type": "string", "example": "12345678" }, "prestador_razao_social": { "type": "string", "example": "Empresa Teste LTDA" }, "prestador_nome_fantasia": { "type": "string", "example": "Empresa Teste" }, "prestador_endereco": { "type": "string", "example": "Rua Teste" }, "prestador_numero": { "type": "string", "example": "100" }, "prestador_complemento": { "type": "string", "example": "Sala 101" }, "prestador_bairro": { "type": "string", "example": "Centro" }, "prestador_cep": { "type": "string", "example": "01310100" }, "prestador_uf": { "type": "string", "example": "SP" }, "prestador_telefone": { "type": "string", "example": "1133334444" }, "prestador_email": { "type": "string", "example": "empresa@teste.com.br" }, "regime_especial_tributacao": { "type": "integer", "example": 6 }, "tomador_documento": { "description": "CPF ou CNPJ do tomador", "type": "string", "example": "52998224725" }, "tomador_razao_social": { "type": "string", "example": "João da Silva" }, "tomador_endereco": { "type": "string", "example": "Av. Paulista" }, "tomador_numero": { "type": "string", "example": "1000" }, "tomador_bairro": { "type": "string", "example": "Bela Vista" }, "tomador_codigo_municipio": { "type": "string", "example": "3550308" }, "tomador_uf": { "type": "string", "example": "SP" }, "tomador_cep": { "type": "string", "example": "01310000" }, "tomador_telefone": { "type": "string", "example": "11999998888" }, "tomador_email": { "type": "string", "example": "joao@email.com" }, "codigo_servico": { "description": "Código do serviço na LC 116", "type": "string", "example": "01.04" }, "discriminacao": { "type": "string", "example": "Serviços de consultoria em TI\nPeríodo: Janeiro/2026" }, "codigo_municipio_prestacao": { "type": "string", "example": "3550308" }, "codigo_cnae": { "type": "string", "example": "6201500" }, "valor_servico": { "type": "number", "format": "float", "example": 5000 }, "valor_deducao": { "type": "number", "format": "float", "example": 0 }, "valor_desconto_incondicionado": { "type": "number", "format": "float", "example": 0 }, "valor_desconto_condicionado": { "type": "number", "format": "float", "example": 0 }, "aliquota_iss": { "description": "Alíquota ISS em %", "type": "number", "format": "float", "example": 2 }, "exigibilidade_iss": { "description": "1=Exigível, 2=Não incidência, etc", "type": "integer", "example": 1 }, "iss_retido": { "type": "boolean", "example": false }, "ibs_cbs_localidade_incidencia": { "description": "Código IBGE localidade incidência IBS/CBS", "type": "string", "example": "3550308" }, "ibs_cbs_nome_localidade": { "description": "Nome da localidade de incidência IBS/CBS", "type": "string", "example": "São Paulo" }, "ibs_cbs_percentual_redutor": { "description": "Percentual redutor alíquota em compra governamental", "type": "number", "format": "float", "example": 0 }, "ibs_cbs_base_calculo": { "description": "Base de cálculo do IBS/CBS", "type": "number", "format": "float", "example": 5000 }, "ibs_cbs_valor_reembolso": { "description": "Valor reembolso/repasse/ressarcimento (não integra BC)", "type": "number", "format": "float", "example": 0 }, "ibs_uf_aliquota": { "description": "Alíquota IBS UF (fase de testes 2026: 0,1%)", "type": "number", "format": "float", "example": 0.1 }, "ibs_uf_percentual_reducao": { "description": "Percentual redução alíquota IBS UF", "type": "number", "format": "float", "example": 0 }, "ibs_uf_aliquota_efetiva": { "description": "Alíquota efetiva IBS UF", "type": "number", "format": "float", "example": 0.1 }, "ibs_uf_valor": { "description": "Valor IBS Estadual", "type": "number", "format": "float", "example": 5 }, "ibs_mun_aliquota": { "description": "Alíquota IBS Municipal", "type": "number", "format": "float", "example": 0 }, "ibs_mun_percentual_reducao": { "description": "Percentual redução alíquota IBS Municipal", "type": "number", "format": "float", "example": 0 }, "ibs_mun_aliquota_efetiva": { "description": "Alíquota efetiva IBS Municipal", "type": "number", "format": "float", "example": 0 }, "ibs_mun_valor": { "description": "Valor IBS Municipal", "type": "number", "format": "float", "example": 0 }, "cbs_aliquota": { "description": "Alíquota CBS (fase de testes 2026: 0,9%)", "type": "number", "format": "float", "example": 0.9 }, "cbs_percentual_reducao": { "description": "Percentual redução alíquota CBS", "type": "number", "format": "float", "example": 0 }, "cbs_aliquota_efetiva": { "description": "Alíquota efetiva CBS", "type": "number", "format": "float", "example": 0.9 }, "cbs_valor": { "description": "Valor CBS", "type": "number", "format": "float", "example": 45 }, "ibs_valor_total": { "description": "Valor total IBS (UF + Municipal)", "type": "number", "format": "float", "example": 5 }, "valor_total_nf_ibs_cbs": { "description": "Valor total NF com IBS/CBS", "type": "number", "format": "float", "example": 5000 }, "certificado_id": { "description": "ID do certificado digital", "type": "integer", "example": 1 }, "contribuinte_id": { "description": "ID do contribuinte prestador", "type": "integer", "example": 1 } }, "type": "object", "example": { "tomador_documento": "52998224725", "tomador_razao_social": "João da Silva", "tomador_endereco": "Av. Paulista", "tomador_numero": "1000", "tomador_bairro": "Bela Vista", "tomador_codigo_municipio": "3550308", "tomador_uf": "SP", "tomador_cep": "01310000", "tomador_email": "joao@email.com", "codigo_servico": "01.04", "codigo_tributacao_municipal": "0104001", "codigo_cnae": "6201500", "discriminacao": "Serviços de consultoria em TI - Janeiro/2026", "valor_servico": 5000, "aliquota_iss": 2, "exigibilidade_iss": 1, "iss_retido": false, "valor_pis": 32.5, "valor_cofins": 150, "valor_ir": 75, "valor_csll": 50 } }, "NFSeEmitidaResponse": { "properties": { "sucesso": { "type": "boolean", "example": true }, "mensagem": { "type": "string", "example": "NFS-e emitida com sucesso" }, "dados": { "properties": { "nfse": { "properties": { "id": { "type": "integer", "example": 10 }, "chave_acesso": { "type": "string", "example": "35260111222333000181NFS0000009049238145145" }, "numero": { "type": "integer", "example": 10 }, "codigo_verificacao": { "type": "string", "example": "F65EF95EC" }, "data_emissao": { "type": "string", "format": "date-time", "example": "2026-01-13T23:27:48.000000Z" }, "data_autorizacao": { "type": "string", "format": "date-time" }, "situacao": { "type": "string", "example": "normal" }, "ambiente": { "type": "integer", "example": 2 }, "prestador_documento": { "type": "string", "example": "11222333000181" }, "prestador_razao_social": { "type": "string", "example": "Empresa Teste LTDA" }, "tomador_documento": { "type": "string", "example": "52998224725" }, "tomador_razao_social": { "type": "string", "example": "João da Silva" }, "codigo_servico": { "type": "string", "example": "01.04" }, "valor_servico": { "type": "string", "example": "5000.00" }, "valor_iss": { "type": "string", "example": "100.00" }, "valor_liquido": { "type": "string", "example": "5000.00" }, "ibs_cbs_localidade_incidencia": { "description": "Código IBGE localidade incidência IBS/CBS", "type": "string", "example": "3550308" }, "ibs_cbs_nome_localidade": { "description": "Nome localidade incidência", "type": "string", "example": "São Paulo" }, "ibs_cbs_percentual_redutor": { "description": "% redutor compra governamental", "type": "string", "example": "0.00" }, "ibs_cbs_base_calculo": { "description": "Base de cálculo IBS/CBS", "type": "string", "example": "5000.00" }, "ibs_uf_aliquota": { "description": "Alíquota IBS UF", "type": "string", "example": "9.35" }, "ibs_uf_percentual_reducao": { "description": "% redução IBS UF", "type": "string", "example": "0.00" }, "ibs_uf_aliquota_efetiva": { "description": "Alíquota efetiva IBS UF", "type": "string", "example": "9.35" }, "ibs_uf_valor": { "description": "Valor IBS UF", "type": "string", "example": "467.50" }, "ibs_mun_aliquota": { "description": "Alíquota IBS Municipal", "type": "string", "example": "3.65" }, "ibs_mun_percentual_reducao": { "description": "% redução IBS Municipal", "type": "string", "example": "0.00" }, "ibs_mun_aliquota_efetiva": { "description": "Alíquota efetiva IBS Municipal", "type": "string", "example": "3.65" }, "ibs_mun_valor": { "description": "Valor IBS Municipal", "type": "string", "example": "182.50" }, "cbs_aliquota": { "description": "Alíquota CBS", "type": "string", "example": "8.80" }, "cbs_percentual_reducao": { "description": "% redução CBS", "type": "string", "example": "0.00" }, "cbs_aliquota_efetiva": { "description": "Alíquota efetiva CBS", "type": "string", "example": "8.80" }, "cbs_valor": { "description": "Valor CBS", "type": "string", "example": "440.00" }, "ibs_valor_total": { "description": "Valor total IBS (UF + Mun)", "type": "string", "example": "650.00" }, "valor_total_nf_ibs_cbs": { "description": "Valor total NF com IBS/CBS", "type": "string", "example": "5000.00" } }, "type": "object" }, "chave_acesso": { "type": "string", "example": "35260111222333000181NFS0000009049238145145" }, "numero": { "type": "integer", "example": 10 }, "codigo_verificacao": { "type": "string", "example": "F65EF95EC" }, "pdf_base64": { "description": "DANFS-e em PDF codificado em base64", "type": "string", "example": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..." }, "xml_base64": { "description": "XML da NFS-e codificado em base64", "type": "string", "example": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..." } }, "type": "object" } }, "type": "object" }, "NFSeConsultaResponse": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "properties": { "id": { "type": "integer", "example": 10 }, "chave_acesso": { "type": "string", "example": "35260111222333000181NFS0000009049238145145" }, "numero": { "type": "integer", "example": 10 }, "codigo_verificacao": { "type": "string", "example": "F65EF95EC" }, "situacao": { "type": "string", "example": "normal" }, "valor_servico": { "type": "string", "example": "5000.00" }, "ibs_cbs_localidade_incidencia": { "description": "Código IBGE localidade incidência IBS/CBS", "type": "string", "example": "3550308" }, "ibs_cbs_base_calculo": { "description": "Base de cálculo IBS/CBS", "type": "string", "example": "5000.00" }, "ibs_uf_valor": { "description": "Valor IBS UF", "type": "string", "example": "467.50" }, "ibs_mun_valor": { "description": "Valor IBS Municipal", "type": "string", "example": "182.50" }, "cbs_valor": { "description": "Valor CBS", "type": "string", "example": "440.00" }, "ibs_valor_total": { "description": "Valor total IBS", "type": "string", "example": "650.00" }, "valor_total_nf_ibs_cbs": { "description": "Valor total NF com IBS/CBS", "type": "string", "example": "5000.00" }, "pdf_base64": { "description": "Retornado apenas se incluir_arquivos=true", "type": "string", "example": "JVBERi0xLjQK..." }, "xml_base64": { "description": "Retornado apenas se incluir_arquivos=true", "type": "string", "example": "PD94bWwgdmVyc2lvbj0i..." } }, "type": "object" } }, "type": "object" }, "NFSeListaResponse": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 50 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "chave_acesso": { "type": "string" }, "numero": { "type": "integer" }, "situacao": { "type": "string" }, "valor_servico": { "type": "string" } }, "type": "object" } } }, "type": "object" } }, "type": "object" }, "EmitirLoteNFSeRequest": { "description": "Emissão em lote de até 50 NFS-e numa única requisição.", "required": [ "documentos" ], "properties": { "certificado_id": { "description": "Opcional — preenchido automaticamente do contribuinte autenticado", "type": "integer", "example": 1 }, "documentos": { "description": "Array de NFS-e para emissão em lote (1 a 50 documentos)", "type": "array", "items": { "$ref": "#/components/schemas/EmitirNFSeRequestFull" }, "maxItems": 50, "minItems": 1 } }, "type": "object", "example": { "documentos": [ { "codigo_municipio": "3550308", "serie": "NFS", "numero": 1, "data_emissao": "2026-01-13", "data_competencia": "2026-01-13", "ambiente": 2, "tipo_emitente": 1, "prestador_documento": "11222333000181", "prestador_razao_social": "Empresa Teste LTDA", "prestador_endereco": "Rua Teste", "prestador_numero": "100", "prestador_bairro": "Centro", "prestador_cep": "01310100", "prestador_uf": "SP", "tomador_documento": "52998224725", "tomador_razao_social": "João da Silva", "codigo_servico": "01.04", "discriminacao": "Serviço prestado item 1", "valor_servico": 1500, "aliquota_iss": 2, "exigibilidade_iss": 1, "iss_retido": false } ] } }, "CancelarNFSeRequest": { "description": "Cancela uma NFS-e dentro do prazo legal. O certificado_id e autor_documento são preenchidos automaticamente do contribuinte autenticado.", "required": [ "motivo", "codigo_motivo" ], "properties": { "motivo": { "type": "string", "maxLength": 255, "minLength": 15, "example": "Erro na emissão - serviço não prestado ao cliente" }, "codigo_motivo": { "description": "1=Erro na emissão, 2=Serviço não prestado, 3=Duplicidade, 4=Erro preenchimento", "type": "string", "maxLength": 10, "example": "1" }, "autor_documento": { "description": "Opcional — preenchido automaticamente do contribuinte", "type": "string", "maxLength": 14, "minLength": 11, "example": "11222333000181" }, "certificado_id": { "description": "Opcional — preenchido automaticamente do certificado ativo do contribuinte", "type": "integer", "example": 1 } }, "type": "object", "example": { "motivo": "Erro na emissão - serviço não prestado ao cliente", "codigo_motivo": "1" } }, "SubstituirNFSeRequest": { "description": "Substitui uma NFS-e cancelada por outra já emitida. ATENÇÃO: a NFS-e substituta precisa ter sido emitida antes (POST /nfse).", "required": [ "chave_substituta", "autor_documento", "certificado_id" ], "properties": { "chave_substituta": { "description": "Chave de acesso (50 caracteres) da NFS-e que vai substituir a original", "type": "string", "maxLength": 50, "minLength": 50, "example": "35260111222333000181NFS0000009049238145146" }, "autor_documento": { "description": "CPF (11) ou CNPJ (14) do autor da substituição, sem formatação", "type": "string", "maxLength": 14, "minLength": 11, "example": "11222333000181" }, "certificado_id": { "description": "ID do certificado digital ativo", "type": "integer", "example": 1 } }, "type": "object", "example": { "chave_substituta": "35260111222333000181NFS0000009049238145146", "autor_documento": "11222333000181", "certificado_id": 1 } }, "EventoResponse": { "properties": { "sucesso": { "type": "boolean", "example": true }, "mensagem": { "type": "string", "example": "Evento registrado com sucesso" }, "dados": { "properties": { "id": { "type": "integer", "example": 1 }, "tipo_evento": { "type": "string", "example": "e101101" }, "sequencial_evento": { "type": "integer", "example": 1 }, "data_evento": { "type": "string", "format": "date-time" }, "status": { "type": "string", "example": "autorizado" }, "numero_protocolo": { "type": "string" } }, "type": "object" } }, "type": "object" }, "AliquotasResponse": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "type": "array", "items": { "properties": { "codigo_servico": { "type": "string", "example": "01.04" }, "descricao": { "type": "string", "example": "Programação" }, "aliquota": { "type": "number", "format": "float", "example": 2 }, "codigo_cnae": { "type": "string", "example": "6201500" } }, "type": "object" } } }, "type": "object" }, "MunicipiosConveniadosResponse": { "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "type": "array", "items": { "properties": { "codigo_ibge": { "type": "string", "example": "3550308" }, "nome": { "type": "string", "example": "São Paulo" }, "uf": { "type": "string", "example": "SP" }, "data_convenio": { "type": "string", "format": "date" } }, "type": "object" } } }, "type": "object" }, "ErrorValidation": { "properties": { "sucesso": { "type": "boolean", "example": false }, "mensagem": { "type": "string", "example": "Erro de validação" }, "erros": { "type": "object", "example": { "campo": [ "O campo é obrigatório" ] } } }, "type": "object" }, "ErrorNotFound": { "properties": { "sucesso": { "type": "boolean", "example": false }, "mensagem": { "type": "string", "example": "Recurso não encontrado" }, "erro": { "type": "string", "example": "NFS-e não encontrada" } }, "type": "object" }, "ErrorUnauthorized": { "properties": { "sucesso": { "type": "boolean", "example": false }, "mensagem": { "type": "string", "example": "Não autorizado" }, "erro": { "type": "string", "example": "Token inválido ou expirado" } }, "type": "object" }, "TributosIBSCBSResponse": { "description": "Tributos IBS e CBS conforme Reforma Tributária, calculados e informados pelo contribuinte/sistema emissor. IBS = Imposto sobre Bens e Serviços (substitui parcialmente ICMS + ISS). CBS = Contribuição sobre Bens e Serviços (substitui PIS + COFINS). Em 2026: alíquotas simbólicas de 0,9% CBS e 0,1% IBS.", "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "properties": { "localidade_incidencia": { "description": "Localidade de incidência do IBS/CBS", "properties": { "codigo_ibge": { "description": "Código IBGE da localidade de incidência", "type": "string", "example": "3550308" }, "nome": { "description": "Nome da localidade de incidência", "type": "string", "example": "São Paulo" }, "percentual_redutor": { "description": "Percentual de redução de alíquota em compra governamental", "type": "number", "format": "float", "example": 0 } }, "type": "object" }, "base_calculo": { "description": "Base de cálculo do IBS/CBS", "properties": { "valor": { "description": "Valor da base de cálculo do IBS/CBS", "type": "number", "format": "float", "example": 5000 }, "valor_reembolso": { "description": "Valor de reembolso/repasse/ressarcimento (não integra BC)", "type": "number", "format": "float", "example": 0 } }, "type": "object" }, "ibs_uf": { "description": "IBS Estadual (UF)", "properties": { "aliquota": { "description": "Alíquota IBS UF parametrizada", "type": "number", "format": "float", "example": 9.35 }, "percentual_reducao": { "description": "Percentual de redução de alíquota estadual", "type": "number", "format": "float", "example": 0 }, "aliquota_efetiva": { "description": "Alíquota efetiva IBS UF (pAliqEfetUF = pIBSUF × (1 - pRedAliqUF) × (1 - pRedutor))", "type": "number", "format": "float", "example": 9.35 }, "valor": { "description": "Valor do IBS Estadual", "type": "number", "format": "float", "example": 467.5 } }, "type": "object" }, "ibs_mun": { "description": "IBS Municipal", "properties": { "aliquota": { "description": "Alíquota IBS Municipal parametrizada", "type": "number", "format": "float", "example": 3.65 }, "percentual_reducao": { "description": "Percentual de redução de alíquota municipal", "type": "number", "format": "float", "example": 0 }, "aliquota_efetiva": { "description": "Alíquota efetiva IBS Municipal (pAliqEfetMun = pIBSMun × (1 - pRedAliqMun) × (1 - pRedutor))", "type": "number", "format": "float", "example": 3.65 }, "valor": { "description": "Valor do IBS Municipal", "type": "number", "format": "float", "example": 182.5 } }, "type": "object" }, "cbs": { "description": "CBS Federal (Contribuição sobre Bens e Serviços)", "properties": { "aliquota": { "description": "Alíquota CBS parametrizada", "type": "number", "format": "float", "example": 8.8 }, "percentual_reducao": { "description": "Percentual de redução de alíquota CBS", "type": "number", "format": "float", "example": 0 }, "aliquota_efetiva": { "description": "Alíquota efetiva CBS (pAliqEfetCBS = pCBS × (1 - pRedAliqCBS) × (1 - pRedutor))", "type": "number", "format": "float", "example": 8.8 }, "valor": { "description": "Valor da CBS", "type": "number", "format": "float", "example": 440 } }, "type": "object" }, "totalizadores": { "description": "Totalizadores IBS/CBS", "properties": { "ibs_valor_total": { "description": "Valor total do IBS (UF + Municipal)", "type": "number", "format": "float", "example": 650 }, "valor_total_nf_ibs_cbs": { "description": "Valor total da NF com IBS/CBS (2026: vTotNF = vLiq; 2027+: vTotNF = vLiq + vCBS + vIBSTot)", "type": "number", "format": "float", "example": 5000 } }, "type": "object" }, "tributacao_regular": { "description": "Tributação regular (opcional)", "properties": { "ibs": { "description": "Valor IBS em tributação regular", "type": "number", "format": "float", "example": 650 }, "cbs": { "description": "Valor CBS em tributação regular", "type": "number", "format": "float", "example": 440 } }, "type": "object", "nullable": true }, "compra_governamental": { "description": "Compra governamental (opcional)", "properties": { "ibs": { "description": "Valor IBS em compra governamental", "type": "number", "format": "float", "example": 0 }, "cbs": { "description": "Valor CBS em compra governamental", "type": "number", "format": "float", "example": 0 } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" }, "TributosIBSCBSFields": { "description": "Campos de tributos IBS/CBS da NFS-e (calculados e informados pelo contribuinte/sistema emissor)", "properties": { "ibs_cbs_localidade_incidencia": { "description": "Código IBGE localidade incidência IBS/CBS", "type": "string", "example": "3550308" }, "ibs_cbs_nome_localidade": { "description": "Nome da localidade de incidência IBS/CBS", "type": "string", "example": "São Paulo" }, "ibs_cbs_percentual_redutor": { "description": "Percentual redutor alíquota em compra governamental", "type": "number", "format": "float", "example": 0 }, "ibs_cbs_base_calculo": { "description": "Base de cálculo do IBS/CBS", "type": "number", "format": "float", "example": 5000 }, "ibs_cbs_valor_reembolso": { "description": "Valor reembolso/repasse/ressarcimento", "type": "number", "format": "float", "example": 0 }, "ibs_uf_aliquota": { "description": "Alíquota IBS UF parametrizada", "type": "number", "format": "float", "example": 9.35 }, "ibs_uf_percentual_reducao": { "description": "Percentual redução alíquota IBS UF", "type": "number", "format": "float", "example": 0 }, "ibs_uf_aliquota_efetiva": { "description": "Alíquota efetiva IBS UF", "type": "number", "format": "float", "example": 9.35 }, "ibs_uf_valor": { "description": "Valor IBS Estadual", "type": "number", "format": "float", "example": 467.5 }, "ibs_mun_aliquota": { "description": "Alíquota IBS Municipal parametrizada", "type": "number", "format": "float", "example": 3.65 }, "ibs_mun_percentual_reducao": { "description": "Percentual redução alíquota IBS Municipal", "type": "number", "format": "float", "example": 0 }, "ibs_mun_aliquota_efetiva": { "description": "Alíquota efetiva IBS Municipal", "type": "number", "format": "float", "example": 3.65 }, "ibs_mun_valor": { "description": "Valor IBS Municipal", "type": "number", "format": "float", "example": 182.5 }, "cbs_aliquota": { "description": "Alíquota CBS parametrizada", "type": "number", "format": "float", "example": 8.8 }, "cbs_percentual_reducao": { "description": "Percentual redução alíquota CBS", "type": "number", "format": "float", "example": 0 }, "cbs_aliquota_efetiva": { "description": "Alíquota efetiva CBS", "type": "number", "format": "float", "example": 8.8 }, "cbs_valor": { "description": "Valor CBS", "type": "number", "format": "float", "example": 440 }, "ibs_valor_total": { "description": "Valor total IBS (UF + Municipal)", "type": "number", "format": "float", "example": 650 }, "valor_total_nf_ibs_cbs": { "description": "Valor total NF com IBS/CBS", "type": "number", "format": "float", "example": 5000 }, "trib_regular_ibs": { "description": "Valor IBS tributação regular", "type": "number", "format": "float", "example": 650, "nullable": true }, "trib_regular_cbs": { "description": "Valor CBS tributação regular", "type": "number", "format": "float", "example": 440, "nullable": true }, "compra_gov_ibs": { "description": "Valor IBS compra governamental", "type": "number", "format": "float", "example": 0, "nullable": true }, "compra_gov_cbs": { "description": "Valor CBS compra governamental", "type": "number", "format": "float", "example": 0, "nullable": true } }, "type": "object" }, "AliquotasIBSCBSResponse": { "description": "Alíquotas parametrizadas de IBS/CBS por município", "properties": { "sucesso": { "type": "boolean", "example": true }, "dados": { "properties": { "codigo_municipio": { "description": "Código IBGE do município", "type": "string", "example": "3550308" }, "nome_municipio": { "description": "Nome do município", "type": "string", "example": "São Paulo" }, "uf": { "description": "UF do município", "type": "string", "example": "SP" }, "ibs": { "properties": { "aliquota_uf": { "description": "Alíquota IBS Estadual", "type": "number", "format": "float", "example": 9.35 }, "aliquota_municipal": { "description": "Alíquota IBS Municipal", "type": "number", "format": "float", "example": 3.65 }, "aliquota_total": { "description": "Alíquota IBS Total (UF + Municipal)", "type": "number", "format": "float", "example": 13 } }, "type": "object" }, "cbs": { "properties": { "aliquota": { "description": "Alíquota CBS Federal", "type": "number", "format": "float", "example": 8.8 } }, "type": "object" }, "aliquota_total_ibs_cbs": { "description": "Alíquota total IBS + CBS", "type": "number", "format": "float", "example": 21.8 }, "vigencia_inicio": { "description": "Data de início da vigência", "type": "string", "format": "date", "example": "2026-01-01" }, "vigencia_fim": { "description": "Data de fim da vigência (null = vigente)", "type": "string", "format": "date", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" } }, "examples": { "LoginRequestExample": { "summary": "Exemplo de login", "value": { "email": "admin@exemplo.com.br", "password": "password", "device_name": "postman" } }, "LoginResponseExample": { "summary": "Resposta de login com sucesso", "value": { "sucesso": true, "dados": { "token": "1|abc123def456ghi789jkl012mno345pqr678stu901vwx234", "user": { "id": 1, "name": "Administrador", "email": "admin@exemplo.com.br", "email_verified_at": "2026-01-13T00:00:00.000000Z", "created_at": "2026-01-13T00:00:00.000000Z", "updated_at": "2026-01-13T00:00:00.000000Z" } } } }, "RegisterRequestExample": { "summary": "Exemplo de registro de usuário", "value": { "name": "Novo Usuário", "email": "novo@exemplo.com.br", "password": "senha123456", "password_confirmation": "senha123456" } }, "ContribuinteRequestExample": { "summary": "Exemplo de cadastro de contribuinte", "value": { "tipo_documento": "CNPJ", "documento": "11222333000181", "razao_social": "Empresa Teste LTDA", "nome_fantasia": "Empresa Teste", "inscricao_municipal": "12345678", "municipio_id": 1, "logradouro": "Rua das Flores", "numero": "100", "complemento": "Sala 101", "bairro": "Centro", "cep": "01310100", "telefone": "1133334444", "email": "empresa@teste.com.br", "regime_tributacao": "6" } }, "ContribuinteResponseExample": { "summary": "Resposta de contribuinte criado", "value": { "sucesso": true, "mensagem": "Contribuinte cadastrado com sucesso", "dados": { "id": 1, "tipo_documento": "CNPJ", "documento": "11222333000181", "razao_social": "Empresa Teste LTDA", "nome_fantasia": "Empresa Teste", "inscricao_municipal": "12345678", "municipio_id": 1, "logradouro": "Rua das Flores", "numero": "100", "complemento": "Sala 101", "bairro": "Centro", "cep": "01310100", "telefone": "1133334444", "email": "empresa@teste.com.br", "regime_tributacao": "6", "ativo": true, "created_at": "2026-01-13T23:00:00.000000Z", "updated_at": "2026-01-13T23:00:00.000000Z", "municipio": { "id": 1, "codigo_ibge": "3550308", "nome": "São Paulo", "uf": "SP" } } } }, "EmitirNFSeRequestExample": { "summary": "Exemplo completo de emissão de NFS-e com tributos IBS/CBS", "value": { "codigo_municipio": "3550308", "serie": "NFS", "numero": 1, "data_emissao": "2026-01-13", "data_competencia": "2026-01-13", "ambiente": 2, "tipo_emitente": 1, "prestador_documento": "11222333000181", "prestador_inscricao_municipal": "12345678", "prestador_razao_social": "Empresa Teste LTDA", "prestador_nome_fantasia": "Empresa Teste", "prestador_endereco": "Rua das Flores", "prestador_numero": "100", "prestador_complemento": "Sala 101", "prestador_bairro": "Centro", "prestador_cep": "01310100", "prestador_uf": "SP", "prestador_telefone": "1133334444", "prestador_email": "empresa@teste.com.br", "regime_especial_tributacao": 6, "tomador_documento": "52998224725", "tomador_razao_social": "João da Silva", "tomador_endereco": "Av. Paulista", "tomador_numero": "1000", "tomador_bairro": "Bela Vista", "tomador_codigo_municipio": "3550308", "tomador_uf": "SP", "tomador_cep": "01310000", "tomador_telefone": "11999998888", "tomador_email": "joao@email.com", "codigo_servico": "01.04", "discriminacao": "Serviços de consultoria em TI\nPeríodo: Janeiro/2026\n\nAtividades realizadas:\n- Análise de sistemas\n- Desenvolvimento de software\n- Suporte técnico", "codigo_municipio_prestacao": "3550308", "codigo_cnae": "6201500", "valor_servico": 5000, "valor_deducao": 0, "valor_desconto_incondicionado": 0, "valor_desconto_condicionado": 0, "aliquota_iss": 2, "exigibilidade_iss": 1, "iss_retido": false, "ibs_cbs_localidade_incidencia": "3550308", "ibs_cbs_nome_localidade": "São Paulo", "ibs_cbs_percentual_redutor": 0, "ibs_cbs_base_calculo": 5000, "ibs_cbs_valor_reembolso": 0, "ibs_uf_aliquota": 0.1, "ibs_uf_percentual_reducao": 0, "ibs_uf_aliquota_efetiva": 0.1, "ibs_uf_valor": 5, "ibs_mun_aliquota": 0, "ibs_mun_percentual_reducao": 0, "ibs_mun_aliquota_efetiva": 0, "ibs_mun_valor": 0, "cbs_aliquota": 0.9, "cbs_percentual_reducao": 0, "cbs_aliquota_efetiva": 0.9, "cbs_valor": 45, "ibs_valor_total": 5, "valor_total_nf_ibs_cbs": 5000, "certificado_id": 1, "contribuinte_id": 1 } }, "NFSeEmitidaResponseExample": { "summary": "Resposta de NFS-e emitida com sucesso", "value": { "sucesso": true, "mensagem": "NFS-e emitida com sucesso", "dados": { "nfse": { "id": 10, "contribuinte_id": 1, "municipio_id": 1, "dps_id": null, "lote_dfe_item_id": null, "chave_acesso": "35260111222333000181NFS0000009049238145145", "numero": 10, "serie": "NFS", "codigo_verificacao": "F65EF95EC", "data_emissao": "2026-01-13T23:27:48.000000Z", "data_competencia": "2026-01-13", "data_autorizacao": "2026-01-13T23:27:49.000000Z", "ambiente": 2, "situacao": "normal", "prestador_documento": "11222333000181", "prestador_inscricao_municipal": "12345678", "prestador_razao_social": "Empresa Teste LTDA", "tomador_documento": "52998224725", "tomador_razao_social": "João da Silva", "tomador_email": "joao@email.com", "codigo_servico": "01.04", "codigo_cnae": "6201500", "descricao_servico": "Serviços de consultoria em TI", "codigo_municipio_prestacao": "3550308", "valor_servico": "5000.00", "valor_deducao": "0.00", "valor_base_calculo": "5000.00", "aliquota_iss": "2.00", "valor_iss": "100.00", "valor_liquido": "5000.00", "iss_retido": false, "valor_iss_retido": "0.00", "ibs_cbs_localidade_incidencia": "3550308", "ibs_cbs_nome_localidade": "São Paulo", "ibs_cbs_percentual_redutor": "0.00", "ibs_cbs_base_calculo": "5000.00", "ibs_cbs_valor_reembolso": "0.00", "ibs_uf_aliquota": "0.10", "ibs_uf_percentual_reducao": "0.00", "ibs_uf_aliquota_efetiva": "0.10", "ibs_uf_valor": "5.00", "ibs_mun_aliquota": "0.00", "ibs_mun_percentual_reducao": "0.00", "ibs_mun_aliquota_efetiva": "0.00", "ibs_mun_valor": "0.00", "cbs_aliquota": "0.90", "cbs_percentual_reducao": "0.00", "cbs_aliquota_efetiva": "0.90", "cbs_valor": "45.00", "ibs_valor_total": "5.00", "valor_total_nf_ibs_cbs": "5000.00", "created_at": "2026-01-13T23:27:48.000000Z", "updated_at": "2026-01-13T23:27:49.000000Z" }, "chave_acesso": "35260111222333000181NFS0000009049238145145", "numero": 10, "codigo_verificacao": "F65EF95EC", "pdf_base64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo...", "xml_base64": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi..." } } }, "NFSeConsultaResponseExample": { "summary": "Resposta de consulta de NFS-e", "value": { "sucesso": true, "dados": { "id": 10, "chave_acesso": "35260111222333000181NFS0000009049238145145", "numero": 10, "serie": "NFS", "codigo_verificacao": "F65EF95EC", "data_emissao": "2026-01-13T23:27:48.000000Z", "situacao": "normal", "ambiente": 2, "prestador_documento": "11222333000181", "prestador_razao_social": "Empresa Teste LTDA", "tomador_documento": "52998224725", "tomador_razao_social": "João da Silva", "codigo_servico": "01.04", "valor_servico": "5000.00", "valor_iss": "100.00", "valor_liquido": "5000.00", "ibs_cbs_localidade_incidencia": "3550308", "ibs_cbs_base_calculo": "5000.00", "ibs_uf_valor": "5.00", "ibs_mun_valor": "0.00", "cbs_valor": "45.00", "ibs_valor_total": "5.00", "valor_total_nf_ibs_cbs": "5000.00" } } }, "NFSeConsultaComArquivosResponseExample": { "summary": "Resposta de consulta de NFS-e com arquivos", "value": { "sucesso": true, "dados": { "id": 10, "chave_acesso": "35260111222333000181NFS0000009049238145145", "numero": 10, "serie": "NFS", "codigo_verificacao": "F65EF95EC", "data_emissao": "2026-01-13T23:27:48.000000Z", "situacao": "normal", "ambiente": 2, "prestador_documento": "11222333000181", "prestador_razao_social": "Empresa Teste LTDA", "tomador_documento": "52998224725", "tomador_razao_social": "João da Silva", "codigo_servico": "01.04", "valor_servico": "5000.00", "valor_iss": "100.00", "valor_liquido": "5000.00", "ibs_cbs_localidade_incidencia": "3550308", "ibs_cbs_base_calculo": "5000.00", "ibs_uf_valor": "5.00", "ibs_mun_valor": "0.00", "cbs_valor": "45.00", "ibs_valor_total": "5.00", "valor_total_nf_ibs_cbs": "5000.00", "pdf_base64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo...", "xml_base64": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi..." } } }, "NFSeListaResponseExample": { "summary": "Resposta de lista de NFS-e paginada", "value": { "sucesso": true, "dados": { "current_page": 1, "data": [ { "id": 10, "chave_acesso": "35260111222333000181NFS0000010049238145145", "numero": 10, "situacao": "normal", "data_emissao": "2026-01-13T23:27:48.000000Z", "valor_servico": "5000.00", "valor_iss": "100.00", "tomador_razao_social": "João da Silva" }, { "id": 9, "chave_acesso": "35260111222333000181NFS0000009049238145145", "numero": 9, "situacao": "normal", "data_emissao": "2026-01-12T15:30:00.000000Z", "valor_servico": "3500.00", "valor_iss": "70.00", "tomador_razao_social": "Maria Souza" } ], "first_page_url": "http://127.0.0.1:8000/api/nfse?page=1", "from": 1, "last_page": 1, "last_page_url": "http://127.0.0.1:8000/api/nfse?page=1", "links": [ { "url": null, "label": "« Anterior", "active": false }, { "url": "http://127.0.0.1:8000/api/nfse?page=1", "label": "1", "active": true }, { "url": null, "label": "Próximo »", "active": false } ], "next_page_url": null, "path": "http://127.0.0.1:8000/api/nfse", "per_page": 15, "prev_page_url": null, "to": 2, "total": 2 } } }, "EmitirLoteNFSeRequestExample": { "summary": "Exemplo de emissão de lote de NFS-e", "value": { "certificado_id": 1, "documentos": [ { "codigo_municipio": "3550308", "serie": "NFS", "numero": 11, "data_emissao": "2026-01-13", "data_competencia": "2026-01-13", "ambiente": 2, "tipo_emitente": 1, "prestador_documento": "11222333000181", "prestador_razao_social": "Empresa Teste LTDA", "tomador_documento": "52998224725", "tomador_razao_social": "João da Silva", "codigo_servico": "01.04", "discriminacao": "Serviços de TI - NF 1", "valor_servico": 2500, "aliquota_iss": 2, "contribuinte_id": 1 }, { "codigo_municipio": "3550308", "serie": "NFS", "numero": 12, "data_emissao": "2026-01-13", "data_competencia": "2026-01-13", "ambiente": 2, "tipo_emitente": 1, "prestador_documento": "11222333000181", "prestador_razao_social": "Empresa Teste LTDA", "tomador_documento": "98765432109", "tomador_razao_social": "Maria Souza", "codigo_servico": "01.04", "discriminacao": "Serviços de TI - NF 2", "valor_servico": 3500, "aliquota_iss": 2, "contribuinte_id": 1 } ] } }, "LoteNFSeResponseExample": { "summary": "Resposta de lote processado", "value": { "sucesso": true, "mensagem": "Lote processado", "dados": { "lote_id": 1, "status": "processando", "quantidade": 2, "protocolo": "LOT202601130001" } } }, "CancelarNFSeRequestExample": { "summary": "Exemplo de cancelamento de NFS-e", "value": { "codigo_cancelamento": "1", "motivo": "Erro na emissão da nota fiscal - serviço não foi prestado conforme descrito", "certificado_id": 1 } }, "CancelarNFSeResponseExample": { "summary": "Resposta de cancelamento com sucesso", "value": { "sucesso": true, "mensagem": "NFS-e cancelada com sucesso", "dados": { "evento": { "id": 1, "tipo_evento": "e101101", "sequencial_evento": 1, "data_evento": "2026-01-13T23:30:00.000000Z", "status": "autorizado", "motivo_cancelamento": "Erro na emissão da nota fiscal" }, "numero_protocolo": "EVT202601130001" } } }, "SubstituirNFSeRequestExample": { "summary": "Exemplo de substituição de NFS-e", "value": { "chave_substituta": "35260111222333000181NFS0000011049238145146", "autor_documento": "11222333000181", "certificado_id": 1 } }, "EventoResponseExample": { "summary": "Resposta genérica de evento", "value": { "sucesso": true, "mensagem": "Evento registrado com sucesso", "dados": { "evento": { "id": 2, "tipo_evento": "e305100", "sequencial_evento": 1, "data_evento": "2026-01-13T23:35:00.000000Z", "status": "autorizado" }, "numero_protocolo": "EVT202601130002", "data_registro": "2026-01-13T23:35:00.000000Z" } } }, "ListaEventosResponseExample": { "summary": "Lista de eventos de uma NFS-e", "value": { "sucesso": true, "dados": [ { "id": 1, "tipo_evento": "e101101", "sequencial_evento": 1, "data_evento": "2026-01-13T23:30:00.000000Z", "status": "autorizado", "numero_protocolo": "EVT202601130001" }, { "id": 2, "tipo_evento": "e305100", "sequencial_evento": 2, "data_evento": "2026-01-13T23:35:00.000000Z", "status": "autorizado", "numero_protocolo": "EVT202601130002" } ] } }, "UploadCertificadoRequestExample": { "summary": "Upload de certificado digital (multipart/form-data)", "value": { "certificado": "(arquivo .pfx)", "senha": "senha_do_certificado", "apelido": "Certificado Principal" } }, "CertificadoResponseExample": { "summary": "Resposta de certificado cadastrado", "value": { "sucesso": true, "mensagem": "Certificado digital cadastrado com sucesso", "dados": { "id": 1, "contribuinte_id": 1, "tipo_certificado": "A1", "cn": "EMPRESA TESTE LTDA:11222333000181", "validade_inicio": "2025-01-01", "validade_fim": "2026-01-01", "ativo": true, "apelido": "Certificado Principal", "created_at": "2026-01-13T00:00:00.000000Z" } } }, "AliquotasResponseExample": { "summary": "Lista de alíquotas por município", "value": { "sucesso": true, "dados": [ { "codigo_servico": "01.01", "descricao": "Análise e desenvolvimento de sistemas", "aliquota": 2, "codigo_cnae": "6201500" }, { "codigo_servico": "01.02", "descricao": "Programação", "aliquota": 2, "codigo_cnae": "6201500" }, { "codigo_servico": "01.03", "descricao": "Processamento de dados", "aliquota": 2, "codigo_cnae": "6311900" }, { "codigo_servico": "01.04", "descricao": "Elaboração de programas", "aliquota": 2, "codigo_cnae": "6201500" } ] } }, "MunicipiosConveniadosResponseExample": { "summary": "Lista de municípios conveniados", "value": { "sucesso": true, "dados": { "total": 5, "municipios": [ { "codigo_ibge": "3550308", "nome": "São Paulo", "uf": "SP", "data_convenio": "2023-06-01" }, { "codigo_ibge": "3304557", "nome": "Rio de Janeiro", "uf": "RJ", "data_convenio": "2023-08-15" }, { "codigo_ibge": "3106200", "nome": "Belo Horizonte", "uf": "MG", "data_convenio": "2023-10-01" }, { "codigo_ibge": "4106902", "nome": "Curitiba", "uf": "PR", "data_convenio": "2024-01-15" }, { "codigo_ibge": "4314902", "nome": "Porto Alegre", "uf": "RS", "data_convenio": "2024-03-01" } ] } } }, "ParametrosMunicipaisResponseExample": { "summary": "Parâmetros do município", "value": { "sucesso": true, "dados": { "codigo_ibge": "3550308", "nome": "São Paulo", "uf": "SP", "conveniado": true, "data_convenio": "2023-06-01", "aliquota_minima": 2, "aliquota_maxima": 5, "regime_especial_tributacao": { "1": "Microempresa Municipal", "2": "Estimativa", "3": "Sociedade de Profissionais", "4": "Cooperativa", "5": "MEI", "6": "ME/EPP Simples Nacional" }, "exigibilidade_iss": { "1": "Exigível", "2": "Não Incidência", "3": "Isenção", "4": "Exportação", "5": "Imunidade", "6": "Exigib. Susp. Dec. Judicial", "7": "Exigib. Susp. Proc. Admin." } } } }, "ErrorValidationExample": { "summary": "Erro de validação", "value": { "sucesso": false, "mensagem": "Erro de validação", "erros": { "email": [ "O campo email é obrigatório." ], "password": [ "O campo senha é obrigatório." ] } } }, "ErrorUnauthorizedExample": { "summary": "Erro de autenticação", "value": { "sucesso": false, "mensagem": "Não autorizado", "erro": "Token inválido ou expirado" } }, "ErrorNotFoundExample": { "summary": "Recurso não encontrado", "value": { "sucesso": false, "mensagem": "Recurso não encontrado", "erro": "NFS-e não encontrada" } }, "ErrorProcessamentoExample": { "summary": "Erro de processamento", "value": { "sucesso": false, "mensagem": "Erro ao emitir NFS-e", "erro": "Certificado digital expirado ou inválido" } }, "TributosIBSCBSResponseExample": { "summary": "Tributos IBS/CBS - Fase de Testes 2026 (alíquotas simbólicas)", "value": { "sucesso": true, "dados": { "localidade_incidencia": { "codigo_ibge": "3550308", "nome": "São Paulo", "percentual_redutor": 0 }, "base_calculo": { "valor": 5000, "valor_reembolso": 0 }, "ibs_uf": { "aliquota": 0.1, "percentual_reducao": 0, "aliquota_efetiva": 0.1, "valor": 5 }, "ibs_mun": { "aliquota": 0, "percentual_reducao": 0, "aliquota_efetiva": 0, "valor": 0 }, "cbs": { "aliquota": 0.9, "percentual_reducao": 0, "aliquota_efetiva": 0.9, "valor": 45 }, "totalizadores": { "ibs_valor_total": 5, "valor_total_nf_ibs_cbs": 5000 }, "tributacao_regular": { "ibs": 5, "cbs": 45 }, "compra_governamental": null } } }, "TributosIBSCBSCompraGovExample": { "summary": "Tributos IBS/CBS com redução para compra governamental", "value": { "sucesso": true, "dados": { "localidade_incidencia": { "codigo_ibge": "3550308", "nome": "São Paulo", "percentual_redutor": 25 }, "base_calculo": { "valor": 10000, "valor_reembolso": 0 }, "ibs_uf": { "aliquota": 9.35, "percentual_reducao": 0, "aliquota_efetiva": 7.01, "valor": 701.25 }, "ibs_mun": { "aliquota": 3.65, "percentual_reducao": 0, "aliquota_efetiva": 2.74, "valor": 273.75 }, "cbs": { "aliquota": 8.8, "percentual_reducao": 0, "aliquota_efetiva": 6.6, "valor": 660 }, "totalizadores": { "ibs_valor_total": 975, "valor_total_nf_ibs_cbs": 10000 }, "tributacao_regular": null, "compra_governamental": { "ibs": 975, "cbs": 660 } } } }, "AliquotasIBSCBSResponseExample": { "summary": "Alíquotas IBS/CBS - Fase de Testes 2026", "value": { "sucesso": true, "dados": { "codigo_municipio": "3550308", "nome_municipio": "São Paulo", "uf": "SP", "ibs": { "aliquota_uf": 0.1, "aliquota_municipal": 0, "aliquota_total": 0.1 }, "cbs": { "aliquota": 0.9 }, "aliquota_total_ibs_cbs": 1, "vigencia_inicio": "2026-01-01", "vigencia_fim": null, "observacao": "Fase de testes - alíquotas simbólicas sem cobrança efetiva" } } }, "AliquotasIBSCBSListaResponseExample": { "summary": "Lista de alíquotas IBS/CBS por UF - Fase de Testes 2026", "value": { "sucesso": true, "dados": { "uf": "SP", "total_municipios": 3, "observacao": "Fase de testes - alíquotas simbólicas sem cobrança efetiva", "municipios": [ { "codigo_municipio": "3550308", "nome": "São Paulo", "ibs_uf": 0.1, "ibs_mun": 0, "cbs": 0.9, "total": 1 }, { "codigo_municipio": "3509502", "nome": "Campinas", "ibs_uf": 0.1, "ibs_mun": 0, "cbs": 0.9, "total": 1 }, { "codigo_municipio": "3518800", "nome": "Guarulhos", "ibs_uf": 0.1, "ibs_mun": 0, "cbs": 0.9, "total": 1 } ] } } }, "EstatisticasResponseExample": { "summary": "Estatísticas do contribuinte", "value": { "sucesso": true, "dados": { "competencia": "2026-01", "total_emitidas": 25, "total_canceladas": 2, "total_substituidas": 1, "valor_total_servicos": 125000, "valor_total_iss": 2500, "valor_total_iss_retido": 500, "media_valor_nfse": 5000, "por_status": { "normal": 22, "cancelada": 2, "substituida": 1 }, "por_tomador": { "João da Silva": { "quantidade": 5, "valor_total": 25000 }, "Maria Souza": { "quantidade": 8, "valor_total": 40000 } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Token de autenticação obtido via endpoint POST /auth/login. Exemplo: Bearer 1|abc123...", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Autenticação", "description": "Endpoints de autenticação e gerenciamento de usuários" }, { "name": "Contribuintes", "description": "Cadastro e gerenciamento de prestadores e tomadores" }, { "name": "DF-e", "description": "Operações de Distribuição de Documentos Fiscais Eletrônicos" }, { "name": "Eventos", "description": "Cancelamento, substituição e outros eventos de NFS-e" }, { "name": "NFS-e", "description": "Emissão, consulta e gerenciamento de Notas Fiscais de Serviço" }, { "name": "Sistema", "description": "Health check e informações do sistema" }, { "name": "Parâmetros Municipais", "description": "Consulta de parâmetros municipais do Sistema Nacional NFS-e" } ] }