{"openapi":"3.0.3","info":{"title":"ClickFin API","version":"2.10.4","description":"Bundled OpenAPI contract for the ClickFin API reference portal.\n\nIntegrações servidor a servidor autenticam com chave de API da licença (`Authorization: Bearer cf_live_…`, esquema `ApiKeyAuth`): uma operação aceita a chave somente com o escopo declarado em `x-clickfin-api-key-scope`.\n\nO contrato público (`GET /openapi.json`) contém exatamente as operações que uma chave de API pode chamar, mais `/healthcheck` e `/openapi.json`. Login, conta, usuários, empresas, auditoria e configurações fiscais e bancárias são da aplicação web e ficam fora dele.\n\nRotas autenticadas respondem 401 para token ausente, inválido ou expirado e 503 `AUTH.SESSION_UNAVAILABLE` quando a sessão não pôde ser consultada por falha do servidor; um 503 não encerra a sessão do cliente. Falhas de provedores externos (Asaas, PlugNotas) nunca repassam 401/403 do provedor: respondem 502 (ou 422/400 quando o provedor recusa os dados enviados).\n\nTodo erro segue o formato `{ \"status\": \"error\", \"category\": …, \"message\": … }`, inclusive os gerados pelo API Gateway antes da aplicação: método ou caminho inexistente responde `404` `ROUTE.NOT_FOUND` (qualquer que seja o `Authorization`); limite do gateway, `429` `RATE_LIMIT.EXCEEDED` com `Retry-After`; corpo acima do limite do gateway, `413` `MIDDLEWARE.HANDLER.INVALID_REQUEST_BODY`; outros 4xx do gateway, `GATEWAY.REQUEST_REJECTED`; 5xx do gateway (falha ou tempo esgotado da integração), `GATEWAY.UNAVAILABLE`."},"servers":[{"url":"https://api.clickfin.com.br","description":"API ClickFin"}],"paths":{"/healthcheck":{"get":{"x-clickfin-audience":"public","tags":["Healthcheck"],"summary":"Verificar saúde da API","description":"Retorna o status operacional da API e da conexão com o banco de dados configurado.\nEste endpoint é público e não requer autenticação.\n","operationId":"healthcheck","responses":{"200":{"description":"API saudável com banco conectado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthcheckResponse"},"examples":{"healthy":{"value":{"status":"ok","db":"connected","timestamp":"2026-06-25T14:00:00.000Z"}}}}}},"503":{"description":"API disponível, mas com banco desconectado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthcheckResponse"},"examples":{"degraded":{"value":{"status":"degraded","db":"disconnected","timestamp":"2026-06-25T14:00:00.000Z"}}}}}}}}},"/openapi.json":{"get":{"x-clickfin-audience":"public","tags":["OpenAPI"],"summary":"Obter o contrato OpenAPI oficial","description":"Retorna o bundle OpenAPI consolidado do backend em `application/json`.\nEsta rota é pública e serve como fonte oficial para portais e integrações de documentação.\n","operationId":"getOpenApiDocument","responses":{"200":{"description":"Contrato OpenAPI retornado com sucesso.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"success":{"value":{"openapi":"3.0.3","info":{"title":"ClickFin API","version":"1.0.0"}}}}}}},"500":{"description":"Erro interno ao carregar o bundle OpenAPI oficial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"unexpected":{"value":{"statusCode":500,"message":"Internal server error","category":"UNEXPECTED_ERROR"}}}}}}}}},"/client":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"clients:read","tags":["Client"],"summary":"Listar clientes com paginação","description":"Retorna uma lista paginada de clientes não excluídos associados à empresa do usuário autenticado.\n**Requer perfil de Administrador.**\n","operationId":"listClients","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"string","default":"1"},"description":"Número da página para a paginação."},{"in":"query","name":"limit","schema":{"type":"string","default":"10"},"description":"Quantidade de itens por página."},{"in":"query","name":"name","schema":{"type":"string"},"description":"Filtra parcialmente pela razão social, sem diferenciar maiúsculas de minúsculas."},{"in":"query","name":"tradeName","schema":{"type":"string"},"description":"Filtra parcialmente pelo nome fantasia, sem diferenciar maiúsculas de minúsculas."},{"in":"query","name":"cpfCnpj","schema":{"type":"string"},"description":"Filtra parcialmente pelo CPF ou CNPJ armazenado."},{"in":"query","name":"email","schema":{"type":"string","minLength":1,"maxLength":254},"description":"Filtra parcialmente os e-mails do cliente."},{"in":"query","name":"status","schema":{"type":"integer","enum":[0,1]},"description":"1 para ativo e 0 para inativo."},{"in":"query","name":"taxRegime","schema":{"type":"string"},"description":"Filtra pelo regime tributário exato."},{"in":"query","name":"companySize","schema":{"type":"string"},"description":"Filtra pelo porte da empresa exato."},{"in":"query","name":"marketSegment","schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"description":"Identificador do segmento de mercado."},{"in":"query","name":"origin","schema":{"type":"string"},"description":"Filtra pela origem exata do cliente."}],"responses":{"200":{"description":"Lista de clientes retornada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedClientResponse"},"examples":{"success":{"value":{"items":[{"_id":"66e1c7f0f2f0b2a6c7a8d999","name":"Cliente Exemplo 1","emails":["cliente1@exemplo.com","financeiro@cliente1.com"],"mobilePhone":"11987654321","cpfCnpj":"12345678901","marketSegment":{"_id":"66e1c8f0f2f0b2a6c7a8dAAA","name":"Varejo"},"licensedId":"66dfb4a6b1bbd81234abcd01","companyId":"66dfb4a6b1bbd81234abcd02"}],"total":1}}}}}},"400":{"description":"Erro de validação nos parâmetros da query ou empresa não selecionada no token.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceErrorResponse"}]},"examples":{"companyNotSelected":{"summary":"Empresa não selecionada no token","value":{"statusCode":400,"message":"Company not selected","category":"COMPANY_NOT_SELECTED"}}}}}},"401":{"description":"Erro de autenticação. O token não foi fornecido, é inválido ou expirou.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"tokenNotProvided":{"summary":"Token não enviado","value":{"statusCode":401,"message":"Token not provided","category":"TOKEN_NOT_PROVIDED"}},"invalidOrExpiredToken":{"summary":"Token inválido ou expirado","value":{"statusCode":401,"message":"Invalid or expired token","category":"INVALID_OR_EXPIRED_TOKEN"}}}}}},"403":{"description":"Erro de autorização. O usuário não tem permissão para acessar este recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"adminProfileRequired":{"summary":"Perfil de admin necessário","value":{"statusCode":403,"message":"Only admin users can access this resource.","category":"ONLY_ADMIN_USERS"}}}}}},"404":{"description":"Configuração de ambiente JWT ausente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"jwtSecretNotFound":{"value":{"statusCode":404,"message":"JWT_SECRET not found","category":"JWT_SECRET_NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno inesperado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"unexpected":{"value":{"statusCode":500,"message":"Internal server error","category":"UNEXPECTED_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"clients:write","tags":["Client"],"summary":"Criar um novo cliente","description":"Cria um novo cliente vinculado à empresa e ao licenciado do usuário autenticado.\nTodos os campos obrigatórios devem ser fornecidos.\nmarketSegment deve identificar um segmento existente do mesmo licenciado e da empresa autenticada.\nSegmentos inexistentes, de outra empresa/licenciado ou com ID malformado retornam 404.\nA empresa é obtida do token; companyId não é aceito no corpo.\nSe a empresa da sessão tiver sido excluída ou deixado de pertencer ao licenciado,\na gravação retorna 401 `CLIENT.CREATE.NOT_AUTHORIZED`.\n**Requer perfil de Administrador.**\n","operationId":"createClient","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClientRequest"},"examples":{"default":{"summary":"Exemplo de um cliente válido para criação","value":{"name":"Padaria Pão Quente LTDA","tradeName":"Pão Quente","cpfCnpj":"12345678000199","address":"Rua das Flores","streetTypeEnum":"Rua","number":"123","complement":"Sala 10","neighborhood":"Centro","postalCode":"30130000","city":"Belo Horizonte","state":"MG","phone":"3133224455","mobilePhone":"31998765432","emails":["contato@paoquente.com","financeiro@paoquente.com"],"companySize":"Microempresa","taxRegime":"Simples Nacional","marketSegment":"66e1c8f0f2f0b2a6c7a8dAAA","origin":"Indicação de Cliente","contactPeople":"João da Silva","observation":"Cliente com potencial para upsell."}}}}}},"responses":{"201":{"description":"Cliente criado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleClientResponse"}}}},"400":{"description":"Erro de validação nos dados do cliente (Zod), CPF/CNPJ já em uso, ou empresa não selecionada no token.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceErrorResponse"}]},"examples":{"invalidEnum":{"summary":"Exemplo de erro de enum","value":{"error":"VALIDATION_FAILED","details":[{"field":"companySize","message":"Invalid enum value. Expected 'Microempreendedor Individual' | ..., received 'MEI'"}]}},"cpfCnpjInUse":{"summary":"CPF/CNPJ já em uso","value":{"statusCode":400,"message":"This CPF/CNPJ is already in use in this account.","category":"CLIENT.CREATE.CPF_CNPJ_IN_USE_IN_THIS_ACCOUNT"}},"companyNotSelected":{"summary":"Empresa não selecionada no token","value":{"statusCode":400,"message":"Company not selected","category":"COMPANY_NOT_SELECTED"}}}}}},"401":{"description":"Erro de autenticação. O token não foi fornecido, é inválido ou expirou.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"tokenNotProvided":{"summary":"Token não enviado","value":{"statusCode":401,"message":"Token not provided","category":"TOKEN_NOT_PROVIDED"}},"companyNotActive":{"summary":"Empresa da sessão excluída ou inativa durante a gravação","value":{"status":"error","message":"You are not authorized to access this company.","category":"CLIENT.CREATE.NOT_AUTHORIZED"}}}}}},"403":{"description":"Erro de autorização. O usuário não tem permissão de Administrador.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"adminProfileRequired":{"summary":"Perfil de admin necessário","value":{"statusCode":403,"message":"Only admin users can access this resource.","category":"ONLY_ADMIN_USERS"}}}}}},"404":{"description":"Segmento de mercado não encontrado no licenciado e na empresa autenticada, ou ID malformado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReferenceErrorResponse"},"examples":{"marketSegmentNotFound":{"value":{"status":"error","message":"Market segment not found.","category":"CLIENT.MARKET_SEGMENT.NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno inesperado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"unexpected":{"value":{"statusCode":500,"message":"Internal server error","category":"UNEXPECTED_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/client/options":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"clients:read","tags":["Client"],"summary":"Listar opções de clientes para seleção","description":"Retorna todos os clientes não excluídos da empresa autenticada com campos mínimos (`_id`, `name`, `tradeName`),\nordenados por razão social. Destinado a comboboxes e filtros; a listagem paginada completa permanece em `GET /client`.\n","operationId":"listClientOptions","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"status","schema":{"type":"integer","enum":[0,1]},"description":"Filtra clientes pelo status (0 = inativo, 1 = ativo)."}],"responses":{"200":{"description":"Opções de clientes retornadas com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientOptionsResponse"},"examples":{"success":{"value":{"items":[{"_id":"66e1c7f0f2f0b2a6c7a8d999","name":"Cliente Exemplo 1","tradeName":"Exemplo"}],"total":1}}}}}},"400":{"description":"Erro de validação nos parâmetros da query ou empresa não selecionada no token.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceErrorResponse"}]}}}},"401":{"description":"Erro de autenticação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"}}}},"403":{"description":"Acesso comercial bloqueado ou sem permissão.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno inesperado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/client/{clientId}":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"clients:read","tags":["Client"],"summary":"Obter um cliente por ID","description":"Retorna os detalhes de um cliente específico pelo seu ID.\nO cliente deve pertencer ao licenciado do usuário autenticado.\n**Requer perfil de Administrador.**\n","operationId":"getClientById","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"clientId","required":true,"schema":{"type":"string","minLength":1},"description":"ID do cliente a ser retornado."}],"responses":{"200":{"description":"Cliente retornado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleClientResponse"},"examples":{"success":{"value":{"success":true,"message":"Client retrieved successfully!","data":{"_id":"66e1c7f0f2f0b2a6c7a8d999","name":"Cliente Exemplo 1","emails":["cliente1@exemplo.com","financeiro@cliente1.com"],"mobilePhone":"11987654321","cpfCnpj":"12345678901","marketSegment":{"_id":"66e1c8f0f2f0b2a6c7a8dAAA","name":"Varejo"},"licensedId":"66dfb4a6b1bbd81234abcd01","companyId":"66dfb4a6b1bbd81234abcd02"}}}}}}},"400":{"description":"Erro de validação no ID do cliente ou empresa não selecionada no token.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceErrorResponse"}]},"examples":{"companyNotSelected":{"summary":"Empresa não selecionada no token","value":{"statusCode":400,"message":"Company not selected","category":"COMPANY_NOT_SELECTED"}}}}}},"401":{"description":"Erro de autenticação. O token não foi fornecido, é inválido ou expirou.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"tokenNotProvided":{"summary":"Token não enviado","value":{"statusCode":401,"message":"Token not provided","category":"TOKEN_NOT_PROVIDED"}}}}}},"403":{"description":"Erro de autorização. O usuário não tem permissão para acessar este recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"adminProfileRequired":{"summary":"Perfil de admin necessário","value":{"statusCode":403,"message":"Only admin users can access this resource.","category":"ONLY_ADMIN_USERS"}}}}}},"404":{"description":"Cliente não encontrado, excluído, pertencente a outro licenciado ou a outra empresa\ndo licenciado (a consulta usa a empresa selecionada no token), ou configuração de ambiente JWT ausente.\nCliente de outro licenciado ou de outra empresa do mesmo licenciado retorna 404\n`CLIENT.GET.NOT_FOUND`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"clientNotFound":{"summary":"Cliente não encontrado","value":{"statusCode":404,"message":"Client not found.","category":"CLIENT.GET.CLIENT_NOT_FOUND"}},"jwtSecretNotFound":{"value":{"statusCode":404,"message":"JWT_SECRET not found","category":"JWT_SECRET_NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno inesperado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"unexpected":{"value":{"statusCode":500,"message":"Internal server error","category":"UNEXPECTED_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"clients:write","tags":["Client"],"summary":"Atualizar um cliente existente","description":"Atualiza as informações de um cliente específico.\nO cliente deve pertencer ao licenciado e à empresa selecionada no token; caso contrário, retorna 404.\nSe a empresa da sessão tiver sido excluída ou deixado de pertencer ao licenciado,\na gravação retorna 401 `CLIENT.UPDATE.NOT_AUTHORIZED`.\nQualquer campo enviado no corpo da requisição substituirá o valor existente.\nQuando enviado, marketSegment deve existir no licenciado autenticado e na empresa já vinculada ao cliente (client.companyId).\nEssa verificação também ocorre quando o mesmo segmento é reenviado; omitir o campo preserva a referência atual.\nSegmentos inexistentes, de outra empresa/licenciado ou com ID malformado retornam 404, sem transferir o cliente entre empresas.\n","operationId":"updateClient","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"clientId","required":true,"schema":{"type":"string","minLength":1},"description":"ID do cliente a ser atualizado."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateClientRequest"},"examples":{"default":{"summary":"Exemplo de atualização de cliente","value":{"name":"Padaria Pão Quente & Cia","emails":["novocontato@paoquente.com","fiscal@paoquente.com"],"cpfCnpj":"12345678000199","postalCode":"30130001"}}}}}},"responses":{"200":{"description":"Cliente atualizado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleClientResponse"}}}},"400":{"description":"Erro de validação nos dados enviados (Zod), CPF/CNPJ já em uso, ou empresa não selecionada no token.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceErrorResponse"}]},"examples":{"cpfCnpjInUse":{"summary":"CPF/CNPJ já em uso","value":{"statusCode":400,"message":"This CPF/CNPJ is already in use in this account.","category":"CLIENT.UPDATE.CPF_CNPJ_IN_USE_IN_THIS_ACCOUNT"}},"companyNotSelected":{"summary":"Empresa não selecionada no token","value":{"statusCode":400,"message":"Company not selected","category":"COMPANY_NOT_SELECTED"}}}}}},"401":{"description":"Erro de autenticação. O token não foi fornecido, é inválido ou expirou.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"tokenNotProvided":{"summary":"Token não enviado","value":{"statusCode":401,"message":"Token not provided","category":"TOKEN_NOT_PROVIDED"}},"companyNotActive":{"summary":"Empresa da sessão excluída ou inativa durante a gravação","value":{"status":"error","message":"You are not authorized to access this company.","category":"CLIENT.UPDATE.NOT_AUTHORIZED"}}}}}},"403":{"description":"Erro de autorização. O usuário não tem permissão para acessar este recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"}}}},"404":{"description":"Cliente não encontrado (inclui cliente de outro licenciado ou de outra empresa, antes 403 `CLIENT.UPDATE.NOT_AUTHORIZED`), ou segmento de mercado não encontrado na empresa do cliente e no licenciado autenticado (inclui ID malformado).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReferenceErrorResponse"},"examples":{"clientNotFound":{"summary":"Cliente não encontrado","value":{"status":"error","message":"Client not found.","category":"CLIENT.UPDATE.NOT_FOUND"}},"marketSegmentNotFound":{"value":{"status":"error","message":"Market segment not found.","category":"CLIENT.MARKET_SEGMENT.NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno inesperado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"unexpected":{"value":{"statusCode":500,"message":"Internal server error","category":"UNEXPECTED_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"clients:write","tags":["Client"],"summary":"Excluir um cliente","description":"Marca o cliente como excluído e o oculta das listagens, opções e consultas comuns.\nO cliente deve pertencer ao licenciado e à empresa selecionada no token; caso contrário, retorna 404.\nSe a empresa da sessão tiver sido excluída ou deixado de pertencer ao licenciado,\nretorna 401 `CLIENT.DELETE.NOT_AUTHORIZED`.\nA exclusão é bloqueada (400 `CLIENT.DELETE.HAS_CONTRACTS` ou `CLIENT.DELETE.HAS_ACCOUNTS_RECEIVABLE`) quando houver contrato, conta a receber ou vencimento ativo vinculado; registros financeiros já excluídos logicamente não bloqueiam. A operação não oferece restauração pela API e requer perfil de Administrador.\n","operationId":"deleteClient","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"clientId","required":true,"schema":{"type":"string","minLength":1},"description":"ID do cliente a ser excluído."}],"responses":{"200":{"description":"Cliente excluído com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"value":{"success":true,"message":"Client deleted successfully!"}}}}}},"400":{"description":"Empresa não selecionada no token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"companyNotSelected":{"summary":"Empresa não selecionada no token","value":{"statusCode":400,"message":"Company not selected","category":"COMPANY_NOT_SELECTED"}}}}}},"401":{"description":"Erro de autenticação. O token não foi fornecido, é inválido ou expirou.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"tokenNotProvided":{"summary":"Token não enviado","value":{"statusCode":401,"message":"Token not provided","category":"TOKEN_NOT_PROVIDED"}},"companyNotActive":{"summary":"Empresa da sessão excluída ou inativa durante a gravação","value":{"status":"error","message":"You are not authorized to access this company.","category":"CLIENT.DELETE.NOT_AUTHORIZED"}}}}}},"403":{"description":"Erro de autorização. O usuário não tem permissão de Administrador.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"adminProfileRequired":{"summary":"Perfil de admin necessário","value":{"statusCode":403,"message":"Only admin users can access this resource.","category":"ONLY_ADMIN_USERS"}}}}}},"404":{"description":"Cliente não encontrado, já excluído, de outro licenciado (antes 403 `CLIENT.DELETE.NOT_AUTHORIZED`) ou de outra empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"clientNotFound":{"summary":"Cliente não encontrado","value":{"statusCode":404,"message":"Client not found.","category":"CLIENT.DELETE.CLIENT_NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno ao tentar excluir o cliente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"deleteFailed":{"summary":"Falha na exclusão","value":{"statusCode":500,"message":"Failed to delete client.","category":"CLIENT.DELETE.DELETE_FAILED"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/supplier":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"suppliers:read","tags":["Supplier"],"summary":"Listar fornecedores","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"cpfCnpj","schema":{"type":"string"}},{"in":"query","name":"name","schema":{"type":"string"}},{"in":"query","name":"tradeName","schema":{"type":"string"}},{"in":"query","name":"email","schema":{"type":"string","format":"email"}},{"in":"query","name":"status","schema":{"type":"integer","enum":[0,1]}},{"in":"query","name":"marketSegment","schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}},{"in":"query","name":"page","schema":{"type":"integer","minimum":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Fornecedores paginados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierListResponse"},"examples":{"default":{"value":{"items":[{"_id":"66e1c7f0f2f0b2a6c7a8d992","name":"Fornecedor Exemplo LTDA","cpfCnpj":"12345678000195","status":1,"marketSegment":{"_id":"66e1c7f0f2f0b2a6c7a8d993","name":"Tecnologia"}}],"total":1}}}}}},"400":{"$ref":"#/components/responses/SupplierValidationError"},"401":{"$ref":"#/components/responses/SupplierUnauthorizedError"},"403":{"$ref":"#/components/responses/SupplierForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"suppliers:write","tags":["Supplier"],"summary":"Criar fornecedor","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierInput"},"examples":{"default":{"value":{"name":"Fornecedor Exemplo LTDA","tradeName":"Fornecedor Exemplo","cpfCnpj":"12345678000195","address":"Rua das Flores","streetTypeEnum":"Rua","number":"100","neighborhood":"Centro","postalCode":"01001000","city":"São Paulo","state":"SP","emails":["contato@fornecedor.com"],"marketSegment":"66e1c7f0f2f0b2a6c7a8d993"}}}}}},"responses":{"201":{"description":"Fornecedor criado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierMutationResponse"},"examples":{"created":{"value":{"success":true,"message":"Supplier created successfully!","data":{"_id":"66e1c7f0f2f0b2a6c7a8d992","name":"Fornecedor Exemplo LTDA","cpfCnpj":"12345678000195","status":1,"marketSegment":"66e1c7f0f2f0b2a6c7a8d993"}}}}}}},"400":{"$ref":"#/components/responses/SupplierCreateError"},"401":{"$ref":"#/components/responses/SupplierUnauthorizedError"},"403":{"$ref":"#/components/responses/SupplierForbiddenError"},"404":{"$ref":"#/components/responses/SupplierMarketSegmentNotFoundError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/supplier/{supplierId}":{"parameters":[{"in":"path","name":"supplierId","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}],"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"suppliers:read","tags":["Supplier"],"summary":"Buscar fornecedor","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"responses":{"200":{"description":"Fornecedor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierReadResponse"},"examples":{"default":{"value":{"success":true,"message":"Supplier retrieved successfully!","data":{"_id":"66e1c7f0f2f0b2a6c7a8d992","name":"Fornecedor Exemplo LTDA","cpfCnpj":"12345678000195","status":1,"marketSegment":{"_id":"66e1c7f0f2f0b2a6c7a8d993","name":"Tecnologia"}}}}}}}},"400":{"$ref":"#/components/responses/SupplierValidationError"},"401":{"$ref":"#/components/responses/SupplierUnauthorizedError"},"403":{"$ref":"#/components/responses/SupplierForbiddenError"},"404":{"$ref":"#/components/responses/SupplierGetNotFoundError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"suppliers:write","tags":["Supplier"],"summary":"Atualizar fornecedor","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierUpdate"},"examples":{"updateName":{"value":{"name":"Fornecedor Exemplo Atualizado"}}}}}},"responses":{"200":{"description":"Fornecedor atualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierMutationResponse"},"examples":{"updated":{"value":{"success":true,"message":"Supplier updated successfully!","data":{"_id":"66e1c7f0f2f0b2a6c7a8d992","name":"Fornecedor Exemplo Atualizado","cpfCnpj":"12345678000195","status":1,"marketSegment":"66e1c7f0f2f0b2a6c7a8d993"}}}}}}},"400":{"$ref":"#/components/responses/SupplierUpdateError"},"401":{"$ref":"#/components/responses/SupplierUnauthorizedError"},"403":{"$ref":"#/components/responses/SupplierForbiddenError"},"404":{"$ref":"#/components/responses/SupplierUpdateNotFoundError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"suppliers:write","tags":["Supplier"],"summary":"Excluir fornecedor logicamente","description":"Marca o fornecedor como excluído; o registro histórico é preservado e deixa de aparecer nas consultas normais.","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"responses":{"200":{"description":"Fornecedor excluído.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierDeleteResponse"},"examples":{"deleted":{"value":{"success":true,"message":"Supplier deleted successfully!"}}}}}},"400":{"$ref":"#/components/responses/SupplierDeleteBlockedError"},"401":{"$ref":"#/components/responses/SupplierUnauthorizedError"},"403":{"$ref":"#/components/responses/SupplierForbiddenError"},"404":{"$ref":"#/components/responses/SupplierDeleteNotFoundError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"services:read","tags":["Service"],"summary":"Listar serviços de uma empresa","description":"Retorna uma lista paginada dos serviços não excluídos da empresa selecionada no token,\nordenada pelo texto do item da Lista de Serviços (`serviceItem.text`) e depois por `_id`.\nDisponível para qualquer perfil da empresa (não exige perfil de Administrador).\n","operationId":"listServices","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Número da página para a paginação. Precisa ser inteiro: um valor decimal (por exemplo\n`1.5`) responde 400.\n"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"default":10},"description":"Quantidade de itens por página. Precisa ser inteiro: um valor decimal responde 400.\n"},{"in":"query","name":"status","schema":{"$ref":"#/components/schemas/ServiceStatus"},"description":"Filtra os serviços pelo status (0 = inativo, 1 = ativo). Sem o filtro, retorna os\nserviços de qualquer status, inclusive os registros mais antigos gravados com\n`status: null`. Outro valor responde 400.\n"}],"responses":{"200":{"description":"Lista de serviços retornada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedServiceResponse"},"examples":{"default":{"value":{"success":true,"message":"Services retrieved successfully!","data":{"items":[{"_id":"66e1c7f0f2f0b2a6c7a8d999","licensedId":"66dfb4a6b1bbd81234abcd01","companyId":"66dfb4a6b1bbd81234abcd02","__v":0,"createdAt":"2026-11-20T13:46:53.000Z","updatedAt":"2026-11-20T13:46:53.000Z","serviceItem":{"oldCode":"1.07","code":"010701","text":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados."},"nbsItem":{"code":"115013000","text":"Serviços de suporte em tecnologia da informação (TI)"},"ibscbs":{"operationCode":"050101","cst":"000","cct":"000001","personalOperation":false},"serviceMunicipalCode":"620910001","nationalMunicipalTaxCode":"501","discrimination":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados.","issTaxationType":6,"issEnforceability":1,"status":1,"retainISS":false,"retainIRRF":false,"retainINSS":false,"retainCSRF":false,"aliquotISS":2.17}],"total":1}}}}}}},"400":{"description":"Parâmetro de consulta inválido ou empresa não selecionada no token.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceCatalogValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"}]},"examples":{"invalidPage":{"value":{"error":"VALIDATION_FAILED","details":[{"field":"page","message":"page deve ser um número maior que 0"}]}},"decimalLimit":{"summary":"Paginação com número decimal","value":{"error":"VALIDATION_FAILED","details":[{"field":"limit","message":"limit deve ser um número inteiro"}]}},"invalidStatus":{"summary":"Status fora de 0 e 1","value":{"error":"VALIDATION_FAILED","details":[{"field":"status","message":"Invalid enum value. Expected 1 | 0, received '3'"}]}},"companyNotSelected":{"$ref":"#/components/examples/ServiceCatalogCompanyNotSelected"}}}}},"401":{"description":"Token ausente, inválido ou expirado, ou empresa do token fora do licenciado\n(`SERVICE.LIST.NOT_AUTHORIZED`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"tokenNotProvided":{"$ref":"#/components/examples/ServiceCatalogTokenNotProvided"},"invalidOrExpiredToken":{"$ref":"#/components/examples/ServiceCatalogInvalidOrExpiredToken"},"listNotAuthorized":{"value":{"status":"error","message":"You are not authorized to access this company.","category":"SERVICE.LIST.NOT_AUTHORIZED"}}}}}},"403":{"$ref":"#/components/responses/ServiceCatalogCommercialForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"services:write","tags":["Service"],"summary":"Criar um novo serviço","description":"Cria um novo serviço vinculado à empresa selecionada no token. Sem `status`, o serviço é\ncriado ativo (`status: 1`). Campos fora do contrato (por exemplo `minValueISS`)\nsão descartados sem erro. O item da Lista de Serviços (`serviceItem.code`) não pode repetir\no de outro serviço não excluído da empresa.\n**Requer perfil de Administrador.**\n","operationId":"createService","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServiceRequest"},"examples":{"default":{"summary":"Serviço de suporte técnico em informática","value":{"serviceItem":{"oldCode":"1.07","code":"010701","text":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados."},"nbsItem":{"code":"115013000","text":"Serviços de suporte em tecnologia da informação (TI)"},"discrimination":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados.","serviceMunicipalCode":"620910001","nationalMunicipalTaxCode":"501","ibscbs":{"operationCode":"050101","cst":"000","cct":"000001","personalOperation":false},"retainISS":false,"retainIRRF":false,"retainINSS":false,"retainCSRF":false,"aliquotISS":2.17,"issTaxationType":6,"issEnforceability":1,"status":1}}}}}},"responses":{"201":{"description":"Serviço criado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleServiceResponse"},"examples":{"created":{"value":{"success":true,"message":"Service created successfully!","data":{"_id":"66e1c7f0f2f0b2a6c7a8d999","licensedId":"66dfb4a6b1bbd81234abcd01","companyId":"66dfb4a6b1bbd81234abcd02","__v":0,"createdAt":"2026-11-20T13:46:53.000Z","updatedAt":"2026-11-20T13:46:53.000Z","serviceItem":{"oldCode":"1.07","code":"010701","text":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados."},"nbsItem":{"code":"115013000","text":"Serviços de suporte em tecnologia da informação (TI)"},"ibscbs":{"operationCode":"050101","cst":"000","cct":"000001","personalOperation":false},"serviceMunicipalCode":"620910001","nationalMunicipalTaxCode":"501","discrimination":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados.","issTaxationType":6,"issEnforceability":1,"status":1,"retainISS":false,"retainIRRF":false,"retainINSS":false,"retainCSRF":false,"aliquotISS":2.17}}}}}}},"400":{"description":"Erro de validação, empresa não selecionada no token ou item da Lista de Serviços já usado\npor outro serviço não excluído da empresa (`SERVICE.CREATE.CODE_IN_USE`, mensagem em pt-BR).\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceCatalogValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"}]},"examples":{"validationFailed":{"value":{"error":"VALIDATION_FAILED","details":[{"field":"nationalMunicipalTaxCode","message":"Código municipal nacional deve ter três dígitos"}]}},"decimalIssTaxationType":{"summary":"Tipo de tributação do ISS decimal","value":{"error":"VALIDATION_FAILED","details":[{"field":"issTaxationType","message":"Tipo de tributação deve ser um número inteiro"}]}},"codeInUse":{"summary":"Item da Lista de Serviços já usado por outro serviço","value":{"status":"error","message":"Já existe um serviço cadastrado com este item da Lista de Serviços para esta empresa.","category":"SERVICE.CREATE.CODE_IN_USE"}},"companyNotSelected":{"$ref":"#/components/examples/ServiceCatalogCompanyNotSelected"}}}}},"401":{"description":"Token ausente, inválido ou expirado, ou empresa da sessão excluída ou fora do licenciado\nno momento da gravação (`SERVICE.CREATE.NOT_AUTHORIZED`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"tokenNotProvided":{"$ref":"#/components/examples/ServiceCatalogTokenNotProvided"},"invalidOrExpiredToken":{"$ref":"#/components/examples/ServiceCatalogInvalidOrExpiredToken"},"companyNotActive":{"value":{"status":"error","message":"You are not authorized to access this company.","category":"SERVICE.CREATE.NOT_AUTHORIZED"}}}}}},"403":{"$ref":"#/components/responses/ServiceCatalogAdminForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service/{serviceId}":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"services:read","tags":["Service"],"summary":"Obter um serviço por ID","description":"Retorna os detalhes de um serviço específico pelo seu ID.\nO serviço deve pertencer ao licenciado e à empresa selecionada no token; caso contrário,\nretorna 404 `SERVICE.GET.NOT_FOUND`, inclusive para serviço de outra empresa do mesmo\nlicenciado.\nDisponível para qualquer perfil da empresa (não exige perfil de Administrador).\n","operationId":"getServiceById","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"serviceId","required":true,"schema":{"type":"string","minLength":24,"maxLength":24},"description":"ID do serviço a ser retornado (24 caracteres; outro tamanho responde 400)."}],"responses":{"200":{"description":"Serviço retornado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleServiceResponse"},"examples":{"default":{"value":{"success":true,"message":"Service retrieved successfully!","data":{"_id":"66e1c7f0f2f0b2a6c7a8d999","licensedId":"66dfb4a6b1bbd81234abcd01","companyId":"66dfb4a6b1bbd81234abcd02","__v":0,"createdAt":"2026-11-20T13:46:53.000Z","updatedAt":"2026-11-20T13:46:53.000Z","serviceItem":{"oldCode":"1.07","code":"010701","text":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados."},"nbsItem":{"code":"115013000","text":"Serviços de suporte em tecnologia da informação (TI)"},"ibscbs":{"operationCode":"050101","cst":"000","cct":"000001","personalOperation":false},"serviceMunicipalCode":"620910001","nationalMunicipalTaxCode":"501","discrimination":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados.","issTaxationType":6,"issEnforceability":1,"status":1,"retainISS":false,"retainIRRF":false,"retainINSS":false,"retainCSRF":false,"aliquotISS":2.17}}}}}}},"400":{"description":"ID com tamanho diferente de 24 caracteres ou empresa não selecionada no token.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceCatalogValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"}]},"examples":{"invalidId":{"value":{"error":"VALIDATION_FAILED","details":[{"field":"serviceId","message":"ID inválido"}]}},"companyNotSelected":{"$ref":"#/components/examples/ServiceCatalogCompanyNotSelected"}}}}},"401":{"$ref":"#/components/responses/ServiceCatalogUnauthorizedError"},"403":{"$ref":"#/components/responses/ServiceCatalogCommercialForbiddenError"},"404":{"description":"Serviço não encontrado, excluído, de outra empresa ou de outro licenciado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"serviceNotFound":{"summary":"Serviço não encontrado","value":{"status":"error","message":"Service not found.","category":"SERVICE.GET.NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"services:write","tags":["Service"],"summary":"Atualizar um serviço existente","description":"Atualiza as informações de um serviço específico. Apenas os campos enviados são\natualizados; um objeto aninhado (`serviceItem`, `nbsItem`, `ibscbs`) enviado precisa vir\ncompleto. `status` ativa (1) ou inativa (0) o serviço. Campos fora do contrato são\ndescartados sem erro. Um `serviceItem.code` diferente do atual não pode repetir o de outro\nserviço não excluído da empresa (400 `SERVICE.UPDATE.CODE_IN_USE`, mesma regra e mensagem\nda criação).\nReenviar o próprio código do serviço não é tratado como repetição.\nO serviço deve pertencer ao licenciado e à empresa selecionada no token; caso contrário,\nretorna 404, inclusive para serviço de outra empresa do mesmo licenciado.\nSe a empresa da sessão tiver sido excluída ou deixado de pertencer ao licenciado,\na gravação retorna 401 `SERVICE.UPDATE.NOT_AUTHORIZED`.\n**Requer perfil de Administrador.**\n","operationId":"updateService","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"serviceId","required":true,"schema":{"type":"string"},"description":"ID do serviço a ser atualizado (24 caracteres; um ID inexistente responde 404)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServiceRequest"},"examples":{"default":{"summary":"Atualização parcial de um serviço","value":{"discrimination":"Suporte técnico remoto em informática.","retainISS":true,"aliquotISS":3}},"inactivate":{"summary":"Inativar o serviço","value":{"status":0}}}}}},"responses":{"200":{"description":"Serviço atualizado com sucesso; retorna o serviço como gravado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleServiceResponse"},"examples":{"updated":{"value":{"success":true,"message":"Service updated successfully!","data":{"_id":"66e1c7f0f2f0b2a6c7a8d999","licensedId":"66dfb4a6b1bbd81234abcd01","companyId":"66dfb4a6b1bbd81234abcd02","__v":1,"createdAt":"2026-11-20T13:46:53.000Z","updatedAt":"2026-11-21T10:00:00.000Z","serviceItem":{"oldCode":"1.07","code":"010701","text":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados."},"nbsItem":{"code":"115013000","text":"Serviços de suporte em tecnologia da informação (TI)"},"ibscbs":{"operationCode":"050101","cst":"000","cct":"000001","personalOperation":false},"serviceMunicipalCode":"620910001","nationalMunicipalTaxCode":"501","discrimination":"Suporte técnico remoto em informática.","issTaxationType":6,"issEnforceability":1,"status":1,"retainISS":true,"retainIRRF":false,"retainINSS":false,"retainCSRF":false,"aliquotISS":3}}}}}}},"400":{"description":"Erro de validação, empresa não selecionada no token ou item da Lista de Serviços já usado\npor outro serviço não excluído da empresa (`SERVICE.UPDATE.CODE_IN_USE`).\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceCatalogValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"}]},"examples":{"validationFailed":{"value":{"error":"VALIDATION_FAILED","details":[{"field":"nationalMunicipalTaxCode","message":"Código municipal nacional deve ter três dígitos"}]}},"decimalIssEnforceability":{"summary":"Exigibilidade do ISS decimal","value":{"error":"VALIDATION_FAILED","details":[{"field":"issEnforceability","message":"Exigibilidade deve ser um número inteiro"}]}},"codeInUse":{"summary":"Item da Lista de Serviços já usado por outro serviço","value":{"status":"error","message":"Já existe um serviço cadastrado com este item da Lista de Serviços para esta empresa.","category":"SERVICE.UPDATE.CODE_IN_USE"}},"companyNotSelected":{"$ref":"#/components/examples/ServiceCatalogCompanyNotSelected"}}}}},"401":{"description":"Token ausente, inválido ou expirado, ou empresa da sessão excluída ou fora do licenciado\nno momento da gravação (`SERVICE.UPDATE.NOT_AUTHORIZED`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"tokenNotProvided":{"$ref":"#/components/examples/ServiceCatalogTokenNotProvided"},"invalidOrExpiredToken":{"$ref":"#/components/examples/ServiceCatalogInvalidOrExpiredToken"},"companyNotActive":{"value":{"status":"error","message":"You are not authorized to access this company.","category":"SERVICE.UPDATE.NOT_AUTHORIZED"}}}}}},"403":{"$ref":"#/components/responses/ServiceCatalogAdminForbiddenError"},"404":{"description":"Serviço não encontrado, excluído, de outra empresa ou de outro licenciado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"serviceNotFound":{"summary":"Serviço não encontrado","value":{"status":"error","message":"Service not found.","category":"SERVICE.UPDATE.NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"services:write","tags":["Service"],"summary":"Excluir um serviço","description":"Marca o serviço como excluído e o oculta das listagens e seletores. A exclusão é bloqueada (400) quando houver contrato, NFS-e, conta a receber ou vencimento ativo vinculado; registros já excluídos logicamente não bloqueiam (uma NFS-e cancelada continua bloqueando). A API não oferece restauração.\nO serviço deve pertencer ao licenciado e à empresa selecionada no token; caso contrário,\nretorna 404, inclusive para serviço de outra empresa do mesmo licenciado.\nSe a empresa da sessão tiver sido excluída ou deixado de pertencer ao licenciado,\na gravação retorna 401 `SERVICE.DELETE.NOT_AUTHORIZED`.\n**Requer perfil de Administrador.**\n","operationId":"deleteService","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"serviceId","required":true,"schema":{"type":"string"},"description":"ID do serviço a ser excluído (24 caracteres; um ID inexistente responde 404)."}],"responses":{"200":{"description":"Serviço excluído com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceDeleteResponse"},"examples":{"deleted":{"value":{"success":true,"message":"Service deleted successfully!"}}}}}},"400":{"description":"Serviço com contrato, NFS-e, conta a receber ou vencimento vinculado, ou empresa não selecionada no token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"hasContracts":{"value":{"status":"error","message":"Cannot delete service with associated contracts.","category":"SERVICE.DELETE.HAS_CONTRACTS"}},"hasInvoices":{"value":{"status":"error","message":"Cannot delete service with associated invoices.","category":"SERVICE.DELETE.HAS_INVOICES"}},"hasAccountsReceivable":{"value":{"status":"error","message":"Cannot delete service with associated accounts receivable.","category":"SERVICE.DELETE.HAS_ACCOUNTS_RECEIVABLE"}},"companyNotSelected":{"$ref":"#/components/examples/ServiceCatalogCompanyNotSelected"}}}}},"401":{"description":"Token ausente, inválido ou expirado, ou empresa da sessão excluída ou fora do licenciado\nno momento da gravação (`SERVICE.DELETE.NOT_AUTHORIZED`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"tokenNotProvided":{"$ref":"#/components/examples/ServiceCatalogTokenNotProvided"},"invalidOrExpiredToken":{"$ref":"#/components/examples/ServiceCatalogInvalidOrExpiredToken"},"companyNotActive":{"value":{"status":"error","message":"You are not authorized to access this company.","category":"SERVICE.DELETE.NOT_AUTHORIZED"}}}}}},"403":{"$ref":"#/components/responses/ServiceCatalogAdminForbiddenError"},"404":{"description":"Serviço não encontrado, excluído, de outra empresa ou de outro licenciado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"serviceNotFound":{"summary":"Serviço não encontrado","value":{"status":"error","message":"Service not found.","category":"SERVICE.DELETE.NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/contract":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"contracts:read","summary":"Lista os contratos","description":"Retorna uma lista paginada de contratos do usuário autenticado, com filtros opcionais.","tags":["Contract"],"security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"name":"limit","in":"query","description":"Número máximo de itens por página (1-100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"page","in":"query","description":"Número da página para paginação (mínimo 1)","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"status","in":"query","description":"Filtra contratos pelo status (valores conforme enum StatusEnum)","required":false,"schema":{"type":"integer","enum":[0,1,2]}},{"name":"isRecurring","in":"query","description":"Filtra contratos recorrentes ou não recorrentes.","required":false,"schema":{"type":"boolean"}},{"name":"issueBankSlipOnBilling","in":"query","description":"Filtra contratos pela emissão automática de boleto.","required":false,"schema":{"type":"boolean"}},{"name":"issueServiceInvoiceOnBilling","in":"query","description":"Filtra contratos pela emissão automática de NFS-e.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Lista paginada de contratos retornada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Contracts listed successfully!"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Contract"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"400":{"description":"Falha na validação dos parâmetros da query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Não autorizado - token ausente ou inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"UNAUTHORIZED"}}}}}},"403":{"description":"Proibido - acesso negado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"FORBIDDEN"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno no servidor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"INTERNAL_SERVER_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"contracts:write","summary":"Cria um novo contrato (recorrente ou não recorrente)","description":"Criação de contrato com distinção clara entre contrato recorrente e não recorrente pelo campo 'isRecurring'. O campo `status` é somente leitura e contratos sem nenhuma cobrança futura válida são rejeitados. Quando os indicadores de emissão automática de boleto ou NFS-e forem `true`, a empresa deve ter ativado e salvo a configuração correspondente.","tags":["Contract"],"security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RecurringContract"},{"$ref":"#/components/schemas/NonRecurringContract"}]},"examples":{"Recorrente":{"summary":"Exemplo de contrato recorrente","value":{"clientId":"68e83117a308dee84a796295","serviceId":"68e831349665e61dfa4d8df2","contractDate":"2025-10-01","value":750,"isRecurring":true,"billingStart":"2025-10-01","billingEnd":null,"dueDay":15,"issueBankSlipOnBilling":false,"issueServiceInvoiceOnBilling":false,"sendBankSlipEmailToIssuerOnBilling":false,"sendBankSlipEmailToCustomerOnBilling":false,"sendServiceInvoiceEmailToIssuerOnBilling":false,"sendServiceInvoiceEmailToCustomerOnBilling":false,"bankSlipConfig":{"discount":{"type":"NONE"},"interest":{"type":"NONE"},"fine":{"type":"NONE"}},"serviceInvoiceConfig":{"defaultDiscrimination":"Referente à prestação de serviços de contabilidade."}}},"NãoRecorrente":{"summary":"Exemplo de contrato não recorrente","value":{"clientId":"68dc5bf75836d8aec28c971d","serviceId":"68dc5c21c25d2cf76c7258a1","contractDate":"2025-10-01","value":750,"isRecurring":false,"billingStart":"2025-10-01","dueDay":15,"installmentsCount":3,"installments":[{"amount":250,"dueDate":"2025-10-15"},{"amount":250,"dueDate":"2025-11-15"},{"amount":250,"dueDate":"2025-12-15"}],"issueBankSlipOnBilling":false,"issueServiceInvoiceOnBilling":false,"sendBankSlipEmailToIssuerOnBilling":false,"sendBankSlipEmailToCustomerOnBilling":false,"sendServiceInvoiceEmailToIssuerOnBilling":false,"sendServiceInvoiceEmailToCustomerOnBilling":false,"bankSlipConfig":{"discount":{"type":"FIXED","daysBeforeDueDate":5,"amountOrPercent":10},"interest":{"type":"MONTHLY_PERCENT","amountOrPercent":2},"fine":{"type":"PERCENT","amountOrPercent":2}},"serviceInvoiceConfig":{"defaultDiscrimination":"Serviços de desenvolvimento web."}}}}}}},"responses":{"201":{"description":"Contrato criado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Contract created successfully!"},"data":{"$ref":"#/components/schemas/Contract"}}}}}},"400":{"description":"Erro de validação ou indisponibilidade de emissão automática na criação do contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"BankSlipNotEnabled":{"summary":"Boleto não está ativado ou configurado para a empresa","value":{"category":"CONTRACT.CREATE.BANK_SLIP_NOT_ENABLED","status":"error","message":"Não é possível usar essa opção pois a empresa não ativou ainda o uso de boletos. Para configurar, acesse o cadastro \"Minhas Empresas\" em \"Configurações\" e em seguida clique na ação \"Ativar boleto\"."}},"ServiceInvoiceNotEnabled":{"summary":"NFS-e não está ativada ou configurada para a empresa","value":{"category":"CONTRACT.CREATE.SERVICE_INVOICE_NOT_ENABLED","status":"error","message":"Não é possível usar essa opção pois a empresa não ativou ainda o uso de notas fiscais de serviço. Para configurar, acesse o cadastro \"Minhas Empresas\" nas \"Configurações\" e em seguida clique na ação \"Ativar NFS-e\"."}}}}}},"401":{"description":"Não autorizado - token ausente ou inválido, ou a empresa da sessão foi excluída ou\ndeixou de pertencer ao licenciado no momento da gravação (`CONTRACT.CREATE.NOT_AUTHORIZED`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"CompanyNotActive":{"summary":"Empresa da sessão não está mais ativa","value":{"category":"CONTRACT.CREATE.NOT_AUTHORIZED","status":"error","message":"You are not authorized to access this company."}}}}}},"403":{"description":"Proibido - acesso negado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"FORBIDDEN"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno no servidor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"INTERNAL_SERVER_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/contract/billing-processings":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"contracts:read","summary":"Lista os processamentos de faturamento","description":"Retorna processamentos do dia escolhido, restritos à empresa da sessão, sem dados brutos de provedores. Processamentos vinculados a Contas a Receber excluídas não são retornados.","tags":["Contract"],"security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"name":"date","in":"query","required":false,"description":"Dia do processamento no horário de Brasília. O padrão é o dia atual.","schema":{"type":"string","format":"date","pattern":"^\\\\d{4}-\\\\d{2}-\\\\d{2}$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["PENDING","SUCCESS","ERROR"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Processamentos paginados retornados com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","required":["items","summary","page","limit","total","totalPages"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BillingProcessing"}},"summary":{"type":"object","required":["pending","success","error","total"],"properties":{"pending":{"type":"integer"},"success":{"type":"integer"},"error":{"type":"integer"},"total":{"type":"integer"}}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"400":{"description":"Falha na validação estrita dos parâmetros de consulta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Não autorizado - token ausente ou inválido"},"403":{"description":"Proibido - acesso comercial negado"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno no servidor"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/contract/billing-processings/retry":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"contracts:write","summary":"Reprocessa faturamentos com erro","description":"Processamentos com erro vinculados a uma Conta a Receber excluída são ignorados e não são reprocessados.","tags":["Contract"],"security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["processingIds"],"additionalProperties":false,"properties":{"processingIds":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}}}}}},"responses":{"200":{"description":"Reprocessamentos aceitos ou ignorados com segurança","content":{"application/json":{"schema":{"type":"object","required":["success","message","data"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","required":["accepted","skipped"],"additionalProperties":false,"properties":{"accepted":{"type":"array","description":"IDs dos processamentos cujo retry foi aceito.","items":{"type":"string"}},"skipped":{"type":"array","description":"Processamentos ignorados com o motivo seguro correspondente.","items":{"type":"object","required":["id","reason"],"additionalProperties":false,"properties":{"id":{"type":"string"},"reason":{"type":"string","enum":["NOT_FOUND","NOT_ELIGIBLE"]}}}}}}}},"examples":{"accepted":{"value":{"success":true,"message":"Billing processings retry requested successfully!","data":{"accepted":["66e1c7f0f2f0b2a6c7a8d992"],"skipped":[]}}},"notEligible":{"value":{"success":true,"message":"Billing processings retry requested successfully!","data":{"accepted":[],"skipped":[{"id":"66e1c7f0f2f0b2a6c7a8d993","reason":"NOT_ELIGIBLE"}]}}}}}}},"400":{"description":"Corpo inválido"},"401":{"description":"Não autorizado"},"403":{"description":"Acesso comercial negado"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/contract/{contractId}":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"contracts:read","summary":"Obtém os detalhes de um contrato específico","description":"Retorna os detalhes completos do contrato identificado por contractId para o usuário autenticado.","tags":["Contract"],"security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"name":"contractId","in":"path","description":"ID do contrato (24 caracteres hexadecimais)","required":true,"schema":{"type":"string","pattern":"^[a-f\\d]{24}$"}}],"responses":{"200":{"description":"Contrato retornado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Contract retrieved successfully!"},"data":{"$ref":"#/components/schemas/Contract"}}}}}},"400":{"description":"Falha na validação do parâmetro contractId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Não autorizado - token ausente ou inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"UNAUTHORIZED"}}}}}},"403":{"description":"Proibido - acesso negado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"FORBIDDEN"}}}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Contract not found."}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno no servidor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"INTERNAL_SERVER_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"contracts:write","summary":"Atualiza um contrato existente","description":"Atualiza os campos editáveis de um contrato existente pelo ID, permitindo atualização parcial. O campo `status` é somente leitura e não pode ser alterado manualmente. Quando os indicadores de emissão automática de boleto ou NFS-e forem `true`, a empresa deve ter ativado e salvo a configuração correspondente.","tags":["Contract"],"security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"name":"contractId","in":"path","description":"ID do contrato (24 caracteres hexadecimais)","required":true,"schema":{"type":"string","pattern":"^[a-f\\d]{24}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContract"},"example":{"dueDay":20,"value":780,"issueServiceInvoiceOnBilling":false,"sendBankSlipEmailToIssuerOnBilling":true,"sendBankSlipEmailToCustomerOnBilling":false,"sendServiceInvoiceEmailToIssuerOnBilling":true,"sendServiceInvoiceEmailToCustomerOnBilling":false,"bankSlipConfig":{"discount":{"type":"PERCENT","daysBeforeDueDate":3,"amountOrPercent":4},"fine":{"type":"FIXED","amountOrPercent":8},"interest":{"type":"DAILY_VALUE","amountOrPercent":0.5}},"serviceInvoiceConfig":{"defaultDiscrimination":"Serviços de contabilidade – manutenção mensal."}}}}},"responses":{"200":{"description":"Contrato atualizado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Contract updated successfully!"},"data":{"$ref":"#/components/schemas/Contract"}}}}}},"400":{"description":"Erro de validação ou indisponibilidade de emissão automática na atualização do contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"BankSlipNotEnabled":{"summary":"Boleto não está ativado ou configurado para a empresa","value":{"category":"CONTRACT.UPDATE.BANK_SLIP_NOT_ENABLED","status":"error","message":"Não é possível usar essa opção pois a empresa não ativou ainda o uso de boletos. Para configurar, acesse o cadastro \"Minhas Empresas\" em \"Configurações\" e em seguida clique na ação \"Ativar boleto\"."}},"ServiceInvoiceNotEnabled":{"summary":"NFS-e não está ativada ou configurada para a empresa","value":{"category":"CONTRACT.UPDATE.SERVICE_INVOICE_NOT_ENABLED","status":"error","message":"Não é possível usar essa opção pois a empresa não ativou ainda o uso de notas fiscais de serviço. Para configurar, acesse o cadastro \"Minhas Empresas\" nas \"Configurações\" e em seguida clique na ação \"Ativar NFS-e\"."}},"InstallmentsCountMismatch":{"summary":"installmentsCount diverge das parcelas existentes ou enviadas","description":"Em contratos não recorrentes, também ocorre quando apenas `installmentsCount` é enviado e não corresponde às parcelas armazenadas.","value":{"category":"CONTRACT.UPDATE.INSTALLMENTS_COUNT_MISMATCH","status":"error","message":"installmentsCount (3) does not match installments length (2)"}}}}}},"401":{"description":"Não autorizado - token ausente ou inválido, ou a empresa da sessão foi excluída ou\ndeixou de pertencer ao licenciado no momento da gravação (`CONTRACT.UPDATE.NOT_AUTHORIZED`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"CompanyNotActive":{"summary":"Empresa da sessão não está mais ativa","value":{"category":"CONTRACT.UPDATE.NOT_AUTHORIZED","status":"error","message":"You are not authorized to access this company."}}}}}},"403":{"description":"Proibido - acesso negado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"FORBIDDEN"}}}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Contract not found."}}}}}},"409":{"description":"Conflito com o estado atual do contrato: cobranças ou documentos já vinculados às parcelas\nou ao modo recorrente/não recorrente alterados, redução do número de parcelas (não permitida; exclua e recrie o contrato) ou\nalteração concorrente por outra requisição (recarregue o contrato e tente novamente).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"BilledInstallmentImmutable":{"value":{"category":"CONTRACT.UPDATE.BILLED_INSTALLMENT_IMMUTABLE","status":"error","message":"Contract installments cannot be changed after billing documents exist."}},"BilledModeImmutable":{"value":{"category":"CONTRACT.UPDATE.BILLED_MODE_IMMUTABLE","status":"error","message":"Contract billing mode cannot be changed after billing documents exist."}},"InstallmentReductionNotAllowed":{"value":{"category":"CONTRACT.UPDATE.INSTALLMENT_REDUCTION_NOT_ALLOWED","status":"error","message":"Não é possível reduzir o número de parcelas de um contrato; exclua e recrie o contrato."}},"ConcurrentModification":{"value":{"category":"CONTRACT.UPDATE.CONFLICT","status":"error","message":"Contract was changed by another request."}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno no servidor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"INTERNAL_SERVER_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"contracts:write","summary":"Exclui um contrato existente","description":"Exclui um contrato pelo ID, se pertencer ao usuário autenticado e à empresa. Contas a receber e notas fiscais ainda ativas vinculadas ao contrato impedem a exclusão; contas a receber excluídas logicamente não são consideradas vínculos ativos.","tags":["Contract"],"security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"name":"contractId","in":"path","description":"ID do contrato (24 caracteres hexadecimais)","required":true,"schema":{"type":"string","pattern":"^[a-f\\d]{24}$"}}],"responses":{"200":{"description":"Contrato excluído com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Contract deleted successfully!"},"data":{"$ref":"#/components/schemas/Contract"}}}}}},"400":{"description":"Falha na validação do parâmetro contractId ou o contrato possui contas a receber ou notas fiscais ativas vinculadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Não autorizado - token ausente ou inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"UNAUTHORIZED"}}}}}},"403":{"description":"Proibido - acesso negado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"FORBIDDEN"}}}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Contract not found."}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"500":{"description":"Erro interno no servidor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"INTERNAL_SERVER_ERROR"}}}}}},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/market-segment":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"market_segments:read","tags":["Market Segment"],"summary":"Listar todos os segmentos de mercado da empresa","description":"Retorna uma lista hierárquica de segmentos de mercado não excluídos associados à `companyId` do usuário autenticado. A lista é estruturada com segmentos principais e seus respectivos subsegmentos aninhados.\n**Requer perfil de Administrador.**\n","operationId":"listMarketSegments","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"responses":{"200":{"description":"Lista de segmentos retornada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMarketSegmentResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"market_segments:write","tags":["Market Segment"],"summary":"Criar um novo segmento de mercado","description":"Cria um novo segmento de mercado vinculado à empresa do usuário autenticado.\n- Para criar um segmento principal, envie `isMain: true` e não envie `parentId`.\n- Para criar um subsegmento, envie `isMain: false` e o `parentId` do segmento principal correspondente.\n**Requer perfil de Administrador.**\n","operationId":"createMarketSegment","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMarketSegmentRequest"},"examples":{"createMainSegment":{"summary":"Exemplo para criar um segmento principal","value":{"name":"Indústria","isMain":true}},"createSubSegment":{"summary":"Exemplo para criar um subsegmento","value":{"name":"Indústria Têxtil","isMain":false,"parentId":"66e1c7f0f2f0b2a6c7a8d999"}}}}}},"responses":{"201":{"description":"Segmento de mercado criado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleMarketSegmentResponse"}}}},"400":{"description":"Erro de validação ou de regra de negócio.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceErrorResponse"}]},"examples":{"mainWithParent":{"summary":"Segmento principal com pai","value":{"statusCode":400,"message":"Main segments cannot have a parent segment.","category":"MARKET_SEGMENT.CREATE.NOT_AUTHORIZED"}},"subWithoutParent":{"summary":"Subsegmento sem pai","value":{"statusCode":400,"message":"Subsegments must have a parent segment.","category":"MARKET_SEGMENT.CREATE.NOT_AUTHORIZED"}},"parentNotMain":{"summary":"Pai informado é um subsegmento","value":{"status":"error","message":"Parent segment must be a main segment.","category":"MARKET_SEGMENT.CREATE.PARENT_NOT_FOUND"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Segmento pai não encontrado (inexistente, excluído, de outra empresa ou de outro licenciado),\nou empresa da sessão excluída/fora do licenciado no momento da gravação\n(`MARKET_SEGMENT.CREATE.NOT_AUTHORIZED` com status 404, mantido por compatibilidade).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"parentNotFound":{"summary":"Segmento pai não existe","value":{"status":"error","message":"Parent segment not found.","category":"MARKET_SEGMENT.CREATE.PARENT_NOT_FOUND"}},"companyNotActive":{"summary":"Empresa da sessão não está mais ativa","value":{"status":"error","message":"Company not found.","category":"MARKET_SEGMENT.CREATE.NOT_AUTHORIZED"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/market-segment/{segmentId}":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"market_segments:read","tags":["Market Segment"],"summary":"Obter um segmento por ID","description":"Retorna os detalhes de um segmento de mercado específico pelo seu ID.\nA consulta é restrita ao licenciado e à empresa selecionada no token; segmentos\nde outra empresa ou de outro licenciado retornam 404.\n**Requer perfil de Administrador.**\n","operationId":"getMarketSegmentById","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"segmentId","required":true,"schema":{"type":"string","minLength":24,"maxLength":24},"description":"ID do segmento a ser retornado (24 caracteres hexadecimais)."}],"responses":{"200":{"description":"Segmento retornado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleMarketSegmentResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Segmento não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"segmentNotFound":{"summary":"Segmento não encontrado","value":{"statusCode":404,"message":"Market segment not found.","category":"MARKET_SEGMENT.GET.NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"market_segments:write","tags":["Market Segment"],"summary":"Atualizar um segmento existente","description":"Atualiza as informações de um segmento de mercado (seja ele principal ou um subsegmento).\n\n**Regras para atualização:**\n- Para manter/transformar em um **segmento principal**: envie `isMain: true` e não envie `parentId`.\n- Para manter/transformar em um **subsegmento**: envie `isMain: false` e o `parentId` de um segmento principal válido. O pai de um subsegmento não pode ser outro subsegmento.\n- Um segmento principal que ainda possui subsegmentos não pode ser transformado em subsegmento (400).\n\nO segmento e o segmento pai devem pertencer ao licenciado e à empresa selecionada no token.\nSegmentos de outro licenciado retornam 404. Se a empresa da sessão tiver sido excluída ou\ndeixado de pertencer ao licenciado, retorna 401 `MARKET_SEGMENT.UPDATE.NOT_AUTHORIZED`.\n\n**Requer perfil de Administrador.**\n","operationId":"updateMarketSegment","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"segmentId","required":true,"schema":{"type":"string","minLength":24,"maxLength":24},"description":"ID do segmento a ser atualizado (24 caracteres hexadecimais)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMarketSegmentRequest"},"examples":{"updateSubSegment":{"summary":"Atualizando um subsegmento","value":{"name":"Indústria Têxtil e Vestuário","isMain":false,"parentId":"66e1c7f0f2f0b2a6c7a8d999"}},"updateMainSegment":{"summary":"Atualizando o nome de um segmento principal","value":{"name":"Indústria de Manufatura","isMain":true}}}}}},"responses":{"200":{"description":"Segmento atualizado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleMarketSegmentResponse"}}}},"400":{"description":"Erro de validação ou de regra de hierarquia.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/ServiceErrorResponse"}]},"examples":{"mainWithParent":{"summary":"Segmento principal com pai","value":{"status":"error","message":"Main segments cannot have a parent segment.","category":"MARKET_SEGMENT.UPDATE.NOT_AUTHORIZED"}},"subWithoutParent":{"summary":"Subsegmento sem pai","value":{"status":"error","message":"Subsegments must have a parent segment.","category":"MARKET_SEGMENT.UPDATE.NOT_AUTHORIZED"}},"segmentHasChildren":{"summary":"Segmento principal com subsegmentos não pode virar subsegmento","value":{"status":"error","message":"Segments with sub-segments must remain main segments.","category":"MARKET_SEGMENT.UPDATE.NOT_AUTHORIZED"}},"parentNotMain":{"summary":"Pai informado é um subsegmento","value":{"status":"error","message":"Parent segment must be a main segment.","category":"MARKET_SEGMENT.UPDATE.PARENT_NOT_FOUND"}},"parentCycle":{"summary":"Pai informado é o próprio segmento","value":{"status":"error","message":"Parent segment not found.","category":"MARKET_SEGMENT.UPDATE.PARENT_NOT_FOUND"}}}}}},"401":{"description":"Erro de autenticação, ou a empresa da sessão foi excluída/deixou de pertencer ao\nlicenciado no momento da gravação (`MARKET_SEGMENT.UPDATE.NOT_AUTHORIZED`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"tokenNotProvided":{"$ref":"#/components/examples/TokenNotProvided"},"companyNotActive":{"summary":"Empresa da sessão não está mais ativa","value":{"status":"error","message":"You are not authorized to access this company.","category":"MARKET_SEGMENT.UPDATE.NOT_AUTHORIZED"}}}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Segmento ou segmento pai não encontrado, excluído, de outra empresa ou de outro licenciado.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"segmentNotFound":{"summary":"Segmento não encontrado","value":{"status":"error","message":"Segment not found.","category":"MARKET_SEGMENT.UPDATE.NOT_FOUND"}},"parentNotFound":{"summary":"Segmento pai não encontrado","value":{"status":"error","message":"Parent segment not found.","category":"MARKET_SEGMENT.UPDATE.PARENT_NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"market_segments:write","tags":["Market Segment"],"summary":"Excluir um segmento ou subsegmento","description":"Marca o segmento de mercado como excluído e o oculta das listagens e seletores.\n\n**Regras para exclusão:**\n- O segmento **não pode** ter subsegmentos não excluídos associados a ele.\n- O segmento **não pode** estar em uso por nenhum cliente não excluído.\n- O segmento **não pode** estar em uso por nenhum fornecedor não excluído.\n\nAs referências históricas de registros excluídos permanecem íntegras porque o segmento também é preservado.\n\nO segmento deve pertencer ao licenciado e à empresa selecionada no token; caso contrário,\nretorna 404. Se a empresa da sessão tiver sido excluída ou deixado\nde pertencer ao licenciado, retorna 401 `MARKET_SEGMENT.DELETE.NOT_AUTHORIZED`.\n\nA API não oferece restauração. Requer perfil de Administrador.\n","operationId":"deleteMarketSegment","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"segmentId","required":true,"schema":{"type":"string","minLength":24,"maxLength":24},"description":"ID do segmento a ser excluído (24 caracteres hexadecimais)."}],"responses":{"200":{"description":"Segmento excluído com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"}}}},"400":{"description":"Erro de regra de negócio, não é possível excluir.","content":{"application/json":{"schema":{"type":"object","required":["status","message","category"],"properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string"},"category":{"type":"string"}}},"examples":{"subsegmentsExist":{"summary":"Segmento possui subsegmentos","value":{"status":"error","message":"Cannot delete segment with associated subsegments.","category":"MARKET_SEGMENT.DELETE.HAS_SUBSEGMENTS"}},"segmentInUse":{"summary":"Segmento em uso por cliente","value":{"status":"error","message":"Cannot delete segment that is in use by clients.","category":"MARKET_SEGMENT.DELETE.IN_USE_BY_CLIENTS"}},"segmentInUseBySupplier":{"summary":"Segmento em uso por fornecedor não excluído","value":{"status":"error","message":"Cannot delete segment that is in use by suppliers.","category":"MARKET_SEGMENT.DELETE.IN_USE_BY_SUPPLIERS"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Segmento não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"segmentNotFound":{"summary":"Segmento não encontrado","value":{"statusCode":404,"message":"Segment not found.","category":"MARKET_SEGMENT.DELETE.NOT_FOUND"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-receivable":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"receivables:write","tags":["AccountReceivable"],"summary":"Criar conta a receber avulsa","description":"Um documento solicitado que não pôde ser emitido aparece em\n`documents.bankSlip` ou `documents.serviceInvoice` com\n`status: error` e `error: { code, message }`, sem desfazer a conta.\n`code` é a categoria do erro da emissão (por exemplo\n`BANK_SLIP.ISSUE_RECONCILIATION_REQUIRED`); um erro sem categoria usa o próprio\ncódigo ou `DOCUMENT_ISSUANCE_FAILED`.\n","operationId":"createManualAccountReceivable","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clientId","serviceId","value","receivableDate"],"properties":{"clientId":{"type":"string"},"serviceId":{"type":"string"},"value":{"type":"number","minimum":0.01},"receivableDate":{"type":"string","format":"date-time"},"observation":{"type":"string"},"issueBankSlip":{"type":"boolean","default":false},"issueServiceInvoice":{"type":"boolean","default":false},"sendBankSlipEmailToIssuer":{"type":"boolean","default":false},"sendBankSlipEmailToCustomer":{"type":"boolean","default":false},"sendServiceInvoiceEmailToIssuer":{"type":"boolean","default":false},"sendServiceInvoiceEmailToCustomer":{"type":"boolean","default":false},"bankSlipConfig":{"type":"object","properties":{"agendaDays":{"type":"integer","minimum":0,"maximum":60},"discount":{"$ref":"#/components/schemas/BankSlipDiscountRule"},"fine":{"$ref":"#/components/schemas/BankSlipFineRule"},"interest":{"$ref":"#/components/schemas/BankSlipInterestRule"}}},"serviceInvoiceConfig":{"type":"object","properties":{"defaultDiscrimination":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Conta a receber avulsa criada; documentos solicitados podem conter resultado parcial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"}}}},"400":{"description":"Erro de validação ou indisponibilidade do documento solicitado.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/DocumentIssuanceErrorResponse"}]},"examples":{"bankSlipUnavailable":{"value":{"status":"error","category":"ACCOUNT.RECEIVABLE.CREATE.BANK_SLIP_NOT_ENABLED","message":"Não é possível usar essa opção pois a empresa não ativou ainda o uso de boletos. Para configurar, acesse o cadastro \"Minhas Empresas\" em \"Configurações\" e em seguida clique na ação \"Ativar boleto\"."}},"serviceInvoiceUnavailable":{"value":{"status":"error","category":"ACCOUNT.RECEIVABLE.CREATE.SERVICE_INVOICE_NOT_ENABLED","message":"Não é possível usar essa opção pois a empresa não ativou ainda o uso de notas fiscais de serviço. Para configurar, acesse o cadastro \"Minhas Empresas\" nas \"Configurações\" e em seguida clique na ação \"Ativar NFS-e\"."}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ServiceError"},"404":{"$ref":"#/components/responses/ServiceError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"receivables:read","tags":["AccountReceivable"],"summary":"Listar contas a receber","description":"Retorna a lista paginada de contas a receber da empresa autenticada.\n","operationId":"listAccountReceivable","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"page","required":false,"schema":{"type":"integer","example":1}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","example":10}},{"in":"query","name":"type","schema":{"type":"string","enum":["AUTOMATIC","MANUAL"]}}],"responses":{"200":{"description":"Lista retornada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"value":{"success":true,"message":"Account Receivable listed successfully!","data":{"docs":[],"page":1,"totalDocs":0}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-receivable/{accountReceivableId}":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"receivables:read","tags":["AccountReceivable"],"summary":"Obter conta a receber","description":"Retorna os dados de uma conta a receber específica da empresa autenticada.\nPara contas avulsas, inclui `editPermissions`, que informa os campos\nliberados conforme os boletos e NFS-e vinculados ao vencimento.\nDocumentos com status `deleted` não bloqueiam edição nem nova emissão.\n","operationId":"getAccountReceivable","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/AccountReceivableId"}],"responses":{"200":{"description":"Registro retornado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"receivables:write","tags":["AccountReceivable"],"summary":"Editar conta a receber avulsa","description":"Edita parcialmente uma conta a receber avulsa. Sem boleto ou NFS-e\nassociados, os campos financeiros podem ser alterados e ambos os\ndocumentos podem ser solicitados. Com um documento associado, somente\na observação e a emissão do outro tipo de documento permanecem\npermitidas. Boletos e NFS-e excluídos logicamente (status `deleted`)\nnão bloqueiam a edição nem uma nova solicitação do mesmo tipo de documento.\nContas automáticas não aceitam esta operação.\nUm documento solicitado que não pôde ser emitido aparece em\n`documents.bankSlip` ou `documents.serviceInvoice` com\n`status: error` e `error: { code, message }`, sem desfazer a conta.\n`code` é a categoria do erro da emissão (por exemplo\n`BANK_SLIP.ISSUE_RECONCILIATION_REQUIRED`); um erro sem categoria usa o próprio\ncódigo ou `DOCUMENT_ISSUANCE_FAILED`.\n","operationId":"updateManualAccountReceivable","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/AccountReceivableId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"clientId":{"type":"string"},"serviceId":{"type":"string"},"value":{"type":"number","minimum":0.01},"receivableDate":{"type":"string","format":"date-time"},"observation":{"type":"string"},"issueBankSlip":{"type":"boolean"},"issueServiceInvoice":{"type":"boolean"},"sendBankSlipEmailToIssuer":{"type":"boolean"},"sendBankSlipEmailToCustomer":{"type":"boolean"},"sendServiceInvoiceEmailToIssuer":{"type":"boolean"},"sendServiceInvoiceEmailToCustomer":{"type":"boolean"},"bankSlipConfig":{"type":"object","properties":{"agendaDays":{"type":"integer","minimum":0,"maximum":60},"discount":{"$ref":"#/components/schemas/BankSlipDiscountRule"},"fine":{"$ref":"#/components/schemas/BankSlipFineRule"},"interest":{"$ref":"#/components/schemas/BankSlipInterestRule"}}},"serviceInvoiceConfig":{"type":"object","properties":{"defaultDiscrimination":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Conta avulsa atualizada; documentos solicitados podem conter resultado parcial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"}}}},"400":{"description":"Erro de validação ou indisponibilidade do documento solicitado.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationErrorResponse"},{"$ref":"#/components/schemas/DocumentIssuanceErrorResponse"}]},"examples":{"bankSlipUnavailable":{"value":{"status":"error","category":"ACCOUNT.RECEIVABLE.UPDATE.BANK_SLIP_NOT_ENABLED","message":"Não é possível usar essa opção pois a empresa não ativou ainda o uso de boletos. Para configurar, acesse o cadastro \"Minhas Empresas\" em \"Configurações\" e em seguida clique na ação \"Ativar boleto\"."}},"serviceInvoiceUnavailable":{"value":{"status":"error","category":"ACCOUNT.RECEIVABLE.UPDATE.SERVICE_INVOICE_NOT_ENABLED","message":"Não é possível usar essa opção pois a empresa não ativou ainda o uso de notas fiscais de serviço. Para configurar, acesse o cadastro \"Minhas Empresas\" nas \"Configurações\" e em seguida clique na ação \"Ativar NFS-e\"."}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ServiceError"},"404":{"$ref":"#/components/responses/ServiceError"},"409":{"$ref":"#/components/responses/ServiceError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"receivables:write","tags":["AccountReceivable"],"summary":"Excluir conta a receber","description":"Exclui logicamente uma conta a receber específica da empresa autenticada.\nUma conta a receber com boleto ou NFS-e ativos associados não pode ser\nexcluída.\n","operationId":"deleteAccountReceivable","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/AccountReceivableId"}],"responses":{"200":{"description":"Registro excluído com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"value":{"success":true,"message":"Account Receivable deleted successfully!"}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"409":{"description":"A conta possui documento financeiro ativo ou reprocessamento de faturamento em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"associatedDocuments":{"value":{"status":"error","category":"ACCOUNT.RECEIVABLE.DELETE.ASSOCIATED_DOCUMENTS","message":"Essa conta a receber não pode ser excluida pois já possui uma NFS-e ou boleto associados."}},"billingProcessingInProgress":{"value":{"status":"error","category":"ACCOUNT.RECEIVABLE.DELETE.BILLING_PROCESSING_IN_PROGRESS","message":"Essa conta a receber não pode ser excluída enquanto o reprocessamento de faturamento estiver em andamento."}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-receivable/{accountReceivableId}/status":{"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"receivables:write","tags":["AccountReceivable"],"summary":"Atualizar status da conta a receber","description":"Atualiza o status de uma conta a receber da empresa autenticada e de suas\nparcelas na mesma transação: ambas as alterações são confirmadas ou\nrevertidas juntas. Contas excluídas logicamente não podem ser reativadas\npor esta operação e retornam 404. Uma alteração concorrente que invalide\no status lido retorna 409, sem aplicar parcialmente a alteração.\nOs valores de status são enviados em letras maiúsculas.\n\n`PAID` (\"Definir como Pago\") registra o pagamento em cada parcela que ainda não\nestava paga: `amountPaid` recebe `amountDue` quando a parcela não tinha valor pago\n(nulo ou 0) e `paymentDate` recebe a data de hoje (00:00 em America/Sao_Paulo)\nquando não havia data; valor e data já registrados (por exemplo, por liquidação de\nboleto) são mantidos, e parcela já paga não é alterada. Ao sair de `PAID` para\n`PENDING`, `OVERDUE` ou `CANCELED`, as parcelas voltam a `amountPaid` 0 e\n`paymentDate` nulo; a auditoria guarda os valores anteriores.\n","operationId":"updateAccountReceivableStatus","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/AccountReceivableId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["PENDING","PAID","CANCELED","OVERDUE"],"example":"PAID"}}}}}},"responses":{"200":{"description":"Status atualizado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"value":{"success":true,"message":"Status atualizado com sucesso.","data":{"newStatus":"PAID"}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"description":"Conta a receber inexistente, fora da empresa autenticada ou excluída logicamente.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"category":{"type":"string"}}},"examples":{"notFoundOrDeleted":{"value":{"status":"error","message":"Account Receivable not found.","category":"ACCOUNT.RECEIVABLE.GET.NOT_FOUND"}}}}}},"409":{"description":"O status foi alterado por outra requisição antes da gravação.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"category":{"type":"string"}}},"examples":{"concurrentModification":{"value":{"status":"error","message":"Status foi alterado por outra requisição. Tente novamente.","category":"ACCOUNT.RECEIVABLE.UPDATE_STATUS.CONCURRENT_MODIFICATION"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-payable":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:read","tags":["Account Payable"],"summary":"Listar contas a pagar","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"supplierId","schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}},{"in":"query","name":"origin","schema":{"type":"string","enum":["MANUAL","NFS_E_IMPORT","NFE_IMPORT"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["PENDING","OVERDUE","PAID","CANCELED"]}},{"in":"query","name":"dueDateStart","schema":{"type":"string","format":"date"}},{"in":"query","name":"dueDateEnd","schema":{"type":"string","format":"date"}},{"in":"query","name":"createdAtStart","schema":{"type":"string","format":"date"}},{"in":"query","name":"createdAtEnd","schema":{"type":"string","format":"date"}},{"in":"query","name":"minValue","schema":{"type":"number","exclusiveMinimum":0}},{"in":"query","name":"page","schema":{"type":"integer","minimum":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"$ref":"#/components/responses/AccountPayableListSuccess"},"400":{"$ref":"#/components/responses/AccountPayableValidationError"},"401":{"$ref":"#/components/responses/AccountPayableUnauthorizedError"},"403":{"$ref":"#/components/responses/AccountPayableForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:write","tags":["Account Payable"],"summary":"Criar conta a pagar manual","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableInput"},"examples":{"pending":{"value":{"supplierId":"66e1c7f0f2f0b2a6c7a8d992","value":33.33,"dueDate":"2026-10-25","observation":"Serviço mensal"}},"paid":{"value":{"supplierId":"66e1c7f0f2f0b2a6c7a8d992","value":33.33,"dueDate":"2026-10-25","paymentDate":"2026-10-20"}}}}}},"responses":{"201":{"$ref":"#/components/responses/AccountPayableMutationSuccess"},"400":{"$ref":"#/components/responses/AccountPayableValidationError"},"401":{"$ref":"#/components/responses/AccountPayableUnauthorizedError"},"403":{"$ref":"#/components/responses/AccountPayableForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-payable/{accountPayableId}":{"parameters":[{"in":"path","name":"accountPayableId","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}],"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:read","tags":["Account Payable"],"summary":"Consultar conta a pagar","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"responses":{"200":{"$ref":"#/components/responses/AccountPayableMutationSuccess"},"400":{"$ref":"#/components/responses/AccountPayableValidationError"},"401":{"$ref":"#/components/responses/AccountPayableUnauthorizedError"},"403":{"$ref":"#/components/responses/AccountPayableForbiddenError"},"404":{"$ref":"#/components/responses/AccountPayableNotFoundError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:write","tags":["Account Payable"],"summary":"Atualizar conta a pagar","description":"O status é derivado de paymentDate. Uma conta CANCELED permanece cancelada em edições comuns enquanto paymentDate continuar nula; a reabertura é feita pela ação de status. Alterar valor ou vencimento de conta paga exige Administrador.","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableUpdate"}}}},"responses":{"200":{"$ref":"#/components/responses/AccountPayableMutationSuccess"},"400":{"$ref":"#/components/responses/AccountPayableValidationError"},"401":{"$ref":"#/components/responses/AccountPayableUnauthorizedError"},"403":{"$ref":"#/components/responses/AccountPayableForbiddenError"},"404":{"$ref":"#/components/responses/AccountPayableNotFoundError"},"409":{"$ref":"#/components/responses/AccountPayableConflictError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:write","tags":["Account Payable"],"summary":"Excluir conta a pagar logicamente","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"responses":{"200":{"$ref":"#/components/responses/AccountPayableDeleteSuccess"},"400":{"$ref":"#/components/responses/AccountPayableValidationError"},"401":{"$ref":"#/components/responses/AccountPayableUnauthorizedError"},"403":{"$ref":"#/components/responses/AccountPayableForbiddenError"},"404":{"$ref":"#/components/responses/AccountPayableNotFoundError"},"409":{"$ref":"#/components/responses/AccountPayableConflictError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-payable/xml-import/preview/{companyId}":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:write","tags":["Account Payable"],"summary":"Pré-visualizar conta a pagar a partir de XML fiscal","description":"Aceita uma NFS-e Nacional ou NF-e autorizada. Não grava dados; o vencimento ausente ou ambíguo deve ser preenchido na revisão.","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["xmlFile"],"properties":{"xmlFile":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Prévia fiscal e pendências de revisão.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableXmlImportPreviewResponse"},"examples":{"reviewRequired":{"value":{"success":true,"data":{"documentType":"NFS_E","fiscalKey":"NFS1-EXAMPLE","invoiceNumber":"1","value":50,"supplierCandidate":{"cpfCnpj":"10456737000177","name":"Fornecedor exemplo"},"recipientDocument":"12345678000195","warnings":[{"field":"accountPayable.dueDate","code":"missing"},{"field":"supplier.address","code":"missing"}],"supplier":null,"duplicate":false}}}}}}},"400":{"$ref":"#/components/responses/AccountPayableValidationError"},"401":{"$ref":"#/components/responses/AccountPayableUnauthorizedError"},"403":{"$ref":"#/components/responses/AccountPayableForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-payable/xml-import":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:write","tags":["Account Payable"],"summary":"Criar conta a pagar a partir de XML fiscal revisado","description":"Reprocessa o XML, reaproveita o fornecedor ativo já cadastrado ou cria, na mesma transação da Conta a Pagar, o fornecedor confirmado na revisão. Quando não houver fornecedor correspondente, envie os dados revisados no campo JSON `supplier`, mesmo que o XML já contenha todos os campos obrigatórios. Exige vencimento revisado, guarda o arquivo-fonte e retorna duplicidade sem criar outro lançamento.","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["xmlFile","value","dueDate"],"properties":{"xmlFile":{"type":"string","format":"binary"},"value":{"type":"number","exclusiveMinimum":0},"dueDate":{"type":"string","format":"date"},"paymentDate":{"type":"string","format":"date","description":"Opcional; não pode ser futura."},"observation":{"type":"string","maxLength":2000},"supplierId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$","description":"Compatibilidade para reutilizar um fornecedor ativo já existente; deve pertencer à mesma empresa e corresponder ao CPF/CNPJ identificado no XML, quando presente. Não combine com `supplier`."},"supplier":{"type":"string","description":"JSON com os dados do fornecedor confirmados na revisão. Obrigatório quando não houver fornecedor correspondente ao XML; o fornecedor é criado somente junto da Conta a Pagar.","example":"{\"cpfCnpj\":\"10456737000177\",\"name\":\"Fornecedor revisado\",\"address\":\"Rua Um\",\"number\":\"100\",\"neighborhood\":\"Centro\",\"postalCode\":\"01001000\",\"city\":\"São Paulo\",\"state\":\"SP\",\"emails\":[\"financeiro@fornecedor.test\"]}"}}},"encoding":{"supplier":{"contentType":"application/json"}}}}},"responses":{"200":{"description":"Nota já importada anteriormente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableXmlImportDuplicateResponse"},"examples":{"duplicate":{"value":{"success":true,"data":{"duplicate":true,"fiscalKey":"NFS1-EXAMPLE"}}}}}}},"201":{"description":"Conta a pagar importada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableXmlImportCreatedResponse"},"examples":{"created":{"value":{"success":true,"data":{"fiscalKey":"NFS1-EXAMPLE","account":{"_id":"66e1c7f0f2f0b2a6c7a8d990","supplierId":"66e1c7f0f2f0b2a6c7a8d991","value":50,"dueDate":"2026-11-10T03:00:00.000Z","paymentDate":null,"origin":"NFS_E_IMPORT","status":"PENDING","fiscalSource":{"documentType":"NFS_E","fiscalKey":"NFS1-EXAMPLE","invoiceNumber":"1"},"createdAt":"2026-10-28T12:00:00.000Z"},"supplier":{"id":"66e1c7f0f2f0b2a6c7a8d991","name":"Fornecedor revisado","created":true}}}}}}}},"400":{"description":"Dados inválidos ou fornecedor inativo com o mesmo CPF/CNPJ.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableServiceError"},"examples":{"inactiveSupplier":{"value":{"status":"error","category":"ACCOUNT_PAYABLE.XML_IMPORT.SUPPLIER_INACTIVE","message":"The supplier with the same CPF/CNPJ is inactive and must be reactivated before importing."}},"recipientMismatch":{"value":{"status":"error","category":"ACCOUNT_PAYABLE.XML_IMPORT.RECIPIENT_MISMATCH","message":"The fiscal invoice recipient does not match the selected company."}}}}}},"401":{"$ref":"#/components/responses/AccountPayableUnauthorizedError"},"403":{"$ref":"#/components/responses/AccountPayableForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-payable/{accountPayableId}/imported-invoice/xml":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:read","tags":["Account Payable"],"summary":"Visualizar XML da nota fiscal importada","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"accountPayableId","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}],"responses":{"200":{"description":"XML fiscal aberto inline","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/ApiKeyUnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"$ref":"#/components/responses/AccountPayableNotFoundError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/account-payable/{accountPayableId}/status":{"put":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"payables:write","tags":["Account Payable"],"summary":"Definir status pelo menu de ações","description":"PAID grava a data atual somente uma vez. PENDING e OVERDUE removem paymentDate e são recalculados pelo vencimento quando a conta estava PAID ou CANCELED. Não é permitido trocar diretamente PENDING por OVERDUE nem OVERDUE por PENDING. CANCELED também remove paymentDate.","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"accountPayableId","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableStatusAction"}}}},"responses":{"200":{"$ref":"#/components/responses/AccountPayableMutationSuccess"},"400":{"description":"Dados inválidos ou ação de status já aplicada.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AccountPayableValidationError"},{"$ref":"#/components/schemas/AccountPayableServiceError"}]},"examples":{"validationFailed":{"value":{"error":"VALIDATION_FAILED","details":[{"field":"status","message":"Invalid enum value"}]}},"alreadyPaid":{"value":{"status":"error","category":"ACCOUNT.PAYABLE.UPDATE_STATUS.ALREADY_PAID","message":"Account payable is already paid."}},"alreadyCanceled":{"value":{"status":"error","category":"ACCOUNT.PAYABLE.UPDATE_STATUS.ALREADY_CANCELED","message":"Account payable is already canceled."}},"alreadyPending":{"value":{"status":"error","category":"ACCOUNT.PAYABLE.UPDATE_STATUS.ALREADY_PENDING","message":"Account payable is already pending."}},"alreadyOverdue":{"value":{"status":"error","category":"ACCOUNT.PAYABLE.UPDATE_STATUS.ALREADY_OVERDUE","message":"Account payable is already overdue."}},"cannotChangePendingToOverdue":{"value":{"status":"error","category":"ACCOUNT.PAYABLE.UPDATE_STATUS.CANNOT_CHANGE_PENDING_TO_OVERDUE","message":"A operação não pode ser realizada pois o contas a pagar ainda está dentro do vencimento."}},"cannotChangeOverdueToPending":{"value":{"status":"error","category":"ACCOUNT.PAYABLE.UPDATE_STATUS.CANNOT_CHANGE_OVERDUE_TO_PENDING","message":"A operação não pode ser realizada pois o contas a pagar já se encontra em atraso."}}}}}},"401":{"$ref":"#/components/responses/AccountPayableUnauthorizedError"},"403":{"$ref":"#/components/responses/AccountPayableForbiddenError"},"404":{"$ref":"#/components/responses/AccountPayableNotFoundError"},"409":{"$ref":"#/components/responses/AccountPayableConflictError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/xml-import/preview/{companyId}":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:write","tags":["ServiceInvoice"],"summary":"Revisar dados de serviço extraídos de XML de NFS-e","operationId":"previewServiceInvoiceXml","description":"Prévia sem persistência, restrita ao administrador da empresa selecionada\nno token e pertencente ao licenciado. O XML pode ter sido emitido por\noutra empresa; issuerMatchesCompany sinaliza a divergência sem expor\nCPF/CNPJ. Recebe uma NFS-e emitida em UTF-8, ISO-8859-1/latin1 ou\nWindows-1252, até 1 MiB.\nSuporta Nacional 1.00/1.01, ABRASF 2.03/2.04 e GINFES v03.\nNo formato nacional, NFSe e DPS têm versões 1.00/1.01 validadas\nseparadamente; NFSe 1.01 pode conter DPS 1.00, e a resposta informa\na versão da NFSe. Inclui a exportação individual ISS Fortaleza com\nNFSE/Nfse/InfNfse,\nnamespace http://www.ginfes.com.br/tipos_v03.xsd e schemaLocation contendo\nhttps://iss.fortaleza.ce.gov.br/grpfor/schema/V2/tipos_v02.xsd.\nTambém reconhece CompNfse/Nfse/InfNfse no namespace\nhttp://www.ginfes.com.br/servico_consultar_lote_rps_resposta_v03.xsd\nquando OrgaoGerador/CodigoMunicipio é 2304400, com os mesmos\nmapeamentos fiscais de Fortaleza descritos abaixo.\nNão aceita lotes, DPS/RPS avulsos, DTD ou entidades declaradas.\nRetorna sugestões parciais e pendências; ausência não significa zero ou\nfalso. Alíquotas retornadas são percentuais; GINFES convencional converte\nsua fração para percentual. A exportação Fortaleza identificada acima\njá informa percentual: Aliquota 2.17 retorna aliquotISS 2.17, sem multiplicar\npor 100. A unidade não é inferida pela magnitude. Fortaleza retorna\nformat=ginfes e version=3.00. Nessa exportação, NaturezaOperacao mapeia\ntipo de tributação/exigibilidade ClickFin: 1→6/1, 2→7/1, 3→1/3, 4→2/5;\n5 e 6 preenchem somente exigibilidade 6 e 7. ExigibilidadeISS explícita\ndivergente gera pendência ambiguous; valor inválido não usa fallback.\nIbsCbs.CodigoIndicadorOperacao preenche ibscbs.operationCode e\nIbsCbs.Valores.TributosIbsCbs.GrupoIbsCbs.CST/CodigoClassTrib preenchem\nibscbs.cst/cct, preservando zeros à esquerda (6/3/6 dígitos).\nCodigoIndicadorOperacaoUsoConsumoPessoal aceita somente 0/1; -1 gera\naviso invalid sem sugerir personalOperation. CodigoIndicadorFinalidadeNFSe\nnão é usado como operação pessoal.\nNão infere alíquotas de valores monetários, regime tributário ou mínimos\nde retenção. Não importa certificado/senha/ambiente.\nVariantes com namespace Nacional ou GINFES reconhecido e estrutura de\nserviço inequívoca podem retornar format=other e apenas códigos/descrição\ndo serviço. Nessas variantes, não sugere tributos sem mapeamento fiscal\nconhecido. Isso inclui outros envelopes GINFES v02/v03/v04 e versões\nnacionais sem adaptador fiscal específico.\nO consumidor deve permitir revisão e escolha dos campos antes de preencher\no formulário e exigir revisão fiscal explícita quando o emitente for\ndiferente, não puder ser identificado ou houver pendências de campos.\nA gravação usa os endpoints\nexistentes e suas validações.\n","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/CompanyId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["xmlFile","target"],"properties":{"xmlFile":{"type":"string","format":"binary","description":"Arquivo .xml não vazio em UTF-8, ISO-8859-1/latin1 ou Windows-1252, máximo 1048576 bytes."},"target":{"type":"string","enum":["service"],"description":"Somente serviços; setting retorna INVALID_REQUEST. Sem campos utilizáveis resulta em NO_DATA."}}}}}},"responses":{"200":{"description":"Dados disponíveis para revisão; nenhuma gravação foi executada.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ServiceInvoiceXmlPreview"}}}}}},"400":{"description":"Categories SERVICE_INVOICE.XML_IMPORT.INVALID_REQUEST, INVALID_XML,\nUNSUPPORTED_FORMAT ou NO_DATA (mesmo prefixo).\nSem conteúdo do XML nas mensagens. MIDDLEWARE.AUTH.COMPANY_NOT_SELECTED\nquando o token não contém empresa selecionada.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XmlImportError"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"SERVICE_INVOICE.XML_IMPORT.FORBIDDEN para empresa diferente da selecionada,\nMIDDLEWARE.ENSURE.UNAUTHORIZED_ACCESS_ADMIN_REQUIRED para perfil não administrador,\nou BILLING.COMMERCIAL.ACCESS_BLOCKED para acesso comercial bloqueado.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XmlImportError"}}}},"404":{"description":"SERVICE_INVOICE.XML_IMPORT.COMPANY_NOT_FOUND para empresa inexistente ou de outro licenciado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XmlImportError"}}}},"413":{"description":"SERVICE_INVOICE.XML_IMPORT.FILE_TOO_LARGE para arquivo maior que 1 MiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XmlImportError"}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:read","tags":["ServiceInvoice"],"summary":"Listar notas de serviço","description":"Retorna a lista de notas de serviço da empresa autenticada. Cada item\ncontém historyData, o contexto fiscal não secreto preservado no momento\nda criação da NFS-e. A grid deve usar esse snapshot para os valores\nhistóricos, inclusive historyData.invoice.number para o número fiscal,\nsem usar cadastros atuais como fallback. Requer perfil de administrador.\n`limit=0` retorna todos os itens em uma única resposta, com `totalPages: 0`.\n","operationId":"listServiceInvoice","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"page","required":false,"schema":{"type":"string","default":"1"},"description":"Página (base 1)."},{"in":"query","name":"limit","required":false,"schema":{"type":"string","default":"10"},"description":"Itens por página. `0` retorna todos os itens (`totalPages` = 0)."},{"in":"query","name":"status","required":false,"schema":{"type":"string","enum":["pending","processing","issued","error","cancelling","cancelled"]},"description":"Filtra pelo status da NFS-e."},{"in":"query","name":"createdAtStart","required":false,"schema":{"type":"string","format":"date"},"description":"Data inicial inclusiva da Data de Emissão (`createdAt`), no formato YYYY-MM-DD e interpretada em America/Sao_Paulo."},{"in":"query","name":"createdAtEnd","required":false,"schema":{"type":"string","format":"date"},"description":"Data final inclusiva da Data de Emissão (`createdAt`), no formato YYYY-MM-DD e interpretada em America/Sao_Paulo."}],"responses":{"200":{"description":"Lista retornada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInvoiceListResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/issue":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:write","tags":["ServiceInvoice"],"summary":"Emitir NFS-e","description":"Dispara o fluxo de emissão de NFS-e.\nPara emissão nacional, o serviço configurado deve ter código nacional de seis dígitos e, quando informado, `nationalMunicipalTaxCode` com exatamente três dígitos. A ausência desse campo permite o fallback do código municipal do serviço (`serviceMunicipalCode`) somente quando ele também tiver três dígitos; valores de outro formato não são truncados. Uma DPS que não atender ao perfil fiscal do ambiente é rejeitada antes de acessar ou assinar o certificado com a categoria `SERVICE_INVOICE.NATIONAL_DPS_INVALID`.\nRequer perfil de administrador.\n\n**Idempotência da emissão manual.** O cabeçalho `Idempotency-Key` é opcional.\nQuando omitido, a API gera uma chave interna para a tentativa (compatível com\nclientes que não enviam o cabeçalho), mas uma repetição da requisição não é\nreconhecida como a mesma emissão. Para repetir com segurança após timeout ou erro\nde rede, envie uma chave opaca estável por tentativa e reutilize-a:\n- mesma chave e mesmo corpo, nota já aceita (`processing`/`issued`): `201` com a\n  nota existente e mensagem `Service invoice request already accepted.`, sem nova\n  chamada ao provedor;\n- mesma chave e corpo diferente: `409` `SERVICE_INVOICE.ISSUE_IDEMPOTENCY_MISMATCH`;\n- mesma chave com reserva ainda pendente ou resultado incerto: `409`\n  `SERVICE_INVOICE.ISSUE_RECONCILIATION_REQUIRED`;\n- chave fora do formato: `400` `SERVICE_INVOICE.ISSUE_IDEMPOTENCY_KEY_REQUIRED`.\n\n**Falhas do provedor.** Uma rejeição definitiva (4xx) do PlugNotas ou da SEFIN\nmarca a nota como `error` e retorna o erro com status `400`. Um resultado incerto\n(timeout, falha de rede, 5xx, resposta inválida) mantém a reserva para conciliação\npelo webhook ou pelo provedor e retorna `409`\n`SERVICE_INVOICE.ISSUE_RECONCILIATION_REQUIRED`, sem reenviar a nota (fail-closed\nintencional para evitar NFS-e duplicada). Uma falha de preparação antes de enviar a\nDPS nacional retorna `422` `SERVICE_INVOICE.ISSUE_PREPARATION_FAILED`.\n\n**Conciliação automática.** Uma nota que fica `pending`/`processing` por resultado\nincerto é conciliada por um job a cada 15 minutos, só com consultas ao provedor\n(DPS na SEFIN, `idIntegracao` no PlugNotas): se o provedor tem a nota, ela passa a\n`issued` com os dados oficiais; se a SEFIN confirma que a DPS não existe após 30\nminutos sem alteração, a nota passa a `error` com `error.code`\n`SERVICE_INVOICE.ISSUE_NOT_CONFIRMED` e uma mensagem orientando emitir novamente\n(o mesmo vale para uma nota interrompida antes do envio à SEFIN). Nenhuma emissão\né reenviada automaticamente.\n","operationId":"issueServiceInvoice","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"description":"Opcional. Chave opaca de 8 a 128 caracteres `[A-Za-z0-9_.:-]` para a emissão manual;\nreutilize-a ao repetir a mesma tentativa após timeout. Ausente: a API gera uma chave\ninterna. Inválida: `400` `SERVICE_INVOICE.ISSUE_IDEMPOTENCY_KEY_REQUIRED`.\n","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueServiceInvoiceRequest"}}}},"responses":{"201":{"description":"Emissão processada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"}}}},"400":{"description":"Erro de validação da requisição ou dos dados fiscais, `Idempotency-Key` em formato inválido (`SERVICE_INVOICE.ISSUE_IDEMPOTENCY_KEY_REQUIRED`) ou rejeição definitiva do provedor (a nota fica com status `error`).","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceInvoiceValidationError"},{"$ref":"#/components/schemas/ServiceInvoiceOperationError"}]},"examples":{"invalidRequestBody":{"summary":"Corpo da requisição inválido","value":{"error":"VALIDATION_FAILED","details":[{"field":"clientId","message":"Client ID is required"}]}},"nationalDpsInvalid":{"summary":"DPS nacional incompatível com o contrato fiscal ativo","value":{"status":"error","category":"SERVICE_INVOICE.NATIONAL_DPS_INVALID","message":"National DPS contract rejects nationalMunicipalTaxCode: must contain exactly three digits."}},"nationalProviderRejected":{"summary":"SEFIN recusou a DPS (a nota fica com status `error`)","value":{"status":"error","category":"SERVICE_INVOICE.NATIONAL_ISSUE_FAILED","message":"SEFIN rejected national service invoice: E0207: CPF do tomador não encontrado no cadastro CPF.","details":{"provider":"sefin_national","providerHttpStatus":400,"providerCode":"E0207","providerReason":"CPF do tomador não encontrado no cadastro CPF.","rejections":[{"code":"E0207","reason":"CPF do tomador não encontrado no cadastro CPF."}]}}},"plugNotasProviderRejected":{"summary":"PlugNotas recusou o JSON da NFS-e (a nota fica com status `error`)","value":{"status":"error","category":"SERVICE_INVOICE.ISSUE_FAILED","message":"PlugNotas error while issuing service invoice: Falha na validação do JSON de NFSe | tomador.cpfCnpj: Deve conter 11 ou 14 dígitos","details":{"provider":"plugnotas","providerHttpStatus":400,"providerReason":"Falha na validação do JSON de NFSe","rejections":[{"field":"tomador.cpfCnpj","reason":"Deve conter 11 ou 14 dígitos"}]}}},"invalidIdempotencyKey":{"summary":"Idempotency-Key fora do formato","value":{"status":"error","category":"SERVICE_INVOICE.ISSUE_IDEMPOTENCY_KEY_REQUIRED","message":"A valid Idempotency-Key is required for service invoice issuance."}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"409":{"description":"Emissão pendente de conciliação ou chave reutilizada com dados diferentes (`SERVICE_INVOICE.ISSUE_RECONCILIATION_REQUIRED`, `SERVICE_INVOICE.ISSUE_IDEMPOTENCY_MISMATCH`). Nenhuma nova chamada ao provedor é feita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"reconciliationRequired":{"summary":"Resultado incerto ou reserva pendente","value":{"status":"error","category":"SERVICE_INVOICE.ISSUE_RECONCILIATION_REQUIRED","message":"Service invoice issuance requires reconciliation."}},"idempotencyMismatch":{"summary":"Chave reutilizada com outro corpo","value":{"status":"error","category":"SERVICE_INVOICE.ISSUE_IDEMPOTENCY_MISMATCH","message":"Service invoice issuance requires reconciliation."}}}}}},"422":{"description":"Preparação falhou antes de enviar a nota ao provedor (`SERVICE_INVOICE.ISSUE_PREPARATION_FAILED`); a tentativa é conclusiva e uma nova chave pode ser usada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"preparationFailed":{"value":{"status":"error","category":"SERVICE_INVOICE.ISSUE_PREPARATION_FAILED","message":"Service invoice was not sent to the provider."}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/{serviceInvoiceId}/pdf":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:read","tags":["ServiceInvoice"],"summary":"Baixar PDF da NFS-e","description":"Retorna o PDF da NFS-e emitida a partir do identificador interno da nota no ClickFin.\n","operationId":"downloadServiceInvoicePdf","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/ServiceInvoiceId"}],"responses":{"200":{"description":"PDF retornado com sucesso.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/pdf/batch-download":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:read","tags":["ServiceInvoice"],"summary":"Baixar PDFs de NFS-e em lote","description":"Gera um arquivo ZIP com os PDFs das NFS-e selecionadas.\nRequer perfil de administrador.\n","operationId":"downloadServiceInvoicePdfBatch","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","maxItems":500,"minItems":1,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"ZIP retornado com sucesso.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/{serviceInvoiceId}/xml":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:read","tags":["ServiceInvoice"],"summary":"Baixar XML da NFS-e","description":"Retorna o XML da NFS-e emitida a partir do identificador interno da nota no ClickFin.\n","operationId":"downloadServiceInvoiceXml","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/ServiceInvoiceId"}],"responses":{"200":{"description":"XML retornado com sucesso.","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/{serviceInvoiceId}/xml/cancellation":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:read","tags":["ServiceInvoice"],"summary":"Baixar XML de cancelamento da NFS-e nacional","description":"Retorna o XML do evento de cancelamento armazenado para uma NFS-e\nemitida pelo canal nacional SEFIN. O XML original da NFS-e permanece\ndisponível na rota padrão de download.\n","operationId":"downloadServiceInvoiceCancellationXml","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/ServiceInvoiceId"}],"responses":{"200":{"description":"XML de evento de cancelamento retornado com sucesso.","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/xml/batch-download":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:read","tags":["ServiceInvoice"],"summary":"Baixar XMLs de NFS-e em lote","description":"Gera um arquivo ZIP com os XMLs das NFS-e selecionadas.\nRequer perfil de administrador.\n","operationId":"downloadServiceInvoiceXmlBatch","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","maxItems":500,"minItems":1,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"ZIP retornado com sucesso.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/{serviceInvoiceId}/cancel":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:write","tags":["ServiceInvoice"],"summary":"Cancelar NFS-e","description":"Solicita o cancelamento de uma NFS-e a partir do identificador interno da nota no ClickFin.\nPara NFS-e municipal, uma solicitação aceita fica com status `cancelling` até o webhook do PlugNotas confirmar `CANCELADO` e então passa para `cancelled`.\nUma nova solicitação durante esse processamento ou após a confirmação retorna sucesso sem reenviar o pedido ao provedor.\nSe a PlugNotas ainda não considerar a NFS-e `CONCLUIDO`, a solicitação é recusada e o status permanece `issued`, permitindo nova tentativa posterior.\nSe a PlugNotas retornar erro transitório ou resultado incerto (por exemplo,\n408, 429 ou 5xx), a API responde `503` com\n`SERVICE_INVOICE.CANCEL_FAILED` e conserva a reserva de cancelamento.\nUma repetição não reenvia o cancelamento até a confirmação ou conciliação\ndo resultado com o provedor. Uma rejeição definitiva (4xx exceto 408/429)\ndevolve a nota para `issued` e retorna `400` `SERVICE_INVOICE.CANCEL_FAILED`.\nPara NFS-e nacional, a nota é reservada em `cancelling` antes do envio à SEFIN.\nUma rejeição definitiva da SEFIN (4xx exceto 408/429) devolve a nota para `issued`\ne retorna `400` `SERVICE_INVOICE.NATIONAL_CANCEL_FAILED`; um resultado incerto\n(5xx, 408, 429, falha de rede) retorna `502` `SERVICE_INVOICE.NATIONAL_CANCEL_FAILED`\ne mantém a reserva (fail-closed intencional): repetições respondem\n\"Service invoice cancellation is already being processed.\" sem reenviar o evento.\nRequer perfil de administrador.\nPara NFS-e nacional, se a SEFIN já tiver aceitado o cancelamento mas a\ngeração dos documentos locais falhar, uma nova chamada reconcilia os\nartefatos sem reenviar o evento de cancelamento à SEFIN.\nO motivo é normalizado sem espaços nas extremidades. Para NFS-e\nnacional, o motivo normalizado deve ter entre 15 e 255 caracteres.\n","operationId":"cancelServiceInvoice","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/ServiceInvoiceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["codigo","motivo"],"properties":{"codigo":{"type":"string","enum":["1","2","9"],"description":"Código de cancelamento (1: Erro na Emissão, 2: Serviço não Prestado, 9: Outros)."},"motivo":{"type":"string","minLength":1,"description":"Motivo do cancelamento. Espaços nas extremidades são removidos; para NFS-e nacional, o valor normalizado deve ter de 15 a 255 caracteres."}}}}}},"responses":{"200":{"description":"Solicitação de cancelamento aceita, em processamento ou já confirmada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"}}}},"400":{"description":"NFS-e ainda não concluída pelo provedor ou solicitação inválida.","$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"502":{"$ref":"#/components/responses/ServiceError"},"503":{"$ref":"#/components/responses/ServiceError"}}}},"/service-invoice/{serviceInvoiceId}/error":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:read","tags":["ServiceInvoice"],"summary":"Consultar erro da NFS-e","description":"Retorna os detalhes do último erro associado à NFS-e usando o identificador interno da nota no ClickFin.\nPara exibir o motivo ao usuário, use `data.providerCode` e `data.providerReason` (ou a lista\n`data.rejections`); `data.message` é técnica. `data` é `null` quando a nota não tem erro.\nRequer perfil de administrador.\n","operationId":"getServiceInvoiceError","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/ServiceInvoiceId"}],"responses":{"200":{"description":"Erro retornado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInvoiceErrorResponse"},"examples":{"nationalRejection":{"summary":"Rejeição da SEFIN gravada na emissão","value":{"success":true,"data":{"code":"SERVICE_INVOICE.NATIONAL_ISSUE_FAILED","message":"SEFIN rejected national service invoice: E0207: CPF do tomador não encontrado no cadastro CPF.","provider":"sefin_national","providerHttpStatus":400,"providerCode":"E0207","providerReason":"CPF do tomador não encontrado no cadastro CPF.","rejections":[{"code":"E0207","reason":"CPF do tomador não encontrado no cadastro CPF."}]}}},"municipalRejection":{"summary":"Rejeição municipal recebida pelo webhook da PlugNotas","value":{"success":true,"data":{"code":"SERVICE_INVOICE_REJECTED","message":"Nota rejeitada pela prefeitura","providerCode":"E-123","providerReason":"Inscrição municipal inválida."}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/service-invoice/{serviceInvoiceId}":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:read","tags":["ServiceInvoice"],"summary":"Consultar NFS-e","description":"Retorna os dados persistidos da NFS-e usando o identificador interno da\nnota no ClickFin, inclusive quando a emissão está com erro. historyData\nrepresenta o contexto fiscal não secreto salvo no momento da criação,\nincluindo historyData.invoice.number quando o número fiscal estiver\ndisponível.\nRequer perfil de administrador e respeita a empresa e o licenciado da sessão.\n","operationId":"getServiceInvoice","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/ServiceInvoiceId"}],"responses":{"200":{"description":"NFS-e retornada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInvoiceResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"service_invoices:write","tags":["ServiceInvoice"],"summary":"Excluir NFS-e","description":"Remove o registro local da NFS-e usando o identificador interno da nota no ClickFin.\nRequer perfil de administrador.\n","operationId":"deleteServiceInvoice","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"$ref":"#/components/parameters/ServiceInvoiceId"}],"responses":{"204":{"description":"Registro excluído com sucesso."},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/bank-slips":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"bank_slips:write","tags":["BankSlip"],"summary":"Emitir boleto avulso","description":"Cria um boleto manual no ClickFin e envia a solicitação para o Banco Inter.\nBoletos com vencimento no mesmo dia só podem ser emitidos até 19:59.\nO cabeçalho `Idempotency-Key` é opcional. Quando omitido, a API gera uma chave\ninterna para a tentativa (comportamento compatível com clientes que não enviam o\ncabeçalho), mas uma repetição da requisição não é reconhecida como a mesma emissão.\nPara repetir com segurança após timeout ou erro de rede, envie uma chave opaca única\npor boleto e reutilize-a na repetição: a mesma chave com os mesmos dados retorna o\nboleto já registrado (inclusive um boleto `error` por falha definitiva do Inter);\na mesma chave com dados diferentes retorna `409` `BANK_SLIP.ISSUE_IDEMPOTENCY_MISMATCH`.\nUma chave enviada fora do formato retorna `400` `BANK_SLIP.ISSUE_FAILED`.\n\nRejeições definitivas do Banco Inter registram o boleto com status `error` e\nretornam `201`; um 429 do Inter também é definitivo (nada foi registrado) e\ngrava `error.code` `BANK_SLIP.PROVIDER.UNAVAILABLE`. Quando o resultado do Inter é incerto\n(timeout, falha de rede, 5xx) ou a emissão com a mesma chave ainda está em andamento, a API responde\n`409` `BANK_SLIP.ISSUE_RECONCILIATION_REQUIRED` e não envia nova emissão ao\nprovedor (fail-closed intencional para evitar boleto duplicado).\n\nUm job concilia a cada 15 minutos os boletos que ficaram `processing`: busca a\ncobrança no Inter pelo `seuNumero` do boleto; se existir, grava o\n`codigoSolicitacao` e aplica o status atual (como o webhook); se o Inter não tiver a\ncobrança após 30 minutos sem alteração, o boleto passa a `error` com\n`error.code` `BANK_SLIP.ISSUE_NOT_CONFIRMED` e pode ser emitido novamente. Boletos\njá registrados cujo webhook não chegou também são sincronizados. Nenhuma emissão é\nreenviada automaticamente.\n**Requer perfil de Administrador.**\n","operationId":"issueBankSlip","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"description":"Opcional. Chave opaca de 8 a 128 caracteres `[A-Za-z0-9_.:-]` para a emissão manual.\nUse uma nova chave para cada boleto distinto e reutilize-a ao repetir a mesma tentativa.\nAusente: a API gera uma chave interna. Inválida: `400` `BANK_SLIP.ISSUE_FAILED`.\n","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueBankSlipRequest"},"examples":{"default":{"value":{"companyId":"66dfb4a6b1bbd81234abcd02","clientId":"66e1c7f0f2f0b2a6c7a8d999","amount":349.9,"dueDate":"2026-06-30T00:00:00.000Z","agendaDays":30,"discount":{"type":"PERCENT","daysBeforeDueDate":5,"amountOrPercent":3},"fine":{"type":"PERCENT","amountOrPercent":2},"interest":{"type":"MONTHLY_PERCENT","amountOrPercent":1.5}}}}}}},"responses":{"201":{"description":"Boleto enviado para processamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleBankSlipResponse"}}}},"400":{"description":"Erro de validação (`VALIDATION_FAILED`). As mensagens de `details[].message` são em pt-BR.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"},"examples":{"minimumAmount":{"summary":"Valor abaixo do mínimo do boleto","value":{"error":"VALIDATION_FAILED","details":[{"field":"amount","message":"O valor mínimo do boleto é R$ 2,50."}]}},"invalidDueDate":{"summary":"Vencimento fora do formato ISO 8601","value":{"error":"VALIDATION_FAILED","details":[{"field":"dueDate","message":"Data e hora inválidas: use o formato ISO 8601 (ex.: 2026-11-20T00:00:00.000Z)."}]}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"409":{"description":"Chave reutilizada com dados diferentes ou emissão em andamento/resultado incerto que requer conciliação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"idempotencyMismatch":{"summary":"Chave reutilizada com dados diferentes","value":{"status":"error","message":"Idempotency-Key was already used for a different bank slip.","category":"BANK_SLIP.ISSUE_IDEMPOTENCY_MISMATCH"}},"reconciliationRequired":{"summary":"Resultado incerto ou emissão em andamento","value":{"status":"error","message":"Bank slip issuance requires reconciliation.","category":"BANK_SLIP.ISSUE_RECONCILIATION_REQUIRED"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"502":{"$ref":"#/components/responses/ServiceError"},"503":{"$ref":"#/components/responses/ServiceError"}}},"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"bank_slips:read","tags":["BankSlip"],"summary":"Listar boletos emitidos","description":"Retorna uma lista paginada dos boletos da empresa autenticada.\n`limit=0` retorna todos os itens em uma única resposta, com `totalPages: 0`.\n**Requer perfil de Administrador.**\n","operationId":"listBankSlips","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"clientId","schema":{"type":"string","minLength":24,"maxLength":24}},{"in":"query","name":"status","schema":{"type":"string","enum":["processing","issued","paid","cancelled","expired","error"]}},{"in":"query","name":"page","schema":{"type":"string","default":"1"}},{"in":"query","name":"limit","description":"Itens por página. `0` retorna todos os itens (`totalPages` = 0).","schema":{"type":"string","default":"10"}}],"responses":{"200":{"description":"Lista retornada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedBankSlipResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/bank-slips/{id}":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"bank_slips:read","tags":["BankSlip"],"summary":"Obter boleto por ID","description":"Retorna os dados principais de um boleto da empresa autenticada.\nA resposta não inclui histórico de reenvios manuais por e-mail.\n","operationId":"getBankSlip","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","minLength":24,"maxLength":24}}],"responses":{"200":{"description":"Boleto retornado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleBankSlipResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}},"delete":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"bank_slips:write","tags":["BankSlip"],"summary":"Excluir boleto","description":"Exclui logicamente um boleto com erro de emissão.\nSe o boleto mudar de estado durante a exclusão (por exemplo, por uma conciliação\nconcorrente), retorna `409` `BANK_SLIP.INVALID_STATUS_FOR_DELETION`.\nRequer perfil de administrador.\n","operationId":"deleteBankSlip","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","minLength":24,"maxLength":24}}],"responses":{"200":{"description":"Boleto excluído logicamente com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleBankSlipResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"409":{"description":"O boleto foi alterado durante a exclusão.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"},"examples":{"changedWhileDeleting":{"value":{"status":"error","message":"Bank slip changed while being deleted.","category":"BANK_SLIP.INVALID_STATUS_FOR_DELETION"}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/bank-slips/{id}/error":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"bank_slips:read","tags":["BankSlip"],"summary":"Obter erro da emissão do boleto","description":"Retorna os detalhes do último erro registrado para um boleto da empresa autenticada.","operationId":"getBankSlipError","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","minLength":24,"maxLength":24}}],"responses":{"200":{"description":"Erro do boleto retornado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankSlipErrorResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}},"/bank-slips/{id}/pdf":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"bank_slips:read","tags":["BankSlip"],"summary":"Baixar PDF do boleto","description":"Busca o PDF do boleto no Banco Inter e retorna o binário.\nSe o Banco Inter não puder atender a chamada (HTTP 5xx ou 429, ou falha de rede sem\nresposta), retorna `502` com a categoria `BANK_SLIP.PROVIDER.UNAVAILABLE`; as recusas\n4xx do Inter respondem `BANK_SLIP.PROVIDER.VALIDATION_ERROR`.\n","operationId":"downloadBankSlipPdf","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","minLength":24,"maxLength":24}}],"responses":{"200":{"description":"PDF retornado com sucesso.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"502":{"$ref":"#/components/responses/ServiceError"},"503":{"$ref":"#/components/responses/ServiceError"}}}},"/bank-slips/pdf/batch-download":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"bank_slips:read","tags":["BankSlip"],"summary":"Baixar PDFs de boletos em lote","description":"Gera um arquivo ZIP com os PDFs dos boletos selecionados.\nSe o Banco Inter não puder atender a chamada (HTTP 5xx ou 429, ou falha de rede sem\nresposta), retorna `502` com a categoria `BANK_SLIP.PROVIDER.UNAVAILABLE`; as recusas\n4xx do Inter respondem `BANK_SLIP.PROVIDER.VALIDATION_ERROR`.\n**Requer perfil de Administrador.**\n","operationId":"downloadBankSlipPdfBatch","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","maxItems":500,"minItems":1,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"ZIP retornado com sucesso.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"502":{"$ref":"#/components/responses/ServiceError"},"503":{"$ref":"#/components/responses/ServiceError"}}}},"/bank-slips/{id}/cancel":{"post":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"bank_slips:write","tags":["BankSlip"],"summary":"Cancelar boleto emitido","description":"Cancela um boleto já emitido.\nA operação só é permitida quando o status atual do boleto é `issued`.\n\nO cancelamento é reservado antes da chamada ao Banco Inter. Uma rejeição definitiva\ndo Inter libera a reserva e a operação pode ser repetida. Um resultado incerto\n(timeout, falha de rede, 5xx) conserva a reserva: novas chamadas retornam `503`\n`BANK_SLIP.CANCEL_FAILED` (\"Bank slip cancellation is pending reconciliation.\") sem\nreenviar o cancelamento até a conciliação com o provedor (fail-closed intencional).\nErros do provedor são devolvidos com o status e a categoria do adaptador do Inter.\nSe o Banco Inter não puder atender a chamada (HTTP 5xx ou 429, ou falha de rede sem\nresposta), retorna `502` com a categoria `BANK_SLIP.PROVIDER.UNAVAILABLE`; as recusas\n4xx do Inter respondem `BANK_SLIP.PROVIDER.VALIDATION_ERROR`.\n**Requer perfil de Administrador.**\n","operationId":"cancelBankSlip","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","minLength":24,"maxLength":24}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelBankSlipRequest"}}}},"responses":{"200":{"description":"Boleto cancelado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleBankSlipResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/ServiceError"},"409":{"$ref":"#/components/responses/ServiceError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"502":{"$ref":"#/components/responses/ServiceError"},"503":{"$ref":"#/components/responses/ServiceError"}}}},"/report/dashboard":{"get":{"x-clickfin-audience":"public","x-clickfin-api-key-scope":"reports:read","tags":["Report"],"summary":"Obter dashboard consolidado","description":"Retorna os indicadores principais do dashboard para o período informado.\nRequer autenticação com token completo e empresa selecionada.\n","operationId":"getDashboardReport","security":[{"ApiKeyAuth":[]},{"BearerAuthComplete":[]}],"parameters":[{"in":"query","name":"startDate","required":false,"schema":{"type":"string","format":"date-time"},"description":"Data inicial do período consultado."},{"in":"query","name":"endDate","required":false,"schema":{"type":"string","format":"date-time"},"description":"Data final do período consultado."}],"responses":{"200":{"description":"Dashboard retornado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardReportResponse"},"examples":{"dashboard":{"value":{"success":true,"data":{"accountReceivable":{"total":12,"paid":7},"bankSlip":{"total":8,"issued":5}}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ApiKeyForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitExceededError"},"503":{"$ref":"#/components/responses/AuthSessionUnavailableError"}}}}},"components":{"schemas":{"HealthcheckResponse":{"type":"object","required":["status","db","timestamp"],"properties":{"status":{"type":"string","enum":["ok","degraded"]},"db":{"type":"string","enum":["connected","disconnected"]},"timestamp":{"type":"string","format":"date-time"}}},"ServiceErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"},"category":{"type":"string"}}},"ValidationErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","details"]},"GenericSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true}}},"CreateClientRequest":{"type":"object","required":["name","cpfCnpj","address","number","neighborhood","postalCode","city","state","mobilePhone","emails","companySize","taxRegime","marketSegment","origin"],"properties":{"name":{"type":"string","minLength":3,"description":"Razão Social do cliente.","example":"Padaria Pão Quente LTDA"},"tradeName":{"type":"string","description":"Nome Fantasia do cliente (opcional).","example":"Pão Quente"},"cpfCnpj":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do cliente.","example":"12345678000199"},"address":{"type":"string","minLength":3,"description":"Endereço (logradouro) do cliente.","example":"Rua das Flores"},"number":{"type":"string","minLength":1,"description":"Número do endereço.","example":"123"},"complement":{"type":"string","description":"Complemento do endereço (opcional).","example":"Sala 10"},"neighborhood":{"type":"string","minLength":3,"description":"Bairro do cliente.","example":"Centro"},"postalCode":{"type":"string","pattern":"^\\d{8}$","description":"CEP do cliente, 8 dígitos sem formatação.","example":"30130000"},"city":{"type":"string","minLength":2,"description":"Cidade do cliente.","example":"Belo Horizonte"},"state":{"type":"string","minLength":2,"maxLength":2,"description":"Sigla do estado (UF).","example":"MG"},"phone":{"type":"string","pattern":"^\\d{10}$","description":"Telefone fixo com DDD, 10 dígitos (opcional).","example":"3133224455"},"mobilePhone":{"type":"string","pattern":"^\\d{11}$","description":"Celular com DDD, 11 dígitos.","example":"31998765432"},"emails":{"type":"array","maxItems":20,"minItems":1,"description":"Lista de emails do cliente usada pelos fluxos de notificacao.","items":{"type":"string","format":"email"},"example":["contato@paoquente.com","financeiro@paoquente.com"]},"companySize":{"type":"string","description":"Porte da empresa do cliente.","enum":["Microempreendedor Individual","Microempresa","Empresa de Pequeno Porte","Média Empresa","Grande Empresa","Entidade do Terceiro Setor"],"example":"Microempresa"},"taxRegime":{"type":"string","description":"Regime tributário do cliente.","enum":["Simples Nacional","Lucro Presumido","Lucro Real","Lucro Arbitrado","Isento","Imune"],"example":"Simples Nacional"},"marketSegment":{"type":"string","description":"ID de um segmento existente no licenciado e na empresa autenticada. ID malformado ou referência fora desse escopo retorna 404 CLIENT.MARKET_SEGMENT.NOT_FOUND.","example":"66e1c8f0f2f0b2a6c7a8dAAA"},"origin":{"type":"string","description":"Origem do cliente.","enum":["Busca Google","Instagram","Facebook","Tik Tok","Evento próprio","Evento entidades","Indicação de Cliente","Indicação de Parceiro","Rádio","TV","Outro"],"example":"Indicação de Cliente"},"retainISS":{"type":"boolean","description":"Indica se o ISS deve ser retido para notas emitidas a este cliente.","example":true},"contactPeople":{"type":"string","description":"Nomes das pessoas de contato na empresa do cliente (opcional).","example":"João da Silva, Maria Oliveira"},"observation":{"type":"string","description":"Observações gerais sobre o cliente (opcional).","example":"Cliente com potencial para upsell."}}},"UpdateClientRequest":{"type":"object","required":["cpfCnpj","postalCode"],"properties":{"name":{"type":"string","minLength":3,"description":"Razão Social do cliente.","example":"Padaria Pão Quente & Cia"},"tradeName":{"type":"string","description":"Nome Fantasia do cliente.","example":"Pão Quente & Cia"},"cpfCnpj":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do cliente.","example":"12345678000199"},"address":{"type":"string","minLength":3,"description":"Endereço (logradouro) do cliente.","example":"Avenida Principal"},"number":{"type":"string","minLength":1,"description":"Número do endereço.","example":"456"},"complement":{"type":"string","description":"Complemento do endereço.","example":"Loja 2"},"neighborhood":{"type":"string","minLength":3,"description":"Bairro do cliente.","example":"Novo Centro"},"postalCode":{"type":"string","pattern":"^\\d{8}$","description":"CEP do cliente, 8 dígitos sem formatação.","example":"30130001"},"city":{"type":"string","minLength":2,"description":"Cidade do cliente.","example":"Belo Horizonte"},"state":{"type":"string","minLength":2,"maxLength":2,"description":"Sigla do estado (UF).","example":"MG"},"phone":{"type":"string","pattern":"^\\d{10}$","description":"Telefone fixo com DDD, 10 dígitos.","example":"3133225566"},"mobilePhone":{"type":"string","pattern":"^\\d{11}$","description":"Celular com DDD, 11 dígitos.","example":"31998765433"},"emails":{"type":"array","maxItems":20,"minItems":1,"description":"Lista de emails do cliente usada pelos fluxos de notificacao.","items":{"type":"string","format":"email"},"example":["novocontato@paoquente.com","fiscal@paoquente.com"]},"companySize":{"type":"string","description":"Porte da empresa do cliente.","enum":["Microempreendedor Individual","Microempresa","Empresa de Pequeno Porte","Média Empresa","Grande Empresa","Entidade do Terceiro Setor"],"example":"Empresa de Pequeno Porte"},"taxRegime":{"type":"string","description":"Regime tributário do cliente.","enum":["Simples Nacional","Lucro Presumido","Lucro Real","Lucro Arbitrado","Isento","Imune"],"example":"Lucro Presumido"},"marketSegment":{"type":"string","description":"ID de um segmento existente no licenciado autenticado e na empresa persistida do cliente. Reenviar o mesmo ID também exige validação; omitir preserva o segmento atual. ID malformado ou referência fora desse escopo retorna 404 CLIENT.MARKET_SEGMENT.NOT_FOUND.","example":"66e1c8f0f2f0b2a6c7a8dBBB"},"origin":{"type":"string","description":"Origem do cliente.","enum":["Busca Google","Instagram","Facebook","Tik Tok","Evento próprio","Evento entidades","Indicação de Cliente","Indicação de Parceiro","Rádio","TV","Outro"],"example":"Busca Google"},"retainISS":{"type":"boolean","description":"Indica se o ISS deve ser retido para notas emitidas a este cliente.","example":false},"contactPeople":{"type":"string","description":"Nomes das pessoas de contato na empresa do cliente.","example":"Carlos Mendes"},"observation":{"type":"string","description":"Observações gerais sobre o cliente.","example":"Negociar novo contrato em Dezembro."}}},"PaginatedClientResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClientResponse"}},"total":{"type":"integer","format":"int32","description":"Número total de clientes que correspondem à consulta.","example":120}}},"ClientOptionItem":{"type":"object","properties":{"_id":{"type":"string","example":"66e1c7f0f2f0b2a6c7a8d999"},"name":{"type":"string","example":"Cliente Exemplo 1"},"tradeName":{"type":"string","example":"Exemplo"}}},"ClientOptionsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClientOptionItem"}},"total":{"type":"integer","format":"int32","description":"Número total de clientes retornados na consulta.","example":120}}},"ClientResponse":{"type":"object","properties":{"_id":{"type":"string","example":"66e1c7f0f2f0b2a6c7a8d999"},"name":{"type":"string","example":"Cliente Exemplo 1"},"emails":{"type":"array","items":{"type":"string","format":"email"},"example":["cliente1@exemplo.com","financeiro@cliente1.com"]},"mobilePhone":{"type":"string","example":"11987654321"},"cpfCnpj":{"type":"string","example":"12345678901"},"retainISS":{"type":"boolean","example":true},"marketSegment":{"type":"object","nullable":true,"properties":{"_id":{"type":"string","example":"66e1c8f0f2f0b2a6c7a8dAAA"},"name":{"type":"string","example":"Varejo"}}},"licensedId":{"type":"string","example":"66dfb4a6b1bbd81234abcd01"},"companyId":{"type":"string","example":"66dfb4a6b1bbd81234abcd02"}}},"SingleClientResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Client retrieved successfully!"},"data":{"$ref":"#/components/schemas/ClientResponse"}}},"ClientReferenceErrorResponse":{"type":"object","required":["status","message","category"],"properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string"},"category":{"type":"string","enum":["CLIENT.UPDATE.NOT_FOUND","CLIENT.MARKET_SEGMENT.NOT_FOUND"]}}},"SupplierInput":{"type":"object","additionalProperties":false,"required":["name","cpfCnpj","address","number","neighborhood","postalCode","city","state","emails"],"properties":{"name":{"type":"string","minLength":3},"tradeName":{"type":"string"},"cpfCnpj":{"type":"string","pattern":"^(?:[0-9]{11}|[0-9]{14})$"},"address":{"type":"string","minLength":3},"streetTypeEnum":{"type":"string","enum":["Alameda","Avenida","Chácara","Colônia","Condomínio","Estância","Estrada","Fazenda","Praça","Prolongamento","Rodovia","Rua","Sítio","Travessa","Vicinal","Eqnp"]},"number":{"type":"string","minLength":1},"complement":{"type":"string"},"neighborhood":{"type":"string","minLength":3},"postalCode":{"type":"string","pattern":"^[0-9]{8}$"},"city":{"type":"string","minLength":2},"state":{"type":"string","minLength":2,"maxLength":2},"phone":{"type":"string","pattern":"^[0-9]{10}$"},"mobilePhone":{"type":"string","pattern":"^[0-9]{11}$"},"emails":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"email"}},"marketSegment":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"contactPeople":{"type":"string"},"observation":{"type":"string"}}},"SupplierUpdate":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":3},"tradeName":{"type":"string"},"status":{"type":"integer","enum":[0,1]},"cpfCnpj":{"type":"string","pattern":"^(?:[0-9]{11}|[0-9]{14})$"},"address":{"type":"string","minLength":3},"streetTypeEnum":{"type":"string","enum":["Alameda","Avenida","Chácara","Colônia","Condomínio","Estância","Estrada","Fazenda","Praça","Prolongamento","Rodovia","Rua","Sítio","Travessa","Vicinal","Eqnp"]},"number":{"type":"string","minLength":1},"complement":{"type":"string"},"neighborhood":{"type":"string","minLength":3},"postalCode":{"type":"string","pattern":"^[0-9]{8}$"},"city":{"type":"string","minLength":2},"state":{"type":"string","minLength":2,"maxLength":2},"phone":{"type":"string","pattern":"^[0-9]{10}$"},"mobilePhone":{"type":"string","pattern":"^[0-9]{11}$"},"emails":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"email"}},"marketSegment":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"contactPeople":{"type":"string"},"observation":{"type":"string"}}},"SupplierMutationRecord":{"type":"object","required":["_id","name","cpfCnpj","status"],"properties":{"_id":{"type":"string"},"name":{"type":"string"},"tradeName":{"type":"string"},"cpfCnpj":{"type":"string"},"status":{"type":"integer","enum":[0,1]},"marketSegment":{"type":"string"}}},"SupplierReadRecord":{"type":"object","required":["_id","name","cpfCnpj","status"],"properties":{"_id":{"type":"string"},"name":{"type":"string"},"tradeName":{"type":"string"},"cpfCnpj":{"type":"string"},"status":{"type":"integer","enum":[0,1]},"marketSegment":{"nullable":true,"type":"object","required":["_id","name"],"properties":{"_id":{"type":"string"},"name":{"type":"string","nullable":true}}}}},"SupplierListResponse":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupplierReadRecord"}},"total":{"type":"integer","minimum":0}}},"SupplierMutationResponse":{"type":"object","required":["success","message","data"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/SupplierMutationRecord"}}},"SupplierReadResponse":{"type":"object","required":["success","message","data"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/SupplierReadRecord"}}},"SupplierDeleteResponse":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"}}},"SupplierValidationErrorResponse":{"type":"object","required":["error","details"],"properties":{"error":{"type":"string","enum":["VALIDATION_FAILED"]},"details":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"SupplierServiceErrorResponse":{"type":"object","required":["status","message","category"],"properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string"},"category":{"type":"string"}}},"ServiceStatus":{"type":"integer","enum":[0,1],"description":"Status do serviço (`StatusEnum`): 0 = inativo, 1 = ativo.","example":1},"ServiceIssTaxationType":{"type":"integer","minimum":1,"maximum":8,"description":"Tipo de tributação do ISS (inteiro; decimal responde 400), enviado à PlugNotas na emissão da NFS-e:\n1 = isento de ISS, 2 = imune, 3 = não incidência no município, 4 = não tributável,\n5 = retido, 6 = tributável dentro do município, 7 = tributável fora do município,\n8 = tributável dentro do município pelo tomador.\n","example":6},"ServiceIssEnforceability":{"type":"integer","minimum":1,"maximum":7,"description":"Exigibilidade do ISS (inteiro; decimal responde 400), enviada à PlugNotas na emissão da NFS-e:\n1 = exigível, 2 = não incidência, 3 = isenção, 4 = exportação, 5 = imunidade,\n6 = suspensa por ação judicial, 7 = suspensa por ação administrativa.\n","example":1},"ServiceItemInput":{"type":"object","required":["oldCode","code","text"],"description":"Item da Lista de Serviços (LC 116). Os três valores precisam ser de um mesmo item da\nlista aceita pela API; valores fora dela respondem 400.\n","properties":{"oldCode":{"type":"string","description":"Código do item no formato da LC 116 (subitem).","example":"1.07"},"code":{"type":"string","description":"Código de seis dígitos do item (código de tributação nacional).","example":"010701"},"text":{"type":"string","description":"Texto oficial do item.","example":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados."}}},"ServiceNbsItemInput":{"type":"object","required":["code","text"],"description":"Item da Nomenclatura Brasileira de Serviços (NBS). Código e texto precisam constar da\nlista NBS aceita pela API; valores fora dela respondem 400.\n","properties":{"code":{"type":"string","description":"Código NBS de nove dígitos.","example":"115013000"},"text":{"type":"string","description":"Descrição oficial do item NBS.","example":"Serviços de suporte em tecnologia da informação (TI)"}}},"ServiceIbsCbsInput":{"type":"object","required":["operationCode","cst","cct","personalOperation"],"description":"Classificação do serviço para IBS/CBS. Os textos são gravados sem espaços nas pontas.","properties":{"operationCode":{"type":"string","minLength":6,"maxLength":6,"description":"Código de operação IBS/CBS (6 caracteres).","example":"050101"},"cst":{"type":"string","minLength":3,"maxLength":3,"description":"CST do IBS/CBS (3 caracteres).","example":"000"},"cct":{"type":"string","minLength":6,"maxLength":6,"description":"Código de classificação tributária do IBS/CBS (6 caracteres).","example":"000001"},"personalOperation":{"type":"boolean","description":"Indica operação de uso pessoal.","example":false}}},"CreateServiceRequest":{"type":"object","required":["serviceItem","nbsItem","discrimination","serviceMunicipalCode","ibscbs","aliquotISS","issTaxationType","issEnforceability"],"properties":{"serviceItem":{"$ref":"#/components/schemas/ServiceItemInput"},"nbsItem":{"$ref":"#/components/schemas/ServiceNbsItemInput"},"discrimination":{"type":"string","minLength":1,"description":"Discriminação detalhada do serviço prestado (gravada sem espaços nas pontas).","example":"Suporte técnico em informática, inclusive instalação, configuração e manutenção de programas de computação e bancos de dados."},"serviceMunicipalCode":{"type":"string","minLength":1,"description":"Código municipal do serviço (varia por prefeitura).","example":"620910001"},"nationalMunicipalTaxCode":{"type":"string","pattern":"^\\d{3}$","description":"Código municipal de três dígitos usado como cTribMun na DPS nacional. É opcional; quando ausente, a emissão nacional reaproveita serviceMunicipalCode somente se ele já tiver exatamente três dígitos. Códigos de outro formato não são truncados.","example":"501"},"ibscbs":{"$ref":"#/components/schemas/ServiceIbsCbsInput"},"retainISS":{"type":"boolean","description":"Retenção do ISS. Quando omitido, não é gravado nem retornado."},"retainIRRF":{"type":"boolean","description":"Retenção do IRRF. Quando omitido, não é gravado nem retornado."},"retainINSS":{"type":"boolean","description":"Retenção do INSS. Quando omitido, não é gravado nem retornado."},"retainCSRF":{"type":"boolean","description":"Retenção de PIS/COFINS/CSLL (CSRF). Quando omitido, não é gravado nem retornado."},"aliquotISS":{"type":"number","description":"Alíquota do ISS (percentual).","example":2.17},"issTaxationType":{"$ref":"#/components/schemas/ServiceIssTaxationType"},"issEnforceability":{"$ref":"#/components/schemas/ServiceIssEnforceability"},"aliquotIRRF":{"type":"number","example":1.5},"aliquotINSS":{"type":"number","example":3},"aliquotPIS":{"type":"number","example":0.65},"aliquotCOFINS":{"type":"number","example":3},"aliquotCSLL":{"type":"number","example":1},"minValueIRRF":{"type":"number","example":100},"minValueINSS":{"type":"number","example":75},"minValueCSRF":{"type":"number","example":30},"status":{"allOf":[{"$ref":"#/components/schemas/ServiceStatus"}],"default":1,"description":"Status inicial do serviço (0 = inativo, 1 = ativo). Quando omitido, o serviço é criado ativo."}}},"UpdateServiceRequest":{"type":"object","description":"Todos os campos são opcionais; apenas os enviados são gravados. `serviceItem`, `nbsItem`\ne `ibscbs`, quando enviados, precisam vir completos, com as mesmas regras da criação.\n","properties":{"serviceItem":{"$ref":"#/components/schemas/ServiceItemInput"},"nbsItem":{"$ref":"#/components/schemas/ServiceNbsItemInput"},"discrimination":{"type":"string","minLength":1,"example":"Suporte técnico remoto em informática."},"serviceMunicipalCode":{"type":"string","minLength":1,"example":"620910001"},"nationalMunicipalTaxCode":{"type":"string","pattern":"^\\d{3}$","description":"Código municipal de três dígitos usado como cTribMun na DPS nacional. Opcional; sem ele, só há fallback de serviceMunicipalCode quando o valor dele tiver exatamente três dígitos.","example":"501"},"ibscbs":{"$ref":"#/components/schemas/ServiceIbsCbsInput"},"retainISS":{"type":"boolean"},"retainIRRF":{"type":"boolean"},"retainINSS":{"type":"boolean"},"retainCSRF":{"type":"boolean"},"aliquotISS":{"type":"number","example":3},"issTaxationType":{"$ref":"#/components/schemas/ServiceIssTaxationType"},"issEnforceability":{"$ref":"#/components/schemas/ServiceIssEnforceability"},"aliquotIRRF":{"type":"number"},"aliquotINSS":{"type":"number"},"aliquotPIS":{"type":"number"},"aliquotCOFINS":{"type":"number"},"aliquotCSLL":{"type":"number"},"minValueIRRF":{"type":"number"},"minValueINSS":{"type":"number"},"minValueCSRF":{"type":"number"},"status":{"$ref":"#/components/schemas/ServiceStatus"}}},"PaginatedServiceResponse":{"type":"object","required":["success","message","data"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string","example":"Services retrieved successfully!"},"data":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceResponse"}},"total":{"type":"integer","minimum":0,"description":"Número total de serviços que correspondem à consulta.","example":25}}}}},"ServiceResponse":{"type":"object","description":"Serviço como gravado. Campos opcionais só aparecem quando foram gravados; registros\nmais antigos podem trazer `null` em `status` e nos campos de retenção, alíquota e valor mínimo.\n`minValueISS` não é exposto.\n","required":["_id","licensedId","companyId","serviceItem","nbsItem","ibscbs","serviceMunicipalCode","discrimination","aliquotISS","issTaxationType","issEnforceability","status"],"properties":{"_id":{"type":"string","example":"66e1c7f0f2f0b2a6c7a8d999"},"licensedId":{"type":"string","example":"66dfb4a6b1bbd81234abcd01"},"companyId":{"type":"string","example":"66dfb4a6b1bbd81234abcd02"},"__v":{"type":"integer","description":"Versão do registro.","example":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"serviceItem":{"type":"object","required":["code","text"],"properties":{"oldCode":{"type":"string","description":"Ausente em registros mais antigos gravados sem o código antigo.","example":"1.07"},"code":{"type":"string","example":"010701"},"text":{"type":"string"}}},"nbsItem":{"type":"object","required":["code","text"],"properties":{"code":{"type":"string","example":"115013000"},"text":{"type":"string"}}},"ibscbs":{"type":"object","required":["operationCode","cst","cct","personalOperation"],"properties":{"operationCode":{"type":"string","example":"050101"},"cst":{"type":"string","example":"000"},"cct":{"type":"string","example":"000001"},"personalOperation":{"type":"boolean"}}},"serviceMunicipalCode":{"type":"string","example":"620910001"},"nationalMunicipalTaxCode":{"type":"string","nullable":true,"description":"Presente apenas quando foi gravado.","example":"501"},"discrimination":{"type":"string"},"issTaxationType":{"$ref":"#/components/schemas/ServiceIssTaxationType"},"issEnforceability":{"$ref":"#/components/schemas/ServiceIssEnforceability"},"status":{"type":"integer","enum":[0,1],"nullable":true,"description":"0 = inativo, 1 = ativo; `null` em registros mais antigos gravados sem status.","example":1},"retainISS":{"type":"boolean","nullable":true},"retainIRRF":{"type":"boolean","nullable":true},"retainINSS":{"type":"boolean","nullable":true},"retainCSRF":{"type":"boolean","nullable":true},"aliquotISS":{"type":"number","example":2.17},"aliquotIRRF":{"type":"number","nullable":true},"aliquotINSS":{"type":"number","nullable":true},"aliquotPIS":{"type":"number","nullable":true},"aliquotCOFINS":{"type":"number","nullable":true},"aliquotCSLL":{"type":"number","nullable":true},"minValueIRRF":{"type":"number","nullable":true},"minValueINSS":{"type":"number","nullable":true},"minValueCSRF":{"type":"number","nullable":true}}},"SingleServiceResponse":{"type":"object","required":["success","message","data"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string","example":"Service retrieved successfully!"},"data":{"$ref":"#/components/schemas/ServiceResponse"}}},"ServiceDeleteResponse":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string","example":"Service deleted successfully!"}}},"ServiceCatalogErrorResponse":{"type":"object","required":["status","message","category"],"properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","example":"Service not found."},"category":{"type":"string","description":"Categoria do erro (ServiceException.category).","example":"SERVICE.GET.NOT_FOUND"}}},"ServiceCatalogValidationErrorResponse":{"type":"object","required":["error","details"],"properties":{"error":{"type":"string","enum":["VALIDATION_FAILED"]},"details":{"type":"array","description":"Lista de violações reportadas pelo Zod.","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string","example":"discrimination"},"message":{"type":"string","example":"Discriminação é obrigatória"}}}}}},"Contract":{"type":"object","properties":{"_id":{"type":"string","description":"ID do contrato"},"companyId":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}}},"clientId":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}}},"serviceId":{"type":"object","properties":{"_id":{"type":"string"},"serviceItem":{"type":"string"}}},"status":{"type":"integer","description":"Status somente leitura, deduzido automaticamente pelo backend"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"BillingProcessingAccountReceivableStage":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["NOT_APPLICABLE","AWAITING_SERVICE_INVOICE","PENDING","SUCCESS","ERROR"]},"error":{"type":"object","properties":{"category":{"type":"string"},"message":{"type":"string"}}},"accountReceivableStatus":{"type":"string","description":"Status financeiro atual da conta a receber vinculada, separado do status técnico da etapa.","enum":["PENDING","PAID","OVERDUE","CANCELED"]}}},"BillingProcessingServiceInvoiceStage":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["NOT_APPLICABLE","AWAITING_SERVICE_INVOICE","PENDING","SUCCESS","ERROR"]},"error":{"type":"object","properties":{"category":{"type":"string"},"message":{"type":"string"}}},"serviceInvoiceStatus":{"type":"string","description":"Status atual da NFS-e vinculada, separado do status técnico da etapa.","enum":["pending","processing","issued","error","cancelling","cancelled","deleted"]}}},"BillingProcessingBankSlipStage":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["NOT_APPLICABLE","AWAITING_SERVICE_INVOICE","PENDING","SUCCESS","ERROR"]},"error":{"type":"object","properties":{"category":{"type":"string"},"message":{"type":"string"}}},"bankSlipStatus":{"type":"string","description":"Status atual do boleto vinculado, separado do status técnico da etapa.","enum":["processing","issued","paid","cancelled","expired","error","deleted"]}}},"BillingProcessing":{"type":"object","required":["id","clientName","contractReference","amount","dueDate","processingDate","status","serviceInvoice","accountReceivable","bankSlip"],"properties":{"id":{"type":"string"},"clientName":{"type":"string"},"contractReference":{"type":"string"},"amount":{"type":"number"},"dueDate":{"type":"string","format":"date-time"},"processingDate":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["PENDING","SUCCESS","ERROR"]},"serviceInvoice":{"$ref":"#/components/schemas/BillingProcessingServiceInvoiceStage"},"accountReceivable":{"$ref":"#/components/schemas/BillingProcessingAccountReceivableStage"},"bankSlip":{"$ref":"#/components/schemas/BillingProcessingBankSlipStage"}}},"Installment":{"type":"object","properties":{"amount":{"type":"number"},"dueDate":{"type":"string","format":"date"}}},"BankSlipConfig":{"type":"object","properties":{"agendaDays":{"type":"integer","minimum":0,"maximum":60,"description":"Prazo após o vencimento; obrigatório a partir de 1 quando houver multa ou juros."},"discount":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","FIXED","PERCENT"]},"daysBeforeDueDate":{"type":"integer","minimum":1,"maximum":365},"amountOrPercent":{"type":"number"}}},"fine":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","FIXED","PERCENT"]},"amountOrPercent":{"type":"number"}}},"interest":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","DAILY_VALUE","MONTHLY_PERCENT"]},"amountOrPercent":{"type":"number"}}}}},"ServiceInvoiceConfig":{"type":"object","properties":{"defaultDiscrimination":{"type":"string"}}},"RecurringContract":{"type":"object","required":["clientId","serviceId","contractDate","value","isRecurring","dueDay"],"properties":{"clientId":{"type":"string"},"serviceId":{"type":"string"},"contractDate":{"type":"string","format":"date"},"value":{"type":"number"},"isRecurring":{"type":"boolean","enum":[true]},"billingStart":{"type":"string","format":"date"},"billingEnd":{"type":"string","format":"date","nullable":true},"dueDay":{"type":"integer","minimum":1,"maximum":31},"issueBankSlipOnBilling":{"type":"boolean"},"issueServiceInvoiceOnBilling":{"type":"boolean"},"sendBankSlipEmailToIssuerOnBilling":{"type":"boolean"},"sendBankSlipEmailToCustomerOnBilling":{"type":"boolean"},"sendServiceInvoiceEmailToIssuerOnBilling":{"type":"boolean"},"sendServiceInvoiceEmailToCustomerOnBilling":{"type":"boolean"},"bankSlipConfig":{"$ref":"#/components/schemas/BankSlipConfig"},"serviceInvoiceConfig":{"$ref":"#/components/schemas/ServiceInvoiceConfig"}}},"NonRecurringContract":{"type":"object","required":["clientId","serviceId","contractDate","value","isRecurring","installments"],"properties":{"clientId":{"type":"string"},"serviceId":{"type":"string"},"contractDate":{"type":"string","format":"date"},"value":{"type":"number"},"isRecurring":{"type":"boolean","enum":[false]},"billingStart":{"type":"string","format":"date"},"dueDay":{"type":"integer","minimum":1,"maximum":31},"installmentsCount":{"type":"integer"},"installments":{"type":"array","maxItems":120,"items":{"$ref":"#/components/schemas/Installment"}},"issueBankSlipOnBilling":{"type":"boolean"},"issueServiceInvoiceOnBilling":{"type":"boolean"},"sendBankSlipEmailToIssuerOnBilling":{"type":"boolean"},"sendBankSlipEmailToCustomerOnBilling":{"type":"boolean"},"sendServiceInvoiceEmailToIssuerOnBilling":{"type":"boolean"},"sendServiceInvoiceEmailToCustomerOnBilling":{"type":"boolean"},"bankSlipConfig":{"$ref":"#/components/schemas/BankSlipConfig"},"serviceInvoiceConfig":{"$ref":"#/components/schemas/ServiceInvoiceConfig"}}},"UpdateContract":{"type":"object","properties":{"clientId":{"type":"string"},"serviceId":{"type":"string"},"contractDate":{"type":"string","format":"date"},"value":{"type":"number"},"issueBankSlipOnBilling":{"type":"boolean","description":"Emite boleto nos próximos faturamentos. Pode ser alterado depois de o contrato faturar; os ciclos já faturados mantêm o valor que tinham."},"issueServiceInvoiceOnBilling":{"type":"boolean","description":"Emite NFS-e nos próximos faturamentos. Pode ser alterado depois de o contrato faturar; os ciclos já faturados mantêm o valor que tinham."},"sendBankSlipEmailToIssuerOnBilling":{"type":"boolean"},"sendBankSlipEmailToCustomerOnBilling":{"type":"boolean"},"sendServiceInvoiceEmailToIssuerOnBilling":{"type":"boolean"},"sendServiceInvoiceEmailToCustomerOnBilling":{"type":"boolean"},"billingStart":{"type":"string","format":"date"},"billingEnd":{"type":"string","format":"date","nullable":true},"dueDay":{"type":"integer","minimum":1,"maximum":31},"isRecurring":{"type":"boolean"},"installmentsCount":{"type":"integer"},"installments":{"type":"array","maxItems":120,"items":{"$ref":"#/components/schemas/Installment"}},"bankSlipConfig":{"$ref":"#/components/schemas/BankSlipConfig"},"serviceInvoiceConfig":{"$ref":"#/components/schemas/ServiceInvoiceConfig"}}},"ErrorResponse":{"type":"object","properties":{"category":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"CreateMarketSegmentRequest":{"type":"object","required":["name","isMain"],"properties":{"name":{"type":"string","minLength":2,"description":"Nome do segmento de mercado.","example":"Comércio"},"isMain":{"type":"boolean","description":"Indica se é um segmento principal (true) ou um subsegmento (false).","example":true},"parentId":{"type":"string","minLength":24,"maxLength":24,"description":"ID do segmento pai. Obrigatório se `isMain` for `false`.","example":"66e1c7f0f2f0b2a6c7a8d999"}}},"UpdateMarketSegmentRequest":{"type":"object","required":["isMain"],"properties":{"name":{"type":"string","minLength":2,"description":"Novo nome do segmento de mercado.","example":"Comércio Varejista"},"isMain":{"type":"boolean","description":"Indica se é um segmento principal (true) ou um subsegmento (false).","example":false},"parentId":{"type":"string","minLength":24,"maxLength":24,"description":"ID do segmento pai. Obrigatório se `isMain` for `false`.","example":"66e1c7f0f2f0b2a6c7a8d999"}}},"MarketSegmentResponse":{"type":"object","properties":{"_id":{"type":"string","example":"66e1c7f0f2f0b2a6c7a8dAAA"},"name":{"type":"string","example":"Comércio"},"isMain":{"type":"boolean","example":true},"parentId":{"type":"string","nullable":true,"example":null},"licensedId":{"type":"string","example":"66dfb4a6b1bbd81234abcd01"},"companyId":{"type":"string","example":"66dfb4a6b1bbd81234abcd02"}}},"ListMarketSegmentResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Market segments retrieved successfully!"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/MarketSegmentResponse"}],"properties":{"subSegments":{"type":"array","items":{"$ref":"#/components/schemas/MarketSegmentResponse"}}}}}}},"SingleMarketSegmentResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Market segment created successfully!"},"data":{"$ref":"#/components/schemas/MarketSegmentResponse"}}},"DocumentIssuanceErrorResponse":{"type":"object","required":["status","category","message"],"properties":{"status":{"type":"string","example":"error"},"category":{"type":"string"},"message":{"type":"string"}}},"BankSlipDiscountRule":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","FIXED","PERCENT"]},"daysBeforeDueDate":{"type":"integer","minimum":1},"amountOrPercent":{"type":"number","exclusiveMinimum":true,"minimum":0}}},"BankSlipFineRule":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","FIXED","PERCENT"]},"amountOrPercent":{"type":"number","exclusiveMinimum":true,"minimum":0}}},"BankSlipInterestRule":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","DAILY_VALUE","MONTHLY_PERCENT"]},"amountOrPercent":{"type":"number","exclusiveMinimum":true,"minimum":0}}},"AccountPayableInput":{"type":"object","additionalProperties":false,"required":["supplierId","value","dueDate"],"properties":{"supplierId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"value":{"type":"number","exclusiveMinimum":0},"dueDate":{"type":"string","format":"date"},"paymentDate":{"type":"string","format":"date","description":"Não pode ser futura."},"observation":{"type":"string","maxLength":2000}}},"AccountPayableUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"supplierId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"value":{"type":"number","exclusiveMinimum":0},"dueDate":{"type":"string","format":"date"},"paymentDate":{"type":"string","format":"date","nullable":true},"observation":{"type":"string","maxLength":2000}}},"AccountPayableStatusAction":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["PENDING","OVERDUE","PAID","CANCELED"]}}},"AccountPayable":{"type":"object","required":["_id","supplierId","value","dueDate","origin","status","createdAt"],"properties":{"_id":{"type":"string"},"supplierId":{"oneOf":[{"type":"string","description":"Identificador retornado nas mutações sem população."},{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}}}]},"value":{"type":"number"},"dueDate":{"type":"string","format":"date-time"},"paymentDate":{"type":"string","format":"date-time","nullable":true},"observation":{"type":"string"},"origin":{"type":"string","enum":["MANUAL","NFS_E_IMPORT","NFE_IMPORT"]},"fiscalSource":{"type":"object","properties":{"documentType":{"type":"string","enum":["NFS_E","NFE"]},"fiscalKey":{"type":"string"},"invoiceNumber":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"}}},"status":{"type":"string","enum":["PENDING","OVERDUE","PAID","CANCELED"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AccountPayableServiceError":{"type":"object","required":["status","category","message"],"properties":{"status":{"type":"string","enum":["error"]},"category":{"type":"string"},"message":{"type":"string"}}},"AccountPayableXmlImportWarning":{"type":"object","required":["field","code"],"properties":{"field":{"type":"string"},"code":{"type":"string","enum":["missing","invalid","ambiguous"]}}},"AccountPayableXmlSupplierCandidate":{"type":"object","properties":{"cpfCnpj":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"neighborhood":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"ibgeCode":{"type":"string"},"phone":{"type":"string"},"emails":{"type":"array","items":{"type":"string","format":"email"}},"streetTypeEnum":{"type":"string","enum":["Alameda","Avenida","Chácara","Colônia","Condomínio","Estância","Estrada","Fazenda","Praça","Prolongamento","Rodovia","Rua","Sítio","Travessa","Vicinal","Eqnp"]},"marketSegment":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}},"AccountPayableXmlImportPreview":{"type":"object","required":["documentType","fiscalKey","supplierCandidate","warnings","supplier","duplicate"],"properties":{"documentType":{"type":"string","enum":["NFS_E","NFE"]},"fiscalKey":{"type":"string"},"invoiceNumber":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"competenceDate":{"type":"string","format":"date-time"},"value":{"type":"number"},"observation":{"type":"string"},"recipientDocument":{"type":"string"},"suggestedDueDate":{"type":"string","format":"date-time"},"supplierCandidate":{"$ref":"#/components/schemas/AccountPayableXmlSupplierCandidate"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/AccountPayableXmlImportWarning"}},"supplier":{"nullable":true,"allOf":[{"type":"object","required":["_id","name","status"],"properties":{"_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"integer","enum":[0,1],"description":"0=inativo; 1=ativo."}}}]},"duplicate":{"type":"boolean"}}},"AccountPayableXmlImportPreviewResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/AccountPayableXmlImportPreview"}}},"AccountPayableXmlImportCreatedResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["account","fiscalKey","supplier"],"properties":{"account":{"$ref":"#/components/schemas/AccountPayable"},"fiscalKey":{"type":"string"},"supplier":{"type":"object","required":["id","name","created"],"description":"Fornecedor efetivamente resolvido na transação da importação.","properties":{"id":{"type":"string"},"name":{"type":"string"},"created":{"type":"boolean","description":"`true` quando a transação criou o fornecedor; `false` quando reutilizou um cadastro ativo."}}}}}}},"AccountPayableXmlImportDuplicateResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["duplicate","fiscalKey"],"properties":{"duplicate":{"type":"boolean","enum":[true]},"fiscalKey":{"type":"string"}}}}},"AccountPayableValidationError":{"type":"object","required":["error","details"],"properties":{"error":{"type":"string","enum":["VALIDATION_FAILED"]},"details":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"AccountPayableMutationResponse":{"type":"object","required":["success","message","data"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/AccountPayable"}}},"AccountPayableListResponse":{"type":"object","required":["success","message","data"],"properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AccountPayable"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"ServiceInvoiceValidationError":{"type":"object","additionalProperties":false,"required":["error","details"],"properties":{"error":{"type":"string","enum":["VALIDATION_FAILED"]},"details":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["field","message"],"properties":{"field":{"type":"string","example":"clientId"},"message":{"type":"string","example":"Client ID is required"}}}}}},"XmlImportError":{"type":"object","required":["status","category","message"],"properties":{"status":{"type":"string","enum":["error"]},"category":{"type":"string"},"message":{"type":"string"}}},"ServiceInvoiceXmlPreview":{"type":"object","additionalProperties":false,"required":["format","version","service","warnings","issuerMatchesCompany"],"properties":{"format":{"type":"string","enum":["national","abrasf","ginfes","other"]},"version":{"type":"string","description":"Versão identificada; string vazia quando indisponível em uma variante."},"issuerMatchesCompany":{"type":"boolean","nullable":true,"description":"true se o emitente é a empresa selecionada, false se difere, null se não identificado; não expõe o documento."},"service":{"type":"object","additionalProperties":false,"properties":{"serviceItem":{"type":"object","required":["code","oldCode","text"],"properties":{"code":{"type":"string"},"oldCode":{"type":"string"},"text":{"type":"string"}}},"nbsItem":{"type":"object","required":["code","text"],"properties":{"code":{"type":"string"},"text":{"type":"string"}}},"discrimination":{"type":"string"},"serviceMunicipalCode":{"type":"string"},"aliquotISS":{"type":"number","minimum":0,"maximum":100},"retainISS":{"type":"boolean"},"issTaxationType":{"type":"integer","enum":[1,2,6,7]},"issEnforceability":{"type":"integer","minimum":1,"maximum":7},"ibscbs":{"type":"object","additionalProperties":false,"properties":{"operationCode":{"type":"string","pattern":"^\\d{6}$"},"cst":{"type":"string","pattern":"^\\d{3}$"},"cct":{"type":"string","pattern":"^\\d{6}$"},"personalOperation":{"type":"boolean"}}}}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Caminho em service do campo que exige revisão manual."},"code":{"type":"string","enum":["missing","invalid","ambiguous"]}}}}}},"ServiceInvoiceRecord":{"type":"object","additionalProperties":true,"properties":{"historyData":{"type":"object","nullable":true,"description":"Snapshot fiscal não secreto usado na emissão. Pode ser parcial ou ausente em NFS-es mais antigas, emitidas antes de o snapshot ser gravado; consumidores não devem usar os cadastros atuais como fallback.","properties":{"issuer":{"type":"object","properties":{"ibgeCode":{"type":"string","example":"2304400"},"cpfCnpj":{"type":"string","example":"12345678000190"}}},"customer":{"type":"object","properties":{"cpfCnpj":{"type":"string"},"businessName":{"type":"string"},"municipalRegistration":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"object","additionalProperties":true}}},"service":{"type":"object","properties":{"serviceItem":{"type":"object","properties":{"code":{"type":"string","example":"010701"},"oldCode":{"type":"string"},"text":{"type":"string"}}},"nbsItem":{"type":"object","additionalProperties":true},"municipalTaxCode":{"type":"string"},"nationalMunicipalTaxCode":{"type":"string","nullable":true,"description":"Código municipal de três dígitos usado na DPS nacional quando presente no cadastro na criação da nota. Pode estar ausente em notas anteriores a esse campo; não inferir a partir do serviço atual.","example":"501"},"description":{"type":"string"},"ibscbs":{"type":"object","additionalProperties":true},"iss":{"type":"object","additionalProperties":true},"retentions":{"type":"object","additionalProperties":true},"amount":{"type":"object","properties":{"service":{"type":"number"}}}}},"invoice":{"type":"object","properties":{"number":{"type":"string","description":"Número fiscal da NFS-e preservado no momento da emissão.","example":"584"},"amount":{"type":"number"},"additionalInformation":{"type":"string"}}},"issuance":{"type":"object","properties":{"channel":{"type":"string","enum":["plugnotas_municipal","sefin_national"]},"environment":{"type":"string","enum":["production","homologation"]},"issuedAt":{"type":"string","format":"date-time"},"competenceDate":{"type":"string","format":"date"},"municipalRegistration":{"type":"string"},"stateRegistration":{"type":"string"},"taxRegime":{"type":"number"},"specialTaxRegime":{"type":"number"},"isSimplesOptant":{"type":"boolean"},"hasFiscalIncentive":{"type":"boolean"},"isCulturalIncentivator":{"type":"boolean"},"serviceInvoiceProduction":{"type":"boolean"}}}}}}},"ServiceInvoiceResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ServiceInvoiceRecord"}}},"ServiceInvoiceListResponse":{"type":"object","required":["items","total","page","limit","totalPages"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceInvoiceRecord"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer","description":"Total de páginas; `0` quando a consulta usa `limit=0` (todos os itens)."}}},"ServiceInvoiceErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ServiceInvoiceError"}]}}},"ServiceInvoiceError":{"type":"object","required":["code"],"description":"Último erro gravado na NFS-e. Em rejeição definitiva do provedor na emissão (SEFIN nacional ou\nPlugNotas, resposta 400) o erro traz também `provider`, `providerHttpStatus`, `providerCode`,\n`providerReason` e `rejections`, com o mesmo conteúdo de `details` da resposta da emissão.\nEm status do PlugNotas não mapeado (`code` `UNMAPPED_PROVIDER_STATUS`, como `INTERROMPIDO`\nquando o PlugNotas esgota as tentativas de emissão) o erro traz `provider`, `status` e, quando\no PlugNotas envia, `providerCode` e `providerReason` sanitizados.\nNotas com erro mais antigas podem ter só `message` (sem `code`).\n","properties":{"code":{"type":"string","description":"Código do erro (`SERVICE_INVOICE_REJECTED` no webhook municipal; a categoria da API, como `SERVICE_INVOICE.NATIONAL_ISSUE_FAILED`, na rejeição síncrona).","example":"SERVICE_INVOICE.NATIONAL_ISSUE_FAILED"},"message":{"type":"string","description":"Mensagem técnica do ClickFin, sem dados pessoais do provedor.","example":"SEFIN rejected national service invoice: E0207: CPF do tomador não encontrado no cadastro CPF."},"provider":{"type":"string","description":"Provedor que recusou (`sefin_national` ou `plugnotas`) ou identificador do provedor para status não mapeados.","example":"sefin_national"},"providerHttpStatus":{"type":"integer","description":"Status HTTP devolvido pelo provedor na rejeição síncrona.","example":400},"status":{"type":"string","description":"Status do provedor para status não mapeados."},"providerCode":{"type":"string","maxLength":120,"description":"Código técnico de rejeição (primeiro item), quando retornado e seguro para exibição.","example":"E0207"},"providerReason":{"type":"string","maxLength":500,"description":"Motivo de rejeição sanitizado (mensagem do provedor ou primeiro item), quando retornado e seguro para exibição.","example":"CPF do tomador não encontrado no cadastro CPF."},"rejections":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ServiceInvoiceProviderRejectionItem"}}},"additionalProperties":true},"ServiceInvoiceProviderRejectionItem":{"type":"object","required":["reason"],"properties":{"code":{"type":"string","maxLength":120,"description":"Código do provedor (SEFIN).","example":"E0207"},"field":{"type":"string","maxLength":120,"description":"Campo recusado (validação de esquema da PlugNotas).","example":"tomador.cpfCnpj"},"reason":{"type":"string","maxLength":500,"example":"CPF do tomador não encontrado no cadastro CPF."}}},"ServiceInvoiceProviderRejection":{"type":"object","description":"Rejeição definitiva do provedor, sanitizada: textos com CPF/CNPJ, e-mail ou telefone são\ndescartados; a resposta bruta do provedor só vai para os logs.\n","required":["provider","providerHttpStatus","rejections"],"properties":{"provider":{"type":"string","enum":["sefin_national","plugnotas"]},"providerHttpStatus":{"type":"integer","example":400},"providerCode":{"type":"string","maxLength":120,"example":"E0207"},"providerReason":{"type":"string","maxLength":500,"example":"CPF do tomador não encontrado no cadastro CPF."},"rejections":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ServiceInvoiceProviderRejectionItem"}}}},"ServiceInvoiceOperationError":{"type":"object","required":["status","category","message"],"properties":{"status":{"type":"string","enum":["error"],"example":"error"},"category":{"type":"string","example":"SERVICE_INVOICE.NATIONAL_DPS_INVALID"},"message":{"type":"string","example":"National DPS contract rejects nationalMunicipalTaxCode: must contain exactly three digits."},"details":{"description":"Presente quando o provedor recusou a emissão (`SERVICE_INVOICE.NATIONAL_ISSUE_FAILED`, `SERVICE_INVOICE.ISSUE_FAILED`).","allOf":[{"$ref":"#/components/schemas/ServiceInvoiceProviderRejection"}]}}},"IssueServiceInvoiceRequest":{"type":"object","required":["serviceId","amount","sendInvoiceEmailToIssuer","sendInvoiceEmailToCustomer"],"properties":{"clientId":{"type":"string","description":"Cliente da emissao manual."},"serviceId":{"type":"string"},"amount":{"type":"number","minimum":0.01},"additionalInformation":{"type":"string"},"sendInvoiceEmailToIssuer":{"type":"boolean","description":"Define se esta emissao manual deve enviar a NFS-e por e-mail para a empresa."},"sendInvoiceEmailToCustomer":{"type":"boolean","description":"Define se esta emissao manual deve enviar a NFS-e por e-mail para o cliente."},"rps":{"type":"object","properties":{"number":{"type":"string"},"series":{"type":"string"},"issueDate":{"type":"string","format":"date-time"},"competence":{"type":"string","format":"date-time"}}}}},"SafeInterProviderDiagnostic":{"type":"object","description":"Diagnóstico limitado e mascarado de uma rejeição do Banco Inter.","required":["providerHttpStatus"],"properties":{"providerHttpStatus":{"type":"integer","description":"Status HTTP retornado pelo Banco Inter."},"violations":{"type":"array","maxItems":10,"items":{"type":"object","required":["property"],"properties":{"property":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_.[\\\\]-]+$","description":"Caminho de campo aceito pelo ClickFin; outros valores são descartados."}}}},"problem":{"type":"object","description":"Problem Details limitado e mascarado; não contém corpo bruto do provedor.","properties":{"title":{"type":"string","maxLength":500},"detail":{"type":"string","maxLength":500},"violations":{"type":"array","maxItems":10,"items":{"type":"object","required":["property"],"properties":{"property":{"type":"string","maxLength":128},"reason":{"type":"string","maxLength":500},"technicalValue":{"type":"string","maxLength":64,"description":"Valor permitido apenas para campos técnicos explicitamente aprovados."}}}}}}}},"BankSlipError":{"type":"object","properties":{"code":{"type":"string","description":"Categoria do erro. Para falhas do Banco Inter (`source: INTER`):\n`BANK_SLIP.PROVIDER.VALIDATION_ERROR` quando o Inter recusou a chamada (4xx),\n`BANK_SLIP.PROVIDER.UNAVAILABLE` quando o Inter não pôde atendê-la no momento\n(HTTP 429),\n`BANK_SLIP.PROVIDER.AUTH_FAILED`, `BANK_SLIP.PROVIDER.TIMEOUT`, entre outras.\n"},"message":{"type":"string"},"source":{"type":"string","enum":["INTER","CLICKFIN"]},"details":{"$ref":"#/components/schemas/SafeInterProviderDiagnostic"}}},"BankSlipErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/BankSlipError"}]}}},"BankSlipPayerSnapshot":{"type":"object","properties":{"name":{"type":"string"},"document":{"type":"string"},"email":{"type":"string","format":"email"}}},"BankSlipExternal":{"type":"object","properties":{"requestId":{"type":"string"},"ourNumber":{"type":"string"},"digitableLine":{"type":"string"},"barcode":{"type":"string"},"pixQrCode":{"type":"string"},"pixCopiaECola":{"type":"string"},"rawStatus":{"type":"string"}}},"BankSlipItem":{"type":"object","properties":{"_id":{"type":"string"},"licensedId":{"type":"string"},"companyId":{"type":"string"},"clientId":{"type":"string"},"status":{"type":"string","enum":["processing","issued","paid","cancelled","expired","error"]},"origin":{"type":"string","enum":["manual","automatic"]},"provider":{"type":"string","example":"inter"},"bank":{"type":"string","example":"inter"},"amount":{"type":"number","minimum":2.5},"dueDate":{"type":"string","format":"date-time"},"issueDate":{"type":"string","format":"date-time"},"description":{"type":"string"},"payerSnapshot":{"$ref":"#/components/schemas/BankSlipPayerSnapshot"},"external":{"$ref":"#/components/schemas/BankSlipExternal"},"error":{"$ref":"#/components/schemas/BankSlipError"}}},"SingleBankSlipResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/BankSlipItem"}}},"PaginatedBankSlipResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BankSlipItem"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer","description":"Total de páginas; `0` quando a consulta usa `limit=0` (todos os itens)."}}}}},"IssueBankSlipRequest":{"type":"object","required":["companyId","clientId","amount","dueDate","sendBankSlipEmailToIssuer","sendBankSlipEmailToCustomer"],"properties":{"companyId":{"type":"string","minLength":24,"maxLength":24},"clientId":{"type":"string","minLength":24,"maxLength":24},"amount":{"type":"number","minimum":0.01},"dueDate":{"type":"string","format":"date-time"},"agendaDays":{"type":"integer","minimum":0,"maximum":60,"description":"Quantidade de dias corridos após o vencimento durante os quais o boleto pode ser pago. Deve ser ao menos 1 quando houver multa ou juros; para boletos sem esses encargos, omitir o campo equivale a 0.\n"},"sendBankSlipEmailToIssuer":{"type":"boolean","description":"Define se esta emissao manual deve enviar o boleto por e-mail para a empresa."},"sendBankSlipEmailToCustomer":{"type":"boolean","description":"Define se esta emissao manual deve enviar o boleto por e-mail para o cliente."},"discount":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","FIXED","PERCENT"]},"daysBeforeDueDate":{"type":"integer"},"amountOrPercent":{"type":"number"}}},"fine":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","FIXED","PERCENT"]},"amountOrPercent":{"type":"number"}}},"interest":{"type":"object","properties":{"type":{"type":"string","enum":["NONE","DAILY_VALUE","MONTHLY_PERCENT"]},"amountOrPercent":{"type":"number"}}}}},"CancelBankSlipRequest":{"type":"object","required":["cancelReason"],"properties":{"cancelReason":{"type":"string","maxLength":50,"description":"Internal cancellation reason that ClickFin maps to the provider payload."}}},"DashboardReportResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true}}},"ApiKeyScope":{"type":"string","enum":["clients:read","clients:write","suppliers:read","suppliers:write","services:read","services:write","market_segments:read","market_segments:write","contracts:read","contracts:write","receivables:read","receivables:write","payables:read","payables:write","service_invoices:read","service_invoices:write","bank_slips:read","bank_slips:write","reports:read"]},"ApiKeyErrorBody":{"type":"object","required":["status","category","message"],"properties":{"status":{"type":"string","enum":["error"]},"category":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","properties":{"requiredScope":{"$ref":"#/components/schemas/ApiKeyScope"}}}}}},"responses":{"UnauthorizedError":{"description":"Token ausente, inválido ou sem empresa selecionada.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"ForbiddenError":{"description":"Falha de autorização.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"}}}},"SupplierValidationError":{"description":"Campo inválido, incluindo identificador inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierValidationErrorResponse"},"examples":{"invalidId":{"value":{"error":"VALIDATION_FAILED","details":[{"field":"supplierId","message":"supplierId inválido"}]}}}}}},"SupplierCreateError":{"description":"Erro de validação ou CPF/CNPJ já cadastrado na empresa.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SupplierValidationErrorResponse"},{"$ref":"#/components/schemas/SupplierServiceErrorResponse"}]},"examples":{"validationFailed":{"value":{"error":"VALIDATION_FAILED","details":[{"field":"cpfCnpj","message":"CPF deve ter 11 dígitos ou CNPJ 14 dígitos"}]}},"cpfCnpjInUse":{"value":{"status":"error","message":"This CPF/CNPJ is already in use in this account.","category":"SUPPLIER.CREATE.CPF_CNPJ_IN_USE"}}}}}},"SupplierUpdateError":{"description":"Erro de validação, cadastro incompleto na reativação ou CPF/CNPJ já cadastrado na empresa.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SupplierValidationErrorResponse"},{"$ref":"#/components/schemas/SupplierServiceErrorResponse"}]},"examples":{"validationFailed":{"value":{"error":"VALIDATION_FAILED","details":[{"field":"status","message":"Invalid literal value, expected 0"}]}},"cpfCnpjInUse":{"value":{"status":"error","message":"This CPF/CNPJ is already in use in this account.","category":"SUPPLIER.UPDATE.CPF_CNPJ_IN_USE"}},"incompleteRegistration":{"value":{"status":"error","message":"Complete the required supplier registration fields before activating it.","category":"SUPPLIER.UPDATE.INCOMPLETE_REGISTRATION"}}}}}},"SupplierGetNotFoundError":{"description":"Fornecedor não encontrado no escopo da empresa selecionada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierServiceErrorResponse"},"examples":{"notFound":{"value":{"status":"error","message":"Supplier not found.","category":"SUPPLIER.GET.NOT_FOUND"}}}}}},"SupplierUpdateNotFoundError":{"description":"Fornecedor ou segmento de mercado não encontrado no escopo da empresa selecionada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierServiceErrorResponse"},"examples":{"supplierNotFound":{"value":{"status":"error","message":"Supplier not found.","category":"SUPPLIER.UPDATE.NOT_FOUND"}},"marketSegmentNotFound":{"value":{"status":"error","message":"Market segment not found.","category":"SUPPLIER.MARKET_SEGMENT.NOT_FOUND"}}}}}},"SupplierDeleteNotFoundError":{"description":"Fornecedor não encontrado no escopo da empresa selecionada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierServiceErrorResponse"},"examples":{"notFound":{"value":{"status":"error","message":"Supplier not found.","category":"SUPPLIER.DELETE.NOT_FOUND"}}}}}},"SupplierDeleteBlockedError":{"description":"Identificador inválido ou fornecedor vinculado a contas a pagar não excluídas.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SupplierValidationErrorResponse"},{"$ref":"#/components/schemas/SupplierServiceErrorResponse"}]},"examples":{"associatedAccountPayables":{"value":{"status":"error","message":"Cannot delete a supplier with associated accounts payable.","category":"SUPPLIER.DELETE.HAS_ASSOCIATED_ACCOUNT_PAYABLES"}}}}}},"SupplierMarketSegmentNotFoundError":{"description":"Segmento de mercado não encontrado no escopo da empresa selecionada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierServiceErrorResponse"},"examples":{"notFound":{"value":{"status":"error","message":"Market segment not found.","category":"SUPPLIER.MARKET_SEGMENT.NOT_FOUND"}}}}}},"SupplierUnauthorizedError":{"description":"Token ausente, inválido ou expirado. Em criação, atualização e exclusão, também é\nretornado quando a empresa da sessão foi excluída ou deixou de pertencer ao licenciado\nno momento da gravação (`SUPPLIER.CREATE.NOT_AUTHORIZED`, `SUPPLIER.UPDATE.NOT_AUTHORIZED`,\n`SUPPLIER.DELETE.NOT_AUTHORIZED`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierServiceErrorResponse"},"examples":{"unauthorized":{"value":{"status":"error","message":"Token not provided","category":"MIDDLEWARE.AUTH.TOKEN_NOT_PROVIDED"}},"createCompanyNotActive":{"value":{"status":"error","message":"You are not authorized to access this company.","category":"SUPPLIER.CREATE.NOT_AUTHORIZED"}},"updateCompanyNotActive":{"value":{"status":"error","message":"You are not authorized to access this company.","category":"SUPPLIER.UPDATE.NOT_AUTHORIZED"}},"deleteCompanyNotActive":{"value":{"status":"error","message":"You are not authorized to access this company.","category":"SUPPLIER.DELETE.NOT_AUTHORIZED"}}}}}},"SupplierForbiddenError":{"description":"A operação foi bloqueada pelas regras comerciais ou pelo perfil do usuário.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierServiceErrorResponse"},"examples":{"commercialBlocked":{"value":{"status":"error","message":"Commercial access blocked.","category":"BILLING.COMMERCIAL.ACCESS_BLOCKED"}}}}}},"ServiceCatalogUnauthorizedError":{"description":"Token ausente, inválido ou expirado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"tokenNotProvided":{"$ref":"#/components/examples/ServiceCatalogTokenNotProvided"},"invalidOrExpiredToken":{"$ref":"#/components/examples/ServiceCatalogInvalidOrExpiredToken"}}}}},"ServiceCatalogCommercialForbiddenError":{"description":"Acesso comercial do licenciado bloqueado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"commercialBlocked":{"$ref":"#/components/examples/ServiceCatalogCommercialBlocked"}}}}},"ServiceCatalogAdminForbiddenError":{"description":"Acesso comercial do licenciado bloqueado ou usuário sem perfil de Administrador.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCatalogErrorResponse"},"examples":{"commercialBlocked":{"$ref":"#/components/examples/ServiceCatalogCommercialBlocked"},"adminProfileRequired":{"summary":"Perfil de Administrador necessário","value":{"status":"error","message":"Unauthorized access. Admin profile required.","category":"MIDDLEWARE.ENSURE.UNAUTHORIZED_ACCESS_ADMIN_REQUIRED"}}}}}},"ValidationError":{"description":"Erro de validação nos parâmetros da consulta.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"ServiceError":{"description":"Erro de regra de negócio ou integração.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceErrorResponse"}}}},"AccountPayableListSuccess":{"description":"Contas a pagar paginadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableListResponse"}}}},"AccountPayableMutationSuccess":{"description":"Operação realizada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableMutationResponse"}}}},"AccountPayableDeleteSuccess":{"description":"Conta excluída logicamente.","content":{"application/json":{"schema":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"AccountPayableValidationError":{"description":"Dados inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableValidationError"}}}},"AccountPayableUnauthorizedError":{"description":"Token ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableServiceError"},"examples":{"tokenMissing":{"value":{"status":"error","category":"MIDDLEWARE.AUTH.TOKEN_NOT_PROVIDED","message":"Token not provided"}}}}}},"AccountPayableForbiddenError":{"description":"Acesso comercial bloqueado ou edição financeira não autorizada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableServiceError"}}}},"AccountPayableNotFoundError":{"description":"Conta não encontrada no escopo da empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableServiceError"},"examples":{"notFound":{"value":{"status":"error","category":"ACCOUNT.PAYABLE.GET.NOT_FOUND","message":"Account payable not found."}}}}}},"AccountPayableConflictError":{"description":"A conta foi alterada por outra operação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPayableServiceError"}}}},"NotFoundError":{"description":"NFS-e não encontrada para a empresa selecionada.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"ApiKeyUnauthorizedError":{"description":"Credencial ausente ou recusada. Com chave de API: `API_KEY.INVALID`\n(chave inexistente, malformada, revogada, expirada ou de empresa\nexcluída: a resposta é a mesma de propósito). Trate qualquer `401`\ncomo credencial recusada: confira a chave e não repita a chamada. Com\no JWT da aplicação web, as categorias de sessão de sempre.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyErrorBody"},"examples":{"invalid":{"value":{"status":"error","category":"API_KEY.INVALID","message":"Invalid API key."}}}}}},"ApiKeyForbiddenError":{"description":"A chave foi reconhecida, mas não pode fazer esta chamada:\n`API_KEY.SCOPE_REQUIRED` (falta o escopo; `details.requiredScope` diz\nqual), `API_KEY.ROUTE_NOT_ALLOWED` (rota fora da API pública),\n`API_KEY.IP_NOT_ALLOWED` (IP fora da lista da chave),\n`API_KEY.PLAN_NOT_ALLOWED` (plano sem acesso à API) ou\n`BILLING.COMMERCIAL.ACCESS_BLOCKED` (licença bloqueada).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyErrorBody"},"examples":{"scopeRequired":{"value":{"status":"error","category":"API_KEY.SCOPE_REQUIRED","message":"This API key does not have the clients:write scope.","details":{"requiredScope":"clients:write"}}},"ipNotAllowed":{"value":{"status":"error","category":"API_KEY.IP_NOT_ALLOWED","message":"This API key is not allowed from this IP address."}},"planNotAllowed":{"value":{"status":"error","category":"API_KEY.PLAN_NOT_ALLOWED","message":"The current plan does not include API access."}}}}}},"RateLimitExceededError":{"description":"Limite de requisições excedido (`RATE_LIMIT.EXCEEDED`). Por chave: 120\nrequisições por minuto (janela fixa de 60 s); o 429 da chave traz\n`X-RateLimit-*` da chave. Por IP, para tráfego com chave: 600\nrequisições em 10 minutos; esse 429 traz só `Retry-After`, sem\n`X-RateLimit-*` (os cabeçalhos descrevem apenas o limite da chave).\nAguarde `Retry-After` segundos antes de tentar de novo.\n","headers":{"Retry-After":{"description":"Segundos até a próxima janela.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Limit":{"description":"Requisições permitidas na janela da chave (só no 429 da chave).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela da chave (só no 429 da chave).","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Fim da janela da chave, em segundos desde a época Unix (só no 429 da chave).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyErrorBody"},"examples":{"apiKey":{"value":{"status":"error","category":"RATE_LIMIT.EXCEEDED","message":"Too many requests for this API key. Try again later."}},"ip":{"value":{"status":"error","category":"RATE_LIMIT.EXCEEDED","message":"Too many requests from this IP, please try again later."}}}}}},"AuthSessionUnavailableError":{"description":"Credencial não pôde ser verificada por falha temporária do servidor\n(`AUTH.SESSION_UNAVAILABLE`). Não invalida a chave nem a sessão: repita\ncom backoff.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyErrorBody"},"examples":{"default":{"value":{"status":"error","category":"AUTH.SESSION_UNAVAILABLE","message":"Serviço temporariamente indisponível. Tente novamente em instantes."}}}}}}},"parameters":{"AccountReceivableId":{"in":"path","name":"accountReceivableId","required":true,"schema":{"type":"string"},"description":"Identificador da conta a receber."},"CompanyId":{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}},"ServiceInvoiceId":{"in":"path","name":"serviceInvoiceId","required":true,"schema":{"type":"string"}}},"examples":{"TokenNotProvided":{"summary":"Token não enviado","value":{"statusCode":401,"message":"Token not provided","category":"TOKEN_NOT_PROVIDED"}},"ServiceCatalogTokenNotProvided":{"summary":"Token não enviado","value":{"status":"error","message":"Token not provided","category":"MIDDLEWARE.AUTH.TOKEN_NOT_PROVIDED"}},"ServiceCatalogInvalidOrExpiredToken":{"summary":"Token inválido ou expirado","value":{"status":"error","message":"Invalid or expired token","category":"MIDDLEWARE.AUTH.INVALID_OR_EXPIRED_TOKEN"}},"ServiceCatalogCompanyNotSelected":{"summary":"Empresa não selecionada no token","value":{"status":"error","message":"Company not selected","category":"MIDDLEWARE.AUTH.COMPANY_NOT_SELECTED"}},"ServiceCatalogCommercialBlocked":{"summary":"Acesso comercial bloqueado","value":{"status":"error","message":"Commercial access blocked.","category":"BILLING.COMMERCIAL.ACCESS_BLOCKED"}}},"securitySchemes":{"BearerAuthComplete":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT **completo** da aplicação web ClickFin, obtido em\n`/auth/select-company`, com o `companyId` selecionado. É a sessão de uma\npessoa no app; integrações servidor a servidor usam `ApiKeyAuth`.\n"},"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"cf_live_<id>_<segredo>","description":"Chave de API da licença, para integrações servidor a servidor:\n`Authorization: Bearer cf_live_<id>_<segredo>`, criada em\nConfigurações → Integrações. Cada operação aceita a chave só com o\nescopo declarado em `x-clickfin-api-key-scope`; operações sem essa\nextensão respondem `403 API_KEY.ROUTE_NOT_ALLOWED`. A chave age em uma\núnica empresa e é auditada como `INTEGRATION`.\n\nErros: `401 API_KEY.INVALID` (inexistente, revogada, expirada ou de\nempresa excluída: mesma resposta),\n`403 API_KEY.SCOPE_REQUIRED` (`details.requiredScope`),\n`403 API_KEY.ROUTE_NOT_ALLOWED`, `403 API_KEY.IP_NOT_ALLOWED`,\n`403 API_KEY.PLAN_NOT_ALLOWED`, `429 RATE_LIMIT.EXCEEDED` (com\n`Retry-After`) e `503 AUTH.SESSION_UNAVAILABLE`. Método ou caminho\ninexistente responde `404 ROUTE.NOT_FOUND`.\n\n`X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`\n(epoch em segundos) descrevem sempre o limite da chave (padrão 120\nrequisições por minuto) e vêm em toda resposta cuja chave foi\nresolvida, inclusive `403 API_KEY.SCOPE_REQUIRED`,\n`403 API_KEY.ROUTE_NOT_ALLOWED` de rota da API e `429` da chave. Não\nvêm quando a chave não chega a ser resolvida: `401`, `503`,\n`404 ROUTE.NOT_FOUND`, `403 API_KEY.ROUTE_NOT_ALLOWED` de rota de\nsessão da aplicação web (ex.: `GET /company`) e o `429` por IP, que\ntraz só `Retry-After`.\n"}}},"tags":[{"name":"Healthcheck","description":"Verificações públicas de status da aplicação."},{"name":"OpenAPI","description":"Operações relacionadas à publicação do contrato OpenAPI oficial."},{"name":"Client","description":"Operações relacionadas a clientes."},{"name":"Service","description":"Operações relacionadas a serviços."},{"name":"Market Segment","description":"Operações relacionadas a segmentos de mercado."},{"name":"AccountReceivable","description":"Listagem, consulta, exclusão e rotinas operacionais de contas a receber."},{"name":"Account Payable","description":"Contas a pagar manuais da empresa selecionada."},{"name":"ServiceInvoice","description":"Ativação, configuração, emissão e acompanhamento de NFS-e."},{"name":"BankSlip","description":"Operações relacionadas a boletos."},{"name":"Report","description":"Operações relacionadas a dashboards e relatórios agregados."}]}