{
    "openapi": "3.0.3",
    "info": {
        "title": "Emissor de NFS-e — API de integração",
        "version": "1.0.0",
        "description": "Emissão de NFS-e Padrão Nacional (MEI, ME e EPP) pela API do Emissor de NFS-e. Autenticação por chave da empresa (Bearer). Documentação completa: /docs/api"
    },
    "servers": [
        {
            "url": "https://e-nfse.com.br/api/v1"
        }
    ],
    "security": [
        {
            "bearer": []
        }
    ],
    "tags": [
        {
            "name": "NFS-e"
        },
        {
            "name": "Empresa"
        },
        {
            "name": "Relatórios"
        },
        {
            "name": "Aplicativo",
            "description": "Login do usuário no app (token de acesso de 15 min + renovação de 60 dias; código de 6 dígitos no 1º acesso de cada aparelho) e cadastros. Com o token do app, as rotas de NFS-e acima também funcionam."
        }
    ],
    "paths": {
        "/ping": {
            "get": {
                "tags": [
                    "Empresa"
                ],
                "summary": "Saúde do serviço",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/me": {
            "get": {
                "tags": [
                    "Empresa"
                ],
                "summary": "Confere a chave e mostra a situação da empresa e da assinatura",
                "description": "Com chave de teste, \"ambiente\" é sempre \"homologacao\".",
                "responses": {
                    "200": {
                        "description": "Situação",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Me"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/NaoAutenticado"
                    }
                }
            }
        },
        "/codigos-municipais": {
            "get": {
                "tags": [
                    "NFS-e"
                ],
                "summary": "Códigos de tributação municipal válidos para o serviço",
                "parameters": [
                    {
                        "name": "codigo_tributacao_nacional",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "01.07.01"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Códigos do município da empresa"
                    },
                    "400": {
                        "$ref": "#/components/responses/Validacao"
                    }
                }
            }
        },
        "/nfse": {
            "post": {
                "tags": [
                    "NFS-e"
                ],
                "summary": "Cria e emite a NFS-e",
                "description": "Idempotente pelo external_id: repetir devolve a mesma nota (200, ja_emitida). Com o cabeçalho Prefer: respond-async (ou \"assincrono\": true) entra na fila de emissão e responde 202. Com o bloco \"substitui\", a nota nova substitui uma autorizada (a SEFIN cancela a original).",
                "parameters": [
                    {
                        "name": "Prefer",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "respond-async"
                            ]
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "description": "Usado como external_id quando o corpo não traz o campo.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/NfseEntrada"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Já emitida antes com este external_id",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Nfse"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "Emitida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Nfse"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Na fila de emissão, ou SEFIN indisponível com reenvio automático (acompanhe por GET /nfse/{id})",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Nfse"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Validacao"
                    },
                    "401": {
                        "$ref": "#/components/responses/NaoAutenticado"
                    },
                    "402": {
                        "description": "Plano vencido ou limite de notas do plano atingido (produção)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "chave_teste (chave de teste substituindo nota de produção) ou plano_sem_api",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Em processamento, ou a DPS já consta na SEFIN (consta_na_sefin) / conferência pendente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Recusada pela SEFIN (veja erros) ou dados de cadastro incompletos; a nota fica salva e pode ser corrigida com o mesmo external_id",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Limite de requisições ou emissões simultâneas (veja Retry-After)"
                    },
                    "502": {
                        "description": "Falha de comunicação com a SEFIN"
                    }
                }
            },
            "get": {
                "tags": [
                    "NFS-e"
                ],
                "summary": "Lista as notas mais recentes, ou busca pelo external_id",
                "parameters": [
                    {
                        "name": "external_id",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "emitida",
                                "erro",
                                "processando",
                                "na_fila",
                                "rascunho",
                                "cancelada"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "busca",
                        "in": "query",
                        "description": "Nome ou CPF/CNPJ do tomador, ou número da NFS-e",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Nota (com external_id) ou lista"
                    },
                    "404": {
                        "$ref": "#/components/responses/NaoEncontrada"
                    }
                }
            }
        },
        "/nfse/{id}": {
            "get": {
                "tags": [
                    "NFS-e"
                ],
                "summary": "Consulta uma nota",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Id"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Nota",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Nfse"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NaoEncontrada"
                    }
                }
            }
        },
        "/nfse/{id}/xml": {
            "get": {
                "tags": [
                    "NFS-e"
                ],
                "summary": "XML da NFS-e autorizada",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Id"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "XML",
                        "content": {
                            "application/xml": []
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NaoEncontrada"
                    },
                    "409": {
                        "description": "Ainda não autorizada"
                    }
                }
            }
        },
        "/nfse/{id}/enviar": {
            "post": {
                "tags": [
                    "NFS-e"
                ],
                "summary": "Envia a NFS-e ao tomador por e-mail e/ou WhatsApp (contas da própria empresa)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Id"
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "canais": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "email",
                                                "whatsapp"
                                            ]
                                        }
                                    },
                                    "email": {
                                        "type": "string",
                                        "description": "Só neste envio (não muda o cadastro)"
                                    },
                                    "telefone": {
                                        "type": "string",
                                        "description": "Só neste envio (não muda o cadastro)"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Enviada por pelo menos um canal"
                    },
                    "409": {
                        "description": "Ainda não autorizada"
                    },
                    "415": {
                        "description": "Corpo não JSON"
                    },
                    "422": {
                        "description": "Nenhum canal entregou"
                    }
                }
            }
        },
        "/nfse/{id}/cancelar": {
            "post": {
                "tags": [
                    "NFS-e"
                ],
                "summary": "Cancela a NFS-e autorizada na SEFIN (evento e101101)",
                "description": "Seguro repetir: nota já cancelada responde 200 com ja_cancelada. O prazo de cancelamento é definido pelo município.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Id"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CancelamentoEntrada"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Cancelada",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Nfse"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/Validacao"
                    },
                    "403": {
                        "description": "chave_teste: a chave de teste não cancela nota de produção"
                    },
                    "404": {
                        "$ref": "#/components/responses/NaoEncontrada"
                    },
                    "409": {
                        "description": "nao_emitida | sem_chave | evento_vinculado | em_andamento",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "415": {
                        "description": "Corpo não JSON"
                    },
                    "422": {
                        "description": "prazo_expirado | recusado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "sefin_indisponivel (veja Retry-After)"
                    }
                }
            }
        },
        "/relatorios/mensal": {
            "get": {
                "tags": [
                    "Relatórios"
                ],
                "summary": "Totais do mês com e sem retenção de ISS e a lista das notas",
                "parameters": [
                    {
                        "name": "mes",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "2026-10"
                        }
                    },
                    {
                        "name": "ambiente",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "producao",
                                "homologacao",
                                "todos"
                            ],
                            "default": "producao"
                        }
                    },
                    {
                        "name": "formato",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "csv"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Relatório (JSON ou CSV)"
                    }
                }
            }
        },
        "/app/entrar": {
            "post": {
                "security": [],
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Login com e-mail, senha e o aparelho",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email",
                                    "senha",
                                    "dispositivo"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string"
                                    },
                                    "senha": {
                                        "type": "string"
                                    },
                                    "dispositivo": {
                                        "$ref": "#/components/schemas/Dispositivo"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Aparelho confiável: tokens",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Tokens"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "1º acesso neste aparelho: código enviado por e-mail/WhatsApp",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Desafio"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "validacao",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "credenciais_invalidas (5 erros bloqueiam 15 min)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "usuario_sem_empresa | trocar_senha",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "limite_excedido | limite_codigos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "codigo_nao_enviado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/app/confirmar": {
            "post": {
                "security": [],
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Confirma o código de 6 dígitos (o aparelho passa a ser confiável)",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "desafio",
                                    "codigo"
                                ],
                                "properties": {
                                    "desafio": {
                                        "type": "string"
                                    },
                                    "codigo": {
                                        "type": "string",
                                        "pattern": "^[0-9]{6}$"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Tokens",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Tokens"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "codigo_invalido (5 tentativas)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "410": {
                        "description": "codigo_expirado (10 minutos, uso único)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/app/reenviar-codigo": {
            "post": {
                "security": [],
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Reenvia o código (até 3 vezes, 1 minuto entre envios)",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "desafio"
                                ],
                                "properties": {
                                    "desafio": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Enviado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Desafio"
                                }
                            }
                        }
                    },
                    "410": {
                        "description": "codigo_expirado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "aguarde_reenvio | limite_codigos (Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/app/renovar": {
            "post": {
                "security": [],
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Troca o refresh_token por um par novo",
                "description": "O refresh_token é de uso único. Reapresentar um já trocado (depois de 30 s) encerra a sessão: o app deve guardar o novo par antes de usar.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "refresh_token"
                                ],
                                "properties": {
                                    "refresh_token": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Tokens",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Tokens"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "nao_autenticado: entrar de novo",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/app/sair": {
            "post": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Encerra a sessão deste aparelho",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/app/sair-de-todos": {
            "post": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Encerra as sessões de todos os aparelhos (os outros voltam a pedir código)",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "manter_este_aparelho": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/app/dispositivos": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Aparelhos do usuário (atual, conectado, último acesso)",
                "responses": {
                    "200": {
                        "description": "Lista"
                    }
                }
            }
        },
        "/app/dispositivos/{id}": {
            "delete": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Remove um aparelho e encerra as sessões dele",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "404": {
                        "description": "nao_encontrado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/app/notificacoes": {
            "put": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Registra o token de notificações push deste aparelho",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "token"
                                ],
                                "properties": {
                                    "token": {
                                        "type": "string"
                                    },
                                    "provedor": {
                                        "type": "string",
                                        "enum": [
                                            "fcm",
                                            "apns"
                                        ],
                                        "default": "fcm"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Remove o token de notificações deste aparelho",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/app/resumo": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Tela inicial: totais do mês, fila, erros, certificado, assinatura e últimas notas",
                "parameters": [
                    {
                        "name": "mes",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "2026-10"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resumo"
                    }
                }
            }
        },
        "/app/cnpj/{cnpj}": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Dados públicos do CNPJ (Receita) e o cliente já cadastrado, se houver",
                "parameters": [
                    {
                        "name": "cnpj",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "situacao: encontrado | nao_encontrado"
                    },
                    "503": {
                        "description": "Receita indisponível"
                    }
                }
            }
        },
        "/app/cep/{cep}": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Endereço pelo CEP",
                "parameters": [
                    {
                        "name": "cep",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Endereço"
                    }
                }
            }
        },
        "/app/codigos-tributacao": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Busca códigos de tributação nacional (até 50)",
                "parameters": [
                    {
                        "name": "busca",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista"
                    }
                }
            }
        },
        "/app/clientes": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Lista/busca clientes (nome, e-mail, CPF/CNPJ)",
                "parameters": [
                    {
                        "name": "busca",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 50,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista"
                    }
                }
            },
            "post": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Cadastra cliente; só com o CNPJ, nome e endereço vêm da Receita",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Cliente"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Criado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Cliente"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "ja_cadastrado (traz o cliente existente)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "dados_invalidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/app/clientes/{id}": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Cliente",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Cliente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Cliente"
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Atualiza só os campos enviados (CPF/CNPJ não muda)",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Cliente"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Atualizado"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Exclui (não se tiver notas)",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "409": {
                        "description": "cliente_com_notas",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/app/servicos": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Serviços (modelos) da empresa",
                "responses": {
                    "200": {
                        "description": "Lista"
                    }
                }
            },
            "post": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Cadastra serviço",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ServicoModelo"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Criado"
                    },
                    "422": {
                        "description": "codigo_municipal_invalido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/app/servicos/{id}": {
            "get": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Serviço",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Serviço"
                    }
                }
            },
            "put": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Atualiza só os campos enviados",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ServicoModelo"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Atualizado"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Aplicativo"
                ],
                "summary": "Desativa o serviço",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearer": {
                "type": "http",
                "scheme": "bearer",
                "description": "Chave da empresa (enfse_... ou, de teste, enfse_test_...). Também aceita o cabeçalho X-API-Key. No aplicativo, o access_token (enfa_...) do login."
            }
        },
        "parameters": {
            "Id": {
                "name": "id",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "integer"
                }
            }
        },
        "responses": {
            "NaoAutenticado": {
                "description": "Chave ausente, inválida ou revogada",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Erro"
                        }
                    }
                }
            },
            "NaoEncontrada": {
                "description": "Não encontrada nesta empresa",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Erro"
                        }
                    }
                }
            },
            "Validacao": {
                "description": "Dados inválidos (veja detalhes por campo)",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Erro"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Erro": {
                "type": "object",
                "properties": {
                    "erro": {
                        "type": "string",
                        "example": "validacao"
                    },
                    "mensagem": {
                        "type": "string"
                    },
                    "detalhes": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "campo": {
                                    "type": "string"
                                },
                                "mensagem": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "erros": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ErroSefin"
                        }
                    }
                }
            },
            "ErroSefin": {
                "type": "object",
                "properties": {
                    "codigo": {
                        "type": "string",
                        "example": "E0840"
                    },
                    "descricao": {
                        "type": "string"
                    },
                    "complemento": {
                        "type": "string"
                    }
                }
            },
            "Endereco": {
                "type": "object",
                "properties": {
                    "cep": {
                        "type": "string",
                        "example": "69000000"
                    },
                    "logradouro": {
                        "type": "string"
                    },
                    "numero": {
                        "type": "string"
                    },
                    "complemento": {
                        "type": "string"
                    },
                    "bairro": {
                        "type": "string"
                    },
                    "cidade": {
                        "type": "string"
                    },
                    "uf": {
                        "type": "string",
                        "example": "AM"
                    },
                    "codigo_ibge": {
                        "type": "string",
                        "example": "1302603"
                    }
                }
            },
            "Tomador": {
                "type": "object",
                "required": [
                    "cpf_cnpj"
                ],
                "description": "Com CNPJ, nome e endereço são opcionais: vêm do cadastro do cliente ou da Receita Federal (veja avisos na resposta). Com CPF, o nome é obrigatório.",
                "properties": {
                    "cpf_cnpj": {
                        "type": "string",
                        "example": "11444777000161"
                    },
                    "nome": {
                        "type": "string",
                        "maxLength": 150
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "telefone": {
                        "type": "string"
                    },
                    "inscricao_municipal": {
                        "type": "string"
                    },
                    "endereco": {
                        "$ref": "#/components/schemas/Endereco"
                    }
                }
            },
            "Servico": {
                "type": "object",
                "required": [
                    "descricao",
                    "valor",
                    "codigo_tributacao_nacional"
                ],
                "properties": {
                    "descricao": {
                        "type": "string",
                        "maxLength": 2000
                    },
                    "valor": {
                        "type": "number",
                        "example": 150
                    },
                    "desconto": {
                        "type": "number"
                    },
                    "codigo_tributacao_nacional": {
                        "type": "string",
                        "example": "01.07.01"
                    },
                    "codigo_municipal": {
                        "type": "string"
                    },
                    "nbs": {
                        "type": "string"
                    },
                    "informacoes_complementares": {
                        "type": "string"
                    },
                    "pedido": {
                        "type": "string"
                    },
                    "documento_referencia": {
                        "type": "string"
                    }
                }
            },
            "NfseEntrada": {
                "type": "object",
                "required": [
                    "external_id",
                    "tomador",
                    "servico"
                ],
                "properties": {
                    "external_id": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9._:\\-]{1,100}$",
                        "description": "O seu identificador do pedido (idempotência)"
                    },
                    "assincrono": {
                        "type": "boolean"
                    },
                    "competencia": {
                        "type": "string",
                        "format": "date",
                        "description": "Competência (dCompet); omitida = dia da emissão; não pode ser futura"
                    },
                    "retencao_iss": {
                        "type": "boolean"
                    },
                    "aliquota_iss": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 5
                    },
                    "retencoes_federais": {
                        "type": "object",
                        "description": "Percentual retido pelo tomador (0 a 30)",
                        "properties": {
                            "irrf": {
                                "type": "number"
                            },
                            "csll": {
                                "type": "number"
                            },
                            "pis": {
                                "type": "number"
                            },
                            "cofins": {
                                "type": "number"
                            },
                            "inss": {
                                "type": "number"
                            }
                        }
                    },
                    "substitui": {
                        "$ref": "#/components/schemas/SubstituicaoEntrada"
                    },
                    "tomador": {
                        "$ref": "#/components/schemas/Tomador"
                    },
                    "servico": {
                        "$ref": "#/components/schemas/Servico"
                    }
                }
            },
            "SubstituicaoEntrada": {
                "type": "object",
                "required": [
                    "motivo"
                ],
                "description": "Informe id ou external_id da nota autorizada a substituir. MEI e Simples: tomador, valor do serviço e competência não podem mudar.",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "external_id": {
                        "type": "string"
                    },
                    "motivo": {
                        "type": "string",
                        "enum": [
                            "01",
                            "02",
                            "03",
                            "04",
                            "05",
                            "99"
                        ]
                    },
                    "justificativa": {
                        "type": "string",
                        "minLength": 15,
                        "maxLength": 255,
                        "description": "Obrigatória com o motivo 99"
                    }
                }
            },
            "CancelamentoEntrada": {
                "type": "object",
                "required": [
                    "motivo",
                    "justificativa"
                ],
                "properties": {
                    "motivo": {
                        "type": "string",
                        "enum": [
                            "1",
                            "2",
                            "9"
                        ],
                        "description": "1 erro na emissão, 2 serviço não prestado, 9 outros"
                    },
                    "justificativa": {
                        "type": "string",
                        "minLength": 15,
                        "maxLength": 255
                    }
                }
            },
            "Nfse": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "external_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "emitida",
                            "erro",
                            "processando",
                            "na_fila",
                            "rascunho",
                            "cancelada"
                        ]
                    },
                    "valor": {
                        "type": "number"
                    },
                    "descricao": {
                        "type": "string"
                    },
                    "tomador": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "nome": {
                                "type": "string"
                            },
                            "cpf_cnpj": {
                                "type": "string"
                            }
                        }
                    },
                    "retencoes": {
                        "type": "object",
                        "properties": {
                            "iss": {
                                "type": "number"
                            },
                            "irrf": {
                                "type": "number"
                            },
                            "csll": {
                                "type": "number"
                            },
                            "pis": {
                                "type": "number"
                            },
                            "cofins": {
                                "type": "number"
                            },
                            "inss": {
                                "type": "number"
                            }
                        }
                    },
                    "numero_dps": {
                        "type": "string"
                    },
                    "serie_dps": {
                        "type": "string"
                    },
                    "origem": {
                        "type": "string",
                        "enum": [
                            "e-nfse",
                            "portal"
                        ]
                    },
                    "criada_em": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "competencia": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "nfse": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "numero": {
                                "type": "string"
                            },
                            "chave": {
                                "type": "string"
                            },
                            "data_emissao": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "ambiente": {
                                "type": "string",
                                "enum": [
                                    "producao",
                                    "homologacao"
                                ]
                            }
                        }
                    },
                    "links": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "danfse": {
                                "type": "string"
                            },
                            "xml": {
                                "type": "string"
                            },
                            "consulta_publica": {
                                "type": "string"
                            }
                        }
                    },
                    "substitui": {
                        "type": "integer",
                        "nullable": true,
                        "description": "Id da nota que esta substitui"
                    },
                    "substituida_por": {
                        "type": "integer",
                        "nullable": true,
                        "description": "Id da nota que substituiu esta"
                    },
                    "cancelamento": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "tipo": {
                                "type": "string",
                                "enum": [
                                    "cancelamento",
                                    "substituicao"
                                ]
                            },
                            "em": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "motivo": {
                                "type": "string"
                            },
                            "justificativa": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "erros": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ErroSefin"
                        }
                    },
                    "reenvio_automatico": {
                        "type": "object",
                        "description": "SEFIN indisponível: estado agendado, esgotado ou cancelado"
                    },
                    "avisos": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Ex.: dados do tomador completados pela Receita"
                    },
                    "mensagem": {
                        "type": "string"
                    },
                    "ja_emitida": {
                        "type": "boolean"
                    },
                    "ja_cancelada": {
                        "type": "boolean"
                    },
                    "posicao_na_fila": {
                        "type": "integer"
                    }
                }
            },
            "Me": {
                "type": "object",
                "properties": {
                    "chave": {
                        "type": "object",
                        "properties": {
                            "nome": {
                                "type": "string"
                            },
                            "prefixo": {
                                "type": "string"
                            },
                            "teste": {
                                "type": "boolean",
                                "description": "Chave de teste: tudo em homologação"
                            },
                            "tipo": {
                                "type": "string",
                                "enum": [
                                    "api",
                                    "aplicativo"
                                ]
                            }
                        }
                    },
                    "empresa": {
                        "type": "object"
                    },
                    "ambiente": {
                        "type": "string",
                        "enum": [
                            "producao",
                            "homologacao"
                        ]
                    },
                    "certificado": {
                        "type": "object"
                    },
                    "cadastro_completo": {
                        "type": "boolean"
                    },
                    "pendencias_cadastro": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "assinatura": {
                        "type": "object"
                    }
                }
            },
            "WebhookAviso": {
                "type": "object",
                "description": "Corpo do POST de webhook (cabeçalhos X-ENFSE-Evento, X-ENFSE-Entrega, X-ENFSE-Timestamp e X-ENFSE-Assinatura = sha256=HMAC(\"<timestamp>.<corpo>\")).",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "whe_1234"
                    },
                    "evento": {
                        "type": "string",
                        "enum": [
                            "nfse.emitida",
                            "nfse.rejeitada",
                            "nfse.cancelada",
                            "nfse.substituida",
                            "ping"
                        ]
                    },
                    "criado_em": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "nfse": {
                        "$ref": "#/components/schemas/Nfse"
                    }
                }
            },
            "Dispositivo": {
                "type": "object",
                "required": [
                    "id"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "minLength": 32,
                        "maxLength": 128,
                        "description": "Identificador SECRETO gerado aleatoriamente pelo app na instalação e guardado no armazenamento seguro do aparelho"
                    },
                    "nome": {
                        "type": "string",
                        "example": "Moto G84"
                    },
                    "plataforma": {
                        "type": "string",
                        "enum": [
                            "android",
                            "ios",
                            "outro"
                        ]
                    },
                    "versao_app": {
                        "type": "string"
                    }
                }
            },
            "Tokens": {
                "type": "object",
                "properties": {
                    "token_type": {
                        "type": "string",
                        "example": "Bearer"
                    },
                    "access_token": {
                        "type": "string",
                        "example": "enfa_..."
                    },
                    "expira_em": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "expira_em_segundos": {
                        "type": "integer",
                        "example": 900
                    },
                    "refresh_token": {
                        "type": "string",
                        "example": "enfr_..."
                    },
                    "refresh_expira_em": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "usuario": {
                        "type": "object"
                    },
                    "empresa": {
                        "type": "object"
                    },
                    "dispositivo": {
                        "type": "object"
                    }
                }
            },
            "Desafio": {
                "type": "object",
                "properties": {
                    "confirmacao_necessaria": {
                        "type": "boolean"
                    },
                    "desafio": {
                        "type": "string"
                    },
                    "enviado_para": {
                        "type": "object",
                        "example": {
                            "email": "jo***@gmail.com",
                            "whatsapp": "*****4567"
                        }
                    },
                    "expira_em": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "Cliente": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "nome": {
                        "type": "string"
                    },
                    "cpf_cnpj": {
                        "type": "string"
                    },
                    "tipo": {
                        "type": "string",
                        "enum": [
                            "PF",
                            "PJ"
                        ]
                    },
                    "email": {
                        "type": "string"
                    },
                    "telefone": {
                        "type": "string"
                    },
                    "celular": {
                        "type": "string"
                    },
                    "inscricao_municipal": {
                        "type": "string"
                    },
                    "endereco": {
                        "$ref": "#/components/schemas/Endereco"
                    },
                    "retem_iss": {
                        "type": "boolean"
                    },
                    "retencoes_federais": {
                        "type": "object",
                        "description": "Percentuais (0 a 30)",
                        "properties": {
                            "irrf": {
                                "type": "number"
                            },
                            "csll": {
                                "type": "number"
                            },
                            "pis": {
                                "type": "number"
                            },
                            "cofins": {
                                "type": "number"
                            },
                            "inss": {
                                "type": "number"
                            }
                        }
                    }
                }
            },
            "ServicoModelo": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "descricao": {
                        "type": "string"
                    },
                    "codigo_tributacao_nacional": {
                        "type": "string",
                        "example": "01.07.01"
                    },
                    "codigo_municipal": {
                        "type": "string"
                    },
                    "nbs": {
                        "type": "string"
                    },
                    "valor_padrao": {
                        "type": "number"
                    },
                    "aliquota_iss": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 5
                    },
                    "observacoes": {
                        "type": "string"
                    }
                }
            }
        }
    }
}
